Workflow pages
Table of Contents
A workflow page is the durable contract for one named server-side process: what it achieves, which components and roles take part, which messages it exchanges, the steps it runs and what each one produces, the failure policy it declares, and the read a client follows to render its progress. A workflow page is written from the definition a service registers, never from a run of it. The run is a workflow instance, and its progress is read rather than written down here.
This folder holds the pages for individual workflows, as
workflow_<slug>.org. It sits beside
doc/knowledge/architecture/ for the same
reason the journey pages sit beside it: a workflow is a durable, cross-cutting
statement, and it outlives the sprint that wrote it.
1. What belongs here, and what does not
- A page here owns one workflow — its purpose, its participants, its messages, its steps, its failure policy, and its progress read.
- The engine that runs a workflow is not this folder's subject. The step
protocol, the instance and step states, failure and retry, idempotency, and
waiting and deadlines are knowledge about the engine and live in
Workflows under
doc/knowledge/architecture/. A workflow page links to that cluster; it never restates it, because a copied rule drifts and the copy is the one a reader finds first. - A fact about one run — where it stopped, what it published, what failed — belongs in the task or the investigation that owns that run, not here.
2. Workflows
This page is the inventory of the workflows the platform supports. Each row names one workflow, what it achieves, and the page that defines it; a new workflow is a new row and nothing else.
| Workflow | What it does |
|---|---|
| Tenant provisioning | Creates a tenant from a starting point and brings it to a working state, with its administrator, its reference data and its parties. |
| Identity | Exercises the engine end to end with no domain data: a completion, a completion with warnings, a failure, a compensation, a slow step and a long run. |
| Report execution | Prepares one report definition's engine input, submits it to the compute grid, records what came back, and settles the report instance. |
The engine cluster that runs these workflows is ordered by Workflows.
3. Adding a workflow
compass add workflow \ --slug <slug> \ --title "<title>" \ --description "<one line>" \ --tags "workflow,<topic>"
--parent-dir defaults to doc/knowledge/workflows, so it can be omitted. The
file is workflow_<slug>.org. Fill in every section the scaffold leaves, then
add a row to the table above. The full contract is on
Document type: workflow; the recipe
is New workflow.
4. See also
- Journey execution — where the transaction boundary sits between a user journey and the workflow that carries its state.