HL7
The HL7 Bridge connects BridgeERP HMS to the laboratory analysers, radiology information systems, registration desks and legacy hospital systems that still speak HL7 version 2.x. It receives and sends the pipe-delimited (ER7) messages those systems use — patient admissions, orders and results — over MLLP, a file hot-folder, HTTP, REST or SFTP, parses each one, logs it, and returns an acknowledgement. This page explains the channels, the message types, the ports involved, and how messages are mapped and routed.
Where to find it
All HL7 tooling lives under HMS Core → Integration → HL7 Bridge:
| Menu | Opens |
|---|---|
| Configuration → Endpoints | Channels (hms.hl7.endpoint) — protocol, host/port, sender & receiver identifiers, version and supported message types. |
| Configuration → Message Types | The message catalogue (hms.hl7.message.type) — mnemonic, wire trigger and a sample payload. |
| Configuration → Mapping Rules | Segment / field mapping into platform records (hms.hl7.mapping.rule). |
| Configuration → Routing Rules | Where each message goes after parsing (hms.hl7.routing.rule). |
| Configuration → Subscriptions | Outbound message subscriptions (hms.hl7.subscription). |
| Operations → Messages | Every inbound / outbound message with its parsed JSON (hms.hl7.message). |
| Operations → ACK Log | Acknowledgements sent and received (hms.hl7.ack.log). |
| Operations → Segment Logs | Per-segment breakdown for debugging (hms.hl7.segment.log). |
Message types supported
The bridge handles the standard v2.x message families. Each is catalogued under Message Types with a mnemonic Code (such as ADT_A01) and a wire Trigger Event (such as ADT^A01):
| Family | Purpose | Typical triggers |
|---|---|---|
| ADT — Admit / Discharge / Transfer | Patient registration and movement events. | A01 admit, A03 discharge, A04 register, A08 update. |
| ORM — Order Message | Lab or imaging orders placed on an external system. | O01 new order. |
| ORU — Observation Result | Results returning from analysers or radiology. | R01 unsolicited result. |
| ACK — Acknowledgement | The reply confirming receipt and processing. | AA accept, AE error, AR reject. |
Channels, MLLP and ports
Each endpoint chooses a Protocol: MLLP / TCP (the default), File Hot Folder, HTTP POST, REST API or SFTP. For MLLP the listener wraps each message in the standard framing bytes (start 0x0B, end 0x1C 0x0D) and listens on the Port you set on the endpoint — a hospital convention is TCP 2575, but the bridge binds whatever port the endpoint specifies. A built-in listener can be started for a 30-second test from the endpoint, reporting how many messages and errors it saw on that port.
Two HTTP routes are also exposed for environments where an external MLLP proxy decodes the framing and forwards the raw payload:
| Route | Method | Purpose |
|---|---|---|
/hl7/inbound | POST | Accepts a raw ER7 payload, stores it as a message, parses it and returns an ACK. The target channel is chosen by the X-Endpoint-Code header (or the first inbound endpoint). |
/hl7/health | GET | A health probe returning the count of active endpoints and messages received in the last 24 hours. |
Step-by-step: receive lab results from an analyser
- Under Configuration → Message Types confirm
ORU_R01exists (add it with triggerORU^R01if not). - Create an endpoint under Configuration → Endpoints: set Direction to Inbound, Protocol to MLLP / TCP, fill in Host, Port, the sender / receiver application and facility fields, and pick the HL7 Version (default 2.5).
- Tick
ORU_R01under Supported Message Types and choose the Partner Facility. - Add a Mapping Rule so result segments land on the right platform records, and a Routing Rule for where parsed results go.
- Run the 30-second listener test on the endpoint, or have the analyser send a sample. Confirm a new row appears under Operations → Messages and an
AAentry under ACK Log.
Message lifecycle & states
Every message is logged with a Direction (Inbound / Outbound) and moves through a status:
| Status | Meaning |
|---|---|
| Received | Raw payload stored, not yet parsed. |
| Parsed | Segments decoded into JSON. |
| Processed | Mapped into platform records. |
| Failed | Parse or processing error (see Error Message). |
| Duplicate | A repeat of a control id already seen. |
| Queued (outbound) / Sent / Acknowledged | Outbound flow: waiting to send, sent, and confirmed by the receiver. |
Acknowledgements carry an ACK Code of AA (Application Accept), AE (Application Error) or AR (Application Reject), recorded against the message and in the ACK Log.
Endpoint field reference
| Field | Meaning | Required |
|---|---|---|
| Name / Code | Label and unique key for the channel. | Yes (code unique) |
| Direction | Inbound, Outbound or Bidirectional. | Yes |
| Protocol | MLLP/TCP, File Hot Folder, HTTP POST, REST API or SFTP. | Yes |
| Host / Port / Path | Network target, or folder / URL path for non-TCP protocols. | As per protocol |
| Sender / Receiver App & Facility | MSH identifiers used to stamp and match messages. | No |
| Version | HL7 v2.x version, 2.3 through 2.9 (default 2.5). | Yes |
| Supported Message Types | Which families this channel accepts. | No |
| Partner Facility | The facility this channel belongs to. | Defaulted |
| Status | Active, Disabled or Error. | Yes |
Roles & access
- HL7 Viewer — read messages, ACK logs and segment logs.
- HL7 Operator — run the listener, resend, and manage day-to-day traffic.
- HL7 Administrator — configure endpoints, message types, mapping and routing.
Troubleshooting
| Symptom | Likely cause & fix |
|---|---|
| Listener will not start | The endpoint has no TCP port, or the protocol is not MLLP/TCP; set a port and protocol. |
| Message stuck at Received / Failed | Malformed segments; open the message and read Error Message and the Segment Logs. |
| Sender gets AE on every message | The parser raised an error and the bridge replied with an application error; fix the mapping or payload. |
| Inbound message lands on the wrong channel | The X-Endpoint-Code header is missing; it falls back to the first inbound endpoint. |
0.0.0.0 on the chosen port and /hl7/inbound is publicly reachable. Place both behind a firewall and only allow your known analyser / partner IP addresses.