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: Configure automatic notifications and resolution behaviors

• Customize Fields: Capture the specific information your team needs for decision-making

Getting Started

Each Duro library comes with two default workflow templates:

1. Default Template (default.yaml): A simple single-stage approval workflow

2. Double Template (double.yaml): A two-stage workflow with impact analysis fields

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

Basic Workflow Structure

Every workflow template follows this structure:

version: '1.0'
description: A clear description of this workflow's purpose
schema_type: change_order_scheme

details:
  info:
    groups:
      # Custom fields for change order creation

stages:
  open:
    # Review stages configuration
  resolved:
    # Actions when change order is resolved
  closed:
    # Final state configuration

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.

Example: Adding Change Classification

details:
  info:
    groups:
      - name: Change Classification
        icon: mdi-tag-multiple
        fields:
          - name: change_category
            type: enum
            label: Category
            description: Primary category of this change
            options:
              - label: Design Update
                value: design
              - label: Cost Reduction
                value: cost
              - label: Quality Improvement
                value: quality
            validations:
              required: true

Supported Field Types

• text: Single-line text input

• longtext: Multi-line text area

• number: Numeric values

• date: Date picker

• currency: Monetary values with currency formatting

• enum: Single selection from predefined options

• list: Multiple selections from predefined options

Configuring Approval Stages

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

Single-Stage Approval

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

Multi-Stage Approval

stages:
  open:
    - name: Technical Review
      types: ['Unanimous']
      default: Unanimous
      minReviewers: 2
      reviewers:
        users:
          - email: [email protected]
            isRequired: true

    - name: Management Approval
      types: ['Majority', 'Minimum']
      default: Majority
      minReviewers: 1
      reviewers:
        users:
          - email: [email protected]
            isRequired: true

Approval Types Explained

• Unanimous: All reviewers must approve

• Majority: More than 50% of reviewers must approve

• Minimum: At least the minimum number of reviewers must approve

Adding Validations

Field validations ensure data quality and completeness:

fields:
  - name: estimated_cost
    type: currency
    label: Estimated Cost
    validations:
      required: true
      min: 0
      max: 1000000

  - name: part_number
    type: text
    label: Affected Part Number
    validations:
      pattern: "^[A-Z]{3}-\\d{4}$"
      required: true

Automating Resolutions

Configure automatic actions when change orders are approved, rejected, or withdrawn:

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

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:

groups:
  - name: Impact Analysis
    icon: mdi-chart-line
    fields:
      - name: schedule_impact
      - name: cost_impact
      - name: quality_impact

4. Document Your Workflow

Always include a clear description:

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:

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

    - name: Executive Approval
      types: ['Minimum']
      default: Minimum
      minReviewers: 1
      reviewers:
        users:
          - email: [email protected]
            isRequiredToApprove: true

Pattern 2: Department-Specific Reviews

When different departments need to review changes:

stages:
  open:
    - name: Engineering Review
      reviewers:
        users:
          - email: [email protected]
          - email: [email protected]

    - name: Manufacturing Review
      reviewers:
        users:
          - email: [email protected]
          - email: [email protected]

    - name: Quality Review
      reviewers:
        users:
          - email: [email protected]
          - email: [email protected]

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 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:

version: '1.0'
description: Engineering Change Review Process
schema_type: change_order_scheme

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
            validations:
              required: true

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

stages:
  open:
    - name: Engineering Review
      types: ['Unanimous', 'Majority']
      default: Majority
      minReviewers: 2
      reviewers:
        users:
          - email: [email protected]
            isRequired: true

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

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

Step 2: Minify Your YAML

Apollo Studio requires the YAML to be provided as a single-line string. To convert your YAML:

1. Visit the YAML Minifier: Go to https://onlineyamltools.com/minify-yaml

2. Paste your YAML: Copy your YAML configuration and paste it into the left input box

3. Copy the minified output: The right side will show your minified YAML as a single line. Copy this entire string.

YAML Minifier showing conversion from formatted to minified YAML

Step 3: Open Apollo Studio

1. Navigate to Apollo Studio: Open https://api.durohub.com/graphql in your browser

2. Set up authentication:

   • Click on the "Headers" tab at the bottom of the Operation panel

   • Add your API key as an x-api-key header

   • The value should be your API key (without quotes)

Apollo Studio Headers tab showing x-api-key configuration

Step 4: Create Your Template

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

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

1. Set up variables: In the Variables panel, create your input object:

{
  "input": {
    "name": "My Engineering Review Process",
    "configYAML": "YOUR_MINIFIED_YAML_HERE"
  }
}

Replace YOUR_MINIFIED_YAML_HERE with the minified YAML string you copied from Step 2.

1. Execute the mutation: Click the "CreateTemplate" button to run the mutation

Apollo Studio showing the complete setup for creating a change order template

Step 5: Verify Your Template

A successful response will show:

{
  "data": {
    "changeOrders": {
      "createTemplate": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "My Engineering Review Process",
        "config": {
          "version": "1.0",
          "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 you receive a YAML parsing error:

• Ensure your YAML is valid before minifying (use a YAML validator)

• Check that the minified string is properly copied without line breaks

• Verify all quotes and special characters are properly escaped

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 your API key has the necessary permissions

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 email addresses and other references are valid

Next Steps

1. Review the Change Order Workflow Reference for complete specification details

2. Explore example templates in your library's configuration

3. Start with a default template and customize it for your needs

4. Test your workflow with a pilot group before full deployment