Clinical Timeline
Category: Healthcare Standards
Node id: clinical-timeline
Maturity: production
Risk tier: B
Standards: FHIR R4, HIPAA, GDPR
Assemble one ordered timeline per patient from reconciled clinical acts: every cluster of duplicates collapses to its single best record, unclustered acts pass through, and each entry keeps the source systems that contributed it. Reads the EMPI service; does not decide matches itself.
What it does
- Collapses each cluster of duplicate acts to its single best record
- Keeps the contributing source systems on every entry
- Orders by start time, with undated acts placed last
- Reports acts it could not place instead of dropping them
Use cases
- One consolidated timeline per patient across heterogeneous systems
- Showing a clinician which systems contributed each visit or test
- Measuring how much duplication a feed carries
Runtime
- Performance tier:
variable
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
record_ids | json | Yes | EMPI record ids of the acts to place on the timeline, as emitted by the EMPI node in ingest mode. |
patient_global_id | text | No | Patient the timeline belongs to. Recorded on the result; acts belonging to a different patient are reported rather than placed. |
input | any | No | Ordering only. The operation reads the inputs and config it needs; a value wired here is ignored. Use it to make a step run after another that it takes no data from. |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
timeline | json | No | Timeline entries ordered by start time, each with its contributing source records. |
entry_count | number | No | Number of timeline entries, after duplicates were collapsed. |
source_count | number | No | Number of source act records the entries were built from. |
reconciled_count | number | No | How many entries came from a cluster of two or more source records. |
problems | json | No | Records that could not be placed, with the reason. Never silently dropped. |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Order | order | enum | No | asc | asc, desc | Chronological order of the timeline. Entries with no readable start time are always placed last. |
| Include Sources | include_sources | boolean | No | true | Attach the contributing source records to each entry. On by default: a merged duplicate whose origin cannot be checked is a fact a clinician cannot verify. |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Max Records | max_records | number | No | 500 | Refuse to build a timeline from more than this many act records. The node issues one request per record plus one per cluster, so an unbounded input is a slow request, not a large one. | |
| EMPI Base URL | empi_base_url | string | No | Override the EMPI service base URL (default from EMPI_SERVICE_URL or http://empi-service:8090). |
Errors
| Code | Description |
|---|---|
TIMELINE_INPUT | record_ids is missing, is not a list, or exceeds max_records |
EMPI_REQUEST | The EMPI service returned a non-2xx status or was unreachable |
Runtime notes
- Requires a signing secret — EMPI_JWT_SECRET, or the platform JWT_SECRET_KEY / JWT_SECRET — and a pipeline org context; the node mints a short-lived service JWT scoped to the active org.
- Issues one request per record plus one per cluster, so it is intended for one patient at a time rather than a population sweep.
- Survivorship is read from the EMPI single-best-record endpoint, not recomputed here, so the timeline and the golden record can never disagree.
- Pairs awaiting a human decision stay separate entries; run the review queue first if the timeline must reflect them.
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Something unclear? Send documentation feedback by email.