Concept explainer
From message to record
Follows an inbound message through receipt, mapping and validation to the typed fact a tool acts on, and shows what is kept at each step.
Pensieve turns an inbound message into a record in a fixed order, from the bridge that frames it to the tool that acts on it. This page follows one message through each step, lists the facts a message can become, and shows what is kept along the way and why a replay is safe.
The path of one message
Receipt, the third step, and meaning, which runs from the fourth step to the verdict, are the two stages the trust boundary describes. The bridge handles the first two steps on the hospital network, before receipt.
- 1
The bridge frames it
A listener on orophin, the bridge on the hospital network, finds where each message starts and ends. It reads an MLLP frame for HL7 v2, checksummed blocks from an analyser on ASTM and the JSON of a FHIR push.
A file in a watched folder is collected as file drops describes. The bridge gives each message a trace identifier.
- 2
The bridge queues it
The bridge seals the message with AES-256-GCM into its local queue, and only then confirms receipt to the sender. The message waits there until the platform confirms its durable write, and is retried with jittered backoff while the link is down. After a bounded number of attempts it is held for review, as message failure and replay describes.
- 3
The platform receives it
Receipt is a single transaction that checks the bridge's intake grant, its right to deliver into this site, and looks for a duplicate. In the same commit it stores the raw message verbatim and writes a SHA-256 integrity record, a boundary record and a "message received" event. The boundary record and the event are free of patient data, and the bridge clears its queue entry once it hears the transaction committed.
The platform splits an HL7 batch at each message header, so each message in it is received, checked and answered on its own.
- 4
The platform gives it meaning
The integration engine, described in the integration architecture, reads the stored message in full. Each code resolves on the platform through terminology mapping, the site overlay before the central base. A code with no match is queued for a person, with its original kept.
The connection's active mapping configuration, described in mapping fields, then maps the message's fields into the record's typed shape, keeping each decimal to the places the sender wrote. Validation checks required values, coded values against their bindings and units against UCUM. The outcome is the mapped record, one per message, holding its verdict and any issues.
- 5
The platform routes it
The message's verb decides where it goes. For HL7 v2 the verb is the message type, trigger event and order control. For FHIR it is the resource type with its status, or the event a message header names.
Each verb leads to exactly one outcome: a typed fact the owning tool subscribes to, a scoped write into a record the connection may update, or a parked state until a route exists.
- 6
The sender reads the verdict
The platform builds the application acknowledgement, and the bridge hands it to the sender byte for byte on the connection the sender kept open. An HL7 v2 sender reads an original-mode acknowledgement whose MSA carries AA, AE or AR, and a FHIR sender reads an OperationOutcome.
A message of a type outside the accepted set is rejected with its reason stated. The accepted types and the meaning of each verdict are listed in HL7 v2, and the types left out in outside the supported set.
The facts a message becomes
A typed fact is a small event that names what happened and points at the mapped record. Results and order replies go to Forge, and admissions, updates and discharges go to Gate, with Atlas taking a patient's changed details.
A result carrying a panic flag also raises a critical-value fact for Sentinel. How the alert reaches a clinician is described in critical results.
| Fact | Raised by | Acted on by |
|---|---|---|
| Lab result available | ORU^R01, or a final FHIR DiagnosticReport | Forge, which moves the order's result from awaited to received |
| Critical value | A result carrying a panic flag, raised beside its lab result fact | Sentinel, which raises the alert |
| Patient admitted | ADT^A01 or ADT^A04 | Gate |
| Patient updated | ADT^A08, and ADT^A02 for a transfer | Gate and Atlas |
| Patient discharged | ADT^A03 | Gate |
| Order acknowledged | ORR^O02 or ORL^O22 | Forge |
| Order status changed | ORM^O01 or OML^O21 whose order control reports a status change | Forge |
What a fact carries
The record of the message's mapped values, where the acting tool reads them.
The site the message arrived for.
The connection the message arrived on.
The moment the fact was recorded.
The references its type needs, such as the accession and the placer and filler order numbers for a result, or the encounter for an admission.
A fact never carries a result value, a name or a diagnosis. The tool that acts on it reads the values from the mapped record under its own permissions, so it sees exactly what those permissions allow.
What is kept at each step
Every mapped record is stamped with the versions of the mapping configuration, the mapping pack and the terminology that produced it.
| Step | What is kept | Why it is kept |
|---|---|---|
| Bridge queue | The message, encrypted, until the platform confirms its write | A dropped link or a restart delays the message and loses nothing |
| Receipt | The raw message verbatim, its integrity record, its boundary record and the received event | The raw bytes are the source for every replay, and the hash proves what arrived |
| Meaning | The mapped record, with its verdict, its issues and the versions that produced it | Every value can be traced to the rules that built it |
| Unmapped codes | The original code and its code system, in a queue for a person | A person maps the code, and the original stays beside the resolved term |
| Routing | The outcome on the mapped record: the fact raised, the write made, or the parked state | A parked message waits for a route and can be replayed once one exists |
Why a replay is safe
A replay runs the stored raw bytes through meaning again, from terminology to the verdict, once a mapping is corrected or a route is added. Receipt runs once, so a replayed message keeps its single integrity record and its single boundary record, and its original bytes stay as they arrived.
The receipt key, made of the site, the bridge, the sending system and the message's own identifier, recognises a message its sender sends again within seven days. The sender is acknowledged again and nothing new is written, as delivery guarantees sets out for each direction.
Common confusions
Can a message write straight into a record?
Only as a scoped write: an allow-listed write into a record its connection may update. Every other verb raises a typed fact for the owning tool or parks the message until a route exists.
How does a result find the right order?
Through the accession and the placer and filler order numbers that mapping lifts from the message. Forge matches the result on those keys, never on the patient alone, because one patient can hold several open orders.
What happens to a message with no route yet?
It is parked, with its mapped record kept. Once a route for its verb exists, a replay carries it on to the outcome that route names.
Read how access, purpose and audit hold over these records in governance of integrated data, and how Pensieve sends data the other way in outbound exchanges.