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
idandtype(notname:). - Most steps support
whenfor conditional execution. - Many steps support
run_afterandcompensatethrough shared mixins. run_afterstatus may be a scalar or a list ({try: [succeeded, failed]}= OR). Workflow-levelon_error/finallyare 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,valueorvalue_from.
context_increment¶
Increment a numeric context key.
- Typical fields:
context_key, optionalby.
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:
valueorvalue_from(exactly one). - Also works if a flow uses
context_setwithcontext_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_keyreads the run context (string compare). Usecontext_extract_json/context_extract_xmlwithinput_from: <step_id>to branch onservice_callor trigger payload fields — see Conditions & Path Expressions.
try¶
Run nested steps and optionally handle failures with catch substeps.
- Typical fields:
steps,catch(orcatch_steps),rethrow(defaultfalse),error_context_key. - On failure the error message is stored in context before catch substeps run.
- Failed
service_callHTTP envelopes remain readable in catch viainput_from: <step_id>(/status_code,/headers,/body). - When
rethrowisfalse, 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 notscoped_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 nestedsteps). Flatsteps:onparallelis 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/messagemay use{context_key}placeholders (and{workflow_name},{step_id},{request_id}).- Optional
notifysends the one-time URL viaegress.smtp.callbefore the run pauses: connection— named SMTP connectionto_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+ markermeshflows.business_eventin 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,pathconnection(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 |
Related References¶
- Workflow YAML schema: Workflow YAML
- Field-level contract: Step Contract
- Context and variables: Context & Variables
- Capability provider contract: Contract 17