Change Order Workflow Reference

Overview

This document provides a complete reference for the Change Order Workflow Template YAML specification. The schema defines the structure and constraints for change order approval workflows in the Duro PLM system.

Schema Information

• Schema Version: 1.0

• Schema URL: https://phoenix-production.durohub.com/static/schemes/change-orders/schema.json

• Type: Object

JSON Schema Validation

The JSON Schema provides automated validation for your workflow templates. When editing YAML files, you can use this schema to:

• Validate your templates before deployment to catch errors early

• Get auto-completion in editors that support YAML Language Server

• Ensure compliance with all required fields and constraints

To use the schema in your YAML files, add this comment at the top:

# yaml-language-server: $schema=https://phoenix-production.durohub.com/static/schemes/change-orders/schema.json

Many editors (VS Code, IntelliJ, etc.) will then provide real-time validation and helpful suggestions as you write your workflow templates.

Root Level Properties

Property	Type	Required	Description
version	string	Yes	Schema version (e.g., "1.0")
description	string	Yes	Human-readable description (max 500 chars)
schema_type	string	Yes	Must be "change_order_scheme"
details	object	Yes	Custom field definitions
validations	array	No	Global validation rules
stages	object	Yes	Workflow stage configuration

Example Root Structure

version: "1.0"
description: "Engineering change order workflow with dual approval"
schema_type: "change_order_scheme"
details: { }
validations: [ ]
stages: { }

Details Object

The details object contains custom field definitions organized in groups.

Structure

details:
  info:
    groups:
      - name: string
        icon: string (optional)
        description: string (optional)
        fields: [ ]

Group Properties

Property	Type	Required	Description
name	string	Yes	Display name (max 100 chars)
icon	string	No	Material Design Icon (format: mdi-icon-name)
description	string	No	Group description (max 500 chars)
fields	array	Yes	Array of field definitions

Field Definitions

Each field in a group has the following properties:

Property	Type	Required	Description
type	string	Yes	Field type (see Field Types section)
name	string	No	Programmatic name (pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$)
label	string	Yes	Display label (max 100 chars)
description	string	No	Help text (max 500 chars)
placeholder	string	No	Placeholder text (max 200 chars)
required	boolean	No	Deprecated - use validations.required
validations	object	No	Field validation rules
default	string	No	Default value (for enum fields)
options	array	Conditional	Required for list/enum types
multiSelect	boolean	No	Enable multi-selection (list type only)

Field Types

Type	Description	Additional Properties
text	Single-line text input	-
longtext	Multi-line text area	-
number	Numeric input	validations.min, validations.max
date	Date picker	-
currency	Currency amount	validations.min, validations.max
enum	Single selection dropdown	options, default
list	Multiple selection	options, multiSelect

Field Validation Object

validations:
  required: boolean
  min: integer
  max: integer
  pattern: string (regex)

Property	Type	Applies To	Description
required	boolean	All types	Field is mandatory
min	integer	number, currency, text	Minimum value or length
max	integer	number, currency, text	Maximum value or length
pattern	string	text	Regex validation pattern

Options for List/Enum Fields

options:
  - label: string
    value: string
    description: string (optional)

Property	Type	Required	Description
label	string	Yes	Display text (max 100 chars)
value	string	Yes	Stored value (max 100 chars)
description	string	No	Option help text (max 500 chars)

Validations Array

Global validation rules (currently reserved for future use).

validations:
  - id: string
    severity: string

Property	Type	Required	Description
id	string	Yes	Validation ID (pattern: ^\d+\.\d+$)
severity	string	Yes	One of: error, warn, info

Stages Object

Defines the workflow stages and their behavior.

stages:
  open: [ ]      # Required: Active review stages
  resolved: { }  # Optional: Resolution configuration
  closed: { }    # Optional: Closed state configuration
  onHold: { }    # Optional: On-hold state configuration

Open Stages Array

Array of sequential review stages. Each stage has:

Property	Type	Required	Description
name	string	Yes	Stage name (max 100 chars)
types	array	Yes	Available approval types
default	string	Yes	Default approval type
minReviewers	integer	No	Minimum reviewers required
reviewers	object	No	Pre-assigned reviewers
notifyList	object	No	Notification recipients

Approval Types

Each stage must support one or more approval types:

Type	Description
Unanimous	All reviewers must approve
Majority	More than 50% must approve
Minimum	At least minReviewers must approve

Reviewers Object

reviewers:
  users:
    - id: string (UUID)      # Use id with user's UUID
      isRequired: boolean
      isRequiredToApprove: boolean
    # OR
    - email: string          # Use email with user's email address
      isRequired: boolean
      isRequiredToApprove: boolean

User Reviewer Properties

Property	Type	Required	Description
id	string	One of id or email	User UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
email	string	One of id or email	User email address
isRequired	boolean	No	Must participate in review
isRequiredToApprove	boolean	No	Must approve for completion

Note: Each reviewer must have either id (UUID) or email, but not both. Use id when you have the user's UUID, or email for easier configuration.

Stage Actions (resolved, closed, onHold)

resolved:
  actions: [string]
  notifyList: { }
  resolutions:
    onapproval: [string]
    onrejection: [string]
    onwithdrawal: [string]

Resolution Types

Value	Description
AUTO_CLOSE	Automatically transition to closed
MANUAL_CLOSE	Require manual closure

Notification List

notifyList:
  users:
    - id: string (UUID)    # Use id with user's UUID
    # OR
    - email: string        # Use email with user's email address
  emails:
    - string (email format) # Additional email addresses not tied to users

Note: For users in the notification list, use either id (UUID) or email, similar to reviewers.

Complete Example

version: "1.0"
description: "Medical device change control workflow"
schema_type: "change_order_scheme"

details:
  info:
    groups:
      - name: "Change Classification"
        icon: "mdi-medical-bag"
        fields:
          - name: "change_type"
            type: "enum"
            label: "Change Type"
            options:
              - label: "Design Change"
                value: "design"
                description: "Modifications to product design"
              - label: "Process Change"
                value: "process"
                description: "Manufacturing process updates"
            default: "design"
            validations:
              required: true
          
          - name: "risk_level"
            type: "list"
            label: "Risk Categories"
            multiSelect: true
            options:
              - label: "Patient Safety"
                value: "safety"
              - label: "Product Performance"
                value: "performance"
              - label: "Regulatory Compliance"
                value: "regulatory"

      - name: "Impact Assessment"
        icon: "mdi-chart-line"
        fields:
          - name: "validation_required"
            type: "enum"
            label: "Validation Required"
            options:
              - label: "Full Validation"
                value: "full"
              - label: "Partial Validation"
                value: "partial"
              - label: "No Validation"
                value: "none"
            validations:
              required: true

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

  resolved:
    resolutions:
      onapproval: ["AUTO_CLOSE"]
      onrejection: ["MANUAL_CLOSE"]
    notifyList:
      users:
        - email: "[email protected]"

  closed:
    notifyList:
      emails:
        - "[email protected]"

Validation Rules

The schema enforces these validation rules:

1. Required Fields: All fields marked as required must have values

2. Pattern Matching: Field names must match ^[a-zA-Z_][a-zA-Z0-9_]*$

3. Length Limits:

   • Descriptions: 500 characters

   • Labels/Names: 100 characters

   • Placeholders: 200 characters

4. Type Constraints:

   • List/Enum fields must have at least one option

   • Only list fields can use multiSelect

5. Stage Requirements:

   • At least one open stage is required

   • Each stage must have a name, types array, and default type

   • Default type must be in the types array

Best Practices

1. Use Semantic Names: Choose descriptive names for fields and stages

2. Provide Descriptions: Help users understand field purposes

3. Set Appropriate Validations: Use min/max for numeric fields

4. Configure Notifications: Ensure stakeholders are informed

5. Test Workflows: Validate all paths through your workflow

6. Version Control: Track changes to workflow templates

7. Document Decisions: Use the description field to explain workflow design choices