Workflow reviews, outputs and parallel branches

This article covers the parts of a workflow that matter to the people who run the deployment. For the screens people use, see the user guide's review queue and reviewing a run.

Who can create workflows#

Creating, editing and publishing a workflow definition needs the manage_coworkers ability.

Who can review a run#

The admin ability gives no access to runs: runs hold business data, and administration does not imply it. Anyone can open a run when it is for them, when they started it, when they own the run's conversation, or when one of its review steps names them (or their team) as reviewer, an administrator included only in those cases. Nobody else can open the run, its review items, or its files and document previews, and the run is left out of their run lists. A run from another company is reported as not found. The Review queue entry in the profile menu is shown to anyone who has at least one review item visible to them, whatever their role.

Opening a run and deciding a review are separate. Who may decide a review depends on its Who reviews setting (below). A guardrail pause is never assigned: only the people the run is for decide it. Re-running from a step is for those same people alone; an assigned reviewer or a team member does not get it.

When a reviewer writes to the Coworker during a review, the turn runs as that reviewer, not as the person the run is for: the Coworker uses the reviewer's own access to Knowledge Bases, secrets and memory, and the usage is recorded against the reviewer. The reviewer needs the same access to the Coworker that chatting with it needs (for example Team scope); without it the message box is off and they can still approve or reject. Steps the engine runs after a decision keep the run's own person, not the reviewer.

Every run has a person it acts for. A run started by hand belongs to whoever started it. A run started through a webhook belongs to the person whose personal API key authenticated the call. A run fired by a schedule has no signed-in person, so it belongs to the Coworker's Supervisor. That person owns the run's conversation, and run conversations never appear in anyone's thread list.

Every run is also owned by a Coworker, the one attached to the workflow. A run for a workflow with no Coworker attached is refused when it starts.

Review steps#

A step of kind review stops the run and puts it in the review queue. Its settings are:

Setting	Meaning
instructions	The text shown as What to check.
on_reject	halt stops the run when the reviewer rejects. route continues at the step named in reject_route_to.
reject_route_to	The id of a step that comes later in the workflow. A route to a step that does not follow the review fails the run with an explanation.
reviewer_mode	Who reviews: default, person or team. See below.
reviewer_person_id	The person who reviews, for person.
reviewer_team_id	The team that reviews, for team.

Who reviews#

Mode	Who decides	Who else sees it
default	The person the run is for (the person who started it, or the person it ran as).	Same people.
person	The chosen person.	The person the run is for can open the run and the review but cannot decide it.
team	Any member of the chosen team. The first decision counts; a second member who tries gets "already decided".	The person the run is for can open the run and the review but cannot decide it.

The team is a team from Settings > Team (the same teams that scope Coworker, App and Knowledge Base access); there is no separate list. Membership is read when someone opens the queue, so adding or removing a member changes who sees the review straight away. The person or team is saved with the workflow version, so a run keeps the reviewer it started with. Publishing a workflow that names a person who is no longer active, or a team that no longer exists, is refused with a message saying which review step to fix.

"Notified" means the review appears in the Review queue of each person who can decide it and is counted in the number beside Review queue and in the badge on their name (both refresh by themselves). The person who decides is recorded on the review and named in the run's conversation ("Review approved by …"). There is no separate email or chat message for a review.

A rejected review with halt fails the run with the reviewer's note in the error. A guardrail that fails on a step also creates a review item, shown with the Guardrail check label.

Building review and parallel steps#

Open Workflows, then Create workflow or Edit on a workflow (needs the manage_coworkers ability). Besides the name, description and Steps, the page has the sections below.

Run inputs, Declared outputs and each step show as a single collapsed row: the step number, its type, a one-line summary, when it runs and (for a review) who reviews. Select a row to open it, and select it again to close it. Expand all and Collapse all above the steps open or close every step. A step you add opens straight away with its first field focused, and so does a section when you add its first item. A row marked Needs attention has a problem that blocks publishing; saving or publishing that reports a problem opens the cards it concerns. Which rows are open is only a view setting and is never saved with the workflow.

• Run inputs — the form people fill in to start the workflow. Add fields with Add input: a Label, a Key (filled in from the label; steps and the run record use it), a Type (Text, Long text, Number, Yes / no, Choice with one option per line, or File), optional help text, and Required. Use Up and Down to reorder. This is the only way a workflow takes input: the same fields are the form for Run now, the values a Coworker supplies when it calls the workflow from a chat, and what the run page shows as its inputs. When should a coworker call this? stays a separate description for the Coworker.
• Declared outputs — the file names the workflow produces, with Add output.
• On each step, Step type includes Review (a person approves before continuing). A review step asks for a Title, What to check, If the reviewer rejects (Stop the run or Continue at a later step, chosen from the steps that follow it) and Who reviews (Whoever starts the workflow, A specific person or A team). Add review step adds one at the end. A review step has no model, prompt or guardrail.
• Runs after on every step. With nothing ticked a step runs after the step before it. Tick several steps to make it wait for all of them; steps that share a step they wait for run at the same time, and the page says Runs in parallel with …. A step that waits for two or more steps also shows If a branch fails (Stop the run or Continue with the branches that finished) and Max parallel branches.
• On prompt-based steps, What this step sees from earlier steps (Default, Nothing from earlier steps, Only the previous step, Chosen steps or Everything so far), and on sub-agent steps an optional Model for this step.

Publishing is refused, with a message, when the steps wait for each other in a circle, a step waits for a step that does not exist, fork settings sit on a step that joins nothing, or a review names a reviewer who does not exist.

Inputs and outputs#

A definition can declare inputs: fields of type text, long_text, number, boolean, choice or file, each required unless marked otherwise. The form is validated when the run starts, and the values become the first message of the run's conversation. A Coworker that calls the workflow from a chat passes the same values as one inputs object.

Workflows saved before the form existed asked for a single free-text input. Such a workflow shows that as one Long text input labelled Input (required if the workflow required input, with the old description as its help text), runs exactly as before, and a Coworker still passes it as a single input text. Saving it in the builder stores it as an ordinary declared input.

A definition can declare outputs, named files the run produces. Files are the outputs of a run. A document preview, if the Coworker made one, is a view of a file.

How outputs are stored#

At every review step and when the run finishes, the run's output files are copied. Each copy is a separate file stored in the application database with its own id, and the live file is never changed. People reviewing a run see and download these copies, so what a reviewer approved cannot change afterwards. When the Coworker changes a file during a review, the reviewer saves the change as a new version, and later steps use the latest version.

If a file cannot be copied, the review item records the reason and the review page lists it under Some files could not be saved for review. The copies count towards the database's storage and are backed up with it.

Parallel branches#

Parallel branches come from step dependencies, not from a separate step type. Steps that share a dependency run as separate branches, each in its own conversation that starts from the run's conversation. A step that depends on several steps joins them and receives each branch's result. Settings on the joining step control the branches:

Setting	Meaning
on_branch_failure	fail_workflow (the default) fails the run when a branch fails. continue leaves the failed branch out of the joined result, records it, and carries on with the rest.
max_concurrency	The most branches that run at the same time. Leave it empty for no limit.

A review step inside a branch gives one review item per branch, so a run can have several items waiting at once. Each item can be decided separately from the queue.

Failures#

A run that failed shows its error on its own page and in All runs under Workflows, where the Failed filter lists it with the start of the error message.