Blog

EHR integration: the routes in, and how to plan the work

EHR integration explained from the standards and US rules: the FHIR, bulk and HL7 v2 routes into a health record, what each allows, and how to plan one.

EHR integration is the work of connecting other software to an electronic health record, so that patient data moves between them without anyone copying it by hand. A scheduling tool reads a patient’s appointments from the record. A lab system sends results back into the chart. A remote monitoring app shows a clinician readings the record never held. In each case the EHR stays the system of record, and the integration decides which data leaves it, which data comes back, and who is allowed to ask. This guide covers the routes into an EHR that the standards and US certification rules define, what each route can and cannot do, and the order in which to plan the work.

The sources are the standards bodies and the regulations themselves: HL7 International’s implementation guides and the US Code of Federal Regulations. For an overview of the systems around the record and the standards each one speaks, start with what software is used in healthcare; this guide picks up where that one stops, at the point where you have to build the connection.

What does EHR integration mean in practice?

It means answering four questions for each flow of data before choosing any technology:

  • Direction. Does your software only read from the record, or must it also write to it?
  • Scope. Is the request about one patient at a time, or a whole population, such as every diabetic patient of a practice?
  • Who is present. Is a clinician or patient signed in and looking at the screen, or does a server run on its own at night?
  • Timing. Must the data arrive the moment something happens in the hospital, or is a daily copy good enough?

The answers point to different routes. An app a doctor opens beside a patient’s chart needs a different connection from a nightly report across thousands of patients, and both differ from a feed that tells you the moment a patient is admitted.

The routes into an EHR

RouteWho starts itWhat it suitsWhat to check first
FHIR API with SMART App LaunchA clinician or patient, signed inApps that show or use one patient’s dataWhich resources the EHR exposes, and which scopes it grants
SMART Backend Services and bulk FHIR exportA server, with no user presentPopulation data, reporting, analyticsWhether the export covers the groups and resources you need
HL7 Version 2 interfaceThe EHR or a department system, as events happenAdmissions, orders, results, in near real timeThe organization’s interface engine and its local message variations
The vendor’s own APIsYour software, under the vendor’s programWriting data back, or features the standard API lacksThe vendor’s terms, and whether the organization will switch the API on

An app launched with SMART on FHIR

FHIR is HL7’s web-based standard for health data. SMART App Launch is the HL7 guide that sets out how an app gets permission to use a FHIR API. It defines two ways in. In an EHR launch, a user already working in the EHR opens the app from there. In a standalone launch, the user starts the app from outside the EHR, as a patient does with an app on their phone. US certification rules name this guide for the standardized API that a certified EHR must offer (45 CFR 170.215).

The SMART App Launch guide lays the sequence out in seven steps:

  1. Register the app with the EHR’s authorization server, once, before any launch.
  2. Launch. In an EHR launch the app receives two values: iss, the address of the EHR’s FHIR endpoint, and launch, an opaque identifier for this launch and its context.
  3. Read the server’s configuration from .well-known/smart-configuration at that endpoint, which says where to ask for authorization and tokens.
  4. Ask for authorization. The EHR decides whether to grant the access the app requested. Where its rules call for it, the user signs in and approves first.
  5. Exchange the code for an access token. When the app was launched in a patient’s context, the token response can say which patient.
  6. Call the FHIR API with the token.
  7. Refresh the token when it runs out, if the server issued a refresh token.

The seven steps of a SMART on FHIR app launch, as a numbered list. One: register the app with the EHR. Two: the app is launched from the EHR and receives the EHR's FHIR address and a launch identifier. Three: the app reads the server's SMART configuration. Four: the app asks for authorization, and the user signs in and approves where the EHR requires it. Five: the app exchanges the code for an access token, which can carry the patient in context. Six: the app calls the FHIR API. Seven: the app refreshes the token when it expires.

Two details catch out teams who have built ordinary OAuth logins before. The guide requires every SMART app to support PKCE, the protection against a stolen authorization code, and servers must refuse its weaker plain variant. And the permissions an app asks for are FHIR scopes, such as read access to one patient’s observations, so the app should request only the resources it will actually use. Expect the health system’s reviewers to read those scopes when they decide whether to approve the app.

A server pulling data in bulk

Some work has no user in the loop: a nightly quality report, a feed into an analytics store, a care management tool that needs every patient in a program. For this, SMART defines Backend Services. The client proves who it is with a JWT signed by its private key, having registered the matching public key in advance, asks for a token with the OAuth client credentials grant, and receives system/ scopes rather than patient or user ones.

With that token, the Bulk Data Access guide lets the client ask for an export of all patients, a defined group of patients, or all the data on the server. The certification rules require only the group export, so check which of the three an EHR offers. The export runs asynchronously. The client sends a kick-off request, receives a status address in the Content-Location header, and checks that address until the server returns a manifest listing the finished files. By default each file is newline-delimited JSON, one FHIR resource per line. An export can partly succeed, in which case the manifest also lists error files, so a client that only checks for success will miss records without noticing.

HL7 Version 2 feeds

Long before FHIR, hospitals connected their systems with HL7 Version 2 messages, and those interfaces are still running. A v2 feed is pushed by events: a patient is admitted, an order is placed, a result is ready. HL7’s v2-to-FHIR mapping guide lists the common message structures, among them ADT_A01 for an admission or visit notification, ADT_A02 for a patient transfer, and OML_O21 for a laboratory order. It also maps ORU_R01, the structure that carries results.

Most hospitals route these messages through an interface engine, which receives each one, transforms it where the receiver needs a different shape and passes it on. Joining that traffic means agreeing on a specification with the organization’s interface team: which events you receive, which segments and fields they fill, and how you acknowledge each message. The local variations HL7 v2 allows are the reason no two feeds are quite alike, as the healthcare software overview explains.

Writing back into the chart

The certified API has a limit that shapes many projects. The US criterion for it, 45 CFR 170.315(g)(10), requires the EHR to respond to requests and searches for a single patient’s data and for multiple patients’ data. It says nothing about creating or updating records. So every EHR certified to this criterion can be read from, for the core data set the rules define, and none is required to accept writes.

So a design that needs to put something into the chart, such as a note, a questionnaire answer or a device reading, has to find out early how that EHR accepts it. The answer may be a write operation in the vendor’s FHIR API, an inbound v2 message through the interface engine, or a document the clinician files. Each one has its own approval path, and the choice can change the scope of the build.

Is HL7 still relevant?

Yes. FHIR has not replaced Version 2 inside hospitals, and the two are built to run side by side. A common pattern is a v2 feed for events that must arrive at once, such as admissions and results, with a FHIR API for an app that looks up the rest of the patient’s record. The US rules still name Version 2.5.1 for reporting to public health agencies and immunization registries (45 CFR 170.205). Anyone integrating with a hospital should expect to meet both standards on the same project.

How to plan an EHR integration

1. Write each flow down

For every flow, record the data it carries, which way it goes, whether it concerns one patient or many, and how fresh it must be. One line per flow is enough. This list is what the EHR vendor, the health system’s IT team and your own developers will all work from.

2. Choose the route per flow

Use the table above. A project often ends up with more than one route, for example a SMART app for clinicians and a v2 results feed into the same backend. That is normal, as long as each flow has one owner and one route.

3. Read the vendor’s API documentation

The certification rule requires the documentation for the certified API to be public, at a link with no preconditions or extra steps. So you can read which FHIR resources, searches and scopes an EHR supports before any meeting. Registration of your app with the EHR’s authorization server is also part of the certified API, though each vendor and each health system runs its own approval process around it.

4. Settle the agreements before the data moves

If your software handles protected health information on behalf of a covered entity, such as a hospital or practice, HIPAA treats you as its business associate. The rules then require a written contract, the business associate agreement, before that information is disclosed to you (45 CFR 164.502(e) and 164.504(e)). Section 164.502(b) also sets the minimum necessary standard: make reasonable efforts to use, disclose and request no more than the task needs. Ask for the narrowest scopes and the fewest resources that do the job, and expect the health system’s security review to check exactly that.

5. Map the codes and the patients

Two systems can agree on FHIR and still disagree on meaning. The US Core profiles call for a LOINC code, where one exists, to say what a lab test measured, RxNorm for medications, and SNOMED CT or ICD-10-CM for problems (US Core). If your software keeps its own lists, map them to these codes and decide what happens to a value that has no match.

Patients need the same care. Your system and the EHR identify a patient by different numbers, so decide early how the two are linked, and what a person does when a match is uncertain. Matching on name and date of birth alone can attach data to the wrong person, because two patients can share both.

6. Test in a sandbox, then in their environment

Build against a vendor sandbox first, since it lets you test the launch, the scopes and the resources with synthetic patients. Then test in the health system’s own non-production environment, where the local configuration and the interface engine’s transformations apply, along with the organization’s real code lists. Data that passed in the sandbox can fail there for reasons that have nothing to do with your code.

7. Log everything and watch for silence

The HIPAA Security Rule requires audit controls that record and examine activity in systems holding electronic protected health information (45 CFR 164.312(b)). Log every request, every message and every token issued. Watch for failures, and also for silence: an interface that stops sending messages raises no error on its own, and the first person to notice may be a clinician looking for a result that never arrived.

What decides how long an EHR integration takes

The code is only part of the timeline. Time also goes into approvals: registering with the vendor’s program, the health system’s security and privacy review, the business associate agreement, and scheduling the interface team. Then come testing in the organization’s environment, mapping codes that do not line up, and agreeing what happens to a message that fails. A read-only SMART app against a well-documented certified API is the lightest case. A two-way integration that writes into the chart through a v2 interface at a hospital is the heaviest. Ask for the vendor’s approval steps and the health system’s review timetable at the start, because they set the date more than the build does.

How we take on an integration project

Healthcare is one of the industries we have worked in, and our engineers have worked under both HIPAA and GDPR. Integration code gets the same treatment as everything else we build: code review, access control and managed secrets, with audit logs built into the systems we hand over. For a new integration, the first scoping call is free. When the work reaches into several of an organization’s existing systems, a short paid assessment comes next: it produces a written map of which systems call which, and which reports depend on which tables, and our quote, fixed and itemized, comes from that map. Linking new software into what an organization already runs belongs to our enterprise software development work.

The full service behind this post: Enterprise Software Development Company & Services.

Ready to scope your project?

Send us two sentences about what you need. We reply within one business day with the next step and any questions we need answered first.

Get a Quote