Authoring Custom Validations
Custom validations are JavaScript functions that run during change order validation. They receive the full change order context — items, attributes, approval stages, custom fields — and return a pass/fail result with a message. You write the logic; Duro handles execution in a secure sandbox.
How It Works
When a change order is validated, Duro sends each custom validation rule to an isolated execution environment. Your code receives a data object containing the change order and its items, runs your logic, and returns a result. Duro waits up to 30 seconds for the result; a rule that takes longer is recorded as a FAIL with Failed to execute validation: timeout of 30000ms exceeded.
Every active custom rule in the library runs on every change order in that library.
The basic contract is simple: export a validate function that accepts the data payload and returns { valid, message }.
exports.validate = async function(data) {
// data.change_order — the change order metadata
// data.items — the components in the change order
// Your logic here...
return {
valid: true, // or false
message: 'Human-readable result'
};
};The Validation Payload
Your validation function receives a single data argument with two top-level properties:
data.change_order— the change order metadata, approval stages, custom fieldsdata.items— the components in the change order, with full attribute data
Change Order Fields
id
string
UUID of the change order
name
string
Change order name/title
description
string
Description text (can be null)
status
string
draft, open, resolved, or closed
resolution
string
pending, approved, rejected, or withdrawn
libraryId
string
UUID of the change order's library
isValid
boolean
The change order's current validation verdict
createdAt / updatedAt
string
Timestamps
createdBy
object
{ id, name, primaryEmail } of the creator
updatedBy
object
{ id, name, primaryEmail } of the last editor
contents
array
Custom form fields: id, name, label, type, values, listOptions, multipleSelect, isRequired, placeholder, description, groupName, order. Omitted when the change order has no custom fields
stages
array
Approval stages: id, name, order, decisionState, decisionMethod, decisionMinimumCount, minReviewers, reviewers, notifyList. Omitted when the change order has no stages
The payload does not include the change order's type (coType). Each contents entry also carries min, max and pattern keys, which are always empty because template field validations are not stored.
Item Fields
Each entry in data.items combines the change order item data with its component information:
id
string
Change order item UUID
itemId
string
Component UUID
itemVersion
number
Component version recorded on the change order item
name
string
Component name
eid
string
Component's external identifier
description
string
Component description
type
string
Category type, such as PART or ASSEMBLY
categoryId
string
Category UUID
category
object
{ id, name, attributes } — category info with attribute definitions
statusId
string
Status UUID
status
object
{ id, name, mapsTo, color } — the component's current status
version
number
Component version number
revisionValue
string
The component's current revision (e.g., "A", "B")
revisionType
string
The component's revision scheme
state
string
RELEASED or MODIFIED
releasedAt / createdAt / updatedAt
string
Timestamps
attributes
object
Human-readable attribute values keyed by name
attributeValues
object
Raw attribute values keyed by UUID (legacy)
status and revisionValue are the component's live values. The payload does not include the status or revision the change order proposes.
Component Attributes
Each item carries attribute data in two forms.
item.attributes — Human-readable, keyed by name. This is what you'll use most of the time.
All attributes assigned to the item's category appear in this map. Unset attributes are null — so you can distinguish "not set" from "attribute doesn't exist on this category."
item.category.attributes — Attribute definitions for the category. Useful when you need to know what attributes exist, their types, or iterate programmatically.
Each definition includes: id, name, type, source, sourceKey, unit.
item.attributeValues — Raw storage format with UUID keys. Kept for backward compatibility. You shouldn't need this unless you're working with attribute IDs directly.
Value Shapes
Attribute Type
Example item.attributes['Name']
STRING, URL, EMAIL, PHONE, DATE, BOOLEAN
"Acme Co" (unwrapped primitive)
NUMBER (simple)
42 (unwrapped number)
NUMBER (measured -- mass, length)
{ value: "25", unit: "g" }
NUMBER (currency)
{ value: 42.50, unit: "USD" }
LIST
"Each" (unwrapped string)
ITEM_LINK
"3f2a…" (the linked component's UUID)
Unset, or a value that could not be converted
null
Writing Your First Validation
Create a .js file that exports a validate function returning an object with valid (boolean) and message (string). The function may be async or synchronous; its result is awaited either way.
validis converted to a boolean, so any truthy value passes.Returning a bare
trueorfalseis accepted, with an empty message.Any other return value is recorded as a failure:
Validation returned unexpected type: <type>.An error thrown inside
validateis recorded as a failure:Exception: <error message>.
Example: Block Components Missing a Manufacturer
That's the whole file. No imports, no boilerplate, no class wiring. Duro loads it, calls exports.validate, and records the result.
Common Patterns
Checking Attribute Values
Checking Category-Specific Rules
Use item.category.name to apply rules only to certain component types:
Validating Approval Stages
The data.change_order.stages array gives you full visibility into the approval workflow:
Enforcing Naming Conventions
Working with Measured Values
Measured attributes (mass, length, etc.) return { value, unit } rather than a bare number. Parse accordingly:
Logging
All console methods are captured and visible in the validation results:
console.info()— informational messages about executionconsole.log()— general-purpose loggingconsole.warn()— warnings about potential issuesconsole.error()— error details
Use logging liberally. It costs nothing and makes debugging much easier when a validation fails unexpectedly.
Logs are accessible via the GraphQL API on each validation result's logs field — see Change Order Validations for the query structure.
Linking to Entities
Duro supports a markdown-inspired syntax for creating clickable links in validation messages and logs. When you reference a component or change order, wrap it in a link so users can click straight through to it in the Duro UI.
Syntax
Supported Link Types
Component
[text](item:component/id)
[CAP-001](item:component/abc-123)
Assembly
[text](item:assembly/id)
[Main Board](item:assembly/xyz-789)
Change Order
[text](co:changeorder/id)
[ECO-2024-001](co:changeorder/co-123)
PCBA
[text](item:pcba/id)
[Power Board](item:pcba/pcb-321)
User
[text](user:profile/id)
[Jane Smith](user:profile/user-456)
Helper Function
A small helper keeps link construction consistent:
Links degrade gracefully — if the UI can't parse them, users still see the display text.
Error vs Warning Mode
The onFailure setting controls what happens when your validation returns { valid: false }:
error
Blocks the change order from proceeding (hard stop)
warning
Alerts reviewers but does not block progress
This is a configuration setting, not something you control in JavaScript. Your code is identical either way — you return { valid: false, message } and the platform decides whether to block or warn based on the mode.
Execution Environment
The sandbox provides a global fetch(url, options) that makes HTTP requests to any URL. The response has ok, status, statusText, headers, and async json() and text() methods. Each request is logged as Fetch request to: <url>, and a failed request throws Fetch failed: <message>.
Your code cannot:
Read or write files
Import modules, including Node.js built-ins (
requireis not available)Access environment variables or
process
console, fetch and exports are predefined globals. Declaring any of them yourself at the top level (for example const fetch = …) fails to compile.
Managing Validations via the API
You can create, update, list, and test custom validation rules through the GraphQL API. Like every library-scoped call, send x-library naming your API key's library; create and list also accept an optional library argument.
Creating a Validation Rule
Variables:
name
string
Display name for the validation rule
description
string
What the rule checks
code
string
The JavaScript source code
type
string
"custom" (the default). A rule with any other type never runs
onFailure
string
"ERROR" (blocks) or "WARNING" (non-blocking)
isActive
boolean
Whether the rule runs during validation. Defaults to true
version
string
Semantic version for tracking changes. Defaults to "1.0.0"
Updating a Validation Rule
You can update any combination of name, code, description, onFailure, isActive, and version. Only type cannot be changed after creation.
Listing Validation Rules
Testing a Validation Rule
Run one rule against an existing change order without recording a validation run:
Deleting a Validation Rule
Source-Controlled Validations
For teams that want to manage validations in version control, Duro provides the library-validations-template — a public GitHub repository to copy for your library. It gives you:
A
validations.yamlfile defining each rule's name, description, version, active state, and failure modeA
validations/directory for your JavaScript filesA sync script that pushes your local definitions to the Duro API via the mutations above
A GitHub Actions workflow that syncs automatically on push to
main
Copy it into a new private repository in your own GitHub organization: clone it and push to an empty private repository rather than forking, because a fork of a public repository stays public and would publish your rules' code. Add your API key as a GitHub secret (DURO_LIBRARY_API_KEY) and make sure Actions are enabled for the repository; from then on, every push to main syncs your validation rules to your Duro library. The sync is additive — it creates new rules, updates changed ones, and deactivates rules removed from the config (it never deletes).
This approach lets you review validation changes in pull requests, track history in git, and deploy consistently across libraries. The repository also includes a CLAUDE.md file that enables AI-assisted validation authoring — describe what you want in natural language and Claude Code generates the JavaScript and YAML config.
Best Practices
Keep validations focused. One validation, one concern. A rule that checks manufacturer data and also enforces naming conventions should be two separate validations. Smaller validations are easier to debug, toggle, and explain to users.
Provide clear messages. Your message is the first thing a user sees when something fails. Tell them what's wrong and which components are affected — not just "validation failed."
Use component links. When referencing specific components in messages or logs, use the [name](item:component/id) syntax so users can click through to the problem.
Handle null and undefined gracefully. Attributes can be null (unset), items can have missing fields, and the stages array can be empty. Defensive checks prevent runtime errors that surface as cryptic failures.
Log diagnostic info. Drop console.info calls at the start of your validation to record how many items you're checking, which categories are present, and any thresholds you're using. When something goes wrong, the logs tell the story.
Return a message on success too. A passing message like "All 12 components have a manufacturer" gives users confidence that the check actually ran and inspected their data.
Last updated
Was this helpful?