EHR Interface

What is an EHR interface?

An EHR interface is a defined, monitored connection that moves one type of clinical or administrative message between an electronic health record and another system, usually as HL7 v2 messages through an interface engine. It has a written spec, an agreed transport, field mappings, acknowledgment rules and a named owner on each side.

The term covers more than the message format. Two systems can both speak HL7 v2 and still fail to connect, because each site fills fields differently, uses local codes and expects its own acknowledgment behavior. The interface is the agreement that settles those differences for one flow.

Interfaces are usually counted one per flow and direction. An outbound ADT feed to a lab system and an inbound results feed from the same lab are two interfaces, with two specs and two test plans, even when they share a VPN and an engine.

FHIR APIs have not made them obsolete. Certified EHRs must offer a standardized read API under 45 CFR 170.315(g)(10), but filing results, orders or documents into the chart usually still runs through an HL7 v2 interface or the EHR vendor's own write APIs.

What goes into the interface spec?

The spec names the flow, the systems, the events and every field the receiver depends on, and it is written before anyone builds a channel. Both teams test against it, so every gap in it turns into a defect later.

• Flow and direction: One sentence that says which events go from which system to which, for example ADT A01, A03 and A08 from the hospital EHR to a remote monitoring platform.
• Trigger events: The exact list, including the cancels and merges the sender emits, with a sample of each taken from the sender's test environment.
• Identifiers: Which PID-3 identifier is the key, which assigning authority it carries, and what the receiver does with a patient it has never seen.
• Code sets: Local codes for locations, order types, results and units, each mapped to the receiver's values, with a default for unknown codes.
• Volume and timing: Expected messages per hour at peak, real time or batch, and the longest acceptable delay from event to delivery.
• Transport: MLLP over a site-to-site VPN, HTTPS to an API, or SFTP for batch files, with the endpoints and certificates for test and production.
• Acknowledgments: Original or enhanced mode, the point at which the ACK is sent, and what the sender does with AE and AR responses.
• Owners: A named contact on each side for build, testing, go-live and production support.

Write the spec from samples, not from the vendor's generic interface document. The generic document describes what the product can send. The samples show what this site actually sends.

How does one message travel from source EHR to target?

A message passes through five stages: the source EHR builds it, the transport carries it, the interface engine receives and acknowledges it, the engine transforms and routes it, and the target system accepts or rejects it. The acknowledgment travels back along the same path to the sender.

• 1. Source EHR: A registration, order or result event fires, and the EHR's outbound interface builds an HL7 v2 message with the message type and trigger event in MSH-9 and a control ID in MSH-10.
• 2. Transport: The message is wrapped in MLLP framing and sent over the VPN to the engine's listener port. The sender usually holds its next message until a reply arrives.
• 3. Interface engine receive: The engine parses the message, stores a copy and returns an ACK. In an engine-level design the ACK goes back once the message is safely stored; in an end-to-end design it waits for the target's result.
• 4. Transform and route: Filters drop events the target does not need, transformers map identifiers, codes and fields, and the router sends the result to the right destination.
• 5. Target system: The receiver takes the message through its own listener or API and returns a success or error response, which the engine logs against the original control ID.
• 6. ACK and error path: AA tells the sender the message was accepted, AE signals an error where a resend may succeed, and AR a rejection. A failed message goes to an error queue with a readable reason.

The choice in stage 3 matters most. An early ACK keeps the sender's queue moving but makes the engine responsible for every message it has accepted. A late ACK tells the sender the truth but lets a slow target hold up the whole feed. Settle it in the spec, not during testing.

The HL7 deep-dives go further into each stage: ADT event handling, Mirth Connect channel design, acknowledgment modes, error reprocessing and v2 to FHIR mapping. This guide stays at the level of the whole interface and the decisions that sit between those topics.

What controls does the connection need?

An interface that carries patient data transmits, and often stores, ePHI, so the engine, its message store and the network path need the same safeguards as any clinical system. Two federal references set the frame, and the rest is engineering practice.

• Audit and transmission: The HIPAA Security Rule at 45 CFR 164.312 requires audit controls for systems that contain or use ePHI and sets a transmission security standard, with encryption in transmission as an addressable specification.
• Safety guidance: The 2025 SAFER Guides from ASTP/ONC include a System Management guide that covers configuration, validation and maintenance of EHR hardware, software and system-to-system APIs.
• Network path: A site-to-site VPN or TLS on the MLLP connection, with the choice and its reasons written into the spec.
• Message store: Encrypted storage for retained messages, a pruning schedule, and access limited to the support team.
• Contracts: A business associate agreement in place before the first sample with real patient data changes hands, when an outside company runs the engine.
• Recovery: Channel exports kept in version control and a tested restore, so a lost server can be rebuilt quickly.

None of these name a product. The spec should record how this interface meets each item, so a security reviewer can check it without reading channel code.

How should the interface be tested before go-live?

Test in layers, from a single message up to a full day of realistic traffic, and include the failures. An interface that has only passed clean messages has not been tested.

• 1. Connectivity: The VPN is up, the listener accepts a test message and returns an ACK, and certificates match on both ends.
• 2. Single messages: Each trigger event in the spec is sent one at a time and compared field by field with the expected output.
• 3. Edge cases: A merge, a cancel after an admit, a patient with two identifiers, a name with an apostrophe, a result with an unmapped code, and an empty optional segment.
• 4. Failure paths: The target is down, the sender resends a duplicate, a message is malformed, and the engine restarts with messages still queued.
• 5. Volume: A replay of a busy day's message count at the expected peak rate, watching queue depth and end-to-end delay.
• 6. Workflow: Clinical or operational users run real scenarios end to end, such as register, admit, order, result and discharge, and confirm what they see in the target system.

Use synthetic test patients, never production records copied into a lower environment. Keep the signed-off results with the spec, because the next change to the interface will need them as its baseline.

What happens on go-live day?

Go-live moves the interface from test endpoints to production with a rollback ready. It is short when the preparation is complete and long when it is not.

• Before the window: Production endpoints, certificates and firewall rules are confirmed, the reviewed channel export is imported rather than edited in place, and users know when data will start to appear.
• Cutover: The sender points to the production listener, a first live message is traced from source to target, and both teams confirm the same control ID on each side.
• Backload: Both teams agree whether events from before go-live are resent, and if so, which date range and in what order.
• First hours: Every error is reviewed, counts are compared with the source system's own outbound log, and build engineers stay on the call until the agreed exit point.
• Rollback: A written condition for turning the feed off, and a plan for the messages that were sent while it was on.

The first live day often brings codes and values the test environment never sent. Log them, add them to the map, and replay the affected messages once the map is fixed.

Where interfaces fail after go-live

Many interface problems after go-live are quiet: nothing errors, and data simply stops arriving or arrives wrong. Monitoring has to look for silence and drift, not only for failures.

• Silent sender: The source EHR's outbound queue stops after an upgrade or restart, and the engine receives nothing. Alert when a feed is idle for longer than its usual gap.
• Growing queue: A slow target makes messages back up in the engine. Alert on queue depth and message age as well as on errors.
• New local codes: The site adds a location, order or result code, and the map sends it to the default value. Report unmapped codes every day.
• Upgrade drift: An upgrade on either side changes a field's content or repetition. Rerun the signed-off test set after every upgrade.
• Unowned errors: The error queue fills with messages nobody reviews. Name an owner and a response routine for each queue.
• PHI in support tools: Full messages get pasted into tickets or chat. Log control IDs and outcomes, and keep message content in the engine's access-controlled store.

A monthly review of these points, with counts taken from the engine, keeps a working interface working. It also produces the activity records the audit controls standard expects to exist.

How Agnotic can help

A single interface touches two vendors, two IT teams and a clinical workflow, and the work between them often has no clear owner. Agnotic Technologies builds that work for the client: the spec drawn from real samples, the engine channel, code maps, the test set, go-live support and the monitoring that catches silent feeds.

Agnotic also reviews interfaces already in production against the failure points above, and fixes the ones that fail quietly.

Sources

• HL7 International: Version 2 product suite (message structure and acknowledgments)
• 45 CFR 170.315: certification criteria, including (g)(10) standardized API
• 45 CFR 164.312: HIPAA technical safeguards, audit controls and transmission security
• ASTP/ONC: SAFER Guides, 2025 edition including System Management