Change Orders

Change Orders (COs) are the backbone of engineering change management in PLM systems. They provide a structured, auditable process for proposing, reviewing, and implementing modifications to your components. Whether you're updating a component specification, revising a BOM, or making design changes, change orders ensure proper review, approval, and traceability.

Overview

What Are Change Orders?

A Change Order is a formal request to modify one or more components in your library. It captures:

• What's changing: The affected components and proposed modifications

• Why it's changing: Description and justification for the change

• Who approves it: Reviewers assigned to evaluate the change

• The outcome: Whether the change was approved, rejected, or withdrawn

Change Order Lifecycle

Change orders follow a defined lifecycle:

DRAFT ──────► OPEN ──────► RESOLVED ──────► CLOSED
  │             │              │
  │             ▼              │
  │         ON_HOLD            │
  │             │              │
  └─────────────┴──────────────┘
            (reset)

Status	Description
DRAFT	Initial state. The CO can be modified freely—add items, assign reviewers, fill in details.
OPEN	Submitted for review. Reviewers evaluate and make decisions.
ON_HOLD	Temporarily paused, awaiting additional information.
RESOLVED	Review complete. Check the resolution field for the outcome.
CLOSED	Final state. The change order is complete.

Resolution Types

When a change order is resolved, the resolution field indicates the outcome:

Resolution	Description
PENDING	Still awaiting reviewer decisions
APPROVED	All required approvals obtained
REJECTED	Rejected by one or more reviewers
WITHDRAWN	Creator withdrew the change order

---

Required Headers

All change order operations require these headers:

curl 'https://api.durohub.com/graphql' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-organization: @your-org' \
  -H 'x-library: @your-org/your-library' \
  -H 'Content-Type: application/json' \
  -d '{"query": "..."}'

Header	Required	Description
x-api-key	Yes	Your API authentication token
x-organization	Yes	Organization slug (e.g., @acme-corp)
x-library	Yes	Library slug (e.g., @acme-corp/main-library)
Content-Type	Yes	Must be application/json

---

Querying Change Orders

List Change Orders

Query change orders with optional filtering and pagination:

query GetChangeOrders {
  changeOrders {
    get(
      filter: { status: [DRAFT, OPEN] }
      pagination: { first: 20 }
    ) {
      connection {
        edges {
          node {
            id
            sequentialId
            name
            description
            status
            resolution
            createdAt
            createdBy {
              firstName
              lastName
              email
            }
            currentStage {
              name
              decisionState
            }
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
      totalCount
    }
  }
}

Filter Options

Field	Type	Description
ids	[ID!]	Filter by specific UUIDs
sequentialIds	[Int!]	Filter by sequential IDs (e.g., CO-001, CO-002)
status	[ChangeOrderStatus!]	Filter by status (DRAFT, OPEN, RESOLVED, CLOSED, ON_HOLD)
resolution	[ChangeOrderResolution!]	Filter by resolution (PENDING, APPROVED, REJECTED, WITHDRAWN)
assigneeId	ID	Filter by assigned reviewer
stageId	ID	Filter by current stage

---

Getting Available Templates

Before creating a change order, query the available templates for your library:

query GetTemplates {
  changeOrders {
    getTemplates {
      id
      name
      config
      createdAt
    }
  }
}

Templates define the workflow structure including:

• Custom fields to capture change information

• Approval stages and their decision methods

• Default reviewers and notification settings

See Change Order Workflows for creating custom templates.

---

Creating a Change Order

Create a new change order in DRAFT status:

mutation CreateChangeOrder {
  changeOrders {
    create(input: {
      name: "ECO-2024-001: Update Motor Specifications"
      description: "Updating motor torque specifications to meet new performance requirements"
    }) {
      id
      sequentialId
      name
      description
      status
      resolution
      stages {
        id
        name
        order
        decisionMethod
      }
      contents {
        id
        name
        label
        isRequired
      }
      createdAt
    }
  }
}

Example Response

{
  "data": {
    "changeOrders": {
      "create": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "sequentialId": 42,
        "name": "ECO-2024-001: Update Motor Specifications",
        "description": "Updating motor torque specifications...",
        "status": "DRAFT",
        "resolution": "PENDING",
        "stages": [
          {
            "id": "stage-uuid-1",
            "name": "Engineering Review",
            "order": 1,
            "decisionMethod": "MAJORITY"
          },
          {
            "id": "stage-uuid-2",
            "name": "Quality Approval",
            "order": 2,
            "decisionMethod": "UNANIMOUS"
          }
        ],
        "contents": [
          {
            "id": "content-uuid-1",
            "name": "change_category",
            "label": "Change Category",
            "isRequired": true
          }
        ],
        "createdAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}

---

Adding Items to a Change Order

Add components to the change order to indicate what will be modified:

mutation AddItems {
  changeOrders {
    addItems(
      changeOrderId: "123e4567-e89b-12d3-a456-426614174000"
      input: {
        items: [
          { id: "component-uuid-1", version: 3 }
          { id: "component-uuid-2", version: 1 }
        ]
      }
    ) {
      id
      itemId
      itemVersion
      proposedRevision
      proposedStatusId
    }
  }
}

Setting Proposed Changes

You can specify what the component will become after the change order is approved:

mutation UpdateProposals {
  changeOrders {
    updateProposalsForItems(
      changeOrderId: "123e4567-e89b-12d3-a456-426614174000"
      input: {
        items: [
          {
            itemId: "component-uuid-1"
            revision: "2.A"
            statusId: "released-status-uuid"
          }
        ]
      }
    ) {
      id
      itemId
      proposedRevision
      proposedStatusId
    }
  }
}

Removing Items

mutation RemoveItems {
  changeOrders {
    removeItems(
      changeOrderId: "123e4567-e89b-12d3-a456-426614174000"
      input: {
        itemIds: ["component-uuid-2"]
      }
    ) {
      id
      itemId
    }
  }
}

---

Setting Custom Field Values

If your template defines custom fields (like "Impact Assessment" or "Change Category"), set their values:

mutation SetContentValue {
  changeOrders {
    setContentValue(
      contentId: "content-uuid-1"
      input: {
        values: ["design"]
      }
    ) {
      id
      name
      label
      values
    }
  }
}

The contentId comes from the contents array in the change order response. Each content field has a unique ID.

---

Adding Reviewers to Stages

Assign users to review each approval stage:

mutation AddReviewers {
  changeOrders {
    addReviewersToStages(
      changeOrderId: "123e4567-e89b-12d3-a456-426614174000"
      input: {
        stages: [
          {
            stageId: "stage-uuid-1"
            userIds: ["user-uuid-1", "user-uuid-2"]
          }
          {
            stageId: "stage-uuid-2"
            userIds: ["user-uuid-3"]
          }
        ]
      }
    ) {
      id
      stages {
        id
        name
        reviewers {
          id
          user {
            firstName
            lastName
            email
          }
          decisionState
        }
      }
    }
  }
}

Removing Reviewers

mutation RemoveReviewers {
  changeOrders {
    removeReviewersFromStages(
      changeOrderId: "123e4567-e89b-12d3-a456-426614174000"
      input: {
        stages: [
          {
            stageId: "stage-uuid-1"
            userIds: ["user-uuid-2"]
          }
        ]
      }
    ) {
      id
      stages {
        id
        reviewers {
          id
        }
      }
    }
  }
}

---

Configuring Stage Decision Methods

Each stage can use different approval logic:

Method	Description
UNANIMOUS	All reviewers must approve
MAJORITY	More than 50% must approve
MINIMUM	At least N reviewers must approve

mutation UpdateDecisionMethods {
  changeOrders {
    updateDecisionMethodsForStages(
      changeOrderId: "123e4567-e89b-12d3-a456-426614174000"
      input: {
        stages: [
          {
            stageId: "stage-uuid-1"
            decisionMethod: MAJORITY
          }
          {
            stageId: "stage-uuid-2"
            decisionMethod: MINIMUM
            decisionMinimumCount: 2
          }
        ]
      }
    ) {
      id
      stages {
        id
        name
        decisionMethod
      }
    }
  }
}

---

Submitting for Review

When your change order is ready, submit it for review. This transitions the status from DRAFT to OPEN:

mutation SubmitForReview {
  changeOrders {
    submitForReview(id: "123e4567-e89b-12d3-a456-426614174000") {
      id
      status
      resolution
      currentStage {
        name
        decisionState
      }
    }
  }
}

Before Submitting: Ensure all required content fields are populated and at least one item is added. Use the canSubmit and cannotSubmitReasons fields to check readiness.

Check Submission Readiness

query CheckReadiness {
  changeOrders {
    get(filter: { ids: ["123e4567-e89b-12d3-a456-426614174000"] }) {
      connection {
        edges {
          node {
            id
            canSubmit
            cannotSubmitReasons
          }
        }
      }
    }
  }
}

---

Making Review Decisions

Reviewers approve or reject their assigned stages:

Approving

mutation ApproveStage {
  changeOrders {
    updateReviewDecision(
      stageId: "stage-uuid-1"
      input: {
        decisionState: APPROVED
        note: "Reviewed and approved. All specifications meet requirements."
      }
    ) {
      id
      decisionState
      note
      decidedAt
      user {
        firstName
        lastName
      }
    }
  }
}

Rejecting

mutation RejectStage {
  changeOrders {
    updateReviewDecision(
      stageId: "stage-uuid-1"
      input: {
        decisionState: REJECTED
        note: "Missing thermal analysis documentation. Please add before resubmission."
      }
    ) {
      id
      decisionState
      note
      decidedAt
    }
  }
}

When a stage meets its decision criteria (based on the decision method), the change order automatically progresses to the next stage or resolves.

---

Completing Change Orders

Closing an Approved Change Order

If approvalRouterOption is MANUAL_CLOSE, you need to explicitly close the change order:

mutation CloseChangeOrder {
  changeOrders {
    close(id: "123e4567-e89b-12d3-a456-426614174000") {
      id
      status
      resolution
    }
  }
}

Withdrawing a Change Order

The creator can withdraw a change order at any time:

mutation WithdrawChangeOrder {
  changeOrders {
    withdraw(id: "123e4567-e89b-12d3-a456-426614174000") {
      id
      status
      resolution
    }
  }
}

Resetting to Draft

Reset a change order back to DRAFT to make modifications and resubmit:

mutation ResetChangeOrder {
  changeOrders {
    reset(id: "123e4567-e89b-12d3-a456-426614174000") {
      id
      status
      resolution
    }
  }
}

When to Reset: Use reset after a rejection to modify the change order and resubmit, or after withdrawal if you want to revive the change order.

---

Complete Workflow Example

Here's a complete example showing the typical happy path:

const { GraphQLClient } = require('graphql-request');

const client = new GraphQLClient('https://api.durohub.com/graphql', {
  headers: {
    'x-api-key': process.env.DURO_API_KEY,
    'x-organization': '@acme-corp',
    'x-library': '@acme-corp/main-library',
  },
});

async function createAndSubmitChangeOrder() {
  // Step 1: Create the change order
  const createResult = await client.request(`
    mutation CreateCO($input: CreateChangeOrderInput!) {
      changeOrders {
        create(input: $input) {
          id
          stages { id name }
          contents { id name }
        }
      }
    }
  `, {
    input: {
      name: "ECO-2024-001: Motor Specification Update",
      description: "Update torque specs for Model X motor"
    }
  });

  const coId = createResult.changeOrders.create.id;
  const stageId = createResult.changeOrders.create.stages[0].id;
  console.log(`Created CO: ${coId}`);

  // Step 2: Add items (components)
  await client.request(`
    mutation AddItems($coId: ID!, $input: AddItemsInput!) {
      changeOrders {
        addItems(changeOrderId: $coId, input: $input) {
          id
        }
      }
    }
  `, {
    coId,
    input: {
      items: [{ id: "component-uuid", version: 1 }]
    }
  });
  console.log("Items added");

  // Step 3: Add reviewers
  await client.request(`
    mutation AddReviewers($coId: ID!, $input: AddReviewersToStagesInput!) {
      changeOrders {
        addReviewersToStages(changeOrderId: $coId, input: $input) {
          id
        }
      }
    }
  `, {
    coId,
    input: {
      stages: [{ stageId, userIds: ["reviewer-uuid"] }]
    }
  });
  console.log("Reviewers added");

  // Step 4: Submit for review
  const submitResult = await client.request(`
    mutation Submit($id: ID!) {
      changeOrders {
        submitForReview(id: $id) {
          status
          resolution
        }
      }
    }
  `, { id: coId });
  console.log(`Status: ${submitResult.changeOrders.submitForReview.status}`);

  // Step 5: Reviewer approves (would be done by the reviewer)
  await client.request(`
    mutation Approve($stageId: ID!, $input: UpdateReviewDecisionInput!) {
      changeOrders {
        updateReviewDecision(stageId: $stageId, input: $input) {
          decisionState
        }
      }
    }
  `, {
    stageId,
    input: {
      decisionState: "APPROVED",
      note: "Approved - specifications verified"
    }
  });
  console.log("Approved!");

  // Step 6: Close the change order
  const closeResult = await client.request(`
    mutation Close($id: ID!) {
      changeOrders {
        close(id: $id) {
          status
          resolution
        }
      }
    }
  `, { id: coId });
  console.log(`Final status: ${closeResult.changeOrders.close.status}`);
}

createAndSubmitChangeOrder().catch(console.error);

---

Handling Rejection

When a change order is rejected:

1. Review the rejection notes to understand what needs to change

2. Reset to DRAFT using the reset mutation

3. Make necessary modifications (update items, content, etc.)

4. Resubmit using submitForReview

# After rejection, reset and fix
mutation ResetAndFix {
  changeOrders {
    reset(id: "co-uuid") {
      status  # Returns to DRAFT
    }
  }
}

# Make your changes, then resubmit
mutation Resubmit {
  changeOrders {
    submitForReview(id: "co-uuid") {
      status
      resolution
    }
  }
}

---

Best Practices

Planning

• Use descriptive names: Include an identifier (e.g., "ECO-2024-001") and brief description

• Choose the right template: Select a template that matches your change type

• Complete all required fields: Fill out custom content fields before submission

Items and Scope

• Include all affected components: Add every component that will be modified

• Specify correct versions: Reference the specific version being changed

• Keep scope focused: One change order should address one logical change

Review Process

• Add appropriate reviewers: Ensure all required stakeholders are included

• Provide context in notes: When approving or rejecting, include detailed notes

• Check canSubmit before submitting: Avoid submission errors

Workflow Management

• Don't skip states: Follow the proper lifecycle transitions

• Close completed COs promptly: Move approved COs to CLOSED when changes are implemented

• Document rejection reasons: Provide actionable feedback when rejecting

---

Next Steps

• Change Order Workflows: Create custom templates with multi-stage approvals

• Change Order Workflow Reference: Complete YAML specification

• Change Order Validations: Implement validation rules

• Webhooks: Get notified when change orders are updated