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 listening port; no HTTP headers.
• HTTP — POST a raw HL7 message to the HL7 HTTP host with an X-API-Key header.

Standard

• Version: v2.5.1 for MLLP and for POST /v2/ingest
• 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)

MLLP listener — connect your interface engine to hl7.integrations.xenrad-staging-app.xyz:3000 (TCP, not HTTPS). DNS and reachability checks are on Endpoints reference.

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

Security model (no API key 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:

HL7 HTTP host — https://hl7.integrations.xenrad-staging-app.xyz (POST https://hl7.integrations.xenrad-staging-app.xyz/v2/ingest, POST https://hl7.integrations.xenrad-staging-app.xyz/v3/ingest). See also Endpoints reference for MLLP and DICOM TCP endpoints.

• POST /v2/ingest on the HL7 HTTP host.
• Header: X-API-Key: <api_key>
• Body: raw HL7 v2.5.1 message as text (pipe-delimited segments with standard \r terminators—the same payload you would place inside MLLP, without MLLP wrapper bytes).

On success the service returns JSON with success: true, the detected message_type, and a rendered ACK string in ack.

For HL7 v3 XML payloads, use POST /v3/ingest on the same host with Content-Type: application/xml.

Interactive reference: /api/documentation on the HL7 host (OpenAPI at /api/documentation/openapi.json).

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 API key (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 on the FHIR host.
• 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

• Integration client with protocols including hl7-mllp and correct allowed IPs (MLLP), or an active site API key for HTTP.
• MSH sending app/facility match your registration if you set them.
• For HTTP, X-API-Key is active and belongs to the target site.

Related

• FHIR — read back persisted data.
• MPPS — modality procedure-step sessions.
• API keys — creating and revoking keys.
• Endpoints reference — MLLP and HTTP hosts.