ApprovalML YAML Syntax Reference

This page provides a detailed reference for the ApprovalML YAML syntax, designed for AI-powered workflow generation.

Overview

ApprovalML is a YAML-based language for defining business approval workflows. It combines form creation with powerful routing logic.

Core Structure

Every ApprovalML file follows this basic structure:

name: "Workflow Name"
description: "A brief summary of the workflow's purpose."
version: "1.0"  # Optional version number
type: "workflow_type"  # Optional classification

# Optional: Define who can submit this workflow
submission_criteria:
  company_roles: []  # Array of roles that can initiate the workflow
  org_hierarchy:
    include_paths: ["1.1.*"]  # Organizational path patterns for eligibility

# Form definition for data collection
form:
  fields: []

# Workflow logic with interconnected steps
workflow:
  step_name: {}

# Optional: Advanced settings for the workflow
settings:
  timeout: {}
  escalation: []
  notifications: {}
  compliance: {}

Form Fields

Define the data to be collected from the user.

Basic Field Types

text: Single-line text input.
textarea: Multi-line text area.
email: Validated email input.
number: Numeric input with validation.
currency: Monetary value with currency formatting.
date: Date picker.
select: Dropdown menu with predefined choices.
multiselect: Dropdown for multiple selections.
checkbox: A single boolean checkbox.
radio: A group of options where only one can be selected.
file_upload: For attaching files.

Field Properties

- name: "field_name"          # Required: A unique identifier for the field.
  type: "field_type"          # Required: One of the types listed above.
  label: "Display Label"      # Required: The text shown to the user.
  required: true/false        # Required: Specifies if the field must be filled.
  placeholder: "Hint text"    # Optional: Placeholder text for the input.
  accept: ".pdf,.jpg,.png"    # For `file_upload`: specifies accepted file types.
  multiple: true/false        # For `file_upload` or `multiselect`: allows multiple values.
  style: "warning"            # Optional: Visual emphasis style (see below).

  # Validation rules for the field
  validation:
    min: 0.01                # Minimum value for `number` or `currency`.
    max: 10000              # Maximum value for `number` or `currency`.

  # Options for `select`, `multiselect`, or `radio`
  options:
    - value: "option_key"
      label: "Display Text"

  # Optional currency code for `currency` fields
  currency: "USD"              # Specifies the ISO currency code (e.g., USD, EUR, JPY).

Field Style Property

Use the style property to visually emphasize important fields during approval:

Style	Appearance	Use Case
`warning`	Amber/Yellow background	Changes requiring attention, diff results
`danger`	Red background	Critical items, deletions, errors
`success`	Green background	Positive outcomes, confirmations
`info`	Blue background	Informational, read-only context

- name: "change_summary"
  type: "textarea"
  label: "Change Summary"
  style: "warning"           # Renders with amber background to draw attention
  required: false

Example: Currency Field

- name: "total_amount"
  type: "currency"
  label: "Total Amount"
  required: true
  currency: "USD"              # Defaults to the company's primary currency if not set.
  validation:
    min: 0.01
    max: 50000

Advanced Field Properties

These properties control the presentation and behavior of certain field types.

Button-style Choices

For radio fields, you can render the options as a button group instead of traditional radio inputs by using the display_as property.

- name: "equipment_check"
  type: "radio"
  label: "Is all equipment accounted for?"
  required: true
  display_as: "buttons"  # Renders choices as buttons
  options:
    - { value: "yes", label: "Yes" }
    - { value: "no", label: "No" }
    - { value: "na", label: "N/A" }

Camera-Only File Upload

For file_upload fields, you can force the use of the device camera for capturing images directly.

capture: Set to "environment" to prefer the rear-facing camera or "user" for the front-facing camera.
multiple: Set to true to allow multiple captures, or false (default) for a single image.

- name: "site_photo"
  type: "file_upload"
  label: "Take a photo of the work site"
  required: true
  accept: "image/*"
  multiple: false
  capture: "environment" # Opens the rear camera directly

Advanced Field Type: Line Items

For creating repeatable sections of fields, like items in an invoice.

- name: "items_to_purchase"
  type: "line_items"
  label: "Items to Purchase"
  min_items: 1
  max_items: 20

  item_fields:
    - name: "item_description"
      type: "text"
      label: "Description"
      required: true
    - name: "quantity"
      type: "number"
      label: "Qty"
      validation:
        min_value: 1
    - name: "unit_price"
      type: "currency"
      label: "Unit Price"
    - name: "total"
      type: "currency"
      label: "Total"
      readonly: true
      calculated: true
      formula: "quantity * unit_price" # Automatically calculates the value

Workflow Steps

Define the logic and routing of the approval process.

1. Decision Step (`decision`)

A standard approval step requiring a user to take action. It can have multiple outcomes.

Example: Simple Approve/Reject

manager_approval:
  name: "Manager Approval"
  type: "decision"
  approver: "${requestor.manager}"  # Dynamically assigns to the requestor's manager
  on_approve:
    continue_to: "FinanceReview"
  on_reject:
    end_workflow: true

Example: Multi-Outcome Decision

Define custom outcomes using on_<action> keys.

triage_step:
  name: "Triage Support Ticket"
  type: "decision"
  approver: "support_lead"
  on_technical:
    text: "Assign to Technical Team"
    continue_to: "TechnicalReview"
  on_billing:
    text: "Assign to Billing"
    continue_to: "BillingReview"
  on_close:
    text: "Close as Duplicate"
    style: "destructive" # Optional UI hint for the action button
    end_workflow: true

2. Parallel Approval (`parallel_approval`)

Allows multiple approvers to act simultaneously.

parallel_step:
  name: "Parallel Step"
  type: "parallel_approval"
  description: "Requires input from multiple stakeholders."
  approvers:
    - role: "purchasing_officer_1"
    - role: "purchasing_officer_2"
    - role: "purchasing_officer_3"
  approval_strategy: "any_one"  # Can be `any_one`, `all`, or `majority`
  on_approve:
    continue_to: "next_step"
  on_reject:
    end_workflow: true

3. Conditional Split (`conditional_split`)

Routes the workflow dynamically based on form data.

routing_step:
  name: "Routing Step"
  type: "conditional_split"
  description: "Routes based on the request amount."
  choices:
    - conditions: "amount > 10000 and urgency == 'critical'"
      continue_to: "ceo_approval"
    - conditions: "department == 'engineering'"
      continue_to: "tech_approval"
  default:
    continue_to: "auto_approve"

4. Automatic Step (`automatic`)

Performs system actions without human intervention. Supports two main operations:

Data Source Fetch (Read)

Fetch data from a configured data source and optionally compare against a baseline resource.

fetch_data:
  type: "automatic"
  name: "Fetch Current Data"
  data_source:
    source_id: "src_xxx"              # Data source unique ID (connector is implicit)
    save_to: "fetched_data"           # Save fetched data to this form field
    compare_to_resource: "baseline"   # Optional: compare with resource baseline
    save_diff_to: "diff_result"       # Optional: save diff result to this field
  on_complete:
    continue_to: "check_changes"

Data Source Properties:

source_id: Unique ID of the data source (required)
save_to: Form field name to store fetched data (required)
compare_to_resource: Resource name to compare against (uses deepdiff)
save_diff_to: Form field for diff result ("None" if no changes)

Diff Result Format: The diff result includes markdown-style emphasis for visual highlighting in the approval UI:

⚠️ **3 change(s) detected**

**➕ ADDITIONS:**
  • Detected addition at **bindings → item #1 → members**:
    Added: **"user:newuser@example.com"**

**➖ REMOVALS:**
  • Detected removal at **bindings → item #5 → members**:
    Removed: **"user:olduser@example.com"**

Text Emphasis Support:

Text and textarea fields support **bold** markdown markers
Bold text renders with red color and yellow highlight
Fields with emphasis get an amber background for attention

Resource Update (Write)

Update a resource with data from a form field.

update_resource:
  type: "automatic"
  name: "Update Baseline Resource"
  resource:
    data_from: "fetched_data"         # Get data from this form field
    resource_name: "baseline"          # Update this resource
  on_complete:
    continue_to: "complete"

Resource Properties:

data_from: Form field containing the data to save (required)
resource_name: Name of the resource to update (required)

Test Mode Behavior:

data_source (read): Executes normally
resource (write): Logs the action but does NOT modify the resource

Complete Example: Data Change Detection Workflow

name: "Data Compliance Monitor"
type: "compliance"

triggers:
  - type: cron
    schedule: "*/15 * * * *"

form:
  fields:
    - name: data_json
      type: textarea
      label: Current Data
    - name: diff_result
      type: textarea
      label: Change Summary

workflow:
  fetch_data:
    type: automatic
    name: Fetch Current Data
    data_source:
      source_id: src_xxx
      save_to: data_json
      compare_to_resource: data-baseline
      save_diff_to: diff_result
    on_complete:
      continue_to: check_changes

  check_changes:
    type: conditional_split
    choices:
      - conditions: diff_result != 'None'
        continue_to: review
    default:
      continue_to: no_changes_end

  review:
    type: decision
    name: Review Changes
    approver: admin
    on_approve:
      continue_to: update_baseline
    on_reject:
      continue_to: rejected_end

  update_baseline:
    type: automatic
    name: Update Baseline
    resource:
      data_from: data_json
      resource_name: data-baseline
    on_complete:
      continue_to: approved_end

  approved_end:
    type: end
    notify_requestor: Changes approved and baseline updated.

  rejected_end:
    type: end
    notify_requestor: Changes rejected.

  no_changes_end:
    type: end

5. Notification Only (`notification_only`)

Sends a non-blocking notification to a user.

notify_step:
  name: "Notify Supervisor"
  type: "notification_only"
  description: "Informs the supervisor about the request."
  approver: "${requestor.supervisor}"
  on_complete:
    continue_to: "next_step"

Approval Types

Define the nature of an approval required from a user.

needs_to_approve (Default): Can approve, reject, or request more information.
needs_to_sign: Requires a digital signature.
needs_to_recommend: Provides an advisory opinion but cannot block the workflow.
needs_to_acknowledge: Requires the user to simply acknowledge receipt.
needs_to_call_action: Triggers a system or manual action.
receives_a_copy: Receives a notification with no action required.

Conditional Expression Syntax

Used in conditional_split steps to control workflow routing.

Operators

Comparison: >, <, >=, <=, ==, !=
Logical: and, or, not
Membership: in, not in

Examples

# Numeric comparison
conditions: "amount > 1000"

# String equality
conditions: "department == 'engineering'"

# List membership
conditions: "category in ['equipment', 'software']"

# Complex expression
conditions: "(urgency == 'high' or priority >= 4) and amount > 10000"

Dynamic Role References

Reference users based on their position in the organizational hierarchy.

${requestor.manager}: The direct manager of the user who submitted the request.
${requestor.supervisor}: The supervisor of the requestor.
${requestor.department_head}: The head of the requestor's department.

Settings

Configure advanced behavior for the workflow.

settings:
  # Step-specific timeouts
  timeout:
    manager_approval: "72_hours"
    ceo_approval: "5_business_days"

  # Escalation rules for timeouts
  escalation:
    - after_timeout: "notify_next_level"
    - final_escalation: "ceo"

  # Notification preferences
  notifications:
    send_reminders: true
    reminder_intervals: ["24_hours", "2_hours"]

  # Compliance requirements
  compliance:
    receipt_required: true
    policy_check: true

ApprovalML YAML Syntax Reference

This page provides a detailed reference for the ApprovalML YAML syntax, designed for AI-powered workflow generation.

Overview

ApprovalML is a YAML-based language for defining business approval workflows. It combines form creation with powerful routing logic.

Core Structure

Every ApprovalML file follows this basic structure:

name: "Workflow Name"
description: "A brief summary of the workflow's purpose."
version: "1.0"  # Optional version number
type: "workflow_type"  # Optional classification

# Optional: Define who can submit this workflow
submission_criteria:
  company_roles: []  # Array of roles that can initiate the workflow
  org_hierarchy:
    include_paths: ["1.1.*"]  # Organizational path patterns for eligibility

# Form definition for data collection
form:
  fields: []

# Workflow logic with interconnected steps
workflow:
  step_name: {}

# Optional: Advanced settings for the workflow
settings:
  timeout: {}
  escalation: []
  notifications: {}
  compliance: {}

Form Fields

Define the data to be collected from the user.

Basic Field Types

text: Single-line text input.
textarea: Multi-line text area.
email: Validated email input.
number: Numeric input with validation.
currency: Monetary value with currency formatting.
date: Date picker.
select: Dropdown menu with predefined choices.
multiselect: Dropdown for multiple selections.
checkbox: A single boolean checkbox.
radio: A group of options where only one can be selected.
file_upload: For attaching files.

Field Properties

- name: "field_name"          # Required: A unique identifier for the field.
  type: "field_type"          # Required: One of the types listed above.
  label: "Display Label"      # Required: The text shown to the user.
  required: true/false        # Required: Specifies if the field must be filled.
  placeholder: "Hint text"    # Optional: Placeholder text for the input.
  accept: ".pdf,.jpg,.png"    # For `file_upload`: specifies accepted file types.
  multiple: true/false        # For `file_upload` or `multiselect`: allows multiple values.
  style: "warning"            # Optional: Visual emphasis style (see below).

  # Validation rules for the field
  validation:
    min: 0.01                # Minimum value for `number` or `currency`.
    max: 10000              # Maximum value for `number` or `currency`.

  # Options for `select`, `multiselect`, or `radio`
  options:
    - value: "option_key"
      label: "Display Text"

  # Optional currency code for `currency` fields
  currency: "USD"              # Specifies the ISO currency code (e.g., USD, EUR, JPY).

Field Style Property

Use the style property to visually emphasize important fields during approval:

Style	Appearance	Use Case
`warning`	Amber/Yellow background	Changes requiring attention, diff results
`danger`	Red background	Critical items, deletions, errors
`success`	Green background	Positive outcomes, confirmations
`info`	Blue background	Informational, read-only context

- name: "change_summary"
  type: "textarea"
  label: "Change Summary"
  style: "warning"           # Renders with amber background to draw attention
  required: false

Example: Currency Field

- name: "total_amount"
  type: "currency"
  label: "Total Amount"
  required: true
  currency: "USD"              # Defaults to the company's primary currency if not set.
  validation:
    min: 0.01
    max: 50000

Advanced Field Properties

These properties control the presentation and behavior of certain field types.

Button-style Choices

For radio fields, you can render the options as a button group instead of traditional radio inputs by using the display_as property.

- name: "equipment_check"
  type: "radio"
  label: "Is all equipment accounted for?"
  required: true
  display_as: "buttons"  # Renders choices as buttons
  options:
    - { value: "yes", label: "Yes" }
    - { value: "no", label: "No" }
    - { value: "na", label: "N/A" }

Camera-Only File Upload

For file_upload fields, you can force the use of the device camera for capturing images directly.

capture: Set to "environment" to prefer the rear-facing camera or "user" for the front-facing camera.
multiple: Set to true to allow multiple captures, or false (default) for a single image.

- name: "site_photo"
  type: "file_upload"
  label: "Take a photo of the work site"
  required: true
  accept: "image/*"
  multiple: false
  capture: "environment" # Opens the rear camera directly

Advanced Field Type: Line Items

For creating repeatable sections of fields, like items in an invoice.

- name: "items_to_purchase"
  type: "line_items"
  label: "Items to Purchase"
  min_items: 1
  max_items: 20

  item_fields:
    - name: "item_description"
      type: "text"
      label: "Description"
      required: true
    - name: "quantity"
      type: "number"
      label: "Qty"
      validation:
        min_value: 1
    - name: "unit_price"
      type: "currency"
      label: "Unit Price"
    - name: "total"
      type: "currency"
      label: "Total"
      readonly: true
      calculated: true
      formula: "quantity * unit_price" # Automatically calculates the value

manager_approval:
  name: "Manager Approval"
  type: "decision"
  approver: "${requestor.manager}"  # Dynamically assigns to the requestor's manager
  on_approve:
    continue_to: "FinanceReview"
  on_reject:
    end_workflow: true

Example: Multi-Outcome Decision

Define custom outcomes using on_<action> keys.

triage_step:
  name: "Triage Support Ticket"
  type: "decision"
  approver: "support_lead"
  on_technical:
    text: "Assign to Technical Team"
    continue_to: "TechnicalReview"
  on_billing:
    text: "Assign to Billing"
    continue_to: "BillingReview"
  on_close:
    text: "Close as Duplicate"
    style: "destructive" # Optional UI hint for the action button
    end_workflow: true

2. Parallel Approval (`parallel_approval`)

Allows multiple approvers to act simultaneously.

parallel_step:
  name: "Parallel Step"
  type: "parallel_approval"
  description: "Requires input from multiple stakeholders."
  approvers:
    - role: "purchasing_officer_1"
    - role: "purchasing_officer_2"
    - role: "purchasing_officer_3"
  approval_strategy: "any_one"  # Can be `any_one`, `all`, or `majority`
  on_approve:
    continue_to: "next_step"
  on_reject:
    end_workflow: true

3. Conditional Split (`conditional_split`)

Routes the workflow dynamically based on form data.

routing_step:
  name: "Routing Step"
  type: "conditional_split"
  description: "Routes based on the request amount."
  choices:
    - conditions: "amount > 10000 and urgency == 'critical'"
      continue_to: "ceo_approval"
    - conditions: "department == 'engineering'"
      continue_to: "tech_approval"
  default:
    continue_to: "auto_approve"

4. Automatic Step (`automatic`)

Performs system actions without human intervention. Supports two main operations:

Data Source Fetch (Read)

Fetch data from a configured data source and optionally compare against a baseline resource.

fetch_data:
  type: "automatic"
  name: "Fetch Current Data"
  data_source:
    source_id: "src_xxx"              # Data source unique ID (connector is implicit)
    save_to: "fetched_data"           # Save fetched data to this form field
    compare_to_resource: "baseline"   # Optional: compare with resource baseline
    save_diff_to: "diff_result"       # Optional: save diff result to this field
  on_complete:
    continue_to: "check_changes"

Data Source Properties:

source_id: Unique ID of the data source (required)
save_to: Form field name to store fetched data (required)
compare_to_resource: Resource name to compare against (uses deepdiff)
save_diff_to: Form field for diff result ("None" if no changes)

Diff Result Format: The diff result includes markdown-style emphasis for visual highlighting in the approval UI:

⚠️ **3 change(s) detected**

**➕ ADDITIONS:**
  • Detected addition at **bindings → item #1 → members**:
    Added: **"user:newuser@example.com"**

**➖ REMOVALS:**
  • Detected removal at **bindings → item #5 → members**:
    Removed: **"user:olduser@example.com"**

Text Emphasis Support:

Text and textarea fields support **bold** markdown markers
Bold text renders with red color and yellow highlight
Fields with emphasis get an amber background for attention

Resource Update (Write)

Update a resource with data from a form field.

update_resource:
  type: "automatic"
  name: "Update Baseline Resource"
  resource:
    data_from: "fetched_data"         # Get data from this form field
    resource_name: "baseline"          # Update this resource
  on_complete:
    continue_to: "complete"

Resource Properties:

data_from: Form field containing the data to save (required)
resource_name: Name of the resource to update (required)

Test Mode Behavior:

data_source (read): Executes normally
resource (write): Logs the action but does NOT modify the resource

Complete Example: Data Change Detection Workflow

name: "Data Compliance Monitor"
type: "compliance"

triggers:
  - type: cron
    schedule: "*/15 * * * *"

form:
  fields:
    - name: data_json
      type: textarea
      label: Current Data
    - name: diff_result
      type: textarea
      label: Change Summary

workflow:
  fetch_data:
    type: automatic
    name: Fetch Current Data
    data_source:
      source_id: src_xxx
      save_to: data_json
      compare_to_resource: data-baseline
      save_diff_to: diff_result
    on_complete:
      continue_to: check_changes

  check_changes:
    type: conditional_split
    choices:
      - conditions: diff_result != 'None'
        continue_to: review
    default:
      continue_to: no_changes_end

  review:
    type: decision
    name: Review Changes
    approver: admin
    on_approve:
      continue_to: update_baseline
    on_reject:
      continue_to: rejected_end

  update_baseline:
    type: automatic
    name: Update Baseline
    resource:
      data_from: data_json
      resource_name: data-baseline
    on_complete:
      continue_to: approved_end

  approved_end:
    type: end
    notify_requestor: Changes approved and baseline updated.

  rejected_end:
    type: end
    notify_requestor: Changes rejected.

  no_changes_end:
    type: end

5. Notification Only (`notification_only`)

Sends a non-blocking notification to a user.

notify_step:
  name: "Notify Supervisor"
  type: "notification_only"
  description: "Informs the supervisor about the request."
  approver: "${requestor.supervisor}"
  on_complete:
    continue_to: "next_step"

Approval Types

Define the nature of an approval required from a user.

needs_to_approve (Default): Can approve, reject, or request more information.
needs_to_sign: Requires a digital signature.
needs_to_recommend: Provides an advisory opinion but cannot block the workflow.
needs_to_acknowledge: Requires the user to simply acknowledge receipt.
needs_to_call_action: Triggers a system or manual action.
receives_a_copy: Receives a notification with no action required.

Conditional Expression Syntax

Used in conditional_split steps to control workflow routing.

Operators

Comparison: >, <, >=, <=, ==, !=
Logical: and, or, not
Membership: in, not in

Examples

# Numeric comparison
conditions: "amount > 1000"

# String equality
conditions: "department == 'engineering'"

# List membership
conditions: "category in ['equipment', 'software']"

# Complex expression
conditions: "(urgency == 'high' or priority >= 4) and amount > 10000"

Dynamic Role References

Reference users based on their position in the organizational hierarchy.

${requestor.manager}: The direct manager of the user who submitted the request.
${requestor.supervisor}: The supervisor of the requestor.
${requestor.department_head}: The head of the requestor's department.

Settings

Configure advanced behavior for the workflow.

settings:
  # Step-specific timeouts
  timeout:
    manager_approval: "72_hours"
    ceo_approval: "5_business_days"

  # Escalation rules for timeouts
  escalation:
    - after_timeout: "notify_next_level"
    - final_escalation: "ceo"

  # Notification preferences
  notifications:
    send_reminders: true
    reminder_intervals: ["24_hours", "2_hours"]

  # Compliance requirements
  compliance:
    receipt_required: true
    policy_check: true

ApprovalML YAML Syntax Reference

On this page

ApprovalML YAML Syntax Reference

On this page