Skip to main content

Workflow Definition Reference

Workflow definitions are YAML documents saved as versioned configuration records. This page explains the common structure shared by workflow types.

The common document format is workflow.definition/v1. Each workflow type supports only a specific set of triggers, conditions, actions, and settings.

Common structure​

schema: workflow.definition/v1
stages:
  - name: INITIAL
    initial: true
  - name: SUCCEEDED
    terminal: success
  - name: FAILED
    terminal: failure
transitions:
  - from: null
    to: INITIAL
    trigger:
      type: EVENT
      config:
        eventTypes:
          - example.workflow-requested

Stages​

Each definition has one initial stage. A terminal stage may declare one of:

  • terminal: success for a business-success outcome;
  • terminal: failure for a business-failure outcome.

Some workflow types may require specific terminal outcomes.

Transitions​

A transition describes how the workflow moves from one stage to another. It defines from, to, one trigger, optional preconditions, and optional ordered actions.

from: null identifies an initial transition. The engine evaluates initial transitions only after it has selected the configuration to use. Later transitions keep using the same version selected at the start.

Triggers​

The generic event form is:

trigger:
  type: EVENT
  config:
    eventTypes:
      - example.workflow-requested

eventTypes is a non-empty list. Depending on the workflow type, triggers may also support a where filter, direct commands, timers, approval responses, or other specialized options.

Actions and preconditions​

Actions and preconditions depend on the selected workflow type. Each item has a type and, when required, a config object.

During execution, actions run in order. If a required action fails, the workflow becomes blocked instead of continuing as if nothing happened.

Validation and publication​

Saving or publishing a definition validates:

  • YAML syntax and workflow.definition/v1 structure;
  • the workflow type's supported trigger, precondition, and action types;
  • each supported configuration schema;
  • workflow-type-specific event rules and terminal outcome requirements.

Activation scope is not part of the workflow definition. It is configured and validated separately as routing settings; see Configure Workflows.