Skip to content

Step Types

This page lists all workflow step types currently supported by the orchestrator.

Source of truth: the WorkflowStep discriminated union in engine/services/orchestrator/app/workflow_runner.py.

How To Read This Page

  • Every step has id and type (not name:).
  • Most steps support when for conditional execution.
  • Many steps support run_after and compensate through shared mixins.
  • run_after status may be a scalar or a list ({try: [succeeded, failed]} = OR). Workflow-level on_error / finally are document fields, not step types — see Error Handling.

Terminology

A capability provider is an HTTP service that registers with the capability-registry. Workflows use exclusively type: service_call plus capability_name and path for integrations, transforms, and scripts. Built-in control/context steps remain orchestrator-owned. Do not add new first-class integration types.

Not every capability uses an egress. prefix — examples: script.execute, transformers.apply_xslt, ftp.call, sftp.list, variables.string_concat.

Built-in Step Types (Orchestrator-Owned)

Exact type values from WorkflowStep:

Type Category
context_set Context
context_increment Context
context_bind Context
context_extract_json Context
context_extract_xml Context
json_set Document mutate
xml_set_text Document mutate
terminate Operational
wait Control flow
wait_for_approval Human-in-the-loop (issue #133)
log Operational
milestone Context / Operations
workflow_call Control flow
collect Control flow
for_each Control flow
repeat_until Control flow
if Control flow
try Control flow
scope Control flow
parallel Control flow
service_call Integration / transform / script

There are no first-class http, xslt, javascript, ftp, storage_read/storage_write, or similar integration types. Use service_call (mapping below).

Context Steps

context_set

Set a context key from a literal value or a resolved reference.

  • Typical fields: context_key, value or value_from.

context_increment

Increment a numeric context key.

  • Typical fields: context_key, optional by.

context_bind

Parse JSON, XML, or YAML once under a document alias; later steps query fields via path refs (request:json:/field). See Bound documents.

  • Typical fields: alias, input_from, format (auto | json | xml | yaml).

context_extract_json

Extract a value from JSON using a JSON pointer and store it in context.

  • Typical fields: input_from, json_path, context_key.

context_extract_xml

Extract a value from XML using XPath and store it in context.

  • Typical fields: input_from, xpath, context_key.

milestone

Write context.milestone and context.milestone_at (UTC ISO-8601). The Operations list-API copies the latest written value in the related-run tree onto the runtime-root / parent row (milestone_at, else the writing run's updated_at). Child rows keep their own value.

  • Typical fields: value or value_from (exactly one).
  • Also works if a flow uses context_set with context_key: milestone.

Document Mutate Steps

json_set

Set or replace a value in a JSON payload using a JSON pointer path.

  • Typical fields: input_from, json_path, value_from, mirror_to_context.

xml_set_text

Set text or an attribute value on an XML node selected by XPath.

  • Typical fields: input_from, xpath, value_from, attribute, mirror_to_context.

Control-Flow Steps

if

Branch execution based on a condition.

  • Typical fields: condition, then_steps, else_steps.
  • condition.context_key reads the run context (string compare). Use context_extract_json / context_extract_xml with input_from: <step_id> to branch on service_call or trigger payload fields — see Conditions & Path Expressions.

try

Run nested steps and optionally handle failures with catch substeps.

  • Typical fields: steps, catch (or catch_steps), rethrow (default false), error_context_key.
  • On failure the error message is stored in context before catch substeps run.
  • Failed service_call HTTP envelopes remain readable in catch via input_from: <step_id> (/status_code, /headers, /body).
  • When rethrow is false, the try step succeeds after catch and the workflow continues.

scope

Group sequential steps as a nested sub-workflow (designer group). Same run context as the parent; connections stay workflow-level.

  • Typical fields: steps (at least one).
  • 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.

for_each

Iterate over array items and run nested steps for each item.

  • Typical fields: input_from, items_path, as_key, index_as, steps, max_iterations.

repeat_until

Repeat nested steps until a condition matches or max iterations is reached.

  • Typical fields: steps, until, max_iterations.

parallel

Run named scopes concurrently and merge selected outputs.

  • Required shape: scopes: (list of named scopes, each with nested steps). Flat steps: on parallel is not supported.
  • Typical fields: scopes, max_concurrency, fail_fast, outputs_map.

Example:

- id: fan_out
  type: parallel
  scopes:
    - name: weather
      steps:
        - id: call_weather
          type: service_call
          capability_name: egress.weatherstack.current
          capability_version: "^1.0"
          path: /current
          connection: weatherstack
          payload_from: initial
    - name: joke
      steps:
        - id: call_joke
          type: service_call
          capability_name: egress.joke-api.random
          capability_version: "^1.0"
          path: /random

collect

Merge outputs from previous steps into one JSON object or array.

  • Typical fields: from_steps, merge_mode, try_parse_json.

wait

Pause execution for a fixed duration in seconds.

  • Typical fields: seconds.

wait_for_approval

Pause until a human approves or rejects via a one-time Dashboard link (issue #133, ADR 0007 checkpoint).

  • Typical fields: title, message, into, approve_value, reject_value, expires_in_hours, notify.
  • Run status becomes waiting_for_approval; resume via /approve/{token} (public page, no login).
  • Token is consumed on first decision; re-click shows “already processed”.
  • Context key on resume: hitl.{step_id}.decision = approve | reject (usually set by the approval endpoint).
  • title / message may use {context_key} placeholders (and {workflow_name}, {step_id}, {request_id}).
  • Optional notify sends the one-time URL via egress.smtp.call before the run pauses:
  • connection — named SMTP connection
  • to_emails — addresses or a ref (context:approver_email, config:email.to_emails)
  • subject — optional; defaults to the rendered title
  • Mail failure aborts the step (no silent pause without a mailed link).

workflow_call

Invoke another workflow as a nested child run.

  • Typical fields: target, payload, output_key, timeout_seconds.
  • Runtime behavior:
  • Inherits call-chain context for cycle detection.
  • Inherits parent timeout budget (optionally capped by timeout_seconds).
  • Emits parent/child trace linkage metadata.

Operational Steps

log

Write a structured log message and optionally store the rendered message in context.

  • Typical fields: level, message, values, tags, into.
  • Business events: tag business-event + marker meshflows.business_event in the message. See Business events.

terminate

Stop workflow execution intentionally with a declared run status.

  • Typical fields: status, reason, http_status.

service_call (Integrations, Transforms, Scripts)

Generic HTTP call to a capability discovered via the capability registry (CAPABILITY_REGISTRY_URL on orchestrator).

Typical fields:

  • capability_name, capability_version, path
  • connection (optional)
  • payload / payload_from / first-class provider fields (see Workflow YAML)
  • output_key, timeout_seconds, retry_policy

See Step Contract for field rules. New connector? Integration end-to-end.

Capability mapping (legacy type → service_call)

Former first-class type Capability Path
http egress.http.call /call
xslt transformers.apply_xslt /applyXSLT
xml2json transformers.xml2json /xml2json
json2xml transformers.json2xml /json2xml
liquid transformers.apply_liquid /applyLiquid
(none — use service_call) transformers.csv_to_json /csv2json
(none — use service_call) transformers.json_to_csv /json2csv
(none — use service_call) transformers.xml_to_csv /xml2csv
(none — use service_call) transformers.csv_to_xml /csv2xml
(none — use service_call) transformers.flatfile_to_xml /flatfile2xml
(none — use service_call) transformers.xml_to_flatfile /xml2flatfile
— transformers.validate_json_schema /validateJsonSchema
— transformers.validate_xsd /validateXsd
javascript / script script.execute /v1/execute
ftp ftp.call /ftp
ssh egress.ssh.exec /exec
sftp (SSH sidecar) egress.ssh.sftp /sftp
sftp (standalone) sftp.list / sftp.download / sftp.upload /sftp/list, /sftp/download, /sftp/upload
imap_peek egress.imap.call /call
smtp_send egress.smtp.call /call
rabbitmq_publish egress.rabbitmq.publish or egress.rabbitmq.topic.send /publish or /publish/topic
storage_read / storage_write egress.s3.get / egress.s3.put (also list, delete) /get, /put, …
gmail_* / Workspace egress.google_workspace.* e.g. /gmail/list

Object storage for workflow data uses S3-compatible capabilities (egress.s3.*) — there are no native storage_read / storage_write steps.

Example: HTTP via service_call

- id: fetch_item
  type: service_call
  capability_name: egress.http.call
  capability_version: "^1.0"
  path: /call
  connection: erpnext
  method: GET
  url: "/api/resource/Item/{item_id}"
  fail_on_error_status: true
  values:
    item_id: "request:xml:/Message/id"

Example: Script via SES

- id: upper
  type: service_call
  capability_name: script.execute
  capability_version: "^1.0"
  path: /v1/execute
  runtime: javascript
  code: |
    result = input.toUpperCase();
  payload_from: previous

See Script steps howto.

For C# / .NET logic, do not use SES — expose a capability provider and call it with service_call. See C# Custom Process.

Demo Workflows

Demo What it shows
flows/workflows/weatherstack_current_demo.yaml Registry-driven weather provider
flows/workflows/transform_testing_demo.yaml transformers.* via service_call
flows/workflows/csv_transform_demo.yaml CSV ↔ JSON via transformers.csv_to_json / json_to_csv
flows/workflows/xml_csv_demo.yaml XML ↔ CSV via transformers.xml_to_csv / csv_to_xml
flows/workflows/flatfile_demo.yaml BizTalk wizard XSD flatfile ↔ nested XML (HDR;/DTL;/FTR;)
flows/workflows/json_schema_validate_demo.yaml JSON Schema via transformers.validate_json_schema
flows/workflows/xsd_validate_demo.yaml XSD via transformers.validate_xsd
flows/workflows/soap_http_xslt_demo.yaml SOAP 1.1 via egress.http.call + XSLT wrap/unwrap
flows/workflows/business_event_demo.yaml Business event via type: log (Loki/LogQL, not BAM)
flows/workflows/joke_api_random_demo.yaml Simple egress provider
flows/workflows/variable_binding_demo.yaml variables.* bindings
flows/workflows/storage_minio_demo.yaml egress.s3.*
Script steps howto script.execute

Quick Cheat Sheet

Step Type Category Typical I/O Notes
service_call Integration Payload → HTTP response body Registry discovery
json_set / xml_set_text Document Document + value ref → updated document Optional context write
context_* Context Literal/ref → context mutation No external I/O
if / try / for_each / repeat_until / parallel Control Nested steps parallel uses scopes only
collect / wait / workflow_call Control Aggregation / delay / child run
log / terminate Operational Message / status