Step Types
Execution model: pure dataflow
Section titled “Execution model: pure dataflow”Steps run by data flow, not by their position in the steps array. On every orchestration
tick, a step starts when all three conditions hold:
- its execution is in
CREATEDstatus (it has not run yet), - all of its incoming links are satisfied — the links named in
preconditions, or inpreconditionStepIds, or the singularpreconditionStepId, - its
preconditionExpression(if any) evaluates truthy.
A link is satisfied when the step it names has COMPLETED and its own condition, if it
declares one, holds:
{ "id": "ship", "type": "ACTION", "name": "Ship", "preconditions": [ { "stepId": "pack" }, { "stepId": "charge", "expression": "amount > 100" } ]}The condition belongs to the link, so it says when arriving by that route counts. A link whose condition is false is not satisfied, and by default a step that waits for all of its links waits — it is not skipped and the process does not finish around it. Conditions are re-evaluated against the process variables on every tick, so one that is false now holds the step until whatever it reads changes.
What a false condition means: onFalse
Section titled “What a false condition means: onFalse”Waiting is one of two things a false condition can mean, and the link says which:
onFalse | A false condition means | The step |
|---|---|---|
WAIT (default) | not yet — the variables may still change | waits, and the process stays open around it |
DISCARD | not this way — the flow did not come by this route | is a branch not taken; the process may finish and cancel it |
{ "id": "charge-penalty", "type": "ACTION", "name": "Charge the penalty", "preconditions": [ { "stepId": "validate", "expression": "ratePlan == 'NON_REFUNDABLE'", "onFalse": "DISCARD" } ]}Reach for DISCARD on an optional or exclusive branch — the step that only some processes go
through — and leave the default on a condition that is genuinely a wait, such as a link into a
step that resumes once a worker or an operator sets the variable it reads. Getting it wrong is
visible in opposite ways: a WAIT that was meant as a branch leaves the process RUNNING
forever, and a DISCARD that was meant as a wait lets the process finish without the step.
preconditionExpression is the older spelling. It gates the step, however it is reached, and
the engine reads it by folding it into every one of the step’s links: “this step only runs if X”
is “every route into it requires X”, so there is one kind of condition and one place that
evaluates it. What it means is folded in too: it becomes an onFalse: "DISCARD" guard, which is
what a step-level expression has always done — a step it holds back is skipped, so the process
can finish around it (see
Conditional skipping). Both
spellings still work and a definition may use either or both; prefer the link, which can say
something different of each route and, with onFalse, say what a false condition means. A step
with no links at all — an entry point — has nothing to fold into, and there the expression stays
its own gate.
Every eligible step starts concurrently. There is no ordering between steps beyond the
precondition graph: an active step never blocks unrelated branches, and array order is
irrelevant. The parallel flag is deprecated and ignored (it still deserializes, so old
definition files keep loading) — parallelism is simply several steps declaring the same
precondition, and a barrier is one step declaring several preconditions.
Because eligibility is driven only by preconditions, a step with no preconditions does not
run — having nothing to wait for is not permission to start. The exceptions are the ways into
a flow, START and a WAIT_FOR_MESSAGE that begins one, and
steps something else starts: a step named as another’s compensationStepId is run by the
rollback pipeline and needs no precondition of its own. A step with no preconditions that is
none of those is rejected at load, because nothing would ever start it.
Migrating an existing definition: add one START step and point your old first steps at
it —
{ "id": "start", "type": "START", "name": "Start" },{ "id": "validate", "type": "ACTION", "name": "Validate", "topic": "order-validator", "preconditionStepId": "start" }Marks an entry point of the workflow. No worker is involved: the step completes instantly
when the process is created, which makes all its successors eligible. A START step must
not declare preconditions (rejected at load). A workflow has at most one START (a second
one is rejected at load); for several branches that run concurrently from creation, give the START
several successors or follow it with a FORK.
{ "id": "start", "type": "START", "name": "Start"}ACTION
Section titled “ACTION”Dispatches a task to a worker microservice (or embedded bean). The workflow pauses until the worker reports completion.
{ "id": "process-payment", "type": "ACTION", "name": "Process Payment", "topic": "payment-service", "preconditionStepId": "start", "timeout": 30000, "retries": 3, "compensable": true, "compensationStepId": "refund-payment"}Required fields: none beyond id, type and name.
task is optional and names the task contract this step
runs, as <id> or <id>@<version>. A bare id is pinned to the contract’s latest version when the
definition is imported, so the reference the worker receives (as the task’s taskId) is always
fully qualified and a definition never changes contract without someone editing the file. The
contract’s own topic becomes this step’s default destination — so with a contract you usually need
no topic here — and an explicit topic still overrides it. A step with no task dispatches an
empty taskId, exactly as every ACTION did before task contracts.
topic is optional and names the destination this step’s task is dispatched to, which is how a
step is handed to a worker pool of its own. Omitted — the usual case — it means the shared
downstream destination, where every task goes unless told otherwise.
In Kafka mode the topic is the binding the task is sent on. A topic with no binding of its own
is a dynamic destination: Spring Cloud Stream creates it on first use, so naming one needs no
configuration in the application. Whatever consumes that topic must, of course, exist — a task sent
where nobody is listening is not refused by anything, and shows up only as a step that sits until
its timeout.
In embedded mode the field is ignored: there is one in-process EmbeddedTaskExecutor and no
transport to route over, so it takes every ACTION step whatever the topic says.
A step’s cancellation (TaskCancellationRequested, sent when a process is cancelled, stepped over
or a task times out) is addressed to the same topic the task was dispatched to, so a worker pool
of its own still hears about work it should stop.
USER_TASK
Section titled “USER_TASK”Pauses the workflow until a human submits a form. Creates a FormExecution instance in the forms engine.
{ "id": "manager-approval", "type": "USER_TASK", "name": "Manager Approval", "formId": "expense-approval-form", "preconditionStepId": "register-expense", "timeout": 86400000}Required fields: formId
The formId references a form definition stored in the forms engine.
Optional fields:
| Field | Type | Description |
|---|---|---|
assignment | object | Who the task is for and how urgent it is, rendered from the process (an iteration’s item too) when the task is created: {assignee?, candidateUsers?, candidateGroups?, priority?, dueDate?, followUpDate?}. Every value may be a ${…} template. priority is 0–100 (default 50); dueDate/followUpDate are an ISO-8601 duration from the task’s creation (P3D), an ISO date or date-time, or a template giving either. A task that names an assignee or candidates is visible and claimable only by them and by task admins |
escalation | object[] | What happens while the task stays open, each entry after an ISO-8601 duration from its creation, listed in the order they fire: {after, action?, to?, escalateTo?, publishEvent?}. action is reassign (the task is for to from now on), notify (recorded and announced, nothing changes) or escalateTo (the task is closed and the process goes on at the step named in escalateTo, as onTimeoutStepId routes a timed-out step — last entry only, not on a forEach step). Any entry may publishEvent (the shape of a PUBLISH_EVENT’s event). Not combined with deadline |
- id: approve type: USER_TASK name: Approve the expense formId: expense-approval preconditionStepId: register timeout: P10D assignment: assignee: "${manager}" candidateGroups: ["finance-${region}"] priority: "${amount > 1000 ? 90 : 40}" dueDate: P2D escalation: - after: PT48H action: reassign to: { candidateGroups: [finance-managers] } - after: P5D escalateTo: director-reviewSee Human tasks: assignment and escalation.
Durably pauses the workflow until a moment in time. No worker is involved: the step stays PENDING and the timer scheduler completes it once the due moment passes. The wait survives restarts — the due moment is recomputed from persisted state (the step definition, its start time and the variable snapshot), so a process can safely wait for days.
Wait for a duration, counted from the moment the step starts:
{ "id": "wait-72h", "type": "TIMER", "name": "Wait 72 hours", "duration": "PT72H", "preconditionStepId": "send-payment-link"}Wait until an absolute date carried by a process variable (e.g. a check-in date):
{ "id": "wait-until-checkin", "type": "TIMER", "name": "Wait until check-in date", "untilVariable": "checkinDate", "preconditionStepId": "confirm-booking"}Wait for a moment computed from the process’s data — three days before check-in, at 09:00 hotel time — which follows the data if it changes while the timer waits (see Scheduling and Deadlines):
{ "id": "wait-balance", "type": "TIMER", "name": "3 days before check-in", "preconditionStepId": "confirm-booking", "until": { "date": "${checkinDate}", "offset": "-P3D", "at": "09:00", "zone": "${hotelZone}", "ifPast": "fire" } }Required fields: one of duration, untilVariable or until
until is a moment: {date, offset, at, zone, ifPast}, or a date template alone. ifPast (fire default, or timeout — which follows onTimeoutStepId or fails) decides what a moment already past does.
duration accepts an ISO 8601 duration string (PT30M, PT72H, P3D) or an integer in milliseconds. untilVariable names a process variable holding an ISO 8601 date (2026-08-01), date-time (2026-08-01T15:00) or offset date-time; it takes precedence over duration. If the referenced variable is missing or unparseable when the step starts, the step ends ERROR through the normal failure pipeline — the process never freezes silently. The timeout field is ignored for TIMER steps.
WAIT_FOR_MESSAGE
Section titled “WAIT_FOR_MESSAGE”Durably pauses the workflow until a matching external message arrives — the equivalent of a BPMN message catch event or a Temporal signal. No worker is involved: the step stays PENDING and the engine completes it when a MessageReceived event with the same messageName and a matching correlation key is published on the upstream surface (Kafka topic, embedded publisher, a SEND_MESSAGE step in another process, the sendMessage MCP tool, or the REST endpoint below).
Correlate by business key:
{ "id": "wait-for-payment", "type": "WAIT_FOR_MESSAGE", "name": "Wait for payment confirmation", "messageName": "payment-received", "correlationExpression": "businessKey", "preconditionStepId": "send-invoice", "timeout": 259200000}Correlate by a process variable via a JEXL expression:
{ "id": "wait-for-payment", "type": "WAIT_FOR_MESSAGE", "name": "Wait for payment confirmation", "messageName": "payment-received", "correlationExpression": "orderId"}Required fields: messageName, correlationExpression
A message matches a waiting step when the message name is equal and the message’s correlationKey equals the key the step expects: the value of correlationExpression — a JEXL expression evaluated against the process variables (same context and same fail-closed semantics as preconditionExpression; an expression that cannot be evaluated matches nothing). To correlate by business key, write "correlationExpression": "businessKey" explicitly. On match, the message’s variables are merged into the process variables (visible to all successor steps) and the step completes.
Delivery semantics:
- Not buffered. A message that matches no waiting step is ignored (and logged). Upstream delivery is at-least-once, so the sender retries — or sends again once the process reaches the waiting step.
- Idempotent. A duplicate delivery of an already-correlated message is ignored: the step only completes once.
- Broadcast. If several processes are waiting on the same
messageNameand correlation key, all of them are resumed.
Fed by a domain event. With an onEvent block, a CloudEvent arriving on a destination becomes the step’s message — no one has to call the message API:
- id: wait-payment type: WAIT_FOR_MESSAGE name: Wait for the payment messageName: payment-captured correlationExpression: bookingId onEvent: destination: payments # workflow.events.destinations.payments.topic type: com.acme.payment.captured # '*' wildcards allowed correlationKey: "${data.bookingId}" # template over the event; default the record key, else the subject filter: "data.status == 'CAPTURED'" # optional JEXL over the event variables: { paymentId: "${data.paymentId}" } # default: data's top-level membersThe same event (CloudEvents source + id) is correlated at most once per message and key. See Starting on and waiting for domain events.
timeout and retries keep their usual meaning: a waiting WAIT_FOR_MESSAGE step that receives no message within timeout transitions to TIMEOUT and the normal retry/failure pipeline engages (a retry re-arms the wait).
Systems that cannot produce to Kafka (webhooks, SaaS callbacks) can deliver messages over REST — same correlation, any mode (embedded or kafka):
curl -X POST http://localhost:8080/workflow/api/messages \ -H "Content-Type: application/json" \ -H "X-Api-Key: mysecret" \ -d '{"messageName": "payment-received", "correlationKey": "res-123", "variables": {"paymentId": "P-9"}}'The endpoint responds 202 Accepted (fire-and-forget: an unmatched message is ignored, per the delivery semantics above). Since 2.27.0 the engine’s REST API (/workflow/api/**) refuses anonymous requests: send an X-Api-Key matching workflow.message-api.api-key, or authenticate through the application’s Spring Security; only workflow.message-api.allow-anonymous=true opens it — see HTTP security.:
workflow: message-api: api-key: mysecret # sent as X-Api-Key; without it (and without Spring Security) the API answers 401SEND_MESSAGE
Section titled “SEND_MESSAGE”The throw side of messaging: emits a MessageReceived event and completes immediately — the equivalent of a BPMN message throw event. No worker is involved. When the step starts, the engine evaluates correlationExpression (same JEXL context as preconditionExpression) to compute the correlation key, publishes MessageReceived(messageName, correlationKey, variables) through the outbox, and completes the step. Any process waiting on a WAIT_FOR_MESSAGE step with the same messageName and key resumes — so a workflow can signal another workflow without an ACTION step and a worker in between.
{ "id": "notify-payment", "type": "SEND_MESSAGE", "name": "Notify payment received", "messageName": "payment-received", "correlationExpression": "orderId", "messageVariables": ["paymentId", "amount"], "preconditionStepId": "charge-card"}Required fields: messageName, correlationExpression
Optional fields: messageVariables — an array of process-variable names selecting which variables the outgoing message carries. Empty or absent means the message carries no variables: process state is never sent implicitly.
Semantics:
- Fire-and-forget. Delivery is not acknowledged: the step completes when the message is emitted, not when someone receives it. A message that matches no waiting process is discarded (not buffered), per the delivery semantics above — sequence the two workflows so the receiver is already waiting, or have the sender retry.
- Fail loud. A missing
messageNameorcorrelationExpression, or a correlation expression that cannot be evaluated, transitions the step toERRORand the normal retry/compensation pipeline engages. This is deliberately not the silent fail-closed behaviour of precondition guards: a message that silently goes nowhere would be much harder to diagnose.
Evaluates a business rule from the rule engine against the process variables. The rule’s outputs are merged back into the process variables.
{ "id": "apply-discount", "type": "RULE", "name": "Apply the discount rule", "ruleId": "high-value-order", "preconditionStepId": "register-order"}Required fields: ruleId
The ruleId references a rule definition (expression rule or decision table) stored in the rule engine. The engine dispatches the step with taskId=evaluate-rule; any app embedding rule-runtime (or rule-standalone-app) evaluates it. See Rule Evaluation.
PROCESS
Section titled “PROCESS”Starts a child workflow as a sub-process. No worker is involved: when the step starts, the
engine creates a process of childWorkflowDefinitionId carrying all the parent’s process
variables, and the parent step waits PENDING until the child reaches a terminal status.
{ "id": "run-kyc", "type": "PROCESS", "name": "Run KYC Check", "childWorkflowDefinitionId": "kyc-workflow", "outputVariables": ["kycResult", "kycScore"], "preconditionStepId": "create-customer", "timeout": "PT1H"}Required fields: childWorkflowDefinitionId — must be different from the workflow’s own
id (direct self-recursion is rejected at load) — or an inline body under steps: (below); a
step declares exactly one of the two.
Optional fields: outputVariables — an array of child-process variable names copied back
into the parent when the child completes. Empty or absent means none: child state is never
merged back implicitly.
Semantics:
- The child process is created with the deterministic business key
parent:<stepExecutionId>, which makes creation idempotent — a redelivered creation event is deduplicated by business key, so at-least-once delivery never spawns a second child. - When the child process reaches
COMPLETED, the parent step completes and only the child variables named inoutputVariablesare copied into the parent process. - When the child ends
ERRORorCANCELLED, the parent step transitions toERRORand the normal retry/compensation pipeline engages. timeoutbounds the wait: a parent step whose child has not finished withintimeoutgoes through the usualTIMEOUT→ retry/ERRORpipeline.- Retries run the child again. With
retriesset, a step whose child endedERRORorCANCELLEDis retried by starting a fresh child process, under the next deterministic key:parent:<stepExecutionId>#2, then#3, and so on. The failed child keeps its own key, status and history. The same goes for an operator retry of the step, or a restart of the parent process. A retry after atimeoutis different: the child is still running, so the retried step re-attaches to it and does not start a second one.
Cancellation propagates from parent to child: when the parent PROCESS step ends CANCELLED,
ERROR or TIMEOUT (retries exhausted), a still-running child process is stopped too — and
the cascade continues to grandchildren. While retries remain, the child is left running: a
retried PROCESS step re-attaches to the same child through the deterministic business key.
How it stops depends on why: when the parent is undoing work — it is rolling back, its
forEach failed fast, or an XOR join’s compensateLosers / an END’s compensateAbandoned
abandoned the branch — the child is rolled back (its completed compensable steps compensated, it
ends COMPENSATED), and the parent’s rollback waits for it. Otherwise — an operator’s cancel among
them — it is cancelled, undoing nothing. A child that already completed is undone by the parent
step’s compensationStepId instead, never both. See
A child process cut short.
Inline body {#inline-body}
Section titled “Inline body {#inline-body}”Instead of naming a child workflow, a PROCESS step can write it in line: steps: holds the
child’s steps, with the same syntax as a definition’s.
- id: rooms type: PROCESS name: Book one room preconditionStepId: start outputVariables: [roomBookingId] forEach: { items: rooms, as: room, output: roomBookings, outputElement: roomBookingId } steps: - { id: start, type: START, name: Start } - { id: create, type: ACTION, name: Create, topic: create-booking, preconditionStepId: start } - { id: end, type: END, name: End, preconditionStepId: create }It runs exactly as a named child does — every rule above applies, and with a forEach each item
starts a child of its own (a dynamic fork; see
Loops and Multi-Instance).
What differs is where the child’s definition comes from:
- Its id is
<workflow id>.<step id>—booking.rooms. Child processes show it as their workflow; a body inside a body composes:booking.rooms.extras. - It is part of the parent’s version. The body is in the parent’s steps, so it changes, is versioned and is migrated with the parent; its children carry the parent’s version number. A running child keeps the body it started with.
- It cannot be started on its own. It is not a definition in the repository — not listed, not startable over REST, MCP, the console, an event or a cron. Only its PROCESS step starts it.
- It inherits the parent’s
sensitiveVariables,requiredScopes/requiredRolesand tags, since its children hold the parent’s variables. - It is validated as a workflow of its own — at load and by
eventconductor:validate— and its problems say where they are:booking.rooms: Step 'confirm' has no preconditions …. - Steps inside it that wait for a message or an event (
WAIT_FOR_MESSAGE,onEvent,awaitReply) are routed as any other’s. ${businessKey}inside it is the parent’s. The body is part of the parent’s definition, so its templates and guards readbusinessKeyas they would next to it: the business key of the process that owns the body (for a body inside a body, the outermost one’s). The child keeps its own key,parent:<stepExecutionId>, asprocess.businessKey, in the console and for everything else. A child named bychildWorkflowDefinitionIdreads its own key, as always.
Under a forEach, every child — inline or named — also receives the item and its index as variables
(as, indexAs), and its templates and guards read the item as structure, as an iteration of any
other step does: ${room.number} works in the body’s HTTP_CALLs, in its compensations and in its
guards. So the example in Not creating duplicates
works unchanged inside an inline body:
- id: rooms type: PROCESS name: Book every room preconditionStepId: start forEach: { items: rooms, as: room } steps: - { id: start, type: START, name: Start } - id: create type: HTTP_CALL name: Create the room booking preconditionStepId: start http: connection: hotel method: POST path: /bookings headers: { Idempotency-Key: "${businessKey}-${room.number}" } # BOOKING-1-101, BOOKING-1-102 … - { id: end, type: END, name: End, preconditionStepId: create }Fans a flow out into parallel branches. No worker is involved: the step completes instantly when it starts, which makes all its successors eligible at once — every step whose precondition is the FORK starts concurrently.
FORK is readability sugar: the fan-out actually comes from several steps declaring the same
precondition (which works with any step type as the predecessor). Use a FORK node when you
want the branching point to be explicit in the definition and the graph.
{ "id": "fork-notifications", "type": "FORK", "name": "Send Notifications", "preconditionStepId": "process-order"},{ "id": "send-email", "type": "ACTION", "name": "Send Email", "topic": "email-service", "preconditionStepId": "fork-notifications"},{ "id": "send-sms", "type": "ACTION", "name": "Send SMS", "topic": "sms-service", "preconditionStepId": "fork-notifications"}The converge point of parallel branches. No worker is involved — once its preconditions are met,
the step completes instantly and the flow continues after it. Its joinType chooses the merge:
AND(default) — a synchronizing join: waits until all the steps in itspreconditionStepIdshaveCOMPLETED.XOR— an exclusive join: proceeds as soon as any one incoming branch completes.
{ "id": "join-notifications", "type": "JOIN", "name": "All notifications sent", "joinType": "AND", "preconditionStepIds": ["send-email", "send-sms"]}The barrier is the multiple preconditions: a JOIN with a single precondition waits for
nothing extra. (Any step may declare several preconditions — a JOIN node just makes the
convergence explicit, exactly as FORK makes the fan-out explicit.) joinType is AND unless
set to XOR; it is ignored on non-JOIN steps.
compensateLosers (XOR only, default false). By default an XOR join leaves the other
branches running: they finish on their own, and what they did stands. With compensateLosers: true
the join abandons them the moment it goes on: their steps still waiting or running are cancelled,
and every compensable step of
theirs that completed is compensated, newest first, as a cleanup beside the flow — the process
carries on down the winning branch. compensateLosers on any other step is a validation error.
There is exactly one winner: the incoming branch whose link step completed first (earliest
completion time; at the same instant, the one listed first in preconditionStepIds). Every other
branch is a loser — also one that had completed too by the time the join was evaluated, which is what
routinely happens when both answer quickly (on the embedded engine’s default single worker thread, it
always does). A losing branch is what leads into the join only through a losing link; a step that also
feeds some other part of the flow is not part of it.
A loser’s outputs are discarded. Once a branch has reached the join first, what a step of a losing
branch reports (worker variables, an HTTP_CALL’s output, a message payload) is not written to
the process: it is kept on that step’s own run, where its compensation reads it (the booking id to
cancel), and the winner’s variables stand. What a losing branch wrote before the winner reached the
join — while the race was still open — is not rolled back from the variables; give the branches’
outputs the same names only where the winner’s value is the one the flow should keep.
- { id: first, type: JOIN, name: First answer, joinType: XOR, compensateLosers: true, preconditionStepIds: [fast, quote] }CHOICE
Section titled “CHOICE”An exclusive split: the branch counterpart of the XOR join. Where a FORK takes every
eligible successor, a CHOICE takes exactly one — the first whose guard holds. No worker is
involved; like FORK and JOIN it completes instantly when it starts, and the decision is made
from the guards on its outgoing links.
The branches are evaluated from the longest guard expression to the shortest — most specific
first, down to the most general — and the first one that holds is taken; the rest are
discarded. A successor whose link carries no guard is the default (else): being the shortest,
it is tried last, and it always holds, so it is taken only when nothing more specific did. Guards
live on the link (a preconditions entry with an expression), so a CHOICE reads the same
per-route conditions the graph shows.
[ { "id": "route", "type": "CHOICE", "name": "Route by customer tier", "preconditionStepId": "score-customer" }, { "id": "handle-vip", "type": "ACTION", "name": "White-glove path", "topic": "vip-service", "preconditions": [{ "stepId": "route", "expression": "tier == 'gold' && region == 'EU'" }] }, { "id": "handle-priority", "type": "ACTION", "name": "Priority path", "topic": "priority-service", "preconditions": [{ "stepId": "route", "expression": "tier == 'gold'" }] }, { "id": "handle-standard", "type": "ACTION", "name": "Standard path", "topic": "standard-service", "preconditions": [{ "stepId": "route" }] }]Here a gold/EU customer takes handle-vip (longest guard, evaluated first); any other gold
customer takes handle-priority; everyone else falls through to the unguarded handle-standard.
The pick latches: once a branch has started, a later change to the variables a guard reads
cannot hand the split to a different branch. The CHOICE decides when it completes and does not
wait — unlike an ordinary guarded link, a branch it did not take is discarded, not held.
Converge exclusive branches with an XOR JOIN, not an AND join. This is the
split↔join pairing — FORK with an AND join, CHOICE with an XOR join. A CHOICE runs only
one branch, so an AND join downstream would wait for the branches that never ran and never
fire; the process then completes implicitly, cancelling the join and everything after it (the
same mechanism as JOIN on a guarded branch above). An XOR join proceeds on the one
branch that did run.
A branch can be the join itself: an XOR join (or an END) may name the CHOICE directly — usually
as its unguarded default — beside its other ways in. That link counts only when the CHOICE picks the
join; when it picks another branch, the join still goes on through its other links (for example
preconditionStepIds: [notify-guest, guest-decision]: everything booked, or the guest’s default
answer, keep). No step in between is needed.
Marks the workflow as complete. The process transitions to COMPLETED.
{ "id": "end", "type": "END", "name": "Done", "preconditionStepId": "last-step"}An END step is recommended, but not enforced: the engine also completes a process implicitly when no runnable steps remain — no step is active, and every remaining step is blocked by a precondition that does not hold. On completion (explicit or implicit), any step still waiting is transitioned to CANCELLED. Declaring an explicit END makes the intended terminal point visible and lets you end the process early while other steps are still eligible.
A step the END cancelled while its work was under way may still complete — the worker had already
booked. That work is always compensated when its step declares a compensation (see
Branches the flow abandons).
With compensateAbandoned: true (default false, END only) the END also compensates what the
branches it cut short had completed in time: every compensable step that is not on the way to this
END and has a step after it that the END cancelled. The process is COMPLETED either way; the
compensations run after it as a cleanup.
- { id: done, type: END, name: Done, compensateAbandoned: true, preconditionStepId: quick }An END that rolls back: compensate {#compensate}
Section titled “An END that rolls back: compensate {#compensate}”With compensate: true (default false, END only) reaching the END rolls the process back
on purpose. It is for a business decision to undo — the guest cancelled — where nothing failed:
- what is still waiting or in flight is cancelled, as any
ENDcancels it (a running childPROCESSis rolled back, not just cancelled); - every compensable step that completed is compensated, newest first, exactly as in a saga rollback — a forEach’s completed iterations once each, its failed ones not at all; work that completes after it was cancelled is undone too;
- the process ends
COMPENSATED(COMPENSATION_FAILEDif a compensation fails), also when there was nothing to undo. It is not counted as a failed process; the reason is on the process (rollbackReason) and in theEND’s log.
In a child process, the parent’s PROCESS step fails when the child ends COMPENSATED — the child did
not do its job — and the parent’s own saga takes it from there. compensate cannot be combined with
compensateAbandoned: it already undoes every branch. The graph draws it with BPMN’s compensation
marker (⏪).
- id: cancelled-by-guest type: END name: Cancelled by the guest compensate: true preconditions: - { stepId: guest-decision, expression: "decision == 'cancel'" }See Compensation on a business decision.
DYNAMIC
Section titled “DYNAMIC”Dispatches a task to a worker like an ACTION, but the worker’s reply may inject new steps into the running process — the steps, and their preconditions, that the worker decided are needed at runtime. This is how a workflow decides part of its own shape: a fan-out whose width is only known once the work starts, a plan a worker computes and then executes.
{ "id": "plan", "type": "DYNAMIC", "name": "Plan the work", "topic": "work", "preconditionStepId": "start"}Required fields: none beyond id, type and name. topic is optional and routes the task — same as ACTION.
The worker injects with WorkerReply.inject(...) / injectAndComplete(...) (message StepsInjected). Injection is add-only, the worker supplies each step’s own preconditions (there is no default wiring — an unreachable injected step is a visible bug, not something the engine fixes up), and the engine validates the whole batch (unique ids, resolved references, no cycle, within the step budget) and fails the DYNAMIC step if it is rejected. Only a DYNAMIC step may inject. See Dynamic Workflows for the full picture.
Acquire a named per-key lock, serializing every process — or every critical section — that targets the same key: for example, all the processes touching one reservation. No worker is involved. The step completes the moment the process holds the lock; if another process holds it, this one parks the step in WAITING_ON_LOCK and is admitted FIFO, in arrival order, when the lock frees.
{ "id": "lock-booking", "type": "LOCK", "name": "Lock the booking", "lockName": "booking", "lockKey": "bookingId", "preconditionStepId": "start"}Required fields: lockKey — a JEXL expression over the process variables giving the key that is locked (e.g. bookingId); a definition with a LOCK or UNLOCK step without one is rejected at load. It is evaluated with the same context as correlationExpression (the variables, plus businessKey and process); a key that cannot be evaluated fails the step (ERROR).
Optional fields: lockName — the lock domain (e.g. "booking"). Together with the key it names the lock: every step and process sharing the (lockName, key) pair is serialized against each other. Defaults to the definition’s id, so give one name to steps of different definitions that must serialize together.
Semantics:
- Reentrant. A process taking a lock it already holds gets it again at once.
- Released by a matching
UNLOCKstep, or — whatever happened in between — when the process reaches a terminal state (COMPLETED,ERROR,CANCELLED,COMPENSATEDorCOMPENSATION_FAILED), so a process that fails, or is cancelled, inside its critical section does not wedge the key. A failed process that has compensations to run keeps its locks until the rollback ends (COMPENSATEDorCOMPENSATION_FAILED): what the lock protects is still being undone, so the next process on the key only starts once it is. A process that ends while queued for a lock leaves the queue. A lease (workflow.lock.lease-ms) is the backstop for a pod that dies while holding one; see Serialization locks. - Always waits. A
LOCKstep never refuses; to refuse a synchronous caller when the key is busy, use a process-level lock withonLockBusy: FAIL(below).
Process-level lock. To serialize whole instances of a definition rather than a section of them, declare processLock on the definition instead of steps: "processLock": { "name": "booking", "key": "bookingId" } (key required, name defaulting to the definition id). An instance that cannot take it makes no progress at all until it is admitted, and holds it until it ends. See Synchronous Invocation — Locks for onLockBusy.
UNLOCK
Section titled “UNLOCK”Release a lock taken by a LOCK step, admitting the next waiter for that key. No worker; completes immediately.
{ "id": "unlock-booking", "type": "UNLOCK", "name": "Release the booking", "lockName": "booking", "lockKey": "bookingId", "preconditionStepId": "update-booking"}Required fields: lockKey, as for LOCK. Optional fields: lockName (default: the definition’s id). Name the same pair as the LOCK it closes. Releasing a lock this process does not hold is a no-op. An UNLOCK is not required for correctness — the process releases everything it holds when it ends — but without one the key stays locked for the rest of the process.
The answer a process gives to whoever invoked it synchronously. No worker: the step completes in the step-over that reaches it, recording the reply on the process in the same transaction, and the flow carries on. Before END it answers with the result; earlier, the caller gets its answer while the process continues.
{ "id": "confirm", "type": "REPLY", "name": "Booking confirmed", "replyVariables": ["bookingId", "confirmation"], "preconditionStepId": "charge"}Optional fields (at most one of the three): replyVariables — the reply is a JSON object with one member per listed variable; replyExpression — a JEXL expression whose value is the reply (e.g. {'bookingId': bookingId, 'status': 'CONFIRMED'}); replyTemplate — a payload template. Neither → {}.
Semantics:
- At most one per run, checked on import and by the Maven plugin: two
REPLYsteps must be separated by an exclusive split (differentCHOICEbranches, or a step’s normal vsonTimeoutStepIdroute) that every way into both goes through. AREPLYcannot be a compensation step or be injected by aDYNAMICstep. At runtime the first reply stands. - Fail loud. A reply that cannot be computed, or is larger than
workflow.sync.max-reply-bytes, fails the step (ERROR), so the failure contract answers the caller instead. - A process started asynchronously still records its reply.
PUBLISH_EVENT
Section titled “PUBLISH_EVENT”Publish a domain event from the process’s state, without a worker. See Publishing Domain Events.
{ "id": "announce", "type": "PUBLISH_EVENT", "name": "Booking confirmed", "preconditionStepId": "confirm", "event": { "destination": "bookings", "type": "com.acme.booking.confirmed", "key": "${bookingId}", "payload": { "bookingId": "${bookingId}" } } }Required: event.destination (a logical name mapped to a topic by workflow.events.destinations), event.type. Optional: event.key (template; default the business key, else the process id), one of event.payload (structured template) / event.payloadTemplate (text) / event.payloadVariables, event.format (binary default, structured, plain).
The engine renders and checks the event when the step starts — an unknown destination, a template that does not render or an oversized payload fails the step at once — and dispatches it to the built-in publish-event@1 task (worker-events; the event travels in task variable __event), whose request rides the outbox with the step’s state. The task sends the event to its destination and completes the step: embedded, it runs in the engine’s pod; in kafka mode it is on topic event-publications, served by the orchestrator itself (a step’s topic overrides). At-least-once, id = the step execution id, stable across redeliveries; the step completes after the event was sent. Timeouts (workflow.default-step-timeout-ms too), retries and incidents work as for ACTION; the task fails with EVENT_DESTINATION (the destination has no topic in the worker’s configuration — final), EVENT_IO (the broker refused it — retried) or EVENT_REQUEST (a malformed task — final).
Waiting for the answer: awaitReply. With an awaitReply block the step is a request that waits for its reply — asynchronous request/response in one step, with no reply lost however fast it comes back:
- id: ask-quote type: PUBLISH_EVENT name: Ask for a quote preconditionStepId: start timeout: PT5M # bounds request + reply retries: 0 onTimeoutStepId: no-quote event: { destination: quote-requests, type: com.acme.quote.requested, key: "${process.businessKey}", payload: { requestId: "${process.businessKey}", item: "${item}" } } awaitReply: messageName: quote-ready # the message that is the reply correlationExpression: businessKey onEvent: # optional: the reply comes as a domain event destination: quote-replies type: com.acme.quote.ready correlationKey: "${data.requestId}" variables: { price: "${data.price}" }awaitReply takes the fields of a WAIT_FOR_MESSAGE — messageName and correlationExpression (both required) and an optional onEvent — with the same meaning. Written on the step itself, outside awaitReply, messageName and correlationExpression are ignored (as they always were) and the import and the Maven plugin warn about them. The wait is armed in the transaction that dispatches the task, so the event cannot leave before the step is waiting for its answer. The step stays PENDING after publishing (the worker’s report leaves it waiting, as for an HTTP_CALL) and completes when the reply is correlated, its variables merged into the process. timeout, deadline, retries and onTimeoutStepId bound the whole exchange; a retry publishes the request again — as a new event, id = <step execution id>-<attempt> — and waits again. See Asynchronous Request/Response.
HTTP_CALL
Section titled “HTTP_CALL”Call an HTTP endpoint and map the response into variables, without writing a worker. See HTTP Calls.
{ "id": "charge", "type": "HTTP_CALL", "name": "Charge", "preconditionStepId": "book", "retries": 2, "http": { "connection": "payments", "method": "POST", "path": "/charges/${bookingId}", "body": { "amount": "${amount * 1}" }, "output": { "chargeId": "body.id" } } }Required: http with exactly one of connection (+ optional path) and url. Optional: method (default GET), query, headers, body / bodyTemplate, successStatus (default 2xx), output (variable ← JEXL over {status, headers, body}), auth (a profile name, or inline with ${secret:NAME} credentials only), retryOn (default [5xx, io] — a 4xx is not retried).
Rendered by the engine and executed by the built-in http-call@1 task (worker-http): embedded in the engine’s pod, or on topic http-calls in kafka mode — served by the orchestrator itself, or by the optional http-worker-standalone-app. Timeouts, retries, compensation and cancellation work as for ACTION.
Waiting for a callback: awaitReply. When the HTTP response only acknowledges the request and the answer comes later — a webhook, a callback, an event — give the step an awaitReply (the fields of a WAIT_FOR_MESSAGE, as on PUBLISH_EVENT):
- id: ask-quote type: HTTP_CALL name: Ask for a quote preconditionStepId: start timeout: PT5M onTimeoutStepId: no-quote http: { connection: pricing, method: POST, path: /quotes, body: { requestId: "${process.businessKey}", item: "${item}" }, output: { ticket: "body.ticket" } } awaitReply: { messageName: quote-ready, correlationExpression: businessKey }The wait is armed before the HTTP task is dispatched, so a callback the remote system sends before (or instead of waiting for) its own response is never lost. The step completes when the reply is correlated:
- Response first, then reply: the 2xx response is recorded —
outputmapped into the process — and the step keeps waiting (PENDING, under the sametimeout). The reply completes it. - Reply first, then response: the reply completes the step; the response that comes after finds it complete and is ignored,
outputincluded. Do not rely onoutputin successors: correlate on an id you send, and carry what you need in the reply. - A failed request (non-2xx, I/O error, before any reply) fails the step as any
HTTP_CALLfails:retriessend the request again — with the sameIdempotency-Key— and re-arm the wait. A reply that arrives while the step waits out its backoff matches nothing. - The worker’s
RUNNINGprogress report leaves the stepPENDING:timeoutbounds the request and the reply together — andworkflow.default-step-timeout-ms, when set, applies to anHTTP_CALLwithout atimeoutwhether or not it awaits a reply, so give one that awaits a slow reply atimeoutof its own.
LLM_CALL
Section titled “LLM_CALL”Ask a language model a question built from the process’s data and map its answer — text, or JSON valid against a schema — into variables, without writing a worker. See LLM Calls.
{ "id": "triage", "type": "LLM_CALL", "name": "Triage", "preconditionStepId": "log", "retries": 2, "llm": { "connection": "claude", "system": "You triage hotel guest complaints.", "prompt": "${guestName} wrote: ${complaint}", "responseSchema": { "type": "object", "required": ["category"], "properties": { "category": { "enum": ["room", "billing", "staff", "other"] } } }, "output": { "category": "json.category" }, "usageVariable": "triageUsage" } }Required: llm with connection (a workflow.llm.connections.<name>), prompt (text template), and one of output / outputVariable. Optional: model (overrides the connection’s), system (text template), temperature (0–2, sent only when set), maxTokens, responseSchema (JSON Schema — the answer is parsed and validated; an invalid one fails with LLM_INVALID_OUTPUT, retried), output (variable ← JEXL over {text, json, usage, model, finishReason}), outputVariable (the text, or the JSON document), usageVariable ({model, inputTokens, outputTokens, totalTokens}), allowSensitiveVariables (true to let system/prompt read the definition’s sensitive variables — without it a prompt naming one is refused at load, and they are left out of the prompt’s context). No key or ${secret:…} in the block: keys are the connection’s configuration.
Rendered by the engine and executed by the built-in llm-call@1 task (worker-llm, on Spring AI: Anthropic and OpenAI-compatible providers): embedded in the engine’s pod, or on topic llm-calls in kafka mode — served by the orchestrator itself, or by the optional llm-worker-standalone-app. Timeouts, retries, compensation and cancellation work as for ACTION; a provider 4xx (bad request, bad key) is final, 429/5xx/timeouts are retried.
Invokes an agent published in the IA catalogue — its system prompt, model, allowed MCP servers, RAG sources, peers and JSON output schema are the catalogue’s — and gives it a task and explicit input. The engine checks the reference against the catalogue when the definition is imported; the agent runtime runs it.
- id: assess type: AGENT name: Assess the claim preconditionStepId: start timeout: 300000 retries: 0 agent: ref: claims-assessor taskPrompt: "Assess claim ${claimId} against the policy." input: { claimId: "${claimId}", amount: "${amount}" } mcp: [crm] outputVariable: assessmentRequired: agent with ref (a published agent) and outputVariable (the variable its JSON result is written
to). Optional: taskPrompt (text template), input (a template of any shape; absent is {}), mcp / rag /
peers (absent inherits the agent’s, [] disables, a list can only narrow what the agent publishes),
allowSensitiveVariables (true to let taskPrompt and input read the definition’s
sensitive variables — without it such a definition is refused at load).
retries must be 0 (an agent failure is final; restarting the process starts a new invocation); timeout
defaults to five minutes. No model, key or credential in the block.
Dispatched as task run-agent@1 on topic agent-calls, with one variable, __agent (the rendered request), and an
invocationId every reply and cancellation is correlated with. The result must be exactly the outputVariable, as
valid JSON; read it with json:parse(assessment).decision. When the outcome of an effect is uncertain — the runtime
asks for a review, the step times out, the process is cancelled while it runs — the step is REVIEW_REQUIRED and
the process PAUSED until the runtime reconciles it. Works with forEach (one invocation per item). See
Agents in workflows.
AGENT_CALL (removed)
Section titled “AGENT_CALL (removed)”AGENT_CALL (added in 2.32.0) was removed in 2.34.0. A definition that still declares a step of this type
fails to load — in the engine and in the Maven plugin — with: AGENT_CALL was removed in 2.34.0; use the AGENT
step (agents from the IA catalogue). Agents are published in the IA catalogue and run by the IA runtime
through the AGENT step.
A process started before the upgrade that reaches an AGENT_CALL step (or has one running) fails that step,
final, with error code STEP_TYPE_REMOVED in its log: no retry is spent on it, the saga compensates as for any
failed step, and the process ends ERROR. To carry such a process on, migrate it
to a version of its definition that replaces the step, then retry it.
CONTINUE_AS_NEW
Section titled “CONTINUE_AS_NEW”Ends this run — COMPLETED, outcome continued, other branches cancelled as an END does — and starts a fresh
run of the same definition with the same business key and the variables it carries, the two linked
(continuedFrom / continuedAs). Keeps the history of entity- and subscription-style processes bounded. See
Long-running processes.
{ "id": "next-month", "type": "CONTINUE_AS_NEW", "name": "Next month", "preconditionStepId": "bill", "continueAsNew": { "version": "latest", "variables": { "customerId": "${customerId}", "month": "${month + 1}" } } }Optional: continueAsNew.version — same (default: the snapshot this run runs) or latest;
continueAsNew.variables — absent: every variable; a list of names; or a map of name → template over the
process. No step may follow it; no forEach, repeat or loopBack. A child process that continues keeps its
parent step waiting until the last run of the chain ends.
Common fields (all step types)
Section titled “Common fields (all step types)”| Field | Type | Default | Description |
|---|---|---|---|
id | string | — | Unique identifier within the workflow |
type | enum | — | Step type (see above) |
name | string | — | Human-readable name |
description | string | — | Optional description |
preconditionStepId | string | — | Single step that must complete before this one starts |
preconditionStepIds | string[] | — | Steps that must all complete before this one starts; takes precedence over the singular preconditionStepId when non-empty |
preconditionExpression | string | — | JEXL expression; step skipped if evaluates to false |
parallel | boolean | false | Deprecated and ignored — every eligible step runs concurrently; kept only so old files keep deserializing |
outputVariables | string[] | — | PROCESS: child variables copied back into the parent on completion; empty/absent = none. Any step: the names sensitiveOutputs marks sensitive |
steps | step[] | — | PROCESS: the child workflow in line, instead of childWorkflowDefinitionId (exactly one of the two). See Inline body |
sensitiveOutputs | boolean | — | true: this step’s outputVariables are sensitive — encrypted at rest and in transit, masked in the console, REST and MCP. Requires outputVariables. Part of the version |
timeout | integer (ms) | 0 | Max execution time; 0 = no timeout |
retries | integer | 0 | Auto-retry attempts on ERROR or TIMEOUT |
compensable | boolean | false | Trigger compensation step on failure |
compensationStepId | string | — | Step to run as compensation. Required when compensable: true (enforced by the JSON schema) |
onTimeoutStepId | string | — | Step to route to when this step times out (after retries are exhausted) instead of failing the process — the step’s own on-timeout branch. See On-timeout routing |
deadline | moment | — | ACTION, USER_TASK, RULE, WAIT_FOR_MESSAGE, PROCESS, HTTP_CALL, LLM_CALL, and a PUBLISH_EVENT with awaitReply: a moment ({date, offset, at, zone} from the process’s data) by which the step must have finished. Reaching it is a timeout that retries do not extend; with timeout too, the earlier wins; it follows the variables. See Scheduling and Deadlines |
awaitReply | object | — | HTTP_CALL and PUBLISH_EVENT only: {messageName, correlationExpression, onEvent?} — the reply the step waits for after sending its request, armed in the same transaction that sends it. See PUBLISH_EVENT and HTTP_CALL |
onEvent | object | — | WAIT_FOR_MESSAGE only: {destination, type, correlationKey?, filter?, variables?} — a domain event that becomes the step’s message. See Starting on and waiting for domain events |
maxSuccessfulExecutions | integer | 0 | Cap on how many times this step may successfully run within one process instance (backstop against runaway loops). 0 inherits the workflow-level defaultMaxStepExecutions; both 0 = only the loop’s own maxIterations and workflow.loops.max-iterations bound it. Enforced when a repeat or loopBack would run the step again: the step fails instead |
forEach | object | — | ACTION, USER_TASK, PROCESS, HTTP_CALL, LLM_CALL, RULE: run the step once per item — {items, as?, indexAs?, mode?, maxConcurrency?, output?, outputElement?, completion?, onIterationFailure?, label?}. See Loops and Multi-Instance |
repeat | object | — | Same types: run the step again until a condition holds — {until, maxIterations, delay?}. See repeat |
priority | integer | 50 | ACTION, HTTP_CALL, LLM_CALL, RULE: 0–100, higher first. Honoured by the HTTP worker queue, the embedded worker pool and the rate-limit queue; a Kafka topic keeps its own order. See Flow control |
loopBack | object | — | Any step but START/END/REPLY: when it completes and while holds, run every step from to to here again — {to, while?, maxIterations, delay?}. See loopBack |