Workflow Schema Reference

The workflow schema is a YAML document that defines the steps, fields, validation rules, and approval routing for a workflow instance.

Top-Level Structure

workflow:
  templateVersion: "1.0"
  title: Vendor Onboarding
  workflowType: governance        # 'governance' | 'standard', default 'standard'
  autoValidateOnCreate: true      # governance workflows only
  layout:                         # optional
    mode: tabs
    pdfColumns: 3
  steps:
    - ...

validation:
  rules:
    - ...

approval:
  routing:
    mode: first-match
    routes:
      - ...
    fallback:
      approver:
        email: approvals@contoso.com

steps lives under the top-level workflow: key, alongside title and workflowType. validation and approval are siblings of workflow, not nested inside it. organizationName and requireOtp are not schema keys - they are set per request, in templateSettings.workflow.organizationName and templateSettings.workflow.requireOtp on the POST /api/workflow call, not authored into the YAML.

workflowType

Steps

Each step collects a set of fields from the participant, grouped into sections. Steps are presented sequentially; the participant must submit each step before advancing.

steps:
  - id: vendor-details
    title: Vendor Details
    sections:
      - title: Basic Information
        blocks:
          - type: paragraph
            text: Enter the vendor's basic information.

          - type: input
            inputType: text
            fieldKey: vendor_name
            label: Vendor Name
            validation:
              required: true
              maxLength: 200

          - type: input
            inputType: email
            fieldKey: vendor_email
            label: Vendor Email
            validation:
              required: true

          - type: input
            inputType: number
            fieldKey: invoice_total
            label: Invoice Total (USD)
            validation:
              required: true
              min: 0

          - type: input
            inputType: select
            fieldKey: payment_terms
            label: Payment Terms
            validation:
              required: true
            options:
              - label: Net 30
                value: net30
              - label: Net 60
                value: net60
              - label: Immediate
                value: immediate

          - type: attachment
            fieldKey: supporting_document
            label: Upload Supporting Document

A flatter, legacy fields: [...] array (each entry the same shape as an input block's own properties, without the sections/blocks nesting) is also accepted at the step level and merged with any sections[].blocks[] present. New schemas should use sections[].blocks[].

Block Types

There is no multiselect block type or inputType value.

Validation Rules

Validation rules evaluate collected field data using boolean expressions. They run when the participant advances past the final step (or at session creation for governance type workflows).

validation:
  rules:
    - id: po_amount_match
      description: PO amount must cover invoice total
      condition: "invoice_total <= po_amount"
      severity: error
      message: "Invoice total exceeds the approved PO amount."
      fieldKey: invoice_total

    - id: gr_quantity_check
      description: Goods receipt quantity check
      condition: "gr_quantity >= invoice_quantity"
      severity: warning
      message: "Goods receipt quantity is less than invoiced quantity. Approver review recommended."
      fieldKey: gr_quantity

    - id: tolerance_check
      description: Invoice vs PO within 5% tolerance
      type: numericTolerance
      condition: "invoice_total <= po_amount * 1.05"
      severity: error
      message: "Invoice exceeds PO amount by more than 5% tolerance."
      left:  { path: "invoice_total", label: "Invoice Total" }
      right: { path: "po_amount",     label: "PO Amount" }
      tolerance:
        percent: 5
      expandableDetails: true
      fieldKey: invoice_total

Validation Rule Properties

Approval Routing

The approval.routing block determines which approver(s) receive the submission once validation passes.

approval:
  routing:
    mode: sequential          # 'first-match' | 'sequential' | 'parallel'
    routes:
      - id: finance-lead
        condition: "invoice_total > 50000"
        priority: 1
        description: High-value - Finance Lead approval required
        approver:
          email: finance-lead@contoso.com
          role: Finance Lead
          escalateAfterDays: 3

      - id: dept-manager
        priority: 2
        description: Standard - Department Manager
        approver:
          email: dept-manager@contoso.com
          role: Department Manager
          escalateAfterDays: 5

    fallback:
      approver:
        email: approvals@contoso.com
        role: Default Approver

Routing Modes

Route Properties

Governance Validation Page

Governance workflows (workflowType: governance) automatically inject a Governance Validation page into the sealed PDF. This page is not present for standard data-collection workflows.

The page is generated at seal time and contains four elements.

Workflow Outcome

A banner at the top of the page states the final outcome of the workflow.

Governance Validation Summary

A summary banner below the outcome shows the overall validation status and rule counts in the format: X failed · Y warning · Z passed (N total).

The status label reflects the most severe outcome.

Validation Rule Breakdown

A table listing every validation rule defined in the schema, with its result.

All rules are listed regardless of outcome, providing a complete audit record of what was evaluated.

Exception Review

When the outcome is Approved with Exception, an Exception Review section is appended below the rule breakdown. This section captures the approver's justification text, the approver role, and the timestamp of the override decision. The justification is sealed into the PDF and included in the append-only, hash-chained audit record.

Electronic Evidence Appendix

A sealed workflow PDF can include an Electronic Evidence Appendix page, injected at seal time by the REFRACT Workflow system. It is available for both standard (data-collection) and governance workflows.

{
  "templateSettings": {
    "workflow": {
      "enabled": true,
      "appendElectronicEvidence": true
    }
  }
}

What the Appendix Contains

The appendix is structured in four sections.

Evidence Details

A table of identifiers and timestamps recorded at seal time. Any change to a sealed PDF breaks its hash chain.

Participant Data

Primary participant identity information is captured within the sealed workflow content. The appendix references that content rather than duplicating it, to prevent the appendix page from exposing PII in plaintext.

Captured Attestations

Any checkbox fields collected during the workflow are reproduced in this section, showing the label and confirmed state. This provides a tamper-evident record of what the participant agreed to.

Audit and Integrity Statement

Three subsections generated by the system.

• Governance Statement. Confirms that all submitted responses were captured and sealed at the time of approval, and that the workflow was processed in accordance with the configured governance settings for the tenant.
• Immutability and Integrity. States that the document hash recorded in the audit store covers the full document, including the appendix. Any modification to the document invalidates the hash and breaks the chain of custody.
• Evidence Storage. Confirms that a WORKFLOW_SEALED audit event has been persisted to the tenant-controlled audit archive in Azure Blob Storage. The archive is deployed with a time-based immutability (WORM) policy. Where that policy has been locked for the account, audit blocks cannot be modified, overwritten, or deleted during the retention window; the policy ships unlocked by default and locking it is a separate deployment action.

Audit Event

When a workflow is sealed, REFRACT Workflow emits a WORKFLOW_SEALED event to the tenant audit archive. The event payload includes the Workflow ID, Correlation ID, Tenant ID, seal timestamp, and a reference to the sealed PDF blob. Events are append-only and subject to the tenant's configured retention policy.

Condition Expressions

Conditions in validation rules and routing routes are simple boolean expressions evaluated against the merged workflow data (all fields collected across all steps). Supported operators: