HL7 integration

Xenrad accepts HL7 v2.5.1 messages to update patient and clinical data for a site. The same data is also available over FHIR after it is stored. Choose transport based on your facility’s capabilities:

• MLLP — long-lived TCP from your engine to a listener your operations team provides; no HTTP headers.
• HTTP — POST a raw HL7 message with a Bearer token.

Standard

• Version: v2.5.1
• Character encoding — follow your engine’s default; the parser expects standard HL7 segment terminators and MLLP framing when using MLLP.

Message types and triggers (supported)

Other message types are rejected with a processing error.

Transport A — MLLP (TCP)

Connection: your sending system opens a TCP connection to the MLLP host and port your operations team gives you.

Framing: messages are wrapped in MLLP block bytes (start of block, end of block) as is conventional for v2.

Security model (no Bearer token on the wire):

1. The sender must be listed on an integration client with protocol hl7-mllp in its protocols list.
2. The remote IP of the connection must pass allowed IPs (single IP, CIDR, or * if your policy allows "any source").
3. Optional MSH filters: if the client has HL7 sender application and/or HL7 sender facility set, the inbound MSH-3 and MSH-4 must match. Leave both empty on the key to skip that check.

A successful process returns an ACK frame with an AA accept; on validation or mapping failure you should see AE with a diagnostic in the MSA segment text.

When to use MLLP: your hospital interface engine already speaks v2 MLLP to downstream systems; you add a new route to Xenrad’s listener.

Transport B — HTTP

Request:

• POST /hl7/messages on the HL7 HTTP base URL you were given.
• Header: Authorization: Bearer <access_token>

Token requirements (in addition to a valid access token for the right site):

• Scopes: system/Patient.write, system/Observation.write, and system/DocumentReference.write must all be present on the token (the HTTP listener enforces the combination).
• Audience: the access token’s aud must be xenrad-hl7-http. Request your token with audience=xenrad-hl7-http as described in OAuth2, API keys, and client assertions.

Body: raw HL7 message as text (the same string you would place inside MLLP, without the MLLP wrapper bytes is typical for HTTP—your integration should follow the example your environment documents). The service parses the payload and returns JSON with a success flag and a rendered ACK string in the body on success.

When to use HTTP: you already centralize on HTTPS, mutual TLS, or API gateways, or your cloud bridge prefers REST-style posting.

Field mapping (conceptual, ADT / PID)

The service reads PID to resolve patient and demographics for the site carried by the authorized client (MLLP) or the token (HTTP):

• Identifier from PID-3 (first component / CX parsing as implemented).
• Name from PID-5 components.
• Date of birth from PID-7 (yyyyMMdd pattern).
• Gender and address and phone from common PID fields (standard positions).

For exact segment requirements when troubleshooting, compare your outbound message to a known-good sample in your test environment. If PID is missing required identifiers, the service responds with a clear error.

ORU^R01

Observation messages are ingested to patient-linked observation content for the same site. Use ORU for structured results your deployment maps; unsupported OBX or missing patient keys surface as errors in ACK/HTTP response.

Relationship to FHIR and the web app

• FHIR can read the updated Patient and other resources.
• The worklist and viewer are driven by DICOM; HL7 does not by itself import images. Use imaging pipelines for DICOM; use HL7 for patient/clinical data.

Operational checklist

• API key with protocols including hl7-mllp and correct allowed IPs (MLLP), or a token-capable key for HTTP.
• MSH sending app/facility match your registration if you set them.
• For HTTP, token scopes and audience=xenrad-hl7-http.

Related

• FHIR — read back persisted data.
• OAuth2 — token issuance and audiences.
• Endpoints reference — how bases and paths fit together.