Flow Connector

Overview

In-process control-flow primitives — branching, looping, parallelisation, error handling, and timing — for use inside runbooks. No external service is called and no credentials are required; every action runs entirely within the Xurrent runbook engine.

Prerequisites

• Access to the Xurrent runbook builder. This connector ships pre-installed; no additional setup is needed.

Authentication

None — runs in-process. No connection needs to be configured.

Triggers

None — this connector exposes actions only.

Actions

If-then-else

Branches on a boolean condition. Routes execution to the True sub-block when the condition is truthy and, optionally, to the False sub-block when it is falsy.

Use case: gate a downstream action on a query result, a comparison, or any boolean-coercible value.

Input Parameters

Parameter	Type	Required	Default	Description
condition	Boolean	Yes	-	The branch selector. Strings such as "True", "true", "F", "false" are coerced to booleans before evaluation.
include_false_path	Boolean	No	true	When false, the False sub-block is removed from the runbook tree and a falsy condition produces no output.

Example Input

{ "condition": true, "include_false_path": true }

Output

Two output schemas — true and false. Each carries a single field:

Field	Type	Required	Description
result	Boolean	Yes	Mirrors the input condition.

Only the matching schema fires per run. When include_false_path is false and condition is falsy, no schema fires and no nested actions run.

Example Output

true schema:

{ "result": true }

false schema:

{ "result": false }

Error Handling

A missing condition fails input validation before the action runs. Otherwise the action does not raise.

Best Practices

• Set include_false_path to false when only the True branch is meaningful — it keeps the runbook tree readable.
• For three or more branches, use Case instead of chaining nested If-then-else actions.

Case

Matches a string expression against a list of candidate values; routes execution to the matching sub-block, or to the Else sub-block when no candidate matches.

Use case: branch on a status field, an event type, or any string with more than two possible values.

Input Parameters

Parameter	Type	Required	Default	Description
expression	String	Yes	-	The value to match.
matches	Array of String	Yes	-	Candidate values; one output schema is created per entry. Maximum 50 entries.
include_else_path	Boolean	No	true	When false, the Else sub-block is removed and a non-matching expression produces no output.

Example Input

{
"expression": "baz",
"matches": ["foo", "bar", "baz", "boo"]
}

Output

One output schema per matches entry (named after the match string), plus optionally an else schema. Each schema carries:

Field	Type	Required	Description
expression	String	Yes	The expression that selected this branch.

Only the matching schema fires per run.

Example Output

baz schema (matched):

{ "expression": "baz" }

else schema (no match):

{ "expression": "unknown" }

Error Handling

A missing expression or matches, or a matches array longer than 50 entries, fails input validation before the action runs.

Best Practices

• Output schema names cannot be remapped from the runbook builder; each branch is named after its match string, which keeps a long Case action readable.
• For a binary branch, use If-then-else — its boolean coercion handles strings like "True" and "F".

Section

A pure passthrough that groups child actions under a named section in the runbook tree. No data transformation.

Use case: organise a long runbook into logical sub-blocks, or scope a sub-tree visually for readability.

Input Parameters

None.

Example Input

{}

Output

One output schema, nested_section, with no fields.

Example Output

{}

Error Handling

None — Section has no failure modes of its own.

Best Practices

• Use Section purely for organisation. Variables, retries, and error handling all live in dedicated actions; Section adds no semantics beyond grouping.

Fork

Starts N parallel sub-blocks. Each branch receives its own zero-based index.

Use case: run independent operations in parallel — e.g. notify two chat channels simultaneously, or fan-out the same lookup to several systems.

Input Parameters

Parameter	Type	Required	Min	Max	Description
nr_of_actions	Integer	Yes	2	50	Number of parallel branches.

Example Input

{ "nr_of_actions": 4 }

Output

One output schema per branch (fork-0, fork-1, …, fork-<N-1>). Each schema carries:

Field	Type	Required	Description
index	Integer	Yes	Zero-based branch position.

All N schemas fire per run, in parallel.

Example Output

Branch outputs for nr_of_actions = 4:

[
{ "index": 0 },
{ "index": 1 },
{ "index": 2 },
{ "index": 3 }
]

Error Handling

nr_of_actions outside [2, 50] fails input validation.

Best Practices

• Branch references stay stable when nr_of_actions shrinks back from a higher value — wiring on the first N branches is preserved across changes.
• Use Fork when each branch performs a different operation. Use Loop when the number of branches is driven by a list of values.

Loop

Iterates over an array, running the nested sub-block once per item. Each iteration receives the current item and a zero-based index.

Use case: process each row of an upstream query result, send one notification per recipient, or apply a transformation to each entry of a list.

Input Parameters

Parameter	Type	Required	Default	Description
items	Array of Any	No	-	The list to iterate. Each entry triggers one iteration. An empty array runs the nested sub-block zero times.

Example Input

{ "items": ["foo", "bar", "baz"] }

Output

One output schema, loop, fired once per item:

Field	Type	Required	Description
item	Any	Yes	The current entry.
index	Integer	Yes	Zero-based position in items.

Example Output

Per-iteration outputs for the input above:

[
{ "item": "foo", "index": 0 },
{ "item": "bar", "index": 1 },
{ "item": "baz", "index": 2 }
]

Error Handling

An empty or absent items array yields zero iterations — the nested sub-block does not run and no error is raised.

Best Practices

• Iterations run sequentially. For independent work, use Fork when the count is fixed.
• When each item drives an external API call and the target API supports bulk requests, use Batch to amortise per-call overhead.

Batch

Splits an array into fixed-size chunks and runs the nested sub-block once per chunk. The final chunk may be smaller.

Use case: feed a bulk-write endpoint that accepts an array of items per call (e.g. "update up to 100 records per request"), or amortise per-call overhead across many small items.

Input Parameters

Parameter	Type	Required	Min	Description
items	Array of Any	Yes	-	The source array to chunk.
batch_size	Integer	Yes	2	Items per chunk.

Example Input

{ "items": [1, 2, 3, 4, 5], "batch_size": 2 }

Output

One output schema, batch, fired once per chunk:

Field	Type	Required	Description
items	Array of Any	Yes	The items in this chunk. The final chunk may contain fewer than batch_size items.

Example Output

Per-chunk outputs for the input above:

[
{ "items": [1, 2] },
{ "items": [3, 4] },
{ "items": [5] }
]

Error Handling

Missing items or batch_size, or batch_size < 2, fails input validation. An empty items array yields zero chunks.

Best Practices

• Match batch_size to the target API's bulk-endpoint maximum (e.g. 100 for many REST APIs, 25 for AWS DynamoDB BatchWriteItem).
• Downstream actions should treat the per-chunk items.size as variable — it equals batch_size for every chunk except, potentially, the last.

Fail

Stops the runbook and marks the run as Failed, with an optional message logged to the run.

Use case: assert an invariant — fail the run if upstream data is missing, malformed, or violates a business rule.

Input Parameters

Parameter	Type	Required	Default	Description
message	String	No	Stopped	Text logged on failure.

Example Input

{ "message": "No matching account found for the supplied ID" }

Output

None — the action terminates the runbook and the run ends in the Failed state.

Example Output

Not applicable.

Error Handling

Always terminates the runbook with message. The run ends in the Failed state.

Best Practices

• Pair Fail with If-then-else or Case — branch into Fail when an invariant breaks, rather than letting an unhelpful runtime error surface later.
• Make message actionable: include the failing value, not just "validation failed".

Finish

Stops the runbook and marks the run as successfully Finished at this step. Logs message to the run.

Use case: short-circuit out of a runbook when there is no further work to do — e.g. an early return after detecting a no-op condition.

Input Parameters

Parameter	Type	Required	Default	Description
message	String	Yes	Runbook execution completed	Text logged on completion.

Example Input

{ "message": "Already up to date — nothing to do" }

Output

None — the action logs message and terminates the runbook. The run ends in the Finished state.

Example Output

Not applicable.

Error Handling

Always terminates the runbook with message. This is a successful exit — the run is marked Finished, not Failed.

Best Practices

• Use Finish only for clean, intentional early exits. For unexpected conditions, use Fail so the run is recorded as failed.
• Make message describe why the runbook is exiting — operators see this in the run log.

Try-catch

Wraps a Try sub-block in error handling. If any action inside Try raises, the runbook engine re-runs this action and routes execution down the Catch sub-block, passing the error message.

Use case: handle expected failures from external systems — a 4xx response, a missing record, a transient network error — without failing the whole runbook.

Input Parameters

None.

Example Input

{}

Output

Two output schemas — try and catch. Exactly one fires per invocation.

try schema — no fields.

catch schema:

Field	Type	Required	Description
error	String	Yes	Error message from the action that raised inside Try.

Example Output

try schema (no error inside Try):

{}

catch schema (an action inside Try raised):

{ "error": "Something went wrong" }

Error Handling

Routing is automatic. On the first invocation the Try schema fires. If a child action of Try raises, the runbook engine re-invokes Try-catch with internal state set so the Catch schema fires next, with error populated from the raised exception's message. Exceptions outside the Try sub-block are not caught.

Best Practices

• Catch only failures you know how to handle. Letting an unrecoverable error surface is usually safer than catching it and continuing on bad data.
• Pair Try-catch with Retry at the end of the Catch sub-block to re-run Try after a remediation step. Without Retry, execution falls through to the next sibling action after Catch completes.
• The error field is a string — to retain structured information, encode it into the message at the source (e.g. JSON-encode a hash before raising).

Retry

Re-runs the surrounding Try-catch action's Try sub-block. Must be placed inside a Catch sub-block.

Use case: handle transient failures by re-attempting the original operation after the catch path has logged or remediated the error.

Input Parameters

None.

Example Input

{}

Output

A single output schema with no fields.

Example Output

{}

Error Handling

When reached inside a Catch sub-block, control returns to the surrounding Try sub-block. Placed outside a Catch block, Retry has no error-handling effect — it simply exits with an empty output.

Best Practices

• The classic transient-retry pattern is: Try-catch with the flaky action inside Try; Wait at the start of Catch to back off; Retry at the end of Catch to re-attempt.
• Guard against infinite retries: combine Retry with a counter (e.g. a runbook variable incremented in the catch path) and switch to Fail once a retry budget is exhausted.

Wait

Pauses the runbook for at least seconds_to_wait seconds before continuing. Reports the actual elapsed time.

Use case: insert a deliberate delay between actions — back off before retrying, give an upstream system time to settle, or schedule the next step.

Input Parameters

Parameter	Type	Required	Min	Description
seconds_to_wait	Integer	Yes	0	Minimum number of seconds to wait. The actual wait may be longer; never shorter.

Example Input

{ "seconds_to_wait": 60 }

Output

One output schema, actual:

Field	Type	Required	Description
started_at	Time	Yes	When the wait began.
requested_wait	Integer	Yes	The configured seconds_to_wait.
completed_at	Time	Yes	When the wait ended.
actual_wait	Integer	Yes	Seconds elapsed between started_at and completed_at. Always >= requested_wait.

Example Output

{
"started_at": "2026-04-28T09:00:00Z",
"requested_wait": 60,
"completed_at": "2026-04-28T09:01:02Z",
"actual_wait": 62
}

Error Handling

When seconds_to_wait > 0, the first invocation suspends the action on the queue and returns no output. The runbook engine resumes the action after the wait elapses, at which point the actual schema fires with the timing fields above. When seconds_to_wait is 0, the action completes on the first invocation with started_at completed_at.

Best Practices

• actual_wait can exceed requested_wait because the engine schedules pickup on its own queue. Branch on actual_wait if exact timing matters downstream.
• For exponential backoff inside a retry loop, drive seconds_to_wait from a runbook variable and double it each iteration.

Runbook Concepts

The Flow connector is the most direct demonstrator of three runbook-engine concepts. They appear in the action descriptions above; this section names them once for reference.

• Nested actions — actions marked nested in this connector (every action except Fail, Finish, and Retry) host child actions in the runbook tree. Each nested action emits one or more output schemas, and the runbook builder lets you wire child actions under each schema.
• Output schema selection — when a nested action emits multiple output schemas (e.g. If-then-else's true/false, Case's per-match schemas, Try-catch's try/catch), only the schemas that fire on a given run propagate to their wired child actions.
• Iteration — Loop, Batch, and Fork fire their output schema multiple times per run, once per item / chunk / branch. Wait and Try-catch also use the iteration mechanism internally to suspend and resume.

Best Practices

• Use Flow for control flow only. Reach for the Ruby connector when you need to transform or compute over data — Flow has no expression evaluation of its own.
• Keep nesting shallow. Each level (e.g. If-then-else inside Loop inside Fork) compounds the runbook's state space and makes failures harder to localise.
• Branch with If-then-else for two paths and Case for many. Don't chain four If-then-else actions when Case would do.
• Use Fail with a specific message when a precondition breaks; Finish marks the run as successful, which is wrong for a precondition violation.
• Reach for Try-catch + Retry + Wait for transient failures from external connectors. For permanent failures, route into Fail instead — retrying a 404 doesn't help.
• Avoid Loop for very large arrays — its sequential model means N items take N times longer than one. Switch to Batch when the downstream action has a bulk endpoint, or Fork when items are independent and the count is fixed.

Common Use Cases

• Branch on a query result — call a lookup action, then If-then-else on whether it returned a record. Wire the True branch to the update path and the False branch to the create path.
• Process a list — chain a list-fetching action into Loop; nest the per-item action inside.
• Bulk-write items — chain a list-fetching action into Batch with batch_size matching the target API's bulk-endpoint maximum; nest the bulk-write action inside.
• Fan out to parallel destinations — chain a payload-builder action into Fork, with one child sub-block per destination.
• Retry a transient failure — wrap the flaky action in Try-catch, add Wait at the start of Catch to back off, end Catch with Retry.
• Assert an invariant — chain the validating action into If-then-else; route the failure branch to Fail with a descriptive message.
• Short-circuit on a no-op — chain a status-check action into If-then-else; route the "nothing to do" branch to Finish.
• Group sub-trees — wrap a logical sub-tree in Section to keep the runbook readable.

References

• For data transformation, computation, or building structured payloads — Flow has no expression evaluation; use Evaluate Ruby Code on the Ruby connector.
• For state that persists across iterations — define a runbook variable on the Runbook Variables connector and update it inside Loop, Batch, or a Try-catch Catch block to track retry counts, accumulators, or progress flags.