HL7 integration

Xenrad accepts HL7 v2.5.1 messages so a site can keep patient and clinical data current. After storage, the same data is also readable over FHIR. Choose transport from what your facility already runs well.

MLLP is a long-lived TCP connection from your interface engine to a listening port. There are no HTTP headers. HTTP is a POST of a raw HL7 message to the HL7 HTTP host with an X-API-Key header.

Standard

Use v2.5.1 for MLLP and for POST /v2/ingest. Character encoding follows your engine’s default. The parser expects normal HL7 segment terminators, and MLLP framing when you use MLLP.

Message types that work

ADT^A01, ADT^A04, and ADT^A08 update visit context and demographics. ADT^A40 is patient merge. ORU^R01 carries observation results into patient observations. Other message types are rejected with a processing error. If your engine wants to send something outside that set, talk to engineering before inventing a mapping.

MLLP

Connect to the MLLP host and port your administrator published. Messages are wrapped in conventional MLLP block bytes.

There is no API key on the wire. The sender must be listed on an integration client with protocol hl7-mllp. The remote IP must pass the client’s allowed IPs. That can be a single IP, CIDR, or * only if policy allows any source. If the client has HL7 sender application or facility set, inbound MSH-3 and MSH-4 must match. Leave both empty on the client to skip that check.

A successful process returns an ACK with AA. Validation or mapping failure should return AE with a diagnostic in the MSA text.

Use MLLP when the hospital engine already speaks v2 MLLP and you are adding a new route.

MLLP listener — connect your interface engine to hl7.stg.xenrad.io:4420 (TCP, not HTTPS). DNS and reachability checks are on Endpoints reference.

HTTP

POST /v2/ingest on the HL7 HTTP host with X-API-Key: <api_key>. Body is the raw v2.5.1 message as text, the same payload you would put inside MLLP, without the MLLP wrapper. On success you get JSON with success: true, the detected message_type, and a rendered ACK string in ack.

For HL7 v3 XML, use POST /v3/ingest on the same host with Content-Type: application/xml. Interactive reference, when enabled, is /api/documentation on the HL7 host.

Use HTTP when you already centralize on HTTPS, mutual TLS, or API gateways.

What the service reads from ADT

PID drives patient resolution for the site carried by the authorized client (MLLP) or API key (HTTP). Identifier comes from PID-3. Name comes from PID-5. Date of birth comes from PID-7 in a yyyyMMdd pattern. Gender, address, and phone come from the usual PID positions. If PID is missing required identifiers, you get a clear error. For exact field fights, compare your outbound message to a known-good sample in a test environment.

ORU and the rest of the product

ORU^R01 lands as patient-linked observation content for the same site. Unsupported OBX patterns or missing patient keys surface in the ACK or HTTP response.

FHIR can read the updated Patient and related resources on the FHIR host. The Horizon worklist and the viewer still depend on DICOM for images. HL7 does not import images by itself.

Before you go live

Confirm the integration client has hl7-mllp and the right allowed IPs for MLLP, or an active site API key for HTTP. Confirm MSH sender filters match what you set. Confirm the HTTP key belongs to the target site. Then send one ADT in a non-prod environment and read the patient back over FHIR.