EHR Connectors

Medipal can link its patients to records in an electronic health record (EHR) system and show clinical data, such as observations, conditions, medications, encounters and appointments, alongside questionnaire results. This page explains what an EHR needs to provide and how a connection is set up.

Clinical sources

A clinical source is the configuration record for one EHR connection on an instance. It identifies the source, describes how to reach it and states which identifier system the hospital uses for patients. An instance can have several sources enabled; searches and data requests fan out across all of them and results are merged by patient identifier.

Supported source types:

Kind	Connection	Description
FHIR	REST	A FHIR R4 server queried directly over HTTPS. The most common option for hospital integrations.
FHIR	Data lake	FHIR resources already exported to a relational store maintained by an ETL process.
OMOP	Data lake	An OMOP common data model database, used for patient search and demographics.

What a FHIR server must provide

| Requirement | Detail | | -------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | FHIR version | R4 | | Capability statement | GET /metadata must be available; it is read on connection and refreshed periodically. | | Resource types | Patient, Observation, Condition, MedicationRequest, Encounter, Appointment | | Patient search | Search by identifier (Patient?identifier=<system> | <value>) using the identifier system declared on the clinical source | | Clinical searches | Search by patient reference on each resource type above | | Transport | HTTPS with a certificate trusted by the instance |

Authentication

Option	When to use
Bearer token	The EHR issues a long-lived token for the Medipal instance. The token is stored in the Vault and referenced from the source configuration.
None	Access is controlled by network rules only, for example a private link between the hospital and the instance.

Tokens are never written into the clinical source itself. They live in the Vault and the configuration points at them by reference, so rotating a token is a Vault change only.

Setting up a connection

1. Store the credential. Create a Vault entry holding the bearer token issued by the EHR.
2. Register the clinical source. Create the source with its name, kind, connection type, base URL, identifier system and a reference to the Vault entry. The configuration is validated when it is saved; an invalid shape is rejected before anything is stored.
3. Verify. From the web application, search for a known test patient by identifier. A result confirms that the capability statement was read and that patient search works.
4. Enable clinical panels. Turn on the clinical view feature so clinicians see the patient's clinical data tabs. See Clinical Sources (EHR).

A source can be disabled without deleting it; disabled sources are skipped by searches and refreshes, and previously linked patients keep their links.

How linking works

1. A clinician searches the EHR by the hospital's patient identifier.
2. Medipal queries every enabled source and shows the matches with their demographics.
3. The clinician links a match to a new or existing Medipal patient. The link is stored as an external identifier on the patient record.
4. From then on the patient's profile shows a demographics snapshot and clinical data panels fetched from the source.

Data refresh

Demographics are cached as a snapshot on the patient record and refreshed in the background after each read, so profile pages stay fast while data stays current. Clinical data panels are fetched on demand with optional date ranges. A clinician can force a refresh of the demographics snapshot from the profile.

Connections are protected against a slow or failing EHR: requests time out, repeated failures pause calls to that source for a short period, and other sources keep working. Metrics on request counts, latency and failures are available to operators.

Testing without a real EHR

A synthetic FHIR test server with fictional patients and clinical data can be provided for evaluation and development. It behaves like a real FHIR REST source and is configured in exactly the same way, so an integration built against it works unchanged against a hospital system.

Privacy considerations

• Clinical data is read from the EHR on request and displayed to authorised clinicians; only the demographics snapshot and the link identifiers are stored on the instance.
• Access to patient search, linking and clinical data is controlled by dedicated patient and clinical-source scopes. See Users, Roles & Scopes.
• Clinical data is not sent to the mobile app.
• Analytics can include clinical values next to questionnaire scores; see Analytics.