Patient journey
Who this is for: front-desk and clinical staff moving a patient from arrival to a completed visit — and the administrator who has to make check-in work in the first place.
Source: guides/demographic.md, guides/queue.md, guides/workflow.md, guides/clinical.md,
guides/billing.md, guides/scheduling.md.
The shape of it
register → (optionally book) → check in → visit → clinical record → orders & results → billing
Two things about this sequence are worth knowing before you start, because both look like faults when you meet them cold:
- Booking an appointment does not check a patient in. They are separate acts, and an appointment alone will not put anyone on a waiting board.
- Check-in only starts a care pathway if someone configured one. Without that configuration the visit still opens perfectly well — it simply does nothing else. See Making check-in actually do something.
1. Register the patient
Patients enter the system through patient registration.
⚠ There is no way to create a "person" directly, and that is deliberate rather than an oversight. A person record reachable on its own would be a way to read or change someone's identity without the checks that patient, staff and provider registration each apply. Registration creates the underlying person as part of registering.
→ Guide: People and patients
2. Book an appointment (optional)
Appointments are useful but not required — a walk-in can be checked in without one.
⚠ Availability is computed on every request from the provider's template, minus blocked time, minus existing bookings. A slot therefore describes what was free when you asked, and a booking can still be refused at the moment you submit it. That refusal is the system preventing a double booking.
→ Guide: Appointments and provider calendars
3. Check in
Check-in is one step that does three things: it opens the visit and issues its visit token, it starts the care pathway configured for that visit type, and it puts the patient on the waiting board.
⚠ This is why there is no "arrived" button on the appointment screen. A second way to check in would be a second place the token can fail to be issued, and that kind of mismatch surfaces on a public waiting board at the start of a clinic, when it is hardest to diagnose.
→ Guide: Queues and waiting boards
Making check-in actually do something
This is the part that most often looks broken, and it is configuration rather than a fault.
A visit type with no journey mapped still opens the visit and still issues the token. It simply starts no pathway. For a long time that state was invisible: the visit opened, the token printed, and the pathway silently did not run — a visit type that started no journey looked exactly like one that worked.
The configuration health panel now says so in plain terms, on the same screen as the fix:
⚠ The health panel names no patient and no visit, deliberately. The gap is a property of the configuration, and naming a patient would both put clinical information on an administration screen and imply the problem was that patient's.
The chain, in order
To make a visit type start a journey, four things must happen in this order:
| # | Step | Why it cannot be skipped |
|---|---|---|
| 1 | Copy a platform starter into your facility | Starters are owned by the Global tenant and are templates. The server refuses to map a visit type to one and answers "copy it into this facility first" |
| 2 | Build the journey on a draft version, binding steps to queues | Structure can only be edited on a draft |
| 3 | Publish that version | Only published definitions can be mapped — the picker offers nothing else, mirroring the server's own refusal |
| 4 | Map the visit type to the definition | This is the link that makes check-in start it |
⚠ Why publishing cannot be undone
A published version is immutable. To change a journey you create a new draft version, edit that, and publish it in turn.
This is not a limitation to work around. Visits already in progress refer to the version they started under, and editing that version beneath them would rewrite the pathway of care that had already been given — retrospectively changing what the record says happened. Creating a new version leaves every in-flight visit on the definition it began with, which is what makes the record trustworthy later.
The workflow code is likewise fixed once created; the name and description can change.
Both halves are optional, but not both at once
A visit-type mapping can name a journey, a checkout queue, or both. Naming neither configures nothing, and the server refuses it rather than storing a row that does nothing.
Also used for: the workflow engine behind this is the same one that runs leave approval, shift swaps and critical-result review. This page describes its patient-visit use; the mechanism is identical, only the subject differs.
→ Guide: Workflows
4. The visit and the clinical record
Once checked in, the patient has an open visit, and clinical work attaches to it.
⚠ Forms that collect a patient's record are opened from the patient's dashboard, not from a forms menu. This is what guarantees the record is attached to the right patient and the right visit — a form opened out of context would have nowhere correct to file what it collects.
⚠ Being a clinician is not by itself enough to open any given patient's record. Access is decided per patient, and every such decision is recorded. A record you cannot see is usually a scope or access-grant question rather than a missing record.
→ Guide: Clinical records
5. Orders, results and referrals
Orders raised during the visit — laboratory, imaging, medication — travel to the module that fulfils them and come back as results against the same visit.
Also used for: a referral is a kind of order, not a separate mechanism. It follows the same lifecycle, which is why it appears alongside clinical orders rather than in a section of its own.
⚠ Critical results are acknowledged, not merely displayed. The acknowledgement runs through the workflow engine, so an unacknowledged critical result stays on someone's queue rather than depending on a clinician happening to look at the right screen.
6. Billing
Charges accrue against the visit and become an invoice.
→ Guide: Billing
What stops this working
| What you see | What it actually is | What to do |
|---|---|---|
| Patient is booked but not on the waiting board | They have not been checked in — booking and check-in are separate acts | Check them in |
| Check-in "works" but no pathway runs | The visit type has no journey mapped, so there is nothing to start | Use the configuration health panel; follow the four-step chain above |
| A starter journey cannot be mapped | It is a Global-owned template | Copy it into your facility first, then map the copy |
| A definition is missing from the mapping picker | It is not published — only published definitions can be mapped | Publish the draft version |
| A journey cannot be edited | That version is published, and published versions are immutable | Create a new draft version; in-flight visits stay on the version they started under |
| The mapping form refuses to save | It names neither a journey nor a checkout queue, so it would configure nothing | Name at least one |
| A clinical form cannot be opened | It is being reached outside a patient context | Open it from the patient's dashboard |
| A clinical write is refused | A prerequisite is missing — an open visit, an encounter, or access to this patient | Check the visit is open and that you have access to this patient |
| A patient's record cannot be seen at all | Access is decided per patient, not per role | Check visibility scope and access grants |
| A patient cannot be found by name | Names are stored encrypted; existing records need re-indexing after that is enabled | An operations task, not a data-entry one |
Where to go next
- Setting up tenants, facilities and modules → Platform administrator journey
- Onboarding staff → Staff journey
- Credentialling and clinical work → Provider journey