> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/library-configuration/change-order-workflows.md).

# Change Order Workflows

## Overview

Change Order Workflow Templates provide a powerful way to customize the approval process for change orders in your PLM library. Using YAML configuration files, you can define multi-stage review processes, specify required approvers, and configure automated actions that align with your organization's change management procedures.

## Why Use Workflow Templates?

Every organization has unique requirements for managing engineering changes. Workflow templates allow you to:

* **Standardize Processes**: Ensure consistent review procedures across all change orders
* **Enforce Compliance**: Meet regulatory requirements with mandatory approval stages
* **Automate Actions**: Choose whether change orders close automatically or manually once resolved, and who is notified along the way
* **Customize Fields**: Capture the specific information your team needs for decision-making

## Getting Started

Each Duro library comes with two default workflow templates:

1. **Single Stage Review** ([`default.yaml`](https://durohub.com/configs/change-orders/default.yaml)): A single-stage approval workflow with a **Details** group containing a single *Reason for Change* field.
2. **Dual Stage Review** ([`double.yaml`](https://durohub.com/configs/change-orders/double.yaml)): A two-stage workflow with an **Impact Analysis** group capturing cost and description impact.

These templates serve as starting points that you can customize for your specific needs.

{% hint style="info" %}
Both default templates ship at schema `version: '1.2'` (their `yaml-language-server` directive points at `schema-1.2.json`) and are **ECO-only** — they declare `co_types: [ECO]` and `default_co_type: ECO`. Change orders created from them are always `ECO` unless you first add other [change order types](https://docs.durohub.com/core-concepts/change-orders.md#change-order-types) to `co_types`. See [Declaring Allowed Change Order Types](#declaring-allowed-change-order-types).

Change order type is a built-in concern configured through `co_types` / `default_co_type` — **not** a content field. Neither built-in template defines a legacy `change_type` enum in `details.info.groups`; that field has been removed from the shipped templates.
{% endhint %}

### Basic Workflow Structure

Every workflow template follows this structure:

```yaml
version: '1.2'
description: A clear description of this workflow's purpose
schema_type: change_order_scheme
co_types: [ECO]

details:
  info:
    groups:                 # custom fields for change order creation (at least one group)
      - name: Details
        fields:
          - name: reason
            type: longtext
            label: Reason for Change

stages:
  open:                     # review stages, in order (at least one)
    - name: Engineering Review
      types: ['Majority']
      default: Majority
  resolved:                 # what happens when the change order is resolved
    resolutions:
      onapproval: [AUTO_CLOSE]
  closed:                   # who is emailed when the change order closes
    notifyList:
      users: []
      emails: []
```

### Choosing a Schema Version

The `version` line declares which version of the template format your file follows. It is not a version of *your* template — it tells Duro which schema to validate the file against.

| `version` | Use it when                                                                                                                                                                                                                                                          | Validated against                                                              |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `'1.2'`   | **Use this for new templates.** Same fields as `'1.1'`, plus [required approvers](#required-approvers). It is the only version Duro validates against its schema at upload, so a malformed template is rejected with a path to the problem instead of failing later. | [`schema-1.2.json`](https://durohub.com/configs/change-orders/schema-1.2.json) |
| `'1.1'`   | You have an existing template that controls [change order types](#declaring-allowed-change-order-types). `co_types` is **required**; `default_co_type` is optional.                                                                                                  | [`schema-1.1.json`](https://durohub.com/configs/change-orders/schema-1.1.json) |
| `'1.0'`   | You have an existing template without `co_types`. It stays valid and implicitly allows only `ECO`. `co_types` and `default_co_type` are rejected under this version.                                                                                                 | [`schema-1.0.json`](https://durohub.com/configs/change-orders/schema-1.0.json) |

To move a `'1.1'` template to `'1.2'`, change `version`; nothing else about the format changes, but the template must now pass schema validation to save. To move a `'1.0'` template forward, also add a `co_types` list. Once a template is at `'1.2'` it cannot be moved back to an earlier version (`CANNOT_DOWNGRADE_SCHEMA_VERSION`). If your editor supports the YAML Language Server, add the matching schema at the top of the file to get validation as you type:

```yaml
# yaml-language-server: $schema=https://durohub.com/configs/change-orders/schema-1.2.json
version: '1.2'
```

Every property table and constraint per version is in the [Workflow Reference → Schema Information](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#schema-information).

<details>

<summary>New to YAML? Read this first</summary>

YAML is a plain-text format. Five rules cover everything in this guide:

1. **Indentation is structure.** Lines indented under a parent belong to it. Use spaces, not tabs, and keep the indentation consistent (the examples here use two spaces).
2. **`key: value` sets a property.** The space after the colon is required: `type: list`, not `type:list`.
3. **A leading `-` starts an item in a list.** Every field under `fields:` and every option under `options:` begins with `-`.
4. **Text after `#` is a comment.** Duro ignores it — the comments in the examples below are there to guide you.
5. **Quote values that could be misread.** `'1.0'` stays a version string; `1.0` becomes a number. `'yes'` stays a word; `yes` becomes `true`.

When you save, the template editor in Duro checks the YAML and marks the line with the problem — so you can fix mistakes before they reach a change order.

</details>

## Creating Custom Fields

The `details.info.groups` section lets you define custom fields that users fill out when creating a change order. Fields are organized into logical groups for better user experience.

### Choosing a Field Type

Start from what you want the person filling out the change order to do, then pick the `type`:

| I want the user to…                           | Use `type:` | Also add                          |
| --------------------------------------------- | ----------- | --------------------------------- |
| Type a short answer (a title, a part number)  | `text`      | —                                 |
| Type a paragraph or more                      | `longtext`  | —                                 |
| Enter a number                                | `number`    | —                                 |
| Enter a monetary amount                       | `currency`  | —                                 |
| Pick a date                                   | `date`      | —                                 |
| Pick **exactly one** option from a fixed set  | `enum`      | `options`                         |
| Pick **one or more** options from a fixed set | `list`      | `options` and `multiSelect: true` |

{% hint style="info" %}
**`enum` versus `list`.** Both take the same `options`, and both render as a single-select dropdown unless you say otherwise. Duro stores an `enum` field as a `list`, so the two behave the same: `multiSelect: true` is the only thing that makes a field accept several values. Use `enum` when one answer is wanted, and `list` with `multiSelect: true` whenever users may need to pick more than one.
{% endhint %}

The [Workflow Reference](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#field-types) lists every property each type accepts.

{% hint style="info" %}
**Users see each option's `value`.** The change order stores and displays the option `value`; an option's `label` and `description` are accepted by the schema but are not shown. Write values as the text you want people to read, such as `Design Update`, and set `label` to the same text.
{% endhint %}

### Example: Adding Change Classification

A single-select dropdown. The user picks one category; the change order stores and shows that option's `value` (for example, `Design Update`).

```yaml
details:
  info:
    groups:
      - name: Change Classification   # heading shown above the fields in this group
        icon: mdi-tag-multiple
        fields:
          - name: change_category      # internal identifier — letters, numbers, underscores
            type: enum                 # enum = pick exactly one
            label: Category            # what the user sees next to the field
            description: Primary category of this change
            options:
              - label: Design Update
                value: Design Update   # stored on the change order and shown in the dropdown
              - label: Cost Reduction
                value: Cost Reduction
              - label: Quality Improvement
                value: Quality Improvement
            required: true             # marked required in the change order form
```

### Example: Letting users pick more than one option

The same shape, but with `type: list` and `multiSelect: true`. The dropdown accepts several picks, and the change order stores every chosen `value` — `["Project A", "Project C"]` — rather than a single one.

```yaml
details:
  info:
    groups:
      - name: Scope
        icon: mdi-folder-multiple
        fields:
          - name: project
            type: list                 # list + multiSelect is the only way to allow several picks
            label: Project
            options:
              - label: Project A
                value: Project A
              - label: Project B
                value: Project B
              - label: Project C
                value: Project C
            description: Which project(s) does this impact?
            multiSelect: true          # remove this line and the field becomes single-select
            required: true             # marked required in the change order form
```

## Declaring Allowed Change Order Types

A template can declare which [change order types](https://docs.durohub.com/core-concepts/change-orders.md#change-order-types) users may choose from when creating a change order, and which one is applied by default. This requires schema `version: '1.1'` or later (current: `'1.2'`).

```yaml
version: '1.2'
description: Engineering change workflow supporting orders, requests, and doc updates
schema_type: change_order_scheme

co_types: [ECO, ECR, DCO]
default_co_type: ECO

details:
  info:
    groups:
      - name: Details
        fields:
          - name: reason
            type: longtext
            label: Reason for Change

stages:
  open:
    - name: Engineering Review
      types: ['Majority']
      default: Majority
```

* `co_types` — the non-empty list of types this template allows. It is **required** whenever `version` is `'1.1'` or later; omitting it fails upload with `CO_TYPES_REQUIRED_IN_SCHEMA_VERSION`. When a change order is created from the template, its `coType` must be one of these values, or creation fails with [`CO_TYPE_NOT_ALLOWED`](https://docs.durohub.com/advanced-topics/error-handling.md#co_type_not_allowed).
* `default_co_type` — the type applied when the creator does not pass an explicit `coType`. It must be a member of `co_types`; if omitted when the template is created, it defaults to `ECO`. When you update a template that already declares `co_types` and leave `default_co_type` out, the template keeps its current default, so a new `co_types` list that drops that default is rejected with `DEFAULT_CO_TYPE_EXCLUDED_BY_UPDATE`. Set `default_co_type` in the same update.

{% hint style="info" %}
**These two keys also govern draft-time edits, not just creation.** A change order in `DRAFT` can switch its type and its template through `submitDraft` (`coType` / `configId`), so:

* `co_types` bounds the types an integration can switch a draft change order *into* — a `coType` outside the list is rejected with `CO_TYPE_NOT_ALLOWED` on `submitDraft` exactly as it is on create.
* `default_co_type` is the type a draft change order lands on when it is switched to this template without an explicit `coType`. Pick a default that is sensible for change orders arriving from another template, not only for brand-new ones.
* Narrowing `co_types` on an existing template does not retype change orders already created from it, but it does stop draft change orders from switching into the removed types.

See [Change Orders → Switching Type and Template in Draft](https://docs.durohub.com/core-concepts/change-orders.md#switching-type-and-template-in-draft).
{% endhint %}

{% hint style="warning" %}
`DCO` (Documentation Change Order) is more than a label — a DCO never bumps component revisions and cannot change a component's status or revision. Duro enforces this with a built-in [DCO baseline validation](https://docs.durohub.com/library-configuration/change-order-validations.md#dco-baseline-freeze) that freezes each DCO item against its last-released baseline and blocks the change order — at submit and again at close — if the item's live status or revision has drifted. Only include `DCO` in `co_types` for workflows meant for documentation-only, no-revision-bump changes; any item that also needs a status or revision change must be routed through a non-`DCO` type instead. See [Change Orders → Change Order Types](https://docs.durohub.com/core-concepts/change-orders.md#change-order-types).
{% endhint %}

Templates without `co_types` (any `version: '1.0'` template) implicitly allow only `ECO`, and adding `co_types` or `default_co_type` to a `'1.0'` template is rejected — bump `version` to `'1.2'` first. For the full list of type values and all validation rules, see the [Workflow YAML Reference](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#change-order-types).

{% hint style="warning" %}
**Don't model change order type as a content field.** Older templates declared a `change_type` enum (ECO / MCO / DCO) inside `details.info.groups` to capture the type. That field is redundant now that type is first-class via `co_types` / `default_co_type`, and it has been removed from the built-in templates. Use `co_types` / `default_co_type` to control the type instead of adding a custom enum field.

Existing `version: '1.0'` templates (and change orders already created from them) that still define a `change_type` content field keep working and continue to show it — the removal only affects the shipped defaults.
{% endhint %}

## Configuring Approval Stages

The `stages.open` section defines your review process. You can create multiple stages that execute sequentially.

### Single-Stage Approval

```yaml
stages:
  open:
    - name: Engineering Review
      types: ['Unanimous', 'Majority', 'Minimum']
      default: Majority
      minReviewers: 2
```

### Multi-Stage Approval

```yaml
stages:
  open:
    - name: Technical Review
      types: ['Unanimous']
      default: Unanimous
      minReviewers: 2
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174001
          - 123e4567-e89b-12d3-a456-426614174002

    - name: Management Approval
      types: ['Majority', 'Minimum']
      default: Majority
      minReviewers: 1
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174003
```

### Pre-Assigning Notifiers

You can also pre-assign notifiers to open stages using a `notifyList` block. Notifiers are added to the stage's notify list when the change order is created but do not participate in the approval process.

A `notifyList` accepts two arrays:

* `users` — internal users, specified as UUID strings (same format as `reviewers.users`).
* `emails` — external recipients, specified as plain email addresses. Use this for people who do not have a Duro account.

```yaml
stages:
  open:
    - name: Engineering Review
      types: ['Unanimous']
      default: Unanimous
      minReviewers: 2
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174001
      notifyList:
        users:
          - 123e4567-e89b-12d3-a456-426614174004
        emails:
          - supplier@example.com
```

{% hint style="info" %}
`reviewers.users` and `notifyList.users` are **internal-only**: each entry must be the UUID of a user in the library's organization. External addresses belong in `notifyList.emails`. To look up a user's UUID, query your organization's members — see [RBAC → Get Organization Members with Roles](https://docs.durohub.com/advanced-topics/rbac.md#get-organization-members-with-roles).

Uploading a template via the GraphQL API requires UUIDs in these arrays. The web template editor also lets you type email addresses for internal users and resolves them to UUIDs on save, so you only need to look up IDs when authoring YAML by hand.

In `notifyList.users`, and in `reviewers.users` below `'1.2'`, each entry is a plain string. From `'1.2'`, a `reviewers.users` entry may also be an `{ id, isRequiredToApprove }` object; see [Required Approvers](#required-approvers). Other object forms, such as `- email: <address>` or an `isRequired` flag, are rejected by the API.
{% endhint %}

#### Editor vs. API: participant values

The structure is identical for both authoring paths — only the participant values differ:

```yaml
# Web template editor — type email addresses; resolved to org users on save
reviewers:
  users:
    - jane@acme.com
```

```yaml
# GraphQL API / direct YAML upload — user UUIDs required
reviewers:
  users:
    - 123e4567-e89b-12d3-a456-426614174001
```

For a required approver, the editor takes an `email` in place of the `id`:

```yaml
# Web template editor (1.2)
reviewers:
  users:
    - email: jane@acme.com
      isRequiredToApprove: true
```

In the editor, unrecognized addresses in a `notifyList` are kept as external `notifyList.emails` recipients. The examples throughout this guide and the [reference](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md) use UUIDs, since they're written for direct API upload.

### Required Approvers

From `version: '1.2'`, you can make a pre-assigned reviewer a **required approver** by writing their entry as an object with `isRequiredToApprove: true`:

```yaml
version: '1.2'
# ...
stages:
  open:
    - name: Engineering Review
      types: ['Majority', 'Unanimous']
      default: Majority
      minReviewers: 2
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174001
          - 123e4567-e89b-12d3-a456-426614174002
          - id: 123e4567-e89b-12d3-a456-426614174003   # must approve
            isRequiredToApprove: true
```

On every change order created from this template:

* The stage is not approved until every required approver approves, even if its approval type is already met. In the example, two approvals make a majority, but the stage stays pending until the third reviewer approves.
* If a required approver rejects, the stage is rejected at once.
* A required approver cannot be removed from the stage (`CANNOT_REMOVE_REQUIRED_REVIEWER`).
* If a required approver can no longer be added (for example, they left the organization), change orders cannot be created from the template, or drafts switched to it, until someone updates it (`REQUIRED_APPROVER_UNRESOLVABLE`).

Required approvers can only come from a saved template: an inline `config` passed to `changeOrders.create` must list reviewers as UUID strings. See the [Workflow YAML Reference](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#required-approvers) for the full rules.

### Approval Types Explained

Each approval type decides both when a stage is approved and when it is rejected:

* **Unanimous**: Approved when every reviewer approves. Rejected as soon as any reviewer rejects.
* **Majority**: Approved when more than half of the reviewers approve. Rejected when more than half reject.
* **Minimum**: Approved when the stage's approval threshold (`decisionMinimumCount`) is reached. Rejected when the same number of reviewers reject. The threshold starts at the stage's `minReviewers`, and the change order's author may raise it.

`minReviewers` is also the fewest reviewers a stage must have before the change order can be submitted, whatever its approval type. Required approvers apply on top of whichever type the stage uses.

## Required Fields and Value Checks

To mark a field required, set `required: true` on the field. The change order form then shows a required marker and will not save the field empty.

```yaml
fields:
  - name: estimated_cost
    type: currency
    label: Estimated Cost
    required: true

  - name: part_number
    type: text
    label: Affected Part Number
    required: true
```

{% hint style="warning" %}
**What Duro does and does not check.**

* `required: true` is applied by the change order form in the web app. The API does not check required fields, so an integration can create and submit a change order with a required field empty.
* The field-level `validations` object (`required`, `min`, `max`, `pattern`) is accepted by the schema but not applied: `validations.required` does not mark a field required, and `min`, `max` and `pattern` are not checked anywhere.
* When a field value is written, the API checks it against the field's type: a `number` or `currency` value must be a number (`CONTENT_VALUE_NOT_A_NUMBER`), a `date` must be a valid date (`CONTENT_INVALID_DATE`), a `list` or `enum` value must be one of the field's option values (`CONTENT_VALUE_NOT_AN_OPTION`), and only a `multiSelect` field takes more than one value (`CONTENT_TOO_MANY_VALUES`).

To enforce anything beyond that, such as a value range or a format, write a [custom validation](https://docs.durohub.com/library-configuration/authoring-custom-validations.md).
{% endhint %}

## Automating Resolutions

Choose what happens when a change order is approved, rejected, or withdrawn. `resolved` sits under `stages`:

```yaml
stages:
  open:
    - name: Engineering Review
      types: ['Majority']
      default: Majority
  resolved:
    resolutions:
      onapproval: [AUTO_CLOSE]      # Automatically close when approved
      onrejection: [MANUAL_CLOSE]   # Require manual closure when rejected
      onwithdrawal: [MANUAL_CLOSE]  # Require manual closure when withdrawn
```

Each list holds the options the change order allows for that outcome, and the first entry is the one applied. An outcome you leave out uses `AUTO_CLOSE`.

To email people when a change order closes, list them under `stages.closed.notifyList` (`users` as UUIDs, `emails` as external addresses). They receive the closed email whatever the outcome, alongside the change order's reviewers and notifiers. Users who are no longer members of the organization or library when the change order closes are skipped. A `notifyList` under `stages.resolved` is accepted but not used, and nobody listed there is emailed.

## Best Practices

### 1. Start Simple

Begin with a basic workflow and add complexity as needed. It's easier to expand a working workflow than debug a complex one.

### 2. Use Descriptive Names

Choose clear, meaningful names for stages and fields:

* ✅ Good: `manufacturing_impact_assessment`
* ❌ Avoid: `field1`, `stage_a`

### 3. Group Related Fields

Organize fields into logical groups to improve the user experience:

```yaml
groups:
  - name: Impact Analysis
    icon: mdi-chart-line
    fields:
      - name: schedule_impact
        type: text
        label: Schedule Impact
      - name: cost_impact
        type: currency
        label: Cost Impact
      - name: quality_impact
        type: longtext
        label: Quality Impact
```

### 4. Document Your Workflow

Always include a clear description:

```yaml
description: |
  Engineering change workflow for hardware modifications.
  Requires technical review followed by management approval
  for changes exceeding $10,000 in impact.
```

### 5. Test Thoroughly

Before deploying a new workflow:

1. Create test change orders using the workflow
2. Verify all stages execute correctly
3. Confirm notifications reach the right people
4. Test edge cases (rejections, withdrawals)

## Common Patterns

### Pattern 1: Cost-Based Escalation

For organizations where higher-cost changes need additional approval:

```yaml
stages:
  open:
    - name: Initial Review
      types: ['Majority']
      default: Majority
      minReviewers: 2

    - name: Executive Approval
      types: ['Minimum']
      default: Minimum
      minReviewers: 1
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174003
```

### Pattern 2: Department-Specific Reviews

When different departments need to review changes:

```yaml
stages:
  open:
    - name: Engineering Review
      types: ['Majority']
      default: Majority
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174001
          - 123e4567-e89b-12d3-a456-426614174002

    - name: Manufacturing Review
      types: ['Majority']
      default: Majority
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174005
          - 123e4567-e89b-12d3-a456-426614174006

    - name: Quality Review
      types: ['Unanimous']
      default: Unanimous
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174007
          - 123e4567-e89b-12d3-a456-426614174008
```

## Creating Templates via the GraphQL API

You can create and manage change order templates programmatically using the GraphQL API through Apollo Studio, Duro's interactive API explorer. This approach is useful for:

* Testing and validating your workflow configurations before deployment
* Creating templates across multiple libraries
* Version controlling your workflow configurations

### Prerequisites

Before you begin, you'll need:

1. **A Duro API Key**: Navigate to `https://durohub.com/org/@<your-org>/libs/<your-library>/settings/api-keys` to generate one. See [Getting Started → Authentication](https://docs.durohub.com/getting-started/authentication.md) for more information.
2. **Your YAML workflow template**: Either use one of the default templates or create your own custom configuration

### Step 1: Prepare Your YAML Configuration

First, create your workflow template YAML file. Here's a starter template:

```yaml
version: '1.2'
description: Engineering Change Review Process
schema_type: change_order_scheme
co_types: [ECO]
default_co_type: ECO

details:
  info:
    groups:
      - name: Change Information
        icon: mdi-information
        fields:
          - name: change_description
            type: longtext
            label: Change Description
            description: Detailed description of the proposed change
            required: true

          - name: impact_assessment
            type: enum
            label: Impact Level
            description: Estimated impact of this change
            options:
              - label: Low Impact
                value: Low Impact
              - label: Medium Impact
                value: Medium Impact
              - label: High Impact
                value: High Impact
            required: true

stages:
  open:
    - name: Engineering Review
      types: ['Unanimous', 'Majority']
      default: Majority
      minReviewers: 2
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174001   # replace with a user ID from your organization

  resolved:
    resolutions:
      onapproval: [AUTO_CLOSE]
      onrejection: [MANUAL_CLOSE]
      onwithdrawal: [MANUAL_CLOSE]

  closed:
    notifyList:
      users: []
      emails: []
```

`resolved` and `closed` belong under `stages`. At the root of the file they are ignored without an error, and every outcome falls back to `AUTO_CLOSE`.

### Step 2: Choose How to Send the Configuration

`CreateTemplateInput` takes the configuration in one of two forms:

* **`configYAML`** — the YAML as a GraphQL string. GraphQL variables are JSON, so the line breaks are written as `\n` (most HTTP clients and YAML libraries produce this for you when they serialize the string).
* **`configJSON`** — the same configuration as a JSON object. Nothing needs escaping, which makes it the easier choice from code.

### Step 3: Open Apollo Studio

1. **Navigate to Apollo Explorer**: Open <https://api.durohub.com/graphql> in your browser. Using the EU or GovCloud region? Use your region's host — see [Endpoints](https://docs.durohub.com/readme.md#endpoints).
2. **Set up headers**: Click on the "Headers" tab at the bottom of the Operation panel and add the following required headers:

| Header           | Value                    | Description                                    |
| ---------------- | ------------------------ | ---------------------------------------------- |
| `x-api-key`      | `your-api-key`           | Your API authentication token                  |
| `x-organization` | `@your-org`              | Your organization slug                         |
| `x-library`      | `@your-org/your-library` | The library where the template will be created |

![Apollo Studio Headers tab showing x-api-key configuration](https://1319565474-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOJejmhbdeb0yjsYB69x4%2Fuploads%2Fgit-blob-6f1960feffc2a09e98a4114a14b2a7974c5781ca%2Fapi-key-header-screenshot.png?alt=media)

### Step 4: Create Your Template

1. **Paste the mutation**: In the Operation panel, paste the following GraphQL mutation:

```graphql
mutation CreateTemplate($input: CreateTemplateInput!) {
  changeOrders {
    createTemplate(input: $input) {
      id
      name
      config
      library {
        id
        name
      }
      createdAt
    }
  }
}
```

2. **Set up variables**: In the Variables panel, create your input object. With `configYAML`, pass the YAML as a string:

```json
{
  "input": {
    "name": "My Engineering Review Process",
    "configYAML": "version: '1.2'\ndescription: Engineering Change Review Process\nschema_type: change_order_scheme\n..."
  }
}
```

Or pass the configuration as an object with `configJSON`:

```json
{
  "input": {
    "name": "My Engineering Review Process",
    "configJSON": {
      "version": "1.2",
      "description": "Engineering Change Review Process",
      "schema_type": "change_order_scheme",
      "co_types": ["ECO"],
      "details": { "info": { "groups": [ "..." ] } },
      "stages": { "open": [ "..." ] }
    }
  }
}
```

3. **Execute the mutation**: Click the "CreateTemplate" button to run the mutation

![Apollo Studio showing the complete setup for creating a change order template](https://1319565474-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOJejmhbdeb0yjsYB69x4%2Fuploads%2Fgit-blob-87a9143ca283d106cd0985be378d9ff374f4802e%2Fapollo-studio-template-create-screenshot.png?alt=media)

### Step 5: Verify Your Template

A successful response will show:

```json
{
  "data": {
    "changeOrders": {
      "createTemplate": {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "name": "My Engineering Review Process",
        "config": {
          "version": "1.2",
          "description": "Engineering Change Review Process",
          // ... rest of your configuration
        },
        "library": {
          "id": "fc28b204-0cd0-46b3-96eb-b0720c16c423",
          "name": "Main Library"
        },
        "createdAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}
```

Your template is now created and ready to use in your change order workflows!

### Troubleshooting Common Issues

#### YAML Formatting Errors

If the YAML cannot be parsed, the request fails with an `Invalid YAML: …` message:

* Ensure your YAML is valid before sending it (use a YAML validator)
* Check that line breaks in `configYAML` are sent as `\n` and quotes are escaped
* Send the configuration as `configJSON` instead to avoid escaping altogether

#### Authentication Failed

If you get an authentication error:

* Verify your API key is correct
* Ensure the `x-api-key` header is properly set in the Headers tab
* Confirm the user who created the API key has the `change_orders.templates.manage` permission in the library, which creating and updating templates requires

#### Invalid Configuration

If the template configuration is rejected:

* Review the error message for specific validation issues
* Ensure all required fields are present in your YAML
* Verify user IDs are valid UUIDs belonging to your organization
* Check that `version` is a quoted string (`'1.0'`, `'1.1'` or `'1.2'`) and that `co_types` / `default_co_type` only appear from `'1.1'`

| Error Code                                               | Cause                                                                                                                |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `TEMPLATE_CONFIG_INVALID`                                | A `'1.2'` template does not match its schema. The message names the config path and the reason.                      |
| `UNSUPPORTED_SCHEMA_VERSION`                             | `version` is not one of the accepted versions.                                                                       |
| `SCHEMA_VERSION_MUST_BE_STRING`                          | `version` is unquoted, so it parsed as a number.                                                                     |
| `CANNOT_DOWNGRADE_SCHEMA_VERSION`                        | An update moves a `'1.2'` template to `'1.0'` or `'1.1'`, or a template with `co_types` back to `'1.0'`.             |
| `CO_TYPES_UNSUPPORTED_IN_SCHEMA_VERSION`                 | `co_types` or `default_co_type` in a `'1.0'` template.                                                               |
| `CO_TYPES_REQUIRED_IN_SCHEMA_VERSION` / `CO_TYPES_EMPTY` | `co_types` is missing or empty in a `'1.1'` or later template.                                                       |
| `DEFAULT_CO_TYPE_REQUIRES_CO_TYPES`                      | `default_co_type` is set without `co_types`.                                                                         |
| `DEFAULT_CO_TYPE_NOT_ALLOWED`                            | `default_co_type` is not a member of `co_types`.                                                                     |
| `DEFAULT_CO_TYPE_EXCLUDED_BY_UPDATE`                     | An update narrows `co_types` so it no longer includes the current default. Set `default_co_type` in the same update. |
| `INVALID_CO_TYPE`                                        | A value in `co_types` or `default_co_type` is not a change order type.                                               |

Each schema version has its own JSON Schema (`schema-1.0.json`, `schema-1.1.json`, `schema-1.2.json`) and a `versions.json` manifest that says which versions Duro accepts and which it validates structurally at upload. Today all three are accepted and only `'1.2'` is structurally enforced: a `'1.2'` template with a wrong field type or missing property is rejected at upload with [`TEMPLATE_CONFIG_INVALID`](https://docs.durohub.com/advanced-topics/error-handling.md#template_config_invalid), naming the config path and reason. In a `'1.0'` or `'1.1'` template the same mistake is stored and only surfaces when a change order is created from it, so validate those against the schema in your editor before uploading. See [Schema versions and the manifest](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md#schema-versions-and-the-manifest).

#### Participant Validation Errors

When a template includes `reviewers.users` or `notifyList.users`, Duro validates the user IDs at upload time:

| Error Code                                | Cause                                                                                                                                                                                                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TEMPLATE_PARTICIPANT_INVALID_USER_ID`    | User ID is not a valid UUID or does not exist                                                                                                                                                                                                                |
| `TEMPLATE_PARTICIPANT_WRONG_ORGANIZATION` | User exists but is not a member of the library's organization                                                                                                                                                                                                |
| `TEMPLATE_PARTICIPANT_MALFORMED_CONFIG`   | Structural error (e.g., `reviewers` is not an object, `users` is not an array, or a `users` entry is an object where only UUID strings are allowed). In a `'1.2'` template most of these are caught first by schema validation as `TEMPLATE_CONFIG_INVALID`. |

External `notifyList.emails` entries are not validated against organization membership. In a `'1.2'` template each entry must be a well-formed email address; in `'1.0'` and `'1.1'` templates the format is not checked.

## Participant Population Behavior

When a change order is created from a template that includes pre-assigned reviewers or a notify list, Duro automatically populates the corresponding stages — adding `reviewers.users` as stage reviewers, and `notifyList.users` / `notifyList.emails` to the stage's notify list. The same population runs when a draft change order is switched to this template, since the switch rebuilds its stages from the template.

### Validation at Upload vs. Creation

Participant validation happens at two points with different behavior:

* **At template upload** (strict): All user IDs must be valid UUIDs, exist in the system, and belong to the library's organization. The template is rejected if any user fails validation.
* **At change order creation** (lenient): Valid users are added to their stages. Invalid or missing users are skipped, and warnings are logged to the change order's activity feed. The exception is a [required approver](#required-approvers): if one can no longer be added, creation fails with `REQUIRED_APPROVER_UNRESOLVABLE` rather than creating a change order that skips them.

This two-phase approach ensures templates stay clean while allowing change orders to be created even if a user has been removed from the organization since the template was last updated.

### Activity Feed Logging

When participants are skipped during change order creation, Duro logs a `template.participants.skipped` activity entry containing the skipped user IDs, their intended stages, and the reason (not found or wrong organization).

## Example Templates

Each of these is a complete `version: '1.2'` template that passes schema validation. Replace the placeholder user IDs with members of your organization before uploading.

| Example                                                                                                                                       | What it shows                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [`basic-single-stage.yaml`](https://github.com/duronext/developer/tree/main/schemas/change-orders/examples/basic-single-stage.yaml)           | One review stage, a few required fields, and an external notifier                                                             |
| [`minimal-auto-close.yaml`](https://github.com/duronext/developer/tree/main/schemas/change-orders/examples/minimal-auto-close.yaml)           | The smallest useful template: a `DCO`-only workflow for documentation changes that closes automatically                       |
| [`multi-stage-review.yaml`](https://github.com/duronext/developer/tree/main/schemas/change-orders/examples/multi-stage-review.yaml)           | Three sequential stages, a selectable change order type (`ECO`, `MCO` or `DCO`), a required approver, and a closed-email list |
| [`medical-device-workflow.yaml`](https://github.com/duronext/developer/tree/main/schemas/change-orders/examples/medical-device-workflow.yaml) | A regulated workflow with four approval stages and the people emailed when a change order closes                              |

## Next Steps

1. Review the [Change Order Workflow Reference](https://docs.durohub.com/library-configuration/change-order-workflow-reference.md) for complete specification details
2. Explore the [example templates](#example-templates) above
3. Start with a default template and customize it for your needs
4. Test your workflow with a pilot group before full deployment


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/library-configuration/change-order-workflows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
