> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Compose a workflow

> Author a workflow as a directed graph: pick node types, wire typed inputs and outputs, reference workflow inputs by name, choose validation strategies and set capability hints.

Last updated 2026-11-11

·
applies to 2026-11-03

·
main

This guide is for the operator authoring a workflow — picking the right node types, wiring typed I/O, choosing validation strategies, and setting capability hints. The thing you are filling in is a graph stored across workflowGraphNodes and workflowGraphEdges; the thing it becomes is a durable, auditable pipeline.

This page is about authoring decisions. For the conversational AI authoring path, see [Use the Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md) — the right starting point for \~80% of new workflows. For the runtime semantics of nodes and edges, see the [The workflow graph](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph). For what happens after publish, see [Workflow Execution](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md).

When to reach for something else

If your task is a single agent answering a single question with no human gate, no fan-out, and no downstream node — open a chat session, don't author a workflow. Workflows pay a fixed cost: a row to maintain, a graph to validate, a Trust Fabric pipeline to satisfy on every node. The investment is worth it when the same shape will run more than a few times, when steps need to be auditable individually, when a human needs to approve before something irreversible happens, or when the pipeline must be restartable from a checkpoint. If the answer is "I just want one agent to do one thing," ship a chat session or an inline prompt instead.

***

## The mental model — graph, not script

A **workflow** is a directed acyclic graph. Nodes do work; edges carry control and information. When a workflow runs, the durable orchestrator walks the graph, dispatches each ready node, advances when results land, and repeats until the graph is terminal. That's the entire model.

Workflows are how Forge turns "something we want done" into "something we can run, observe, and audit." They replace ad-hoc scripts with a shape you can inspect, version, and hand off — rows in `workflowGraphNodes` and `workflowGraphEdges` keyed polymorphically to a `workflowVersions` row (published, immutable) or a `workflowDrafts` row (editable workspace).

A run pins a specific `versionId` (or `draftId` for test runs) at launch and is frozen for the duration. Publishing a new version never affects in-flight runs. Rolling back is a republish.

***

## Decide first: prescriptive or delegated?

TWO RUN STYLES

<ol aria-label="TWO RUN STYLES" />

**Prescriptive runs** walk the graph step by step. No LLM tokens spent on orchestration decisions — the DAG *is* the plan. Fully auditable, fully restartable, predictable cost. Use this when the process is well-understood, the handoffs are known, and compliance needs a reproducible trail. Most workflows are prescriptive.

**Delegated runs** hand a goal and a bounded set of guardrails (cost cap, duration limit, handoff limit, approval gates) to an agent. The agent decides what to do within authority. Cheaper to set up; harder to audit step-by-step. Use this when adaptive reasoning matters more than a fixed sequence.

Both run types share the `workflowRuns` table — same status machine, same observability, same cost attribution. They fill different fields. The rest of this guide is about prescriptive composition; for delegated runs, the authoring step is the agent definition plus the run-time guardrails, not the graph.

***

## Pick node types

The whole vocabulary:

| Type | Purpose |
| - | - |
| Agent | Produces a result via an AI or human agent. Reads inputs, runs a turn, passes outputs downstream. When the resolved worker is an agent, Forge composes the agent and runs its turn. When the resolved worker is an EMPLOYEE or CONTRACTOR, the step becomes a human task, syndicated to Slack / chat / Console, and blocks until the human responds — with declarative timeout behaviour. The backbone of every workflow. |
| router | Picks which outgoing edges to follow. Rules-based (deterministic) or LLM-based. Supports multi-select. |
| join | Synchronises fan-in. Waits for `all`, `any`, or `n_of_m` incoming branches before continuing. |
| publish | Terminal delivery — Slack, chat, email, storage, or HTTP API. Always prefer publish over a `produce` node that side-effects an external system. |
| notify | Always notifies people. Records a bell, Slack, or email notification for Forge people (the run starter, the workflow owner, a person, an org unit's members) and Slack channels, then completes; delivery follows per notification. Never takes a raw email address. |

**Agent** is the shared workflow node for AI and human work. In its properties, choose **Assigned to → AI**, **Human**, or **Role**. The existing API/storage discriminator remains `produce`; the resolved worker kind determines how the task executes.

For each type's full field surface, see [The workflow graph](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph).

### A decision table for "which node?"

| Situation | Node type |
| - | - |
| Produce, analyse, or transform content with an agent | Agent (AI) |
| Wait for a person to review, approve, or add context | Agent (Human — EMPLOYEE / CONTRACTOR) |
| Branch based on a classification or condition | `router` |
| Collect multiple parallel branches before proceeding | `join` |
| Deliver a final artifact to Slack / chat / email / storage / API | `publish` |
| Tell people that something happened — a bell, Slack post, or email that must not depend on an agent choosing to send it | `notify` |
| Mutually exclusive branching | `router` with `multiSelect: false` |
| "Any of these apply" parallel branching | `router` with `multiSelect: true` |
| Boolean branching on an agent's structured output | Conditional **edges** — no router needed |
| Branching on a human's approve / reject | Conditional **edges** on the Agent node assigned to that person — not `onError`, not a router |
| Error-handler lane | Edge with `onError: true` — only for genuine failures |
| Fork into parallel work | Multiple unconditioned edges from the same node |

***

## Wire typed I/O

Every non-terminal node declares `inputs` and `outputs`. Types: `string`, `number`, `integer`, `boolean`, `object`, `array`, `date`, `month`, `file`, `string[]`, `number[]`, `file[]`.

* **Inputs** wire from upstream: `source: { nodeId, output }` — pull from another node's output. Or `source: { workflowInput: "key" }` — pull from the run's runtime arguments. Or `literal` — a constant fixed at authoring time, which may embed [`{{workflow.<name>}}` references](#reference-a-workflow-input-from-inside-a-node).
* **Outputs** are the node's declared contract. Other nodes reference them by key.
* **Files** flow as opaque `fileId` references. Bytes remain behind the Files-and-Bindings service; the bound reference moves between nodes.

A `file` or `file[]` output injects `putFile` at dispatch. The agent binds the file to the declared output key and returns its `fileId`, not raw content. Validation refuses unbound ids and raw bytes. See [Files and bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md).

Keys are stable contracts. Renaming an output without updating downstream wires breaks the graph; the validator catches it but the fix is the wire, not the validator.

***

## Ask each question once

A workflow's input contract has three kinds of entry. Only one of them is a question.

| Kind | Who supplies it | Rendered as |
| - | - | - |
| **Parameter** | Whoever launches the run | An editable field in every dispatch surface |
| **Derived** | Computed at launch from the parameters | A read-only preview. Never asked, never editable |
| **Asset** | Bound once at the workflow level | The current binding, replaceable with `workflows:manage` |

The distinction matters because a flat contract quietly turns every encoding a
node happens to need into a human question. A monthly close that genuinely
decides one thing — *which month* — ends up asking for the month, its first
day, its last day, a display label, and a fiscal-period token, then trusting
the operator to keep all five consistent. Four of those are functions of the
first.

Declare the decision as a parameter and compute the rest:

```json theme={null}
[
  { "name": "period", "type": "month", "required": true,
    "defaultExpr": "previousMonth(today())" },

  { "name": "periodStart", "type": "date", "required": true,
    "derived": { "expr": "startOfMonth(period)" } },

  { "name": "periodEnd", "type": "date", "required": true,
    "derived": { "expr": "endOfMonth(period)" } },

  { "name": "periodLabel", "type": "string", "required": true,
    "derived": { "expr": "format(period, \"MMMYY\")" } },

  { "name": "acumaticaPeriods", "type": "string[]", "required": true,
    "derived": { "expr": "[fiscalPeriod(period, \"outreach\")]" } }
]
```

The dispatch dialog now shows one month picker and a read-only expansion of
everything computed from it. The run still persists all five keys, so nodes
bind them exactly as before — a node cannot tell a computed value from a
typed one, which is the point.

### Expressions

Expressions are written in a small closed language: nine functions
(`startOfMonth`, `endOfMonth`, `previousMonth`, `nextMonth`, `addMonths`,
`format`, `fiscalPeriod`, `fiscalYear`, and `today` — the last available in
default expressions only), no operators, no conditionals. It is deliberately not a
general expression engine — the contract is meant to be auditable at a glance.

Two contexts:

* **`derived.expr`** sees run parameters only. It cannot call `today()` and
  cannot reference another derived field, so a replay of a run always computes
  the same answer it did the first time.
* **`defaultExpr`** additionally sees `today()` and `lastRun.<param>`. This is
  what makes a recurring workflow schedulable with no stored arguments at all:
  the trigger stores nothing, and `previousMonth(today())` fills the period at
  fire time.

Everything an expression can get wrong is caught when you save the draft — an
unknown function, a parameter that does not exist, a return type that does not
match the declared type, a `format` pattern typo, a fiscal calendar nobody
configured. That timing is the feature. A close that fires unattended at 6am
on the first should never be the thing that discovers a bad expression.

### Fiscal calendars

`fiscalPeriod(period, "outreach")` reads a named calendar from
**Platform → Fiscal Calendars**, which stores the month a fiscal year begins.
With a February start, `2026-06` is period 5 of FY2026 (`052026`) and
`2026-01` is period 12 of **FY2025** (`122025`) — January precedes February,
so it closes the prior fiscal year.

`fiscalYear(period, "outreach")` returns that year on its own — `"2026"` for
`2026-06`, `"2025"` for `2026-01` — named for the calendar year in which the
fiscal year started. It is the `YYYY` half of the `PPYYYY` token, exposed
separately because the language has no operators and no substring function, so
a value fused into a composite return is otherwise unreachable. Both take the
calendar as a quoted name — a string literal, not a parameter reference — and
an unknown name is rejected at publish. Both are available in `derived.expr`
and `defaultExpr`.

That rollback is the reason this is data rather than prose in an input's
description. It is easy to state, easy to misapply, and a wrong answer is a
well-formed string that pulls the wrong GL month without failing anything.
The authoring panel evaluates your expression against a sample as you type so
you can see the actual token before publishing.

### Assets — configuration that happens to be a file

Some inputs are files that change on their own schedule, not the run's. An
entity roster revised twice a year was, until assets existed, a mandatory
upload on every single monthly close. That one fact made the workflow
unschedulable and Slack launch impractical, because neither a cron nor a slash
command can attach a file.

Mark the input `asset: true` (file / `file[]` only) and bind it once:

```json theme={null}
{ "name": "rosterFile", "type": "file", "required": true, "asset": true }
```

The binding lives on the workflow. Every launch surface shows what is currently
bound — `intercompany_roster.csv · updated May 12` — and anyone with
`workflows:manage` can replace it inline from the run dialog. Replacing it
changes what every future run reads without republishing the contract, which is
why it carries the same permission as editing the contract itself.

Each launch snapshots the concrete file id into the run's arguments, so "which
roster did the June close use?" stays answerable from the June run whatever is
bound today — and a **Retry** of that run reproduces the file it actually used.

A required asset with nothing bound refuses the launch, before the run starts,
naming the input. That is deliberate: a run that dies mid-flight on a missing
file is the worse outcome.

### Retry versus rerun

A run persists the concrete expansion, not the expressions. **Retry** replays
those stored values verbatim, so retrying a June close next quarter still runs
June — even if the fiscal calendar has been edited since. **Rerun** opens the
dialog for editing and re-derives from whatever you set.

***

## Reference a workflow input from inside a node

A node reads a launch argument two ways. Wiring an input with
`source: { workflowInput: "key" }` hands that node a whole slot fed by the
argument. **Interpolation** puts the value *inside* a string — a
`{{workflow.<name>}}` reference the orchestrator substitutes at dispatch.

The second form exists because a slot is not always available to write into. A
procedure node's input keys are fixed by its pinned manifest, so a per-run value
that has to live inside a literal's shape has nowhere else to go:

```json theme={null}
{
  "inputs": {
    "pageFilters": {
      "type": "array",
      "required": true,
      "description": "Dimension filters for the report request.",
      "literal": [{ "dimensionName": "Time", "memberIds": ["{{workflow.periodLabel}}"] }]
    }
  }
}
```

Without the reference, that graph is re-authored every month to change one string.

### Three forms, two scopes

| Form | Resolves against | Honoured in |
| - | - | - |
| `{{fieldName}}` | this node's resolved `inputs` | agent `prompt`, publish and notify `message` |
| `{{inputs.fieldName}}` | this node's resolved `inputs` — the explicit spelling of the row above, same meaning | agent `prompt`, publish and notify `message` |
| `{{workflow.inputName}}` | the run's launch arguments | agent `prompt`, publish and notify `message`, **and `literal` bindings** |

Node scope versus workflow scope is the distinction that matters. `{{x}}` and
`{{inputs.x}}` are node-scoped: `x` must be a key in *this node's* `inputs`,
whatever that key is bound to. `{{workflow.x}}` skips the node entirely and reads
the launch arguments, so it needs no `inputs` entry — but `x` must be declared on
the workflow's input contract.

A publish message can therefore read a launch argument with no wire at all.
`"Weekly vendor digest for {{workflow.period}}:\n\n{{digestText}}"` needs a
binding for `digestText` and none for `period`.

**Only `literal` bindings are interpolated.** A value arriving through `source`
or `workflowInput` is passed through untouched even when it happens to contain
`{{…}}` text, so run data can never rewrite itself. Object *keys* are never
scanned either — only string values.

### A whole-string reference keeps its type

Substitution has two modes, and the difference is the point.

| The literal string | What is substituted | Result |
| - | - | - |
| exactly one reference — `"{{workflow.regions}}"` | the **typed** value | a `string[]` input yields a real array, not a stringified one |
| a reference inside surrounding text — `"FY{{workflow.year}}-Q{{workflow.qtr}}"` | the value, stringified and spliced | `"FY2026-Q3"` |

So a `string[]` workflow input can fill an array-typed procedure slot whole, and
the same input can also be spliced into a label somewhere else in the shape.

### An unresolvable reference throws in a literal and blanks in a prompt

The two surfaces fail differently, on purpose.

* In a **`literal` binding**, a reference with no value at dispatch throws and
  fails the node, naming the input.
* In an **agent prompt or publish message**, an unknown key renders as the empty
  string, so operators never see `{{undefined}}` in a published message.

`memberIds: [""]` is a syntactically valid reporting-API request that returns the
wrong numbers — a failure nobody notices. A degraded prompt is recoverable. The
literal path is the one worth stopping.

### What the validator catches before publish

| Code | Severity | Fires on |
| - | - | - |
| `WORKFLOW_REF_MISSING` | error | `{{workflow.x}}` where `x` is not a declared workflow input, or is optional with neither a `default` nor a `defaultExpr` |
| `LITERAL_TEMPLATE_UNRECOGNIZED` | warning | a literal containing any `{{…}}` that is not a valid `{{workflow.x}}` reference — typos, Handlebars blocks, bare `{{x}}`, and the prompt-only `{{inputs.x}}` spelling |

The optional-with-no-default case is the one `WORKFLOW_REF_MISSING` exists for, and
it is **rejected at publish time**: the preflight wiring gate refuses a draft
carrying any `severity: "error"` issue, and wiring errors are not overridable.
Without that gate the graph would publish cleanly and then throw only on the runs
where the operator left the field blank — passing its first test and failing in
production. Give any interpolated input a value on every run — required,
`derived`, or optional carrying a `default` / `defaultExpr`.

> [!WARNING]
>
> `{{inputs.x}}` and bare `{{x}}` are **not** supported inside a literal. A literal
> has no node-scoped resolver, so those strings are sent to the procedure verbatim;
> they only warn. If the value you want really is this node's own input rather than
> a launch argument, bind it with `source` / `workflowInput` on its own input key
> instead of templating it.

> [!NOTE]
>
> There is no expression syntax inside a placeholder — a reference names a declared
> workflow input and nothing else. Compute the value with a `derived` entry on the
> input contract and reference the result.

***

## Pick a validation strategy per Agent node

The single biggest correctness lever on a `produce` node is its `validation` field.

| Strategy | When to use |
| - | - |
| `passthrough` | Exploratory, creative, or freeform work. Agent writes to the thread only — no structured output. **Downstream edges cannot evaluate conditions** against this node's outputs. |
| `schema` | The node's output is a data contract. Zod / JSON schema validates the structure before the run advances. The right default for anything feeding a downstream agent's typed inputs. |
| `validated` | High-stakes outputs — legal, financial, compliance. Schema validation **plus** a validator-agent reviews semantic quality before passing downstream. Expensive; reserve it. |

Pick the weakest strategy that meets the correctness bar. Most pipelines end up with `schema` on most nodes and `validated` on the two or three nodes where semantic quality matters.

### Let an agent correct a rejected output

`validation.maxRetries` sets how many times a producer whose output fails validation is asked to
correct it. For a person, it re-opens the task. For an agent, it applies only when the workflow uses
outcome routing (`outcomesV1`) and the node runs inline, not detached. The agent is re-prompted in
the same conversation thread, inside the same run attempt, with the validation feedback as the next
message. An agent is re-prompted at most 5 times per run attempt, even if `maxRetries` is higher.

An agent is re-prompted only when its rejected turn is safe to repeat: the turn must not have called
any tool. A turn that called a tool might have changed something outside the platform, so its
rejected output fails the node immediately. When the re-prompts run out, the node fails with the
validation detail, and its failure binding records `retry: { tries, refusal: "attempts_exhausted" }`.
A detached agent's rejected output always fails the node. Validation warns with
`INEFFECTIVE_AUTOMATED_RETRIES` when `maxRetries` is set on a node that cannot use it.

***

## Set capability hints — narrow, don't sprawl

`produce` nodes whose worker is an agent can declare `capabilityHints` — the per-node lever that turns one agent definition into many personas:

```yaml theme={null}
capabilityHints:
  skills: ["analysis-discipline", "code-review"]
  toolSets: ["platformQuery", "runAnalysis"]
  externalTools: ["context7"]
  skillMode: "always"
  maxSkillTokens: 2000
```

At dispatch, the resolver intersects the agent definition's permitted capabilities with the node's hints. So adding a skill to a hint that isn't in the agent's permitted set produces a warning or failure depending on `skillMode` — hints narrow, they don't expand.

Capability-hint **sprawl is the most common authoring mistake**. Requesting every skill and tool set on every node burns prompt budget and weakens the agent's focus. Request only what the node's prompt actually uses. The Workflow Architect tends toward thoroughness — tighten before publishing.

***

## Declare the runtime budget

Every agent-backed `produce` node carries a **Timeout**. It is not a defensive guardrail you set low. It is the control that decides **where the turn executes**, and it is the only such control.

| Declared timeout | Where the turn runs | Ceiling |
| - | - | - |
| At or below the inline budget (**8 minutes**) | **Inline** — one Convex action, today's path. The common case: small nodes, latency-sensitive steps. | Hard-killed at the Convex action wall. |
| Above the inline budget | **Detached** — the same turn, driven from its own VM. | Up to **24 hours**, held against the budget you declared. |

There is no placement toggle, no pin, and no prediction engine. Placement is a pure function of the number you type, resolved at dispatch and identical everywhere it is displayed. In the builder, the Timeout field is a duration control (value + `min` / `h`) with a live readout underneath — **Runs inline** or **Runs in a detached VM (up to 24 h)** — that updates as you type. Nobody thinks in milliseconds, and nobody should have to guess where a node will land.

Both placements are the same turn: the same governance preflight, the same thread, the same cost attribution, the same streamed Session feed. The [run view](https://docs.gloo.com/forge/console/production/runs.md) shows which one a step took; nothing else in the product behaves differently.

The `Enable sandbox VM` checkbox is a different control

`SANDBOX — Enable sandbox VM` grants the agent a VM **as a tool**, so it can execute code. It does **not** extend how long the agent may run. Raising Timeout is what moves a node into a detached VM. These are independent: a node can run detached with no sandbox tool, and a node with the sandbox tool enabled still dies at the action wall if its declared timeout is inline-sized. This conflation has already cost a production run — check which one you actually need.

### Size the node, then round up

Over-declaring is close to free; under-declaring is not. Three facts make "when in doubt, declare big" honest guidance rather than sloppiness:

* A detached VM bills roughly memory while it sits waiting on model streams — pennies for a multi-hour budget.
* A **dead** run is caught by a lease-bounded staleness backstop, not by the declared deadline. A 4-hour declaration whose VM died in minute one is reaped minutes later, not four hours later. Declaring big does not mean waiting big to find out something broke.
* An under-declared node dies mid-turn and the work is discarded. There is no partial credit.

Rough arithmetic is enough — you are picking an order of magnitude, not forecasting:

```
budget ≈ (expected items × ~60 output tokens) ÷ observed tokens-per-second
       + ~4 min time-to-first-token   (a tool-bearing turn thinks before it emits)
```

A 782-item adjudication needs **40+ minutes** on that arithmetic. If you estimate 25 minutes, declare an hour. Given two candidate numbers, take the larger one.

The shape that needs this most is the **bulk-judgment node**: an `array`-typed input (a work list — candidates, transactions, findings, PRs) feeding a node that emits one structured result per item. One item is cheap; the node's cost is `items × per-item`, and the operator's brief usually names the work ("every ambiguous PR") without naming the count. Ask for the count when it is implied but unstated.

Never cap a work list to fit a budget

"Adjudicate the first 50" when the brief said "adjudicate every ambiguous one" is not a smaller version of the workflow — it is a different, wrong workflow that reports success. This is the anti-pattern the declared budget exists to end. If the list is genuinely unbounded and the work is mechanical, that is a **procedure** node. If the work needs judgment per item, declare the budget the judgment needs.

Fan-out and budget buy different things. Splitting a work list across N branches into a `join` buys **latency**; a larger timeout buys **ceiling**. Fan out when the operator needs the answer sooner. Raise the budget when the operator needs the whole list processed — fanning out to dodge a timeout adds a join, N sets of bindings, and N failure modes to solve what one field already solves.

### What the platform tells you when the budget is wrong

* **`AGENT_BUDGET_UNDERSIZED`** — an authoring-time **warning** (L3), raised on a tool-bearing `produce` node with declared outputs, an array-typed input, and an inline-sized timeout. It carries the sizing arithmetic and arrives as a one-click `timeout` fix chip in the builder's issue rail and in the Architect's fix-flow. It is advisory: since placement follows the declaration, there is no invalid combination to block — only an under-declaration to flag. It never blocks publish.
* **`RAISE_TIMEOUT`** — a runtime failure, labeled **Inline budget exhausted**. Past \~80% of its inline budget with work outstanding, an inline turn gives up at the next tool-call boundary and names the node, its budget, and the fix, rather than burning the remaining minutes and dying as an opaque action-wall error. It is not retryable — a retry reproduces the same exhaustion. The fix is the Timeout field.

Long-running work needs an explicit notification design. Add a `notify` node or configure the relevant delivery surface when a person must learn that the run finished; do not assume every long run sends an automatic completion message.

The [Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md) applies all of the above when it authors nodes for you — it recognizes the bulk-judgment shape, sizes it, quotes past runtime measurements for a node it has seen run before, and declares the budget rather than capping the work.

***

## Wire edges that mean something

An edge from A to B means "when A finishes, consider traversing to B." Three optional fields change the semantics:

| Field | Meaning |
| - | - |
| `condition` | Expression evaluated against A's structured outputs. Edge traverses only if truthy. |
| `label` | For edges out of a `router`: traverse only if the router selected this label. |
| `onError` | When true, traverse only when A *failed*. The error-handler lane. |

Multiple unconditioned edges from the same node **fork** — all fire in parallel. Multiple conditional edges all evaluate in parallel; every truthy condition fires (which is how you get conditional fan-out *without* a router). Error edges are mutually exclusive with success edges on the same source.

A human's rejection is not a failure

`onError` means the source node *failed* — an exception, a schema rejection, a timeout. A human step that comes back **rejected** has still completed successfully; the person did their job and the answer was no. So an `onError` edge off a human step **does not carry the rejection.**

It is not a useless edge, though — a human step *can* fail. It fails when the deadline lapses with no answer, and when the submission still does not satisfy the step's declared outputs after its retries. Those are what an `onError` edge off a human step catches. The validator flags the edge as `HUMAN_NODE_ONERROR_NOT_REJECTION` so you can confirm which of the two you meant; if you meant the timeout lane, leave it as it is.

Branch on the decision separately. Give the human step two outgoing edges to two **different** targets, and put a condition on each:

```text theme={null}
Compliance Approval ──[ decision == "approved" ]──► Disburse Funds
                    └─[ decision == "rejected" ]──► Notify Rejection
```

Three things to get right: the human step must declare `decision` in its outputs (otherwise `CONDITION_MALFORMED` blocks publish); string literals in a condition must use **double** quotes, since single quotes are swallowed to a silently false branch; and the two edges must land on different nodes, because only one edge is allowed per source-target pair.

In the console, select the edge and fill in **Edge Properties → Condition**. The **Error Path** toggle beside it is the `onError` control — leave it off here.

Legacy workflows treat a handler whose *only* incoming edges are error edges as an **entry node**. It can dispatch before its source fails. The explicit outcome-routing contract below removes that behavior; existing workflows retain their runtime contract.

### Author expected outcomes and technical failure paths

Authoring does not activate production admission

In workflow settings, **Use outcome routing** explicitly selects the new contract for the draft.
You can configure and validate its routes and failure bindings. A published marker does not open
the production launch gate: the deployment must separately complete immutable qualification and
its operator-target, recovery-owner, monitoring, sweep, and measured-drill prerequisites before
setting the exact admission value. Existing versions and in-flight runs are never upgraded.

Keep expected business outcomes in the node's structured outputs. For example, a Workday lookup
can return a required string enum such as `ready`, `person_missing`, `multiple_people`, or
`phone_missing`. Select that field under **Outcome output**, then mark the relevant values under
**Expected exceptions**. Use ordinary conditional edges to send each value to its intended next
node. Only `ready` should reach the SMS node. An authentication error or failed API request belongs
on the technical failure path, rather than being reported as a missing person.

With this contract, the existing **Error Path** edge connects a failed node to an ordinary handler
node. A handler reached only by error edges waits for an actual failure. Add an object input on the
handler and choose its **Failure source** under **Failure input bindings**. The binding carries
structured failure information, including the originating run, node, attempt, category, code,
message, retryability, and known external-effect state. It is separate from the source's successful
output bindings and cannot supply data from an unrelated failure.

Validation checks the declared outcome field, enum members, failure-source reachability and error
edges. Simple equality conditions can establish coverage of every enum member; more complex
conditions may require your review of a coverage warning. A declared outcome with no selected route,
an invalid router selection, or malformed condition fails visibly. An ordinary valid condition that
evaluates false still skips its edge normally. Multiple matching ordinary paths all activate.

Handlers use the same typed inputs, outputs and validation controls as other nodes. A handler's
successful completion records that the failure was handled; it does not erase the original technical
failure or convert the run into an ordinary success. Error edges cannot feed a data join directly.
Route them through an appropriate handler first. Routing a failure never repeats the failed node,
and it never makes an uncertain external operation safe to repeat.

### Retry a node automatically when it is safe

A Procedure node or an AI Agent node can declare a `retryPolicy`:

```json theme={null}
{ "maxAttempts": 3, "initialBackoffMs": 5000, "backoffMultiplier": 2 }
```

`maxAttempts` counts every try, including the first, and must be a whole number from 2 to 5.
`initialBackoffMs` is the wait before the second try, a whole number from 1,000 to 300,000.
Each later wait is multiplied by `backoffMultiplier`, from 1 to 4 (default 2). The waits together
may not exceed 900,000 ms. With the example above, a node waits 5 s before its second try and 10 s
before its third.

The policy asks for more tries; the runtime decides whether to make them. A failed try is repeated
only when all of these hold:

* the workflow uses outcome routing (`outcomesV1`);
* the failure is an execution, infrastructure or timeout failure, not an input, output, routing or
  governance failure;
* the platform's own dispatch evidence shows that no external operation took effect or could have
  taken effect. Only a read whose result is unknown is repeated after it started;
* no tool-dispatch fence is set on the step.

A procedure's `idempotent` flag, the effect state a sandbox reports, and a `retryable` hint never
grant a try. In practice, a failure before the node's first external call starts (for example, an
unavailable sandbox) is retried. A call that started and then failed or timed out is not retried,
because it may have written something. Route that failure to an error path instead.

Every try runs inside the same run attempt. Each failed try is recorded and shown in the run's
event stream, and its token usage and cost are kept. When the tries run out, or the runtime refuses
a try, the node fails through the normal failure path. Its failure binding carries
`retry: { tries, refusal }`, for example `{ "tries": 3, "refusal": "attempts_exhausted" }` or
`{ "tries": 1, "refusal": "effect_unknown" }`. Cancelling a run stops a try that is still waiting.

Validation reports `RETRY_POLICY_REQUIRES_OUTCOMES` (a warning) when a workflow without outcome
routing declares a policy, because legacy runs ignore it. It reports `RETRY_POLICY_UNSUPPORTED_NODE`
(an error that blocks publish) for a policy on a Router, Join, Publish or Notify node, on an Agent
node assigned to a person, or outside the bounds above. A person's submission that fails validation
is re-prompted through the node's validation settings, not through `retryPolicy`.

### Configure required outcome notifications

When **Use outcome routing** is selected, Workflow Settings also exposes **Required outcome
notifications**. Every admitted run must have at least one authorized in-app recipient. A person
who starts a run is included automatically; add one or more operators so scheduled and other
automated runs have an accountable recipient. Expected exceptions and technical failures notify
every configured operator. You can also stage required Slack workspace and channel targets, but
production admission remains closed until the deployment completes qualification and the operational
prerequisites in the outcome-recovery runbook.

These receipts are delivery obligations, not advisory preferences. Muting personal notifications
does not remove them. The runtime freezes the resolved recipients on each attempt, so later edits do
not rewrite the evidence for an in-flight or historical run. An effective exception or failure and
its obligations commit together; terminal outcomes create their own obligation, including success.
A scheduled dispatcher, completed handler, or emitted event is not delivery proof—the obligation
is satisfied only when its personal in-app receipt commits.

Workflow completion arrives through a callback tied to the expected attempt and engine instance.
A stale callback cannot finalize a newer attempt, and the watchdog uses the same terminal writer to
recover a callback that never arrives. Delivery failures do not roll back the workflow outcome;
safe in-app failures receive bounded retries, while revoked recipients and exhausted retries are
held for operator attention. Required notifications are not evidence that business work failed or
should be retried. A bell or Slack delivery problem keeps the original business verdict and is
recovered through the notification controls. If an external effect is `unknown`, reconcile it before
restart; do not use notification repair, rewind, or a new run to repeat the call. The `outcomesV1`
new-launch gate defaults closed; disabling it never blocks recovery for existing runs.

`sourceHandle` and `targetHandle` identifiers exist for the visual designer — they pin an edge to a specific port on a multi-handle node (a router's per-label ports, for example), so a reload or a fresh automatic layout doesn't reshuffle the topology. In the builder, a connection drawn from an AI router's route port carries that route's label.

Watch for the merge-shortcut anti-pattern

The most common structural mistake: routing from A to B and C, planning to join at D, *also* drawing direct edges from B and C to a downstream step E. The result — E runs once per path. The graph validator enforces `CONVERGE_WITHOUT_JOIN`, which flags a non-`join` node with multiple convergent incoming paths where at least one of them is not bound by a typed input on the receiver. (Typed multi-input fan-in, where every upstream is named by one of the receiver's declared input sources, is allowed and fires once — unless, on the default runtime contract, those upstreams sit on mutually exclusive branches: the untaken branch's edge never settles, so the step never runs. The validator flags that shape too.) When in doubt, force the merge through a `join` node.

***

## Save checkpoints automatically

Every step completion writes a checkpoint to the run record. Two operations use them:

* **Rewind** — roll a running or failed run back to a prior checkpoint. Completed steps are preserved; subsequent steps are cleared; execution resumes from the checkpoint moment. Recovers from failures without restarting from scratch.
* **Branch** — create a new run from a checkpoint with modified inputs. The original run is unaffected. Useful for "what if" exploration and A/B testing.

Each checkpoint stores `completedStepIds`, `skippedStepIds`, the full accumulated `variables` scope, `accumulatedOutputs` keyed by step ID, the `variableOverwriteOrder` for deterministic replay, and a monotonic `sequence` counter. Checkpoints can also be triggered from the Platform API; configuration options include interval-based capture (every N steps) and phase-boundary capture.

You don't author checkpoints — they author themselves on every step boundary. The decision is whether to expose **rewind** and **branch** as first-class operator actions in your workflow's UI surface, or hide them from non-admin operators. That decision is set on the workflow's policy, not in the graph.

***

## Author the graph — three paths

You have three ways to compose:

1. **Talk to the [Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md).** A Forge-native agent that takes plain-language intent, drafts a validated graph in real time, and watches every tool call render in the drawer. The right path for \~80% of new workflows. The Architect deliberately has no publish authority — promotion is yours.

2. **Use the visual builder by hand.** The graph editor at `/production/workflows/convex/builder-v2`. Steps are arranged automatically: click a `+` on a connection or under a final step to insert a step (or drag a step type from the palette onto a `+`), use **Add a branch** on forks and routers, drag from a step's bottom port to another step's top port to connect them, and fill in fields in the step's panel. See [Editing the builder canvas](https://docs.gloo.com/forge/console/production/workflows/builder-canvas.md#editing-the-builder-canvas). Faster than the Architect for two-node sequential graphs and purely cosmetic edits.

3. **Drive the Platform API.** Programmatic graph authoring through the workflow CRUD endpoints. Useful for templated workflow generation (e.g., per-customer pipelines that share a shape).

All three paths land in the same `workflowDrafts` row. The validator runs the same way regardless of authoring source.

***

## Pre-publish checklist

Before clicking **Publish**:

* [ ] **Terminal paths end at `publish`.** Every path through the graph should end at a publish node (or an explicitly terminal agent). A path that just stops is almost always a bug.
* [ ] **Human gates on irreversible actions.** Sending email, calling external APIs, posting to public channels — wrap with a `produce` node assigned to a human worker unless you've measured the downside-risk and decided otherwise.
* [ ] **Capability hints are tight.** Drop the skills and tool sets the node doesn't actually use.
* [ ] **Timeouts are declared honestly.** Any node whose input is a work list has a budget sized from `items × per-item`, rounded up. Read every `AGENT_BUDGET_UNDERSIZED` warning rather than dismissing it — it is the only signal you get before the run.
* [ ] **Validation strategies are honest.** `passthrough` only where downstream nodes don't depend on structured output. `validated` only where semantic quality matters more than cost.
* [ ] **Router coverage is complete.** Every `routeOptions` entry has at least one outgoing edge with that label. The validator flags `UNCOVERED_ROUTE_LABEL` when missing.
* [ ] **`validateGraphTool` returns `clean`.** The Architect calls this at the end of every turn; manual authoring should run it explicitly. `warnings` is acceptable if you've read each warning and decided to accept it.
* [ ] **Capability gaps resolved.** The publish gate checks the graph's capabilities before it saves anything. If a node references a skill / tool / agent / procedure that does not resolve in your workspace, publish is refused — see "The publish gate" below.

***

## The publish gate

Clicking **Publish** runs two checks before the version row is written:

1. **Wiring validation** — L1+L2 graph topology + schema-component references. Always hard-blocking; a draft with wiring errors cannot publish.
2. **Capability validation** — every `capabilityHints.skills`, `capabilityHints.toolSets`, `capabilityHints.externalTools`, `agentDefinitionId`, and `procedureId` referenced by any node must resolve to an active row in this workspace's registry. Reasons a gap surfaces:
   * **`not_found`** — the referenced skill / agent / procedure id is not in the registry. Synthesize it or substitute an existing primitive.
   * **`not_permitted_in_org`** — your workspace has not been granted access to an external tool the node references. Ask an admin to grant it.
   * **`deprecated`** — the referenced procedure version is past its deprecation horizon. Move to the latest active version.
   * **`duplicate_name`** — two synthesis-pending primitives share a name in this workspace (warning only — informational, doesn't block).

When capability gaps with `severity: error` are present, the dialog renders the gap list with two paths:

* **Fix first** — closes the dialog. You return to authoring, resolve each gap, and re-publish.
* **Publish anyway** — requires a non-empty override reason. The publish proceeds and writes an `auditEvents` row (`workflow_published_with_capability_override`) carrying your identity, the draft id, the override reason, and the full gap list. Use this when a gap will resolve on the next sync (e.g. a tool grant landing later today) and you do not want to block the deploy.

Warning-severity gaps (currently just `duplicate_name`) never block publish and never require an override — they are surfaced in the dialog as advisory.

The same check is exposed to the Workflow Architect as a pre-flight tool (`validateCapabilities`). The Architect calls it before emitting `proposePlan` and resolves error-severity gaps via synthesis, substitution, or operator escalation — so by the time the operator clicks Publish, the gaps list should be empty.

***

## Pin the run to a version

Publishing produces a `workflowVersions` row with `status: "active"`. A production run pins a specific `versionId` at launch; a test run pins a `draftId`. Upgrading a workflow — publishing a new version — never affects in-flight runs. The orchestrator walks the graph the run was pinned to, keyed by whichever foreign key the run carries. `workflowVersions` rows are immutable once published, so historical runs always replay against the exact shape they ran against.

To start a run of the published workflow, dispatch it: from the workflow in the Console, over HTTP with [`POST /api/v3/workflows/dispatch`](https://docs.gloo.com/forge/reference/http-api/workflows/dispatch), or over MCP with `forge_run_workflow_and_wait` (see the [MCP server](https://docs.gloo.com/forge/reference/mcp-server.md)). For the trigger paths (manual, API, scheduled), see [Scheduling and triggers](https://docs.gloo.com/forge/run/scheduling-and-triggers.md). For the Console operator surface, see [Console — Workflows](https://docs.gloo.com/forge/console/production/workflows).

***

## Do it over the API

The Platform API path builds a draft's structure: create the workflow, add nodes, connect them, validate, and publish. These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md), but not its token: that token is scoped for dispatch and carries no workflow-authoring scope, so the first call below would answer `403`. Mint a token with the scopes these steps need:

```bash theme={null}
ACCESS_TOKEN=$(curl -fsS -X POST "$FORGE_BASE/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$FORGE_CLIENT_ID" \
  -d "client_secret=$FORGE_CLIENT_SECRET" \
  -d "scope=workflows:read workflows:write workflows:manage agents:use" | jq -er .access_token)
```

Scopes only narrow the app's roles, so the app must also hold roles carrying these permissions. **Builder** holds `workflows:read`, `workflows:write` and `agents:use`; publishing also needs `workflows:manage` at platform scope, which **Operator** and **Platform admin** hold.

Only structure and content are machine-writable. A node's agent, worker, person, recipient, channel, credential, vault, tool, skill, procedure, model and sandbox fields are Console-only, and a write that names one answers `400`. Bind the agent to a `produce` node in the builder before you publish. To build or change a whole workflow, ask the [Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md); use these calls for precise edits you already know.

**1. Create the workflow**

```bash theme={null}
WORKFLOW_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-summary-workflow-v1" \
  -d '{"name": "Ticket summary", "description": "Summarise a support ticket and post the summary."}' \
  | jq -r '.data.workflowId')
```

This needs `workflows:write` and `workflows:read` at the home the workflow is created in. An External App creates at its owning org unit; a platform API key cannot create.

**2. Add the nodes**

```bash theme={null}
PRODUCE_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/draft-nodes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-summary-node-summarise-v1" \
  -d '{"type": "produce", "name": "Summarise", "position": {"x": 0, "y": 0}, "config": {"prompt": "Summarise the ticket in three sentences."}}' \
  | jq -r '.data.node.nodeId')

PUBLISH_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/draft-nodes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-summary-node-publish-v1" \
  -d '{"type": "publish", "name": "Post summary", "position": {"x": 0, "y": 200}}' \
  | jq -r '.data.node.nodeId')
```

Each needs `workflows:read` and `workflows:write` at the workflow's home. A node name must be unused in the draft (`409` otherwise).

**3. Connect them**

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/draft-edges" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-summary-edge-v1" \
  -d "{\"fromNodeId\": \"$PRODUCE_ID\", \"toNodeId\": \"$PUBLISH_ID\"}" \
  | jq '.data.edge | {edgeId, fromNodeId, toNodeId}'
```

The builder's connection checks apply: no self-loop, at most one edge per node pair. A cycle is not refused here; validation reports it.

**4. Validate the draft**

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/draft-validation" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {status, publishable: .publishability.status, issues: [.issues[] | {code, severity, nodeId}]}'
```

This needs `workflows:read` and changes nothing. `status` is `clean`, `hasWarnings` or `hasErrors`; `publishability.status` is `publishable`, `gated` or `broken`. Bind the `produce` node's agent in the builder, then validate again.

**5. Publish**

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/publish-draft" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-summary-publish-v1" \
  -d '{"expectedActiveVersionId": null, "publishNote": "First version"}' \
  | jq '.data | {versionId, version, judgeGate}'
```

Publishing runs every Console publish gate on the draft as it is now. It needs `workflows:manage` at the platform scope plus `agents:use` for the agents the version runs; a refusal is `422` and nothing is written. `expectedActiveVersionId` is `null` for a workflow never published; otherwise name the active version, or the call answers `409`.

Over MCP, `forge_call_operation` runs the same writes and `forge_call_read_operation` the validation; both are in the default `start` job. Adding a node:

```json theme={null}
{
  "operationId": "createWorkflowDraftNode",
  "idempotencyKey": "ticket-summary-node-summarise-v1",
  "input": {
    "workflowId": "<workflow id>",
    "type": "produce",
    "name": "Summarise",
    "position": { "x": 0, "y": 0 },
    "config": { "prompt": "Summarise the ticket in three sentences." }
  }
}
```

Validating it:

```json theme={null}
{ "operationId": "validateWorkflowDraft", "input": { "id": "<workflow id>" } }
```

***

## See also

* [Use the Workflow Architect](https://docs.gloo.com/forge/build/use-workflow-architect.md) — the conversational authoring path
* [Dispatch a workflow](https://docs.gloo.com/forge/reference/http-api/workflows/dispatch.md) — start a run of the published version with its input arguments
* [The workflow graph](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph) — the runtime data model and node-type field reference
* [Workflow Execution](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md) — what the orchestrator does after publish
* [Define an agent](https://docs.gloo.com/forge/build/define-an-agent.md) — the rows your agent-backed `produce` nodes reference
* [Configure a sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md) — the VM *tool*, which is not the runtime budget
* [Console — Runs](https://docs.gloo.com/forge/console/production/runs.md) — placement, liveness, and cost for a step once it is running
* [Files and bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md) — the auto-injected tool for `file` outputs
* [Workflows and runs](https://docs.gloo.com/forge/concepts/workflows-and-runs.md) — why workflows look the way they do
* [Console — Workflows](https://docs.gloo.com/forge/console/production/workflows) — the operator walkthrough


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.