Functional standard / What is being done / PatientInstance
Journey
The patient's path through states defined by a journey Definition: a program, an encounter flow, or a setting.
- Kind
- journey
- Collection
- /v1/journeys
- Initial state
- active
- Classification
- Operational
Scope and usage
The definition owns the state names and the effects on enter. The instance owns where this patient is, and the history.
Boundaries and relationships
- Resource status (active, completed, cancelled) is not the journey state. The journey state is the element state, moved with /move.
- Workflow guards are requires and gates on the definition, not code. See Care workflows.
Resource content
Elements this resource adds. It also carries the Instance, including patient_id.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| association_type | 1..1 | code | B | care_setting, encounter, or care_program. |
| association_id | 0..1 | id | — | The setting, encounter, or program. |
| state | 0..1 | code | R | Current step. Set from the definition's initial state. Harness-owned. |
| history | 0..* | JourneyStep | R | state, at, by, reason. Harness-owned. |
State machine
active/ initial — The path is open.completed— Reached a terminal definition state, or closed. Frozen.cancelled— Abandoned. Frozen.
active → completed, cancelled. The inner state machine is the definition's.
Frozen: completed and cancelled.
Invariants
ccs-jrn-1— A move must be allowed by the definition transitions. An empty transition map means any step.ccs-jrn-2— on_enter and on_exit effects follow the tiered rule: clinical effects are proposals.ccs-jrn-3— A journey cannot leave a state with unmet requirements. Care-team staff may force a move with a reason, and it is recorded as forced.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/journeys | List journey. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/journeys | Create a journey. Body is the resource minus harness-owned elements. |
| GET | /v1/journeys/{id} | Read one journey. |
| PATCH | /v1/journeys/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/journeys/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/journeys/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
| POST | /v1/journeys/{id}/move | Move the inner state. Body is { to, reason }, with force where allowed. |
| GET | /v1/workflows | List encounter workflows. |
| GET | /v1/workflows/{key}/board | Every encounter on this workflow, by stage. |
Notes
- Definition kind journey.
Example
{ "patient_id": "pat_…", "definition_key": "journey_opd_flow", "association_type": "encounter" }