Concept explainer
Proving an integration
Explains how a connection is proven before it carries live data, through dry runs on a sandbox site, golden messages, round trips and the activation gate.
Pensieve proves each connection before it carries live data, by running its messages through the pipeline that will run them live while recording nothing. This page explains each proof, from the dry run to the gate a version passes before live traffic reads it.
The sandbox site
A sandbox site is a site set aside for testing, and a dry run starts only there. Every other site counts as live and is refused twice: before the message is parsed, and again where its writes would land. Even a misconfigured run therefore stops short of a live record.
An HL7 v2 sample whose processing ID marks it as production traffic runs with a warning beside its result. A message the connection already received can be replayed into a dry run read-only, and nothing from the run is stored.
What a dry run proves
A dry run takes a message through the same code as live traffic up to the write, which it captures, so its result stands for the live outcome. How to read that result is shown in the dry run simulator.
Codes that match nothing are listed in the result and stay out of the unmapped-code queue. An outbound run shows the exact HL7 v2 message or FHIR bundle that would be sent. It also shows whether the writes would travel as one transaction, and which conditional creates would find a record already on the sandbox site.
Golden messages and round trips
A golden message is a sample input kept with a connection, together with its approved result: the writes it would make, the acknowledgement verdict and the route. Every mapping change runs the connection's whole set, and a change that alters an approved result waits until the difference is reviewed and the new result approved. Each golden message is synthetic, or has had every patient detail replaced.
A round trip maps a message in and back out, and the values that come back must equal the values in the original. A field the mapping is set to drop is flagged as lossy and passes, and any other loss fails the check and names the field.
| Check | What it answers | Compared with | When it runs |
|---|---|---|---|
| Dry run | What one message would do under a chosen draft or the active version | The operator's own reading of the result | On demand, from the connection in Westron |
| Golden messages | Whether a change alters any approved result | The approved result kept for each message | On every mapping change, before promotion |
| Round trip | Whether mapping in and back out loses a value | The message's own original values | On every mapping change, before promotion |
Golden messages and round trips both set aside what differs on every run, such as the message time, the control identifier, generated identifiers, the order of repeated fields and line endings. Decimal values keep the places the sender wrote, so a change in precision counts as a real difference.
The gate to live traffic
A draft becomes the active version only after its dry run, golden messages and round trip pass. A version whose output fails validation or draws a rejection stays a draft. Promotion retires the active version in the same step, leaving exactly one version live for each connection and direction.
A connection carries live data only once it is activated after a passing simulation. The claims and payment rails then wait for a second person's approval, given under the rules in approval and second signature.
Live traffic reads the active version
Each message on a live connection is mapped by the connection's active version alone. Drafts, dry runs and failed checks leave that version, and the live record, as they stand.
Versions and going back
Each mapping version is a draft, active or retired. Saving writes a new draft and leaves the active version untouched, and Westron marks a connection whose draft differs from the version that is live. How rules and packs make up a version is set out in mapping fields.
Retired versions stay as they were, and each mapped record names the version that produced it. Going back to earlier rules is a change like any other: they are saved as a new draft, pass the same gate and are promoted, retiring the version they replace.
Rails proven before credentials
A rail is an outside service that carries claims, invoices or payments, such as the claims exchange, the Invoice Registration Portal, a payer or the payment gateway. Pensieve keeps a conformance bench for each of these rails: a stand-in for the outside service that answers in that service's own protocol. Each rail is exercised against its bench with signing, encryption and authentication running in full, which proves its exchanges before any hospital's credentials are configured.
The payment gateway's bench speaks the gateway's real protocol. Its signed capture notifications pass the same verifier as live ones, so moving to the hospital's merchant account changes the credentials and leaves the code as it is. The payment flow itself is set out in payments.
Until a rail's credentials are configured and switched on for a site, the rail reports that it is not configured. Staff carry on by hand meanwhile: claims are filed manually or on paper, and payment is taken at the counter.
Common confusions
Does a passing dry run put a connection live?
A passing dry run is one of the three checks. The draft becomes eligible for promotion only once its golden messages and round trip have also passed. The connection then carries live data after the version is promoted and the connection is activated.
Can we return to last month's mapping?
The earlier version is kept as it was. Its rules come back as a new draft, pass the same checks and are promoted, so a rollback is recorded like any other change.
Where do golden messages come from?
They start as synthetic messages, joined by the hospital's own samples with all patient details made up. Each is kept with its connection, and a dry run can take one as its input.
Read where proving sits among the other stages in the integration lifecycle, and how a proven connection is watched once it is live in running an integration.