Clinical workflow orchestration — user guide

This guide walks through the patient-journey features delivered by Milestone 28, in the order a facility would actually use them: configure a pathway, wire it to check-in, watch the journey run with the queue, and route checkout. Every walkthrough below was performed against a live system as part of delivery; the screens and behaviours described are the ones verified there.

Who this is for: facility administrators configuring pathways, front-desk staff running check-in, and clinical staff working the boards.

The governing rule: the platform ships the mechanism, never a pathway. Every facility defines its own workflows — or adopts a starter template and makes it its own.

---

1. Build a pathway (Workflow builder)

Screen: Workflows → Builder (/workflows/builder).

A workflow definition is a set of stages connected by transitions, optionally decorated with rules. While it is a draft you can edit everything; once published it is immutable — running patients must never have the pathway change beneath them. To change a published pathway, create a new draft (or copy it) and publish that.

When you create a definition the form asks two questions before anything else:

• What is it about? (subject type) — required. This is what the pathway carries: a Visit, a leave request, a claim review. Only a workflow whose subject type is Visit can be mapped to a visit type in §2, so getting this wrong produces a pathway that can never start at check-in. The three platform starters are already Visit, and a copy keeps its source's answer.
• What kind is it? (category) — optional, and administered from the Workflow categories panel on the same page rather than typed in. The platform ships Clinical; add your own beside it. A category cannot be deleted once definitions use it — retiring it leaves those references intact.

The list's About and Category columns show both. — under About means the definition is unclassified and cannot be mapped to a visit type until it is.

For each stage the add-stage form offers:

• Initial stage — where a journey begins (exactly one per definition).
• Terminal stage — reaching it ends the journey (or that branch of it, see §4).
• Queue (optional) — entering the stage places the patient on this queue; leaving ends the queue entry. This is how the waiting board follows the journey. A stage with no queue enqueues nothing ("In consultation" needs no queue).
• Fork (parallel split) — entering this stage fans the journey across all its outgoing transitions at once (see §4).
• Join (reconvergence) — ALL waits for every incoming branch before activating; ANY admits the first branch and quietly merges the rest.

While the definition is a draft, stages are drag-reorderable by the grip handle on each row (keyboard-operable too); the order is the sort order boards and pickers show. Transition edges are edited in the transitions form below the list — the builder deliberately does not promise a flowchart canvas.

Each stage row's caption states what was declared — "Forks across its transitions.", "Join (ALL: waits for every branch).", "Bound to Triage Queue." — so a pathway's shape is readable without opening anything.

Required forms (the stage ↔ form binding): each stage can name one or more published forms its assigned roles fill, with a minimum submission count. The journey cannot leave the stage until the required submissions exist for it — the refusal names the form, so the clinician knows what to fill rather than just that something is missing. Submissions filled for a journey record which stage they were filled at, so clinical registers fall out of the process automatically. The override (§3) deliberately bypasses form requirements, exactly as it bypasses the pathway itself.

Rules automate movement:

• REQUIRE_DATA — the journey cannot leave the stage until named data keys are present.
• AUTO_ADVANCE — on entering a stage, the journey immediately advances (optionally conditional). Chains are depth-capped: a cycle of auto-advancing stages halts loudly instead of looping.
• CONDITIONAL_BRANCH — a move is redirected by instance data (e.g. payer type).
• TRIGGER_ON_EVENT — a queue fact advances the journey: when the receptionist marks the queue item COMPLETED on the board, the journey moves on by itself. The board and the journey never disagree about where the patient is.

2. Wire pathways to check-in (visit-type mapping)

Screen: the Check-in journeys panel on the builder list page.

Which journey starts when a patient arrives is decided by visit type, per facility. Map Outpatient → Outpatient Pathway, Emergency → ED Pathway, and so on. Only published definitions are offered, and only ones whose subject type is Visit — mapping any other is refused, naming the mismatch:

Workflow definition LEAVE_APPROVAL is about LEAVE_REQUEST, not VISIT, so a visit type cannot start it.

A definition with no subject type at all is refused the same way, with the remedy in the message. Set it on the definition, then map.

There is deliberately no separate check-in screen. Clinical work starts from the patient's dashboard — checking in a scheduled appointment, starting a visit, or admitting — and every one of those paths opens a visit, which:

1. Issues the visit token — a daily waiting-area number, unique per facility per day, restarting at 1 each morning. The token belongs to the visit, so the patient keeps one number through every department — and it is never the hospital number, which would link a person across days on a public board. Facilities with no workflow configured at all still get tokens.
2. Starts the mapped journey (if the visit's type is mapped), with the visit as its subject. If the journey's first stage is queue-bound, the patient is on the board immediately. An unmapped visit type opens the visit normally — token included — and starts no journey.

Verified live: mapping Outpatient to a pathway through the panel, opening a visit from the patient dashboard, and watching token "001" appear at the top of the queue-bound first stage's waiting board — with the token (not the name) displayed when the board hides patient names.

3. Run the journey (moves, boards, and the override)

The journey advances three ways:

• Declared moves — staff move the instance along a declared transition.
• Queue triggers — completing the patient's queue item on the board fires any TRIGGER_ON_EVENT rule for that stage.
• The override — a permitted senior can move the journey to any stage of its definition, with a mandatory reason. The reason box is deliberately empty every time: a pre-filled reason becomes the reason everyone picks, and the override count stops being evidence that a pathway is wrong. Overrides are recorded as their own event type and are visibly distinct in the timeline. Overriding also moves the queue — no patient is left stranded in a queue nobody is calling.

Recording during the journey — the forms drawer on the patient's chart

Clinical observation forms are filled from the patient's chart, not from the form catalogue. Open a patient and use Clinical forms at the top of the chart: a panel slides in from the right listing the observation forms you can fill for this patient right now, with a search box for when the list is long.

What appears there depends on the visit:

• A visit type with a configured pathway — the panel offers only the forms the patient's current stage asks for, with Required against any the stage still needs and Complete against any already filled to its maximum. During a fork, the forms of both live stages are offered together.
• A visit type with no pathway — every observation form you have access to.
• No open visit — the panel says so rather than showing an empty list. An observation is recorded against a visit, so start one from the chart's actions first.

Show all forms I can access widens the panel past the stage, and says so while it is on. The pathway describes the expected route; it is not permission to refuse something the patient in front of you needs, so the stage list is a default, never a lock. Use it, and record why in the form.

Two people opening the same patient can legitimately see different lists — the panel obeys the same role and department/unit scoping as the form catalogue, so a midwife and a lab technician are offered their own forms and not each other's.

4. Parallel stages (bloods and X-ray at once)

Ordinary outpatient reality: the patient awaits bloods and imaging at the same time. Declare a fork stage (e.g. WORKUP) with transitions to BLOODS and IMAGING, and a join stage (e.g. REVIEW, join ALL) that both feed into:

• Entering WORKUP fans the journey: the patient occupies BLOODS and IMAGING simultaneously (two boards, if both stages are queue-bound). The fork itself is never somewhere a patient waits.
• While forked, a move must say which branch is moving.
• Arrivals at an ALL join park until the last declared branch lands; then the join activates and the journey is ordinary again. ANY admits the first arrival and merges the rest.
• A terminal stage ends its own branch; the journey completes only when the last branch ends — bloods resulting must not close a journey whose imaging is still walking.
• The override collapses every branch into its target: the clinician reroutes the patient, not a thread.

Verified live: a definition authored through the builder with a fork and an ALL join persisted both declarations, and the acceptance suite walks the full TRIAGE → WORKUP → (BLOODS ∥ XRAY) → REVIEW → DONE journey, including the parked first arrival and the branch-scoped move requirement.

5. Patient status alerts and checkout routing

Status alerts. When a patient joins a queue they are texted their position ("You have joined the queue. Your position is 3."); when they are called, they are texted to come forward. The "wait estimate" is deliberately the position number — an invented minutes prediction would be worse than a position a patient can reason about. Alerts respect the patient's notification preferences end to end: a muted channel produces a recorded suppressed event, never a text — only critical-result chasing may bypass an opt-out. A patient with no phone on record simply gets no alert; the board still shows the truth.

Checkout routing. The visit-type mapping's second half: an optional checkout queue per visit type. When a visit of that type ends (from the patient dashboard's End visit / discharge actions), the patient lands as a WAITING item in the configured queue — billing or follow-up picks them up from there, and the consulting room is free. This hangs off the visit, not the workflow, so a small clinic with no pathway at all still routes checkout. A mapping may carry a journey, a checkout queue, or both — never neither.

Verified live: a mapping carrying both halves authored through the panel; a real visit ended from the API landed as a WAITING item in the configured billing queue.

6. Shared templates and platform starters

Three sharing tiers, labelled on every definition:

Tier	Who sees and uses it
This facility	Only the facility that created it.
Tenant-wide	Every facility of the tenant may map it directly, and any facility may copy it to customise.
Platform starter	Every tenant sees it — as a template only: copy it to adopt it.

• Definitions are created facility-scoped. Sharing one tenant-wide is a deliberate action behind its own permission (held by tenant administrators, not by ordinary builder users).
• Copying (Copy on any visible definition) creates a fresh draft in your own facility, carrying stages (fork/join included), transitions and rules. Queue bindings are carried only when copying within the same facility — queues are facility business — and any number of facilities can each take their own copy of the same template.
• The platform ships three starters: Outpatient Visit, Emergency Department (with a parallel workup, so the first thing a copying facility sees is the fork/join machinery working) and Antenatal Care. Starters carry no queues, roles or rules — those are yours to add after copying. Mapping a visit type straight onto a starter is refused with a message telling you to copy it first.

Permissions referenced in this guide

Permission	Grants
workflow.definition.read / .write	See / author definitions, structure, and copies
workflow.tenant-definition.write	Share a definition tenant-wide
workflow.instance.write	Ordinary journey moves and task actions
workflow.instance-override.write	The pathway override (granted to seniors separately)
workflow.visit-type-mapping.read / .write / .delete	The check-in journeys / checkout panel
workflow.category.read / .write	See / administer workflow categories
workflow.subject-type.read	The subject-type picker on the definition form
queue.queue.read	The queue pickers (screens degrade gracefully without it)