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 Queue, AMQP Topic DSAV) 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 underflows/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).on_error/onError: optional workflow-level steps after the main graph when a step failure remains pending. Context keyworkflow.errorholds the error message. Defaulton_error_rethrow: true(run still fails after the handler). Setfalseto swallow.finally: optional steps that always run after main (andon_error), before the run returns or re-raises.
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).
service_call field convention¶
Provider call parameters are first-class YAML nodes on the step. The Dashboard writes them from registry form_fields.yaml_path. The Orchestrator keeps them as extras on service_call (no per-provider fields in core code) and composes the POST body from registry designer metadata (compose_payload_from_fields, optional body_key, payload_from_body_key). Use payload / payload_from for the body or envelope source, not for call metadata.
| Capability | First-class YAML | Body / envelope |
|---|---|---|
egress.http.call |
url, method, headers, body, request_timeout_seconds, fail_on_error_status, accepted_status_codes |
optional body or payload_from → request body |
egress.rabbitmq.topic.send |
domain, service, action, version, content_type, optional message |
usually payload_from → message |
egress.smtp.call |
to_emails, subject, body, … |
body_from / attachments |
egress.imap.call |
action, mailbox, filter, limit, message_id, include_body, include_attachments, mark_seen, attachment_max_bytes |
connection supplies host/auth |
script.execute |
runtime, code, timeout_ms |
payload_from → SES input |
Legacy JSON payload that embeds those keys remains readable as a compose fallback (no hard break). Prefer first-class nodes in new and migrated workflows.
Example HTTP:
- id: fetch_item
type: service_call
capability_name: egress.http.call
path: /call
connection: erpnext
method: GET
url: "/api/resource/Item/{item_id}"
fail_on_error_status: true
request_timeout_seconds: 60
values:
item_id: "request:xml:/Message/id"
timeout_seconds: 60
Example DSAV topic send:
- id: publish
type: service_call
capability_name: egress.rabbitmq.topic.send
path: /publish/topic
connection: rabbitmq_events
domain: MasterData
service: Products
action: Publish
version: "1.0"
content_type: application/xml
payload_from: map_to_cdm
timeout_seconds: 30
Triggers (start contracts)¶
HTTP, schedule, named AMQP queue bindings, AMQP Topic DSAV subscriptions, gateway paths, idempotency, and throttles 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).
A durable cursor / watermark (last-seen datetime, mail UID, SFTP mtime) is workflow state (cursor: next to scoped_context), not a trigger field. Polling is Recurrence + a first workflow step that looks for new work.
Scope (grouped steps)¶
type: scope groups sequential steps as a sub-workflow in the designer. It is not parallel.scopes (concurrent lanes) and not scoped_context (variables). Logic Apps grouping Scopes import here; exception Scopes with a Failed sibling import as type: try.
- id: try
type: scope
steps:
- id: getdata
type: service_call
# …
Cursor (watermark)¶
cursor:
enabled: true
bucket: trigger-cursors
key: Import/LogicApps/demo/table/row
default_value: "1970-01-01T00:00:00Z"
context_key: filterDateTime
update_from_context: currentDateTime
The orchestrator injects context_key at run start and writes update_from_context on succeeded. Inspect / reset via Dashboard Design → Cursor. Legacy invocation.trigger_cursor on a trigger is still a fallback.
AMQP Topic DSAV (subscription filters)¶
Topic receive filtered on Domain / Service / Action / Version is authored on a trigger document (invocation.type: amqp + DSAV triggerFilters), not on the workflow:
# flows/triggers/rabbitmq-dsav-topic-receive-amqp.yaml
name: rabbitmq-dsav-topic-receive-amqp
target_workflow: rabbitmq_dsav_topic_receive_demo
invocation:
type: amqp
triggerFilters:
- property: header:Domain
equals: Topic
- property: header:Service
equals: Orders
- property: header:Action
equals: DsavEcho
- property: header:Version
equals: "1"
- property: context:amqp.routing_key
equals: topic.orders.dsavecho.1
One published DSAV message can start every workflow whose filters match (POST /invoke/amqp/dispatch). Deprecated workflow field subscription.amqp_dsav is ignored at load. See RabbitMQ — DSAV.
Event Grid uses the same exchange (meshflows.events) with header:EventType instead of DSAV. See RabbitMQ — Event Grid.
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.
See also¶
- ADR 0005 — External triggers
- Gateway API — HTTP entry via triggers and edge routes
- Orchestrator
GET /workflows— returnspayload_format,response_format, and mergedstart_contractwhen triggers are bound