HL7 Listener
Category: Trigger
Node id: hl7-listener
Trigger node that receives HL7v2 messages via MLLP/TCP, parses MSH segments, applies message type/event filters and decides the HL7 ACK (AA/AE/AR)
What it does
- Receives HL7v2 messages via MLLP/TCP as a pipeline trigger
- Parses full MSH segment: message type, event, sender/receiver, timestamp, control ID, processing ID, version
- Filters by message type (ADT, ORM, ORU, SIU, MDM, VXU, etc.)
- Filters by trigger event (A01, A08, R01, etc.)
- Filters by sending application and facility
- Filters by HL7 version (2.3 through 2.8)
- Standard HL7 ACK: AA, AE with the run error, AR for header/version/filter/route rejections, ERR segment with table 0357 codes, custom sender identity
- MLLP over TLS and mutual TLS, configured on the server (MLLP_TLS_*); tls_enabled refuses messages that arrived over plain TCP
- IP-based access control
Use cases
- Trigger patient admission workflows on ADT^A01 messages
- Process lab results from ORU^R01 messages
- Route HL7 messages by type/event to different downstream pipelines
- Integrate legacy EHR systems that communicate via HL7v2/MLLP
Runtime
- Performance tier:
fast
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
hl7_message | text | Yes | Raw HL7v2 message text. In production this is injected by the MLLP trigger. For testing, provide via a test fixture or input override. |
hl7_rejection | json | No | Set by the MLLP server only for a message it rejected at the header (receive_rejected): ack_code AR, error_code (HL7 table 0357), location, reason. The node then outputs valid=false and result.rejected=true. |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | Parsed HL7 message metadata with type, event, sender, receiver, and segment details |
raw_message | text | No | Raw HL7v2 message text passed through for downstream processing |
valid | boolean | No | Whether the message passed filters and is valid HL7 |
success | boolean | No | Whether HL7 message processing completed |
Settings
Connection
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| MLLP Port | listen_port | number | No | 2575 | TCP port to listen on for inbound MLLP connections | |
| Listen Host | listen_host | string | No | 0.0.0.0 | Host/IP to bind the MLLP listener to | |
| Connection Timeout (ms) (not used) | connection_timeout | number | No | 30000 | Not used: connections belong to the shared MLLP port, not to a workflow; the idle timeout is MLLP_IDLE_TIMEOUT on the server. Kept so existing workflows load. | |
| Max Connections (not used) | max_connections | number | No | 10 | Not used: connections belong to the shared MLLP port, not to a workflow; the cap is MLLP_MAX_CONNECTIONS on the server. Kept so existing workflows load. |
Filtering
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Filter Message Type | filter_message_type | string | No | Only accept messages of this type (e.g., ADT, ORM, ORU, SIU, MDM, VXU). Empty accepts all. | ||
| Filter Event | filter_event | string | No | Only accept messages with this trigger event (e.g., A01, A08, R01). Empty accepts all. | ||
| Filter Sending Application | filter_sending_application | string | No | Only accept messages from this sending application (MSH-3). Empty accepts all. | ||
| Filter Sending Facility | filter_sending_facility | string | No | Only accept messages from this sending facility (MSH-4). Empty accepts all. | ||
| HL7 Version | hl7_version | enum | No | "" | "", 2.3, 2.4, 2.5, 2.5.1, 2.6, 2.7, 2.8 | Only accept messages with this HL7 version. Empty accepts all. |
Security
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Require TLS | tls_enabled | boolean | No | false | Only receive messages that arrived over TLS. The MLLP port is shared by every workflow, so TLS is configured once on the Hydra server: MLLP_TLS_CERT_FILE and MLLP_TLS_KEY_FILE, plus MLLP_TLS_CLIENT_CA_FILE for mutual TLS. When true and the server port is plain TCP, messages are answered AR and this workflow does not run. | |
| TLS Certificate Path (not used) | tls_cert_path | string | No | Not used: one MLLP port has one certificate, set on the server with MLLP_TLS_CERT_FILE. Kept so existing workflows load. | ||
| TLS Key Path (not used) | tls_key_path | string | No | Not used: the server key is MLLP_TLS_KEY_FILE. Kept so existing workflows load. | ||
| Allowed Source IPs | allowed_ips | string | No | Comma-separated source IP addresses or CIDRs this workflow accepts messages from; a message from any other address is answered AR and this workflow does not run. Empty allows all. Connections are first filtered server-wide by MLLP_ALLOWED_CIDRS. |
Ack
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| ACK Mode | ack_mode | enum | No | auto | auto, manual, none | How to acknowledge received messages, after the run: auto (AA on success, AE when the run fails, AR when rejected before processing), manual (the run decides: a terminal node output ack_code AA/AE/AR, optional ack_text for MSA-3 — sent to the sender as written, so it must not carry PHI; without one, as auto), none (no ACK is written; with several workflows on the port, only when all of them say none) |
| ACK Sending Application | ack_application | string | No | TIETAI | MSH-3 value in ACK responses. Empty: the receiving application (MSH-5) of the inbound message, else TIETAI. With several workflows on the port, the first one's value is used. | |
| ACK Sending Facility | ack_facility | string | No | HIP | MSH-4 value in ACK responses. Empty: the receiving facility (MSH-6) of the inbound message, else HIP. | |
| NACK on Filter | nack_on_filter | boolean | No | false | Answer AR (with the filter reason in MSA-3) instead of AA when this listener's filters reject a message that no other workflow on the port accepts | |
| Receive Rejected Messages | receive_rejected | boolean | No | false | Also run this workflow for messages rejected at the header (unreadable MSH, missing MSH-9/10/12, version not 2.x), e.g. to quarantine them. The listener's tls_enabled, allowed_ips and max_message_size still apply: a message they refuse does not run. The sender still receives AR; this run's outcome does not change the ACK. |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Max Message Size | max_message_size | number | No | 1048576 | Largest message in bytes this workflow accepts; a larger one is answered AR and this workflow does not run (0 = no per-workflow limit). The server-wide cap MLLP_MAX_MESSAGE_BYTES (default 1 MiB) applies first. | |
| Character Set | charset | enum | No | UTF-8 | UTF-8, ISO-8859-1, ASCII | Character encoding for HL7 messages |
| Segment Delimiter | segment_delimiter | enum | No | auto | auto, CR, LF, CRLF | Expected segment delimiter in incoming messages |
| Pass Through Raw | pass_through_raw | boolean | No | true | Include the raw unparsed HL7 message in output for downstream processing |
Errors
| Code | Description |
|---|---|
MISSING_HL7_MESSAGE | hl7_message input is required but was empty |
INVALID_MSH_SEGMENT | MSH segment is missing or has fewer than 10 fields |
Runtime notes
- TRIGGER NODE: In production, hl7_message is injected by the MLLP listener service. For pipeline testing, you MUST add a test fixture or input override with a sample HL7v2 message — the node will fail without it.
- WIRING: Connect raw_message(text) port — NOT result — to downstream nodes that expect raw HL7 text (hl7-validate.message, hl7-parse.message). The result port is a JSON metadata map that will cause 'input is required' errors on text input ports.
- When a message is filtered out, valid=false and result contains filtered=true with a reason string. The raw_message is still passed through so downstream nodes can inspect it.
- With receive_rejected, a message the server answered AR also runs the workflow: valid=false, result.rejected=true with ack_code, error_code, location and reason; raw_message is passed through for quarantine.
- MSH segment must have at least 10 pipe-delimited fields or the node returns an error.
- ROUTING: the MLLP server (MLLP_PORT) runs every saved workflow whose hl7-listener listen_port equals that port and whose filters accept the message; a workflow whose filters reject the message does not run.
- ACK: AA when every run succeeds; AE when a run fails (MSA-3 = 'processing error; execution <id>' — the run error itself stays in the run history, never in the ACK); AR before any run when MSH-9, MSH-10 or MSH-12 is missing, the version is not 2.x, every listener filters the message out and one sets nack_on_filter, or no workflow listens on the port (MLLP_NO_ROUTE_ACK, default AR). AE/AR carry an ERR segment with the HL7 table 0357 code.
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Something unclear? Send documentation feedback by email.