Route, repeat, and parallelize steps

What these nodes do

Control-flow nodes decide which steps run, how many times, and in what order. You add them from the Add node panel under the System tab, in the Control Flow category.

• Branch sends a run down a different path depending on whether each condition is true.
• Switch evaluates one value and routes to the case that matches it.
• Loop repeats a path a fixed number of times, until a condition is met, or once per item in an array.
• Parallel runs two or more paths at the same time and merges their outputs.

This page covers configuring each node and merging branches back together. To write the expressions that conditions and selectors read, see Expressions.

When to use each node

Configure a Branch node

A Branch node holds a list of conditions. Each condition routes to its own output path. You can also add a default path for runs that match no condition.

1. Add the Branch node

   Open Add node, switch to the System tab, and choose Branch from the Control Flow category. Connect your upstream step into it.

2. Write each condition

   A condition has three parts: a field (a JSONata path into upstream data, such as $trigger.order.total), an operator, and a value. Pick the operator from the fixed list:

   Operator	Needs a value?
   Equals	Yes
   Not Equals	Yes
   Contains	Yes
   Not Contains	Yes
   Greater Than	Yes
   Less Than	Yes
   Exists	No
   Not Exists	No

   Exists and Not Exists ignore the value box. Every other operator needs a non-empty value.

3. Combine conditions with AND or OR

   Set the logical operator between conditions to AND or OR. A Branch node requires at least 2 conditions and allows at most 8. Connect each condition's output handle to the path that should run when it matches.

4. Add a default path (optional)

   If you want a fallback for runs that match no condition, connect the node's default path handle to a downstream step. It is fine to leave the default path unconnected: a run that matches no condition simply ends at the Branch. Publishing shows no warning for it. An assistant building the workflow for you sees a note about it when it validates the draft or previews the publish.

Configure a Switch node

A Switch node evaluates one selector expression, then compares its result against each case's value and routes to the first match.

1. Set the selector

   Enter a selector, a JSONata expression that produces the value you want to route on, for example $trigger.status or $steps.classify.data.output.label. The selector cannot be empty and must be valid JSONata.

2. Add cases

   Add at least one case. Each case has a value to match and a unique path ID; you can also give it a label and description. Connect every case to the step that should run when it matches.

3. Choose a match mode

   The match mode controls how the selector value is compared to each case value. The default is Strict.

   Match mode	Value	Behavior
   Strict	strict	Exact match with type coercion for common cases (for example, "123" = 123).
   Loose	loose	Attempts type coercion before comparison.
   Regex	regex	Case values are treated as regex patterns (strings only).
   Contains	contains	Checks if the selector value contains the case value (strings/arrays).

4. Choose no-match behavior

   Decide what happens when nothing matches. The default is Default.

   No-match behavior	Value	Result
   Default	default	Take the default path if configured, otherwise complete the workflow.
   Error	error	Fail the step (code SWITCH_NO_MATCH) if no case matches and no default path is connected.
   Skip	skip	Skip execution and complete the workflow gracefully.

   If you set a default path, connect its handle to a downstream step. If no default path is connected and No match behavior is Default (or you configured a default path and left it unwired), publish and validation warn that runs end at this step without doing anything. Error mode fails the step instead, and Skip with no default path is an explicit choice, so neither warns.

Configure a Loop node

A Loop node repeats a path. It has two output handles: continue (the loop body that runs each pass) and exit (the path taken once looping finishes). Connect both, or the publish gate warns that one is unconnected.

1. Pick a loop type

   Choose how the loop decides when to stop:

   Loop type	Value	What it needs
   Fixed Count	count	Runs a fixed number of times.
   Condition-based	condition	A non-empty exit condition expression; repeats until the condition is met.
   Array Iteration	array	A non-empty arrayPath, a dot-notation path to the array, for example data.items.

2. Set the maximum iterations

   Every loop requires Maximum Iterations. The range is 1 to 1000. A cap above 500 raises a warning because high caps increase execution time and cost.

3. Reference the current item inside an array loop

   Inside the body of an Array Iteration loop, two bindings are available: $currentItem (the current element) and $currentIndex (its zero-based position). Use them in any field inside the loop body, for example $currentItem.email.

4. Choose an execution mode (array loops only)

   Array loops run sequential by default. Switch to parallel to process items concurrently. Parallel mode is only valid for Array Iteration loops; sequential loops must not carry the parallel-only fields.

   When you choose parallel, set:

   • Max Concurrent Iterations (maxConcurrency), range 1 to 50, default 10.
   • An error policy, one of:

   Error policy	Behavior
   Continue on error	Collect failures and still succeed (default).
   Collect errors	Succeed if all items pass, fail otherwise.
   Fail fast	Cancel remaining iterations on the first failure.

   An empty array is not an error in either mode: the loop runs zero times and takes its exit path.

Configure a Parallel node and merge branches

A Parallel node runs two or more branches concurrently. Each branch is one outgoing path. Their outputs come back together at the join, where a merge strategy combines them.

A path inside a branch that ends, such as a handled error path with no next step or a Branch with no matching condition, ends that branch. The join still waits for the other branches, and the steps after it run.

1. Define branches

   A Parallel node ships with two branches ("Branch 1", "Branch 2") and requires at least 2. Each branchId must be unique and non-empty. Connect each branch to the path it should run.

2. Choose a completion mode

   The completion mode sets when the block is considered done. The default is all.

   Completion mode	Value	Behavior
   All	all	Wait for every branch. Cancel on a non-skippable failure.
   Race	race	First successful branch wins, remaining branches cancel. Requires at least 2 branches.
   Settled	settled	Wait for all branches regardless of failures.
   Independent	independent	Fire and forget. Branches run with no barrier.

3. Choose a merge strategy

   The merge strategy decides how branch outputs combine at the join. The default is array. This is only meaningful when the completion mode is not independent.

   Merge strategy	Value	Result
   Array	array	Each successful branch's output, keyed by branchId.
   First	first	The output of the first successful branch in definition order.
   Merge	merge	Successful branch outputs shallow-merged into one object.

4. Set per-branch and group limits (optional)

   Tune these when you need them; all default to "off":

   • skipFailure (per branch, default false, shown as Skip failure): only matters in All mode. When Enabled, the other branches keep running if this branch fails; when Disabled, this branch failing cancels the branches still running.
   • branchTimeoutMs (per branch, default 0 = no timeout) and groupTimeoutMs (whole block, default 0 = no timeout). Both must be non-negative.
   • maxConcurrency (default 0 = unlimited). A value larger than the branch count raises a warning. Must be non-negative.

After the join, downstream steps receive a structured output:

• results is an array of branch results, ordered by branch definition (not completion order).
• mergedData holds the successful branches' data, keyed by branchId.
• summary reports counts (succeeded, failed, cancelled, timedOut, total) and a releaseReason of all_completed, failure_threshold, race_winner, or timeout.

Read these with $steps, for example $steps.parallel1.data.summary.succeeded or $steps.parallel1.data.mergedData.branch-0.

Verify your configuration

Each control-flow node has a test button in its configuration panel ("Test branch", "Test switch", "Test loop"). Testing runs the node for real against pinned upstream output, so route decisions reflect actual data.

The test button only fires once the node is valid. For example, an unconfigured Switch shows the tooltip "Configure a selector and at least one valid case before testing." Configure the node until the button enables, then run the test and confirm the run took the path you expected. See Test a node and publish for the full test-then-publish flow.

Troubleshooting

These messages come from the publish gate. A version cannot enter the live cohort until every one clears.

A common case worth calling out: when you add a Branch condition or Switch case but forget to connect its handle, publish still succeeds, and the toast warns Branch "<step name>" condition <n> (handle: condition-<i>) has no following node — the run ends when this path is taken or Switch "<step name>" case "<label>" (pathId: <id>) has no following node — the run ends when this path is taken. A Switch in Default no-match mode with no connected default path warns that when no case matches, runs end at the step without doing anything. A Branch with no default path publishes without a warning, because ending the run when no condition matches is a normal way to build. Inside a Parallel branch or a parallel Loop item, an unmatched Branch ends only that branch or item, and the rest of the run carries on. Connect every condition and case you expect to continue to a downstream step, and connect a default path unless you want unmatched runs to end there. The same applies to a Loop: connect both the continue and exit handles. For the complete publish-gate reference, see Fix publish errors.

Related

• Expressions for the JSONata aliases conditions and selectors read.
• Test a node and publish for testing nodes and clearing the publish gate.
• Fix publish errors for the full list of validation messages.