Data model

Anatomy of a connection

Describes what a connection holds in Westron, its class, category, endpoint, purpose, mapping and credential reference, and the states it moves through.

Pensieve keeps one connection for each system it reaches through orophin, the bridge, or calls over a direct connection: a record in Westron that governs every exchange with that system. This page sets out the fields of that record, the states a connection moves through, and how templates, testing and a clean disconnect act on it.

What a connection holds

A connection is the platform's record of one counterpart: the bridge or address that reaches it, the purpose that justifies each exchange, and the rules that turn its messages into Pensieve's own shapes. It belongs to one site, and every crossing it carries is attributed to it. The wizard that creates one is walked through in connections and credentials.

site reference Required	The site that owns the connection, resolved from the operator's own session when the connection is created.
class choice Required	Bridge-hosted, for a system on the hospital network that the bridge reaches, or direct, for a partner service the platform calls.
category choice Required	Bridge, for every bridge-hosted connection. For a direct connection, the kind of counterpart: ABDM, NHCX, TPA, insurer or custom REST. The category fixes which endpoint fields apply.
wire format choice Required	HL7 v2, FHIR R4, ASTM, delimited rows or JSON.
endpoint structured Required	The bridge that carries a bridge-hosted connection. For ABDM, the participant code with any health information provider and user identifiers; for NHCX, the participant code and a reference to the encryption certificate; for a TPA, insurer or custom REST service, the base address and the authentication kind.
purpose of use choice Required	Why the connection exists, such as result intake or an order push. Every boundary record the connection produces carries it, and a crossing without one is refused.
mapping reference	The active mapping configuration for each direction, built from a pack and the connection's own overrides, with earlier versions retired and kept.
routes reference	The verb routes that send each mapped inbound message to a typed fact, a scoped write or a parked state.
credential reference reference	For a connection that uses a credential, a pointer to the hospital's secret in the secret store, at a pinned version.
declared capability snapshot	For a partner FHIR server, the resources and interactions it declares, read at the test and checked before every call.
status choice Required	Draft, configured, active, degraded or archived.
kill switch state Required	Released or engaged, stamped with who engaged it, when, and any reason given.
health derived Required	The last successful call and the run of consecutive failures, read from real traffic.

How a mapping is built from rules, and how its versions are kept, is described in mapping fields.

Bridge-hosted and direct

The class decides the route each exchange takes. A bridge-hosted connection rides the bridge's link, which reaches its system on the hospital network. The platform records each message it brings in against that bridge and the site the bridge serves.

A direct connection is called by the platform over HTTPS with the hospital's own credential, which the connection names by reference and the platform reads at the moment of the call. The methods each class carries are listed in connection methods.

The states a connection moves through

Figure 1.Diagram showing a connection moving from draft to configured to active, between active and degraded on the outcome of real calls, to archived when its kill switch is engaged and back to active on release, and out of the registry in a clean disconnect.

A connection is a draft while its details are being set, and becomes configured once they are saved and pass validation. Activation follows a passing test and the proving steps in proving an integration, and from then on the outcome of real calls moves it between active and degraded.

Engaging the kill switch stops intake before any write, closes live sessions within seconds and moves the connection to archived, where it stays in the registry. Releasing the switch returns it to active. Each connection's health shows on the board described in monitoring a connection.

Templates

A template is a preset that fills a new connection's defaults for a common kind of system: HIS, LIS, RIS-PACS, pharmacy and analyser families, and ABDM and NHCX. Templates carry no secrets, and each is checked against its category as it loads, so a mismatched preset fails before anyone uses it.

Presets are a starting point and certify nothing about any vendor's product. Their values can be changed before the connection is saved, and the connection they start is proved with sample messages before it carries live data.

Testing a connection

The test reaches as far as the class allows. A direct connection sends one bounded request, free of patient data and credentials, to its counterpart's address and reports whether the address answered and how long it took.

For a partner FHIR server, the test also reads the server's declared capability and keeps it on the connection, and every later call is checked against it before it leaves. A passing test proves reachability, and whether messages map and route as intended is proved separately in a dry run on a sandbox site.

A clean disconnect

A clean disconnect takes a connection out of the registry in six ordered steps: kill switch, drain, export, revoke, delete and confirm. The export is a snapshot of the configuration with patient data and secrets left out, and it stays as the record of what was removed. The guided sequence is walked through in connections and credentials.

A deletion is refused while the switch is released, and repeating one changes nothing, so an interrupted disconnect can run again.

Common confusions

How many connections can one bridge carry?

One bridge serves a site and carries many connections, each with its own record, mapping and routes. Every bridge-hosted connection names the bridge that carries it.

Does a passing test mean messages will map?

The test stops at reachability. Mapping, validation and routing are proved in a dry run on a sandbox site, which saves nothing.

Does the bridge hold partner credentials?

Credentials for national, payer and partner services belong to direct connections. Each is held by reference and read on the platform at the moment of the call, so it never reaches the bridge.

Read how a live connection is watched, replayed and rotated in running an integration, and how each crossing a connection makes is recorded in governance of integrated data.