Change Order Validations

Overview

Change Order Validations provide a comprehensive system for ensuring data integrity and enforcing business rules throughout your change management process. This powerful feature allows you to run both built-in system validations and custom validation rules that align with your organization's specific requirements.

Why Validations Matter

In complex engineering environments, a single oversight can lead to costly errors, production delays, or compliance issues. The validation system helps you:

• Prevent Errors Early: Catch issues before changes are approved and implemented

• Enforce Standards: Ensure all changes meet your organization's requirements

• Maintain Consistency: Apply the same rules across all change orders

• Provide Transparency: Give reviewers clear visibility into validation results

• Enable Custom Logic: Create organization-specific validation rules

Understanding Validation Types

The Duro platform provides two types of validations:

System Validations

Built-in validations that run automatically to ensure fundamental data integrity:

• Items must not exist in other OPEN change orders (prevents conflicts)

• DCO items must not have drifted from their last-released baseline

• Components must have a valid primary source

• Required fields must be populated

• Data types must match expected formats

• Cross-references must be valid

DCO baseline freeze

Change orders of type DCO are revision-frozen, so a built-in validation guards their items against drifting from the last-released baseline. For every item on a DCO, it compares the item's live status and revision to its last-released baseline and fails the change order when they no longer match. It fails when any of the following holds:

• the live status differs from the baseline status;

• the live revision differs from the baseline revision;

• the item has no releasable baseline (it was never released), or its live component can't be found.

This validation runs only for DCOs — change orders of any other type skip it. A DCO can only be created from a template that lists DCO in co_types, which requires template schema version: '1.1' or later — see Change Order Workflows → Choosing a Schema Version. Change orders from '1.0' templates are always ECO, so this validation never runs for them. Because it is checked both when the DCO is submitted and again when it closes, a DCO can't slip through if a concurrent change order releases one of its items in the meantime. A failure surfaces as DCO_STATUS_CHANGE_NOT_ALLOWED / DCO_REVISION_CHANGE_NOT_ALLOWED.

Primary source required

A built-in validation named Components must have a valid primary source. checks that the parts and assemblies being promoted by a change order can actually be bought. For every item the change order promotes out of DESIGN status, the item must have an active primary source — a designated primary manufacturer part with a distributor quote that carries a price. A quote priced at $0 counts as priced and is valid; a missing price is not.

Items whose target status is DESIGN are not checked, so early design work is never held up by sourcing data.

This validation is configured per library and has three modes:

Mode	Result state	Effect
off	—	The validation does not run and does not appear in the run's results
warning	WARNING	Surfaces on the change order but does not block it (onFailure is WARNING)
error	FAIL	Blocks the change order from proceeding (onFailure is ERROR)

A result therefore looks like any other system validation — read state, onFailure, and errorMessage from the run to see which items are missing a priced primary source:

{
  "node": {
    "name": "Components must have a valid primary source.",
    "validationType": "SYSTEM",
    "state": "WARNING",
    "onFailure": "WARNING",
    "errorMessage": "Components must have a valid primary source."
  }
}

Fails closed. Duro resolves sourcing through an internal service. If that service can't be reached, the validation does not silently pass — it reports:

Could not verify sourcing — vendor-sourcing is temporarily unavailable. Please try validating again.

Treat this as a transient condition and re-run changeOrders.validate(id) rather than as a sourcing data problem on the items.

System validations are not configured in the workflow template. The template's root validations array is reserved in every schema version and does not enable or disable anything today — see Workflow Reference → Validations Array. The template's schema version only affects which validations run indirectly, through the change order types it allows.

Custom Validations

JavaScript-based rules you create to enforce your specific business logic:

• Cost threshold checks

• Part number format validation

• Required approver verification

• Impact assessment requirements

• Custom field dependencies

Running Validations

Validations can be triggered manually at any time during the DRAFT state of the change order lifecycle. Here's how to run validations and interpret the results:

Basic Validation Query

mutation ValidateChangeOrder($changeOrderId: ID!) {
  changeOrders {
    validate(id: $changeOrderId) {
      id
      isValid  # Overall validation result

      validationRun {
        id
        state  # PASS or FAIL
        summary {
          passCount
          failCount
          warningCount
        }

        results(pagination: { first: 50 }) {
          edges {
            node {
              name
              state
              errorMessage
            }
          }
        }
      }
    }
  }
}

Example Response

{
  "data": {
    "changeOrders": {
      "validate": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "isValid": false,
        "validationRun": {
          "id": "987fcdeb-51a2-43d1-9876-543210fedcba",
          "state": "FAIL",
          "summary": {
            "passCount": 8,
            "failCount": 2,
            "warningCount": 1
          },
          "results": {
            "edges": [
              {
                "node": {
                  "name": "Items must not exist in other OPEN Change Orders",
                  "state": "FAIL",
                  "errorMessage": "Item P123-456 exists in Change Order CO-2024-001"
                }
              }
            ]
          }
        }
      }
    }
  }
}

Accessing Validation History

Every validation run is stored, allowing you to track how validation results change over time as issues are resolved.

Viewing Latest Validation Results

query GetLatestValidation($changeOrderId: ID!) {
  changeOrders {
    get(filter: { ids: [$changeOrderId] }) {
      connection {
        edges {
          node {
            id
            name
            isValid

            latestValidationRun {
              id
              state
              createdAt
              createdBy {
                name
              }

              summary {
                passCount
                failCount
                warningCount
              }

              # Get detailed results with logs
              results(pagination: { first: 100 }) {
                edges {
                  node {
                    name
                    validationType  # SYSTEM or CUSTOM
                    state          # PASS, FAIL, or WARNING
                    onFailure      # ERROR or WARNING
                    errorMessage

                    # Access validation logs for debugging
                    logs {
                      error {
                        message
                      }
                      info {
                        message
                      }
                      all {
                        message
                        type
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Viewing Historical Validation Runs

Track how validation results have changed over time:

query GetValidationHistory($changeOrderId: ID!) {
  changeOrders {
    get(filter: { ids: [$changeOrderId] }) {
      connection {
        edges {
          node {
            id

            # Get all historical validation runs
            validationRuns(pagination: { first: 10 }) {
              edges {
                node {
                  id
                  collectionId
                  state
                  createdAt
                  createdBy {
                    name
                  }

                  summary {
                    passCount
                    failCount
                    warningCount
                  }

                  # Can drill into specific failed validations
                  results(pagination: { first: 100 }) {
                    edges {
                      node {
                        name
                        state
                        errorMessage
                      }
                    }
                  }
                }
              }
              totalCount
            }
          }
        }
      }
    }
  }
}

Understanding Validation Results

Each validation result provides detailed information to help you understand and resolve issues:

Validation States

• PASS: The validation succeeded without issues

• FAIL: The validation failed and must be resolved

• WARNING: The validation found potential issues that should be reviewed

OnFailure Behavior

• ERROR: Blocks the change order from proceeding (hard stop)

• WARNING: Alerts reviewers but doesn't block progress (soft warning)

Validation Logs

Each validation generates detailed logs that help with debugging:

logs {
  # Informational messages about validation execution
  info {
    message
  }

  # Warnings about potential issues
  warn {
    message
  }

  # Error details when validation fails
  error {
    message
  }

  # All logs in chronological order
  all {
    message
    type  # "info", "warn", "error", or "log"
  }
}

Working with Custom Validations

Custom validations allow you to implement organization-specific business rules. When a custom validation runs, you can access both the validation result and the underlying rule definition:

query GetCustomValidationDetails($changeOrderId: ID!) {
  changeOrders {
    get(filter: { ids: [$changeOrderId] }) {
      connection {
        edges {
          node {
            latestValidationRun {
              results(pagination: { first: 50 }) {
                edges {
                  node {
                    name
                    validationType
                    state
                    errorMessage

                    # Only populated for CUSTOM validations
                    validationRule {
                      id
                      name
                      type
                      version
                      code  # The JavaScript validation code
                      library {
                        id
                        name
                      }
                    }

                    # Debug custom validation execution
                    logs {
                      all {
                        message
                        type
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Practical Examples

Example 1: Check Only Failed Validations

When debugging validation failures, focus on just the problems:

query GetFailedValidations($changeOrderId: ID!) {
  changeOrders {
    get(filter: { ids: [$changeOrderId] }) {
      connection {
        edges {
          node {
            id
            name
            isValid

            latestValidationRun {
              state
              summary {
                failCount
                warningCount
              }

              # Fetch all results, then filter client-side
              results(pagination: { first: 100 }) {
                edges {
                  node {
                    name
                    state
                    errorMessage
                    logs {
                      error {
                        message
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Then filter the results in your application code:

const failedValidations = data.changeOrders.get.connection.edges[0]
  .node.latestValidationRun.results.edges
  .filter(edge => edge.node.state === 'FAIL' || edge.node.state === 'WARNING');

Example 2: Monitor Validation Progress

Track validation improvements over multiple runs:

query CompareValidationRuns($changeOrderId: ID!) {
  changeOrders {
    get(filter: { ids: [$changeOrderId] }) {
      connection {
        edges {
          node {
            # Current state
            latestValidationRun {
              createdAt
              summary {
                passCount
                failCount
                warningCount
              }
            }

            # Historical comparison
            validationRuns(pagination: { first: 5 }) {
              edges {
                node {
                  createdAt
                  summary {
                    passCount
                    failCount
                    warningCount
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Example 3: Validation Integration Workflow

Here's a complete workflow for integrating validations into your change order process:

// 1. Create or update a change order
const changeOrderId = await createChangeOrder(changeOrderData);

// 2. Run validations
const validationResult = await runValidation(changeOrderId);

// 3. Check if valid
if (!validationResult.isValid) {
  // 4. Get detailed failure information
  const failures = validationResult.validationRun.results.edges
    .filter(edge => edge.node.state !== 'PASS')
    .map(edge => ({
      name: edge.node.name,
      error: edge.node.errorMessage,
      severity: edge.node.onFailure
    }));

  // 5. Display failures to user
  displayValidationErrors(failures);

  // 6. Allow user to fix issues
  await promptUserToResolveIssues(failures);

  // 7. Re-run validations after fixes
  const retryResult = await runValidation(changeOrderId);

  if (retryResult.isValid) {
    console.log('All validations passed!');
  }
}

// 8. Proceed with approval workflow only if valid
if (validationResult.isValid) {
  await submitForApproval(changeOrderId);
}

Best Practices

1. Run Validations Early and Often

Don't wait until the approval stage to run validations. Run them:

• After initial change order creation

• After any significant updates

• Before submitting for approval

• After resolving validation failures

2. Provide Clear Error Messages

When creating custom validations, ensure error messages are actionable:

• ✅ Good: "Part number ABC-123 must have an associated drawing document"

• ❌ Avoid: "Validation failed"

3. Use Warnings Appropriately

Reserve warnings for issues that should be reviewed but don't necessarily block progress:

• Missing optional documentation

• Unusual but acceptable values

• Recommendations for best practices

4. Monitor Validation Trends

Track validation patterns across change orders to identify:

• Common failure points in your process

• Training opportunities for users

• Potential system improvements

5. Leverage Validation Logs

Use the detailed logs to:

• Debug custom validation logic

• Understand validation execution flow

• Provide context to users about failures

Troubleshooting

Common Issues

Validation Runs But Shows No Results

Ensure you're requesting the results field with proper pagination:

validationRun {
  results(pagination: { first: 100 }) {  # Don't forget pagination
    edges {
      node {
        name
        state
      }
    }
  }
}

Custom Validation Not Running

Verify that:

• The validation rule is active in your library

• The validation rule code is syntactically correct

• The change order meets the criteria for the validation to run

Inconsistent Validation Results

Check for:

• Data changes between validation runs

• Updates to validation rules

• Different validation contexts (some validations may be conditional)

Next Steps

1. Review your organization's validation requirements

2. Implement custom validations for your specific needs

3. Integrate validation checks into your change order workflow

4. Monitor validation metrics to improve your process

For a complete guide to writing custom validation rules — including the payload structure, attribute access patterns, and practical examples — see Authoring Custom Validations.