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.

  # 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).

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.

processing_step:
  name: "Processing Step"
  type: "automatic"
  description: "Updates external systems."
  actions:
    - update_accounting_system: true
    - schedule_reimbursement: true
  on_complete:
    notify_requestor: "Your request has been processed."
    end_workflow: true

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.

  # 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).

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.

processing_step:
  name: "Processing Step"
  type: "automatic"
  description: "Updates external systems."
  actions:
    - update_accounting_system: true
    - schedule_reimbursement: true
  on_complete:
    notify_requestor: "Your request has been processed."
    end_workflow: true

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