Workflows Overview
A workflow defines the processing pipeline for a project: which activities run, in what order, and how they are configured. Every transaction in the project is processed by walking its workflow from the first activity to the last.
You design workflows visually in Project Settings → Workflow, where each activity is a node on a canvas. You can enable or disable nodes, reorder them, configure each one, and add branching.
The processing pipeline
A typical document pipeline looks like this:
Import → OCR → Split → Classify → Extract → Validate → Human Review → Export
Each step consumes the output of the previous one:
| Stage | What it produces |
|---|---|
| Import | Normalized page images from the uploaded files |
| OCR | Machine-readable text (and optional barcodes) per page |
| Split | Page ranges grouped into documents |
| Classify | A document class (type) for each document |
| Extract | Structured field values for each document |
| Validate | Business-rule results (warnings and errors) |
| Human Review | A human decision (accept, reject, or redirect) |
| Agent Review | An agent's decision (accept, reject, or redirect), taken unattended by the built-in agent or by an agent on an integration key; the step fails, down its Failed exit, when no agent decides (Agent Review) |
| Export | Output files (PDF, JSON, and more) |
Not every project needs every stage. If your documents are already single-page and pre-classified, you can disable Split and Classify and go straight to Extract.
Activity categories
Activities fall into two groups:
- Processing activities do the document work: Import, OCR, Split, Classify, Extract, Validate, Transform, Human Review, Agent Review, Export, Notification.
- Control-flow activities change the path through the workflow: If and Switch.
See the Activities section for one article per activity.
Enabling and disabling activities
Toggle any activity on or off from its node. A disabled node is skipped at runtime but stays on the canvas, so you can turn it back on without rebuilding it. This is the quickest way to trim a pipeline for a project that does not need a given stage.
Branching
Workflows are not limited to a straight line. Use control-flow activities to route transactions:
- If Condition sends the transaction down a true or false branch based on a condition.
- Switch routes to one of several named branches based on a value.
- Human Review and Agent Review can expose accept, reject, and custom send-to exits that jump to other steps.
Branches let you, for example, send high-value invoices to human review while auto-approving the rest.
Handling failures
By default, when an activity fails, the transaction fails and processing stops. You can decide differently per step: every activity except If, Switch and Human Review can expose a second exit for failures.
Turn on Failure exit in the activity's settings panel. The node then shows two exits instead of one: a green Success handle and a red Failed handle below it.
| Failed exit | What happens when the activity fails |
|---|---|
| Not connected | The transaction fails and processing stops. This is how every activity behaves until you connect it. |
| Connected to another activity | The step is still recorded as failed, and the transaction continues from the activity you connected it to. |
The most useful target is a Human Review step. A transaction that hits a problem then reaches a person, along with everything that did process correctly, instead of stopping. A Human Review step reached through a Failed exit, directly or after other steps such as that Notification, always pauses for a reviewer, even when its policy would otherwise approve the transaction automatically. Some teams put a Notification step in front of the Human Review step so the failure also raises an alert.
Connect a failure exit to a step that only failures reach. An exit back to an earlier step, such as from Validate back to OCR, or to a step that runs anyway, is reported as an error. To have a document processed again, connect the failure exit to a Human Review step and connect the reviewer's decision back to the step to repeat. To return to a step the transaction has already passed, go through a Human Review step's decision; a plain connection from the failure branch back to such a step is reported as an error.
If several steps share one Human Review step for their failures, and after the reviewer sends the transaction on to a later step another of them fails, the transaction fails and says why. Sending the transaction back to the step that failed lets the Human Review take its next failure.
What counts as a failure
The failure exit is for problems that will not resolve on their own:
- A step that keeps failing on the content or the configuration, after its retries are used up.
- A Transform script that deliberately calls
fail(). - A Classify pre- or post-classification rule that cannot run, for example because a regular expression in it does not compile.
- A Validate business rule that cannot run, for example because it throws an error. Validation errors that rules report are not failures: they go to review.
It does not fire while the system is waiting. Pauses for model capacity, rate limits or a budget limit are not failures: the transaction waits and then carries on by itself. Retries always run first, so a step only takes the failure exit once it has genuinely given up. A licensing problem always fails the transaction, because nothing further can be processed.
Reading the result
A routed failure is still a failure in the record. The step shows as failed with its error, the Activity Log names it and says where it was routed, and any document that could not be processed carries its own error. Nothing is quietly turned into a success.
Reading the Activity Log
The transaction's Activity Log records each step as it runs, and says what the step did, not only that it finished:
- Validate shows how many checks ran, how many passed, and how many warnings and errors the rules reported.
- Human Review and Agent Review get an Issues to review entry when the transaction reaches them. It counts what they found by kind, for example "3 validation errors, 1 unconfirmed split", or says there was nothing to review. The decision that ends a review is a Review entry of its own, naming the exit taken.
- A step that is turned off says so. It is passed over without running, so it is not a step that ran and found nothing.
- A step with several exits, such as an If, a Switch, or a review step that passed on Approved without a review, names the exit taken.
Where settings live
Each step's panel holds that step's settings: its model, inputs, page limits, threshold, discovery and whether it is on. Two Extract steps can therefore run on different models, for example one for standard documents and one for hard ones behind a Switch.
The document classes, fields and guidelines belong to the project, and every step reads them. A step can use some of them only, or send its own text for one of them, marked Custom in this step with Reset to project text. See Project Settings.
A project upgraded from an earlier version moves its step settings onto its steps the first time it is changed; nothing about how its steps run changes.
How the engine runs a workflow
The workflow engine:
- Picks up transactions from the Redis queue.
- Runs each enabled activity in order, following any branches.
- Tracks status and duration per activity.
- Retries transient failures (for example, a temporary model rate limit).
- Reports completion, or stops on a terminal failure, unless that step has a connected failure exit to follow.
Monitoring progress
Open a transaction to watch its workflow. Each activity shows its status (pending, running, completed, or failed), its duration, and any error detail if it stopped. See Troubleshooting when a step fails.
Next steps
- Browse Common Workflows for ready-made pipeline recipes.
- Read the Activities reference for each node's settings.