Document type: workflow

Implements

sequencing, declaration, recording. A workflow page declares the work a named workflow does, sequences its steps, and records what each step produces and how a failure of it is handled. See Regulatory Functions.

Folder

doc/knowledge/workflows/, one page per workflow, as workflow_<slug>.org. The folder sits beside doc/knowledge/architecture/ for the same reason a journey folder sits beside it: a workflow page is a durable, cross-cutting contract, not a record of one story's work.

Scope

the page owns one named workflow — what it achieves, who takes part, which messages it exchanges, and which steps it runs. The engine that runs it is not this page's subject. The step protocol, the instance and step states, failure and retry, idempotency, and waiting and deadlines are knowledge about the engine and stay in doc/knowledge/architecture/, indexed by Workflows. A workflow page links to that cluster; it does not restate it.

Level

cross.

Filename

workflow_<slug>.org. The workflow_ prefix sorts the pages together in the folder and makes the type obvious in ls.

Title

free-form; the codegen adds no prefix. Write the workflow's name as a reader would say it, for example Tenant provisioning.

(no term)

Not stateful — no TODO, no * Status table. A workflow page is the definition of a repeatable process, not a run of it. The run of a workflow is a workflow instance, and its progress is read, not written down here.

How to create

compass add workflow. --parent-dir is optional and defaults to doc/knowledge/workflows/. See How do I create a new doc? for the flags, and How do I add a doc with compass? for the verb.

Required sections (in this order)

• Blurb — three to five sentences between the frontmatter and the first * heading. It states the workflow's purpose and what it leaves behind when it finishes. A workflow page carries no * Summary heading; the blurb is the summary.
• * Purpose — the business outcome the workflow achieves, and what is true when it finishes.
• * Participants — the components and the roles that take part, and what each one is responsible for.
• * Messages — every message the workflow exchanges, each named with its subject and its objective. A message's key fields are shown by a class diagram rather than listed in prose.
• * Steps — a table of the workflow's steps: the operation, what it produces, and how a failure of it is handled.
• * Interaction — the interaction diagram, embedded with a #+caption: line and a [[proj:...png]] image, followed by the .puml source link and the plantuml -tpng regenerate line.
• * Failure and recovery — the failure policy the workflow declares, what a retry resumes from, and what cancelling it does.
• * Progress — the read a client follows to render progress, and the states it exposes.
• * Patterns used — one line per service architecture pattern the workflow applies, saying how it applies it. A workflow coordinates services, so the section is never empty. A pattern whose page exists is linked, and lists the workflow back under * In ORE Studio; a pattern whose page is not yet written is named in plain text. build/scripts/check_pattern_uses.py checks the links.
• * Related — a link to every page that bears on the workflow: [[file:...]] links for pages in the documentation, and id: links for the agile artefacts that built it, such as its story and its task.
• * See also — external references only. An internal link belongs in * Related or in the body, never here.

A workflow page is the durable statement of a process, so it outlives the sprint that wrote it. Two rules follow.

• The page is written from the definition, not from the run. Read the definition a service registers and the messages it declares, then write the page from them. A run that has not finished yet is not evidence for the page; the state a run reached belongs in a task or an investigation.
• The page owns the workflow, not the engine. A fact about how the engine dispatches, retries, or compensates a step belongs to the architecture cluster. When a workflow needs a rule the engine already states, link the rule; do not copy it. A copied rule drifts, and the copy is the one a reader finds first.

A user journey is a design document: what one person is trying to do, before anything is built. A workflow page is the server-side process that carries out the part of a journey that outlives a request. When a journey needs resumable state, the state is a workflow instance and the journey links the workflow page that defines it. See Journey execution for where the transaction boundary sits between the two.