Workflow YAML Format¶

Workflows are declarative YAML documents loaded by Orchestrator. They describe what runs (steps, connections, variables, message formats). How a workflow may be started (HTTP, schedule, AMQP, gateway path, filters) lives in separate trigger documents under flows/triggers/.

Minimal Structure¶

name: demo
group: Demo/First
payload_format: auto    # input: auto | xml | json | raw
response_format: auto   # output: auto | xml | json | raw

example_payloads:
  - name: sample
    payload:
      xml: |
        <root><id>1</id></root>

steps:
  - id: first_step
    type: log
    message: "hello"

Pair with a trigger, for example flows/triggers/demo-http.yaml:

name: demo-http
target_workflow: demo
invocation:
  type: http
  http_method: POST

Common Top-Level Fields¶

name: unique workflow name (required).
group: logical grouping for dashboard organization (default: "General").
payload_format: hint for input message shape (auto, xml, json, raw). Used by dashboard and response heuristics.
response_format: hint for output message shape (auto, xml, json, raw).
connections: optional embedded connection definitions for this workflow only (same schema as connection documents under flows/connections/). Names must be unique within the list. At run time they are merged into the orchestrator connection registry; the same name as a cluster/storage connection overrides that connection for this workflow. In Dashboard → Workflow → Design, use Workflow connections to add or edit these entries.
example_payloads: optional payload presets for dashboard/testing (empty list is allowed).
scoped_context: optional declarative variable slots for this workflow; see Scoped context below.
steps: ordered list of workflow steps (required, at least one step for runnable workflows).

Message formats (workflow-owned)¶

Workflows do not declare invocation.type or http_method. Those belong on trigger YAML.

payload_format: xml
response_format: json

auto: engine or dashboard may infer from payload content or examples.
xml / json / raw: primary body interpretation for steps and HTTP responses.

Legacy workflow files may still contain a top-level invocation: block; on load, only payload_format and response_format are kept on the workflow. Start-contract fields in that block are ignored (use triggers instead).

Triggers (start contracts)¶

HTTP, schedule, AMQP, gateway paths, idempotency, throttles, and trigger filters are configured on trigger documents that reference target_workflow. See trigger YAML examples under flows/triggers/ and the gateway/orchestrator docs.

Multiple triggers may target the same workflow; the orchestrator merges their start contracts at load time into a runtime start_contract (not written back to the workflow file).

Field Ordering¶

Field order is flexible. The reference above shows a recommended convention.

Scoped context (sketch)¶

Optional declarative variable slots at workflow scope (names, types, optional defaults). See wiki ADR 0002 / 0004 and scoped_context in examples.