Workflow Schema Reference

The workflow schema is a YAML document stored in Azure Blob Storage. It defines the steps, fields, validation rules, and approval routing for a workflow instance. The schema is referenced by blob path when creating a workflow session.

Top-Level Structure

id: vendor-onboarding
title: Vendor Onboarding
description: Collect vendor information for approval and contract generation
workflowType: governance        # 'governance' | 'standard'
organizationName: Contoso Ltd   # Used in notification emails
requireOtp: false               # Require OTP before participant accesses steps

steps:
  - ...

validation:
  rules:
    - ...

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

workflowType

Steps

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

steps:
  - id: vendor-details
    title: Vendor Details
    description: Enter the vendor's basic information
    fields:
      - key: vendor_name
        label: Vendor Name
        type: text
        required: true
        maxLength: 200

      - key: vendor_email
        label: Vendor Email
        type: email
        required: true

      - key: invoice_total
        label: Invoice Total (USD)
        type: number
        required: true
        min: 0

      - key: payment_terms
        label: Payment Terms
        type: select
        required: true
        options:
          - label: Net 30
            value: net30
          - label: Net 60
            value: net60
          - label: Immediate
            value: immediate

      - key: supporting_document
        label: Upload Supporting Document
        type: attachment
        required: false
        accept: ".pdf,.docx"
        maxSizeMb: 10

Field Types

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 immutable audit record.

Electronic Evidence Appendix

A sealed workflow PDF can include an Electronic Evidence Appendix page, injected at seal time by the VaultWorkflow 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 immutable identifiers and timestamps recorded at seal time.

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 immutable audit archive in Azure Blob Storage. The archive uses a time-based immutability policy. Once written, audit blocks cannot be modified, overwritten, or deleted during the retention window.

Audit Event

When a workflow is sealed, VaultWorkflow 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: