Workflow Nodes

Some things a graph cannot express as a condition, and the honest answer is to stop:

The run ends as failed at that node, and the sentence you passed is what the run viewer, the run history and the server log all show. Without fail the only way to stop is to throw, and the author’s message then arrives wrapped in whatever shape the script engine gave it.

Give the failure a name — fail('NO_STOCK', …​) — and it stops being the end of the run: an error boundary on this node can catch it and route somewhere else. See Catching a failure.

Three things worth knowing:

track(note) posts a comment on the record’s own message stream, where somebody reading the record will find it — unlike log, which reaches only whoever is reading the server log.

The note is authored by whoever triggered the run when there is one, and by nobody on a scheduled run. It does not email anyone directly — the record’s followers are notified by the same machinery that handles any other comment.

wait="any" is the "either of these will do" shape — two approvals where one suffices, or a review racing a deadline:

The first approval carries the run past the join. The other branch is cancelled and its approval withdrawn, so it disappears from that person’s inbox rather than sitting there for work that is over.

wait="quorum" is the same shape with a threshold — "any two of the three directors", where it does not matter which two:

That is what a count is for, and it is the only way to say it: a threshold is evaluated against the branches the split activated, so it cannot be rebuilt by nesting joins. Nesting gives you conditions over distinct branches (all of X plus any of Y and Z); a quorum is a threshold over interchangeable ones, and writing "any 2 of 3" as a tree of joins would need the same approval to appear twice — two tasks for one person.

Only arrivals count towards the threshold. A branch that reaches an <end> before the join is neither an arrival nor a rejection — it just means one fewer branch that could still arrive. So a rejected approval counts if its flow leads to the join; route it to an <end> if it should not.

Two rules keep a race from waiting for something that can never come:

Branches run one after another, in declaration order, against the same record and the same variables — a split is about which paths are taken, not about running them at the same time.

A branch of a some/all split may wait — on a task or a wait — because such a split always has exactly one join, so there is always a barrier for a woken branch to arrive at. When one branch parks, the engine writes down where every branch of that activation got to, and the join counts them back in as they finish: the run stays waiting until the last branch it is owed reports back, and the join then runs exactly once. Completing one approval never carries the run past a barrier its siblings have not reached.

A branch may wait more than once before its join — two approvals in a row is an ordinary shape — and each branch that waits on a timer keeps its own wake time, so branches with different delays wake independently.

A split may also sit inside a branch of another split, and wait there. Joining the inner join carries that branch on towards the outer one, so the outer join waits for it exactly as it waits for a branch that parked directly.

If a branch fails, the fork fails with it: the run is failed and the approvals its siblings were holding are withdrawn, rather than left clickable on a run that is already over. Deleting the record does the same for every branch: there is nothing left to approve, so the run is cancelled and its approvals go with it.

One structural rule: two branches of the same split may not share any node before their join, except the join itself — or an <end>, since an end does no work. Settling on the same end from two branches is fine, including a shared terminate end: reaching it from either side ends the whole run, so there is nothing to run twice. That is the shape behind "a rejection on either side stops the process":

Anything with real work in it — a script, another task — must instead be given its own node past the join, or moved into its own <call>, rather than shared between branches ahead of it.

Every branch of one run shares a single in-run record, so a fork should accumulate its changes and persist them once past the join rather than save in each branch:

Saving in each branch instead writes the record once per matching branch: every write runs the record’s save hooks and can re-trigger a workflow watching a field that branch just set, and it exposes partly-updated states to anything watching. One save past the join goes from the old state to the final one.

This applies to some/all. A one split runs exactly one branch, so the save() in the branch that acts is already a single write and needs no join.

The name says what happened; the key says what it happened to. Both sides have to agree on both, and nothing checks them across definitions — a <send message="order-paid"> and a <wait message="order_paid"> will simply never meet. Because runs are anchored to a record, the key is usually an id:

The boundary is the point. Nothing about a message park is special to the deadline that bounds it, because a message park is a park.

A <payload> is an expression returning an object, evaluated as the sending node runs and delivered with the message. The receiver reads it as message.data:

The payload is checked only for parsing when the definition is saved. What the expression returns is not knowable until it runs, so the shape of a payload is an agreement between the two sides, exactly like the name they correlate on. A receiver reading a field the sender never sent gets undefined, not an error.

Two things a payload may not contain, both refused at run time with the node failing rather than sending something misleading:

Dates and times arrive as ISO-8601 text ("1980-05-17"), and message.data is an empty object when the sender wrote no payload — never null, so message.data.amount can be read without guarding first.

The row is written in the sending run’s own transaction and delivered afterwards, by the scheduler. That gap is deliberate: it is what makes sending before the receiver has parked work. A message that matches nothing yet stays pending and is offered again on the next poll, so a run that parks a moment later is still woken.

Two consequences worth knowing:

By default a message reaches every run listening for that name and key — several is ordinary, because runs are anchored to records and more than one workflow may care about the same one.

expect="one" says that was not meant to happen. It reports rather than prevents: delivery is asynchronous, so by the time the count is known every match has already been woken and nothing can be taken back. What it buys is that the message says so.

Messages that went nowhere are kept rather than deleted, and their status is where a correlation failure becomes visible at all:

A <send> with signal in place of message announces that something has happened, by name, to everyone waiting for it. Every run parked on that name continues, whichever record each of them is about; the walk passes straight through.

Everything else it shares with a message: the row is committed with the rest of the node’s work and delivered by a later poll, so a signal sent before its receivers have parked still reaches them; it never waits for a receiver; and it is not undone by a later failure in the same walk.

A <call> with no selector at all calls the child once, on this record. Because there is exactly one child, the caller can wait for it:

If order-approval parks — on a task, or a wait — then this run parks here too, at the call node, and resumes at ship when the child reaches its end. A child that fails fails the caller, at the call node, with the child’s own error attached, unless an error boundary on the call node catches it.

Because the caller parks, it can be interrupted like any other park: attach a boundary to give the call a deadline or a get-out condition.

Everything else — any of record, each or filter — is multi-instance: the elements run one after another inside the caller’s walk.

An element may park, which is how one approval per line is written:

Each element becomes its own child run, and each opens its own approval. The caller waits at the call node until every element has come back, then carries on to next — once, however many elements there were. Elements that run to completion without parking behave exactly as they always did, and nothing is written down for them.

A failing element ends the iteration: the approvals its siblings were holding go back, their runs are cancelled, and the caller fails at the call. There is no partial result to reason about.

maxSize caps how many elements a node may run, and it is worth setting when they park — each one is a run row and an approval in somebody’s inbox, not just a step in a long transaction.

A call activity inside a branch of a split fork parks like any other branch: the park belongs to the branch rather than to the run, and the child’s completion brings that branch back to walk on to its join. A failed child fails the branch, which takes the activation down with it — the siblings' approvals go back, the same as any branch that fails.

A <call> names another definition. That definition has an identity, a model and a revision of its own, anyone may call it, and it is isolated: it starts a run of its own, with its own variables, reading the caller’s only through the read-only parent.

A <subflow> carries its graph, and that graph runs inside the caller’s run. It has no identity — nothing else can run it, it is deployed and revised with its caller, and a run parked inside it stays on the revision its caller was pinned to rather than drifting onto a newer one. It shares the caller’s variables, and everything that happens in it belongs to the run: its parks are the run’s parks, and an approval it raises appears on the run’s record whatever the body is standing on.

That last part is the one to read twice. A <subflow each="self.lines"> runs its body over each line, so self inside it is a line — but the approvals it opens are filed against the order, and only there. Forty lines out for approval are forty approvals on one order, told apart by the line each one names: a node’s title is static, so the approval carries the element it was raised over and the inbox shows that beside the title. A model with no name field has nothing to show there, and those rows do read alike. A <call each="self.lines"> does the opposite: forty runs, each about a line, with its approval on that line.

So: reuse across definitions is a <call>; a region of this process is a <subflow>. They are BPMN’s callActivity and subProcess, and mean the same things — a call activity starts a new process instance, an embedded sub-process is part of the one it is written in.

A <subflow> is entered from its own node and from nowhere else, so on, message, watch, repeat, delay and unit are all refused on its <start>. when is allowed and is the useful one: it gates each element, exactly as a called workflow’s own start condition does.

Node ids are scoped to it, so it may reuse ids its caller already has — handy when the same shape is written twice.

And a <subflow> may not contain another. One level is what a diagram can show and a reader can hold; a region that wants a region of its own is a workflow of its own to <call>.

There is one rule, and it is the one every scope in the engine follows:

So an author says which they meant by where they first wrote the name, and declares nothing:

Both halves survive a pause. A body that parks on an approval finds its own names again when it resumes, and the caller sees what the body wrote to its names — but never what the body kept to itself.

This is the reason the node exists.

A boundary watches a stretch of process, not a node. Attach one to a <subflow> and it is armed from the moment the walk enters the region until the moment it leaves — however many threads are inside, and wherever each of them has stopped.

"Every line approved within seven days, or escalate." The seven days are measured from when the order reached the node, not from when any one line happened to park. If the deadline passes with two of forty still out, the boundary fires once: the two approvals still open are withdrawn, nothing is left waiting, and the run continues from escalate. A non-interrupting boundary (cancel="false") runs its own branch beside the region and leaves it going.

This is the one thing a <call> cannot do. Its elements are runs of their own with nothing holding them together, so a deadline on the node could only ever mean a deadline per element — which is a boundary inside the child, and what BPMN prescribes there. boundary-host-invalid still says so for a <call>.

A timer or condition boundary needs a region that can stop: a body that runs straight through has no more to interrupt than a script does, and boundary-host-invalid says so. An error boundary needs no park and catches a failure raised anywhere inside.

A body parks in the run: when it stops, the run stops at the subflow node, and an iterating body opens one approval per element and waits for all of them before the run carries on past next.

One limit is worth knowing: a filter source needs model, since a query has to be a query against something.

when, on its own, only gates completion: a person can still always decide, but Approve is refused while it is false and allowed once it holds. autoComplete is a separate, opt-in step further — letting the condition resolve the task itself, with nobody deciding at all:

Without autoComplete, the last two never happen: the condition only ever gates a person’s own decision, and a pending task stays pending — however true it becomes — until somebody clicks Approve. autoComplete and <blocked> both require when, and are rejected without it.

Some approvals should only ever be completed, never rejected — a step that is a formality once reached, or one where "no" has to be escalated rather than recorded. allowReject="false" refuses a rejection on the task entirely; the person can still act, just not that way. allowForceComplete="false" similarly withdraws the one override even an admin normally has, for a task where nobody should be able to skip the check it exists to make, and allowCancel="false" withdraws the other: the run cannot be abandoned from an approval that has to be answered. All three default true, and none is related to when, which never gates any of them.

Note what allowCancel="false" does not do. A run parked on such a task can still be ended — by a boundary that withdraws the task on a deadline or an event, which is a route the workflow itself declares. What it refuses is the unplanned exit: an administrator discarding the run from the approval screen.

Each setting is snapshotted onto the task when it parks, so the approval screens draw only the buttons the node allows — a withdrawn action is absent rather than offered and then refused. The service checks again when the action is attempted: the snapshot shapes the screen, it never authorizes.

A rework loop — reject, fix, submit again — is an ordinary shape, and nothing stops it going round for ever. maxVisits on a task or a wait is the one guard the engine can honour: when the run reaches the node for the maxVisits+1-th time, it fails there instead of parking again, with a message naming the node and the limit.

Only the nodes that park carry a limit, deliberately: their count is durable across resumes at every trace level, while an ordinary node’s is known only within the current segment of the walk, and the engine does not promise what it cannot keep. Scripts can read the same count as visit. When a node declares no maxVisits, the workflow.node.max-visits option applies; unset, there is no limit.

A boundary declared cancel="false" fires without closing anything: the park stays open, and the run starts a second, independent path from the boundary’s own next alongside it — see Monitoring runs for where that path shows up.

A timer boundary like remind fires once per park. To chase somebody more than once, give it a repeatCount rather than writing one boundary per reminder — each occurrence falls one delay further from the park than the last.

That nudges the approver a day after the run parked, again on days two and three, and then goes quiet. Every occurrence starts its own escape branch. Occurrences already overdue — after downtime, say — are taken one per scheduler pass rather than all at once.

A condition boundary is edge-triggered instead: it fires when its when becomes true, and is armed again once the condition has dropped and comes true a second time. It needs no count.

A run whose own walk has already finished holds at waiting — never completed or failed — while a branch it spawned is still going, and settles once the last one ends.

on="error" is the odd one out. Its host is a node that runs rather than one that parks, nothing arms it, and it is consulted where the failure is raised rather than by the scheduler. It is how a path that did not work out becomes a route rather than the end of the run:

Three things to know before relying on it.

A code catches only a failure raised under that name; no code catches any. fail() and an <end error="…​"> raise a named failure, and an agent that did not answer or a send the email provider refused raise one without a name. A boundary without a code also catches what merely escaped — a null dereference in a script, a bad field name — so a mistake there takes the boundary’s path instead of failing the run. The node’s visit still records the error, so check the run history when a handler fires more often than expected. A failure that left the transaction unable to commit, such as a constraint violation on save, is never caught: nothing the handler wrote could be saved.

Nothing is rolled back. A failing node’s writes are committed with the rest of the dispatch, so the handler resumes from a record the failed node may already have changed. Treat a handler as compensation, not as a retry: it should assume the work was partly done. The one exception is a multi-instance call, whose elements run inside the caller’s own transaction — there a failing element does take the caller back with it, as the warning under call says.

A failure reaches no run that is not an ancestor of the failing one. It travels up — a <call> child’s uncaught failure is offered to an error boundary on the <call> node that called it — and never sideways to an unrelated run. That is the whole difference from a broadcast.

The node is still recorded as failed, whether or not a boundary catches it: a boundary changes where the run goes next, not what happened.

The boundary’s path reads what it caught as error: error.message is the failure’s text and error.code its name, or null when it has none. Like agent, it stays bound along that path, across any park, until another caught failure replaces it or a join ends the branches:

Each of these is caught when the workflow is saved or loaded, naming the boundary and its host.

The split above reads agent.result.urgency, which is a promise nobody made. If the agent answers in prose instead of JSON, agent.result is that prose, urgency is absent, and the split quietly takes its default branch: the run succeeds and the ticket is routed wrongly. Nothing distinguishes the agent did not answer in the shape we wanted from the field was absent.

An <output> child closes that gap. It is described to the agent as part of the prompt, and the answer is checked against it before any later node can read it.

A string field may also list the values it accepts:

The list is sent to the agent and checked on the way back. Matching is exact and case-sensitive: High is not high, and nothing is trimmed or repaired — a near-miss is precisely what a split would route on wrongly rather than notice. Options are for strings only; on any other type they would read as a constraint and do nothing, so they are rejected.

A model that has called tools often wraps its answer in a code fence or leads with a sentence. Where a shape is declared, the one JSON object the answer holds is read out of that wrapping; text with no object in it still fails the node. Three things fail the node, each naming what went wrong: an answer that is not a JSON object at all, a missing required field, and a field whose value has the wrong type. Failing is the point — the alternative is routing a record on a field the agent never gave. An optional field may simply be absent, and the workflow decides what that means.

There is no nesting: a nested shape is type="object", and what you read inside it is at your own risk. Declaring nothing keeps the old behaviour exactly — whatever the agent said is bound as-is.