HL7 interfaces, in plain English

If you run a clinic, a health-tech product, or the IT shop between them, you have probably had this meeting.

Two systems need to talk. Someone says “we’ll build an HL7 interface.” Everyone nods. Six months later the project is somehow both over budget and not done.

This is the plain-English version of what is actually going on.

What an HL7 interface really is

HL7 develops a family of healthcare interoperability standards, including HL7 v2, CDA and FHIR. In this article, an HL7 interface means the familiar v2 message exchange. Examples of v2 message families include:

• ADT — admissions and demographics
• ORM — orders
• ORU — results
• SIU — scheduling

An “interface” is the pipe that carries those messages from one system to another, plus all the translation that happens in the middle.

Both systems speak HL7 the way two people can both speak English and still misunderstand each other.

One message, read out loud

Here is the part nobody shows you. An HL7 v2 message, the old version and still what most interfaces I meet run on, is plain text: each line is a segment named by three letters.

MSH|^~\&|EHR|HOSPITAL|BILLING|CLINIC|20260921083000||ADT^A08|00921|P|2.3

PID|1||100574^^^HOSPITAL^MR||DOE^JANE^A||19850214|F|||123 MAIN ST^^AUSTIN^TX^78701

This is an invented two-segment fragment for reading practice, not a complete conformant ADT message. The required segments and fields depend on the v2 version, trigger event and implementation profile. MSH identifies sender, receiver, timestamp and message type; ADT^A08 represents a patient-information update. PID holds patient identifiers and demographics.

Bars separate fields, carets separate the pieces inside a field, and nothing is labeled, because meaning is positional. That birth date is a birth date because it sits in the seventh field of PID and both systems agreed years ago.

Read the acknowledgment code, not just the presence of an ACK. HL7 distinguishes application acceptance, error and rejection (AA, AE, AR); enhanced acknowledgment also distinguishes commit outcomes (CA, CE, CR). The agreed mode determines what each response establishes. Even an accepted message still needs reconciliation against the intended patient and business result. See the HL7 acknowledgment-code definitions.

Where the translation actually breaks

The translation is the whole job, and it is decided field by field — the same work as finding the three fields that actually matter in a resource. One system puts the patient’s insurance in a field the other system uses for something else. One sends a cancellation as a new message; the other expects a status change. The standard is a starting point, not a guarantee.

The mismatches are boring and they repeat. One field here, two fields there, so somebody decides in writing where the middle initial in DOE^JANE^A ends up. A code that is a number on one side and a word on the other. And when the standard has no home for something a vendor needs, the vendor adds a segment of its own, a Z-segment, which only those two systems understand.

Corrections and merges need their own tested paths. HL7 v2 includes merge events, such as ADT^A40 for patient identifiers. If that event is not sent, mapped or applied correctly, a receiver may keep duplicate records after the source has merged them. Agree on the surviving identifier, references and reconciliation procedure. These are the kinds of mismatches behind two dashboards disagreeing.

Why the integration engine matters more than the interface

You can wire system A directly to system B. It works — once.

As systems and message flows multiply, separate point-to-point routes can accumulate duplicated translation logic. Count the actual directions, profiles and failure paths; there is no fixed number of pipes created by a third integration.

An integration engine — such as Mirth Connect, Rhapsody or Cloverleaf — can centralize configured channels and connectors. A system may need more than one connection or mapping. Depending on configuration, the engine provides:

• Routing
• Translation
• Queuing when a system goes down
• Message and error logs with defined access controls, retention and deletion

When an interface breaks at 2 a.m., the engine is the difference between “replay the queue” and “call the vendor and pray.”

The problem the engine quietly creates

The hub creates problems of its own. Queuing hides failure, which is what you asked it to do: a system vanishes for three hours, the engine replays the backlog, and nobody learns it is fragile. Retry without notification is not resilience.

Rules migrate into the engine too. Every exception that did not fit becomes transformation logic in a channel, and the engine ends up holding rules that exist nowhere else. Treat channel logic like code somebody reviews.

“Why not just use FHIR and skip all this?”

FHIR represents data as resources such as Patient and Observation. REST APIs are one exchange pattern, alongside documents and messaging. For an on-demand query, a supported FHIR endpoint may be a good fit; check the actual implementation and profile. Reading an API like you belong in the room is useful here.

FHIR also supports event-driven exchange through messaging and subscriptions; availability varies by server, release and implementation guide. A working v2 interface can still be the right choice because its partners, mappings and operating procedures are established. Compare the actual capabilities and migration risks rather than treating v2 as push and FHIR as pull.

And the part that surprises people: FHIR does not remove the mapping work. Extensions are the new Z-segments, and two organizations can both be conformant and still put the same fact in different places.

The four questions to ask before any integration project

I ask these before quoting anything.

A mapping you cannot write is a mapping you do not have. If the coming argument is about what was promised rather than fields, write the scope that prevents it.

The first mistake, and the signal you fixed it

Almost everyone gets the same thing wrong first: they test with the vendor’s sample messages. Samples are clean, built to demonstrate the format, and they pass every test you write.

Test representative cases: missing fields, rapid encounter changes, duplicate identities, retries and source upgrades. Use synthetic data or appropriately authorized, de-identified samples; removing a name alone does not establish de-identification. The HHS guidance describes the applicable methods. Choose cases by risk and coverage, not a fixed message count, and repeat the tests after either system changes.

You will know it worked when:

• Someone who did not build it can say what crosses the interface, by message type.
• Both sides agree on yesterday’s counts, and when they differ you can tell which is wrong.
• A question about a field is answered from the mapping document, not a vendor ticket.

Where I fit

I have spent years on healthcare data plumbing — HL7 interfaces, integration engines, and the unglamorous work of making clinical data agree with itself.

The way I engage is deliberately small at first: an integration assessment that maps your systems, your message flows, and the two or three risks that will actually bite, before anyone commits to a build.

If the problem is less about one pipe and more about where episodes get lost between systems, that is a different exercise: map the journey across three systems and count the handoffs first.

If you are staring at one of these projects: here is how I run healthcare technology work, and here is a free half hour to talk through the specific mess. No deck, no pitch — bring the diagram, or the napkin, or nothing.

Try this

Take one interface you already depend on and answer four questions without asking a vendor: which message types cross it, what happens to a message that fails, where the field-by-field mapping document lives, and who would find out if it stopped at two in the morning. The questions you cannot answer are your real integration risk, and they are far cheaper to find today than during a go-live.