Skip to content

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 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).
  • on_error / onError: optional workflow-level steps after the main graph when a step failure remains pending. Context key workflow.error holds the error message. Default on_error_rethrow: true (run still fails after the handler). Set false to swallow.
  • finally: optional steps that always run after main (and on_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 — returns payload_format, response_format, and merged start_contract when triggers are bound