Every field available when creating or editing an MLLP channel in the web admin dashboard under Channels > HL7 > MLLP.
All fields on this page can also be configured via enmasse YAML. See the enmasse reference for the YAML schema.
For use-case-driven explanations of each group, see the Receiving HL7v2 over MLLP page.
| Field | Type | Default | Description |
|---|---|---|---|
| Name | text | - | Unique name for this channel. Used in logs, dashboard listings, and as the basis for the REST channel name if the REST bridge is enabled. |
| Active | bool | on | Whether the channel accepts connections. Inactive channels remain configured but do not listen for messages. |
| Service | select | - | The Zato service invoked for each incoming message. The service receives the parsed HL7Message object (or raw ER7 string if parsing is off) as self.request.input. |
| HL7 version | select | HL7 v2.x | The HL7 version used for parsing and validation. |
| Parse on input | bool | on | When on, the raw ER7 bytes are parsed into a typed HL7Message object before the service is invoked. When off, the service receives the raw string. Turn off for batch messages or when your service handles parsing itself. |
| Validate | bool | on | When on, the parser validates the message structure against the HL7 schema - required segments, cardinality rules, and choice groups. Invalid messages are rejected with an AE acknowledgment. |
| Return errors | bool | off | When on, AE acknowledgments include the actual exception text in the ERR segment. When off, a generic error message is returned. Keep off in production to avoid leaking internal details. |
| Log messages | bool | off | When on, the full raw ER7 payload and ACK response are written to the server log. See Logging for details. |
Controls which messages this channel handles when multiple channels share the same MLLP listener. Only filled fields are checked - empty fields act as wildcards. Matching is case-insensitive.
See Routing for examples.
| Field | Type | Default | MSH position | Description |
|---|---|---|---|---|
| Sending application | text | - | MSH-3 | Match the sending application identifier, e.g. WELLNESS_APP, LAB_SYS. |
| Sending facility | text | - | MSH-4 | Match the sending facility, e.g. MAIN_FAC, EAST_CLINIC. |
| Receiving application | text | - | MSH-5 | Match the receiving application, e.g. SCHEDULING, HIS. |
| Receiving facility | text | - | MSH-6 | Match the receiving facility. |
| Message type | text | - | MSH-9.1 | Match the message type code, e.g. ADT, ORM, ORU. |
| Trigger event | text | - | MSH-9.2 | Match the trigger event code, e.g. A04, O01, R01. |
| Processing ID | text | - | MSH-11 | Match the processing ID: P (production), T (training), D (debugging). |
| Version ID | text | - | MSH-12 | Match the HL7 version in the message, e.g. 2.5, 2.9. |
| Default | bool | off | - | When on, this channel catches any message that does not match another channel's filters. Only one default channel is allowed per MLLP listener. If no channel matches and there is no default, Zato responds with an AR acknowledgment. |
Wire-level settings for the MLLP framing and TCP connection.
See Framing for details on tolerant framing and oversized message handling.
| Field | Type | Default | Description |
|---|---|---|---|
| Start sequence | hex | 0b | Hex bytes marking the start of an MLLP frame. The standard value is 0b (ASCII VT, 0x0B). If the sender omits the start byte but the payload begins with MSH, Zato auto-detects the frame start. |
| End sequence | hex | 1c 0d | Hex bytes marking the end of an MLLP frame. The standard value is 1c 0d (ASCII FS + CR, 0x1C 0x0D). |
| Max message size | number | 2 | Maximum allowed message size. Messages exceeding this limit are rejected and the connection is closed. Increase for messages with embedded binary data (e.g. PDF or images in OBX segments). |
| Max message size unit | select | MB | Unit for the max message size: kB or MB. |
| Read buffer size | number | 32768 | TCP read buffer size in bytes. Larger buffers reduce the number of system calls for big messages but use more memory per connection. |
| Receive timeout | number | 250 | Socket read timeout in milliseconds. Controls how long Zato waits for data on each read call before checking for idle connections. |
Preprocessing toggles that fix common issues in non-standard HL7 messages before parsing and routing. All toggles are on by default unless noted otherwise.
See Tolerance for the processing order and troubleshooting tips.
These toggles operate on raw bytes before the message is parsed.
| Field | Type | Default | Description |
|---|---|---|---|
| Normalize line endings | bool | on | Converts LF (\n) and CRLF (\r\n) to CR (\r), which is the HL7-standard segment separator. Required for messages from Windows-based systems that use CRLF. |
| Force standard delimiters | bool | on | Rewrites MSH-2 to ^~\& and translates all field, component, subcomponent, and repetition delimiters in the message body to standard characters. Handles senders that use non-standard delimiter sets. |
| Repair truncated MSH | bool | on | Pads the MSH segment if it has fewer than 12 fields. Some legacy systems send minimal MSH headers missing optional trailing fields like processing ID or version. |
| Split concatenated messages | bool | on | Splits multiple messages received in a single MLLP frame into separate messages, each starting with MSH. Each is routed and processed independently. |
| Use MSH-18 encoding | bool | on | Reads the character encoding from MSH-18 instead of using the default. See the Encoding tab for the MSH-18 to codec mapping table. |
These toggles control content-level fixups applied by the Rust ER7 parser during parse_hl7.
| Field | Type | Default | Description |
|---|---|---|---|
| Fill empty OBX-2 value type | bool | on | When OBX-2 is empty but OBX-5 contains data, fills OBX-2 with ST. Common with lab systems that omit the value type for string results. |
| Replace invalid OBX-2 value type | bool | on | Replaces unrecognized OBX-2 data types (e.g. TX typos, nonstandard codes) with ST so the observation value can still be accessed. |
| Strip orphan escape characters | bool | on | Removes stray backslash (\) characters that do not form a valid HL7 escape sequence. Prevents parse errors from malformed escape codes. |
| Clear OBX-8 literal null | bool | on | Clears OBX-8 (Abnormal Flags) when it contains the literal string null instead of a valid flag value. Seen in some EHR exports. |
| Strip multi-quote sequences | bool | on | Strips sequences of two or more consecutive double-quote characters ("", """", etc.) that some systems emit as empty-field placeholders. |
| Pad short encoding characters | bool | on | Pads MSH-2 with standard encoding characters when the sender provides fewer than the required four. Allows parsing of messages from minimal senders. |
| Fix off-by-one field index | bool | off | Removes a spurious empty first field from non-MSH segments. Some legacy systems prepend a leading field separator that shifts all field indices by one. |
Message deduplication based on MSH-10 (Message Control ID).
See Deduplication for how duplicates are handled.
| Field | Type | Default | Description |
|---|---|---|---|
| Dedup TTL | number | 14 | How long to remember message control IDs. If a message with the same MSH-10 arrives within this window, Zato returns an AA acknowledgment without invoking the service. Set to 0 or leave empty to disable deduplication. |
| Dedup TTL unit | select | Days | Unit for the TTL: Minutes, Hours, or Days. The 14-day default provides a wide safety margin for most clinical retransmission policies. |
Character encoding settings.
See Encoding for the full MSH-18 codec mapping table.
| Field | Type | Default | Description |
|---|---|---|---|
| Default character encoding | select | UTF-8 | Encoding used to decode incoming message bytes when MSH-18 is empty, unrecognized, or the MSH-18 toggle is off. Available values: UTF-8, ISO-8859-1, Windows-1252, US-ASCII. ACK responses are always encoded with this value. |
| Field | Type | Default | Description |
|---|---|---|---|
| Logging level | select | INFO | Minimum severity for log entries: DEBUG, INFO, WARNING, or ERROR. |
| Log messages | bool | off | When on, logs the full raw ER7 payload and ACK response for every message. Enable only during development - HL7 messages contain PHI. |
Expose the MLLP channel over HTTP for systems that cannot speak MLLP.
See REST bridge for usage examples.
| Field | Type | Default | Description |
|---|---|---|---|
| Use REST | bool | off | When on, creates a companion HTTP channel named hl7.rest.<channel-name> that accepts POST requests with an ER7 body. The same service handles both MLLP and REST messages. |
| REST only | bool | off | When on, the TCP listener is not started. Messages arrive only over the REST endpoint. Use when the sending system speaks HTTP but not MLLP. |
| URL path | text | - | The HTTP path for the REST endpoint, e.g. /hl7/adt. |
| Security | select | - | Security definition for the REST endpoint: Basic Auth, API key, or other configured security. |
Landing page with code examples, features and full reference
Routing, acknowledgments, deduplication and REST bridge
Encoding, tolerance, batch mode and all channel settings
Parse ER7-encoded messages into typed Python objects
Access segment fields by name using typed Python objects
Navigate nested fields and components with dot-path syntax
Validate messages against schema definitions
Convert messages between ER7 and JSON formats
All HL7 message structures, grouped by domain
All HL7 segments, grouped by domain
Book a demo with an expert who will help you build meaningful systems that match your ambitions
"For me, Zato Source is the only technology partner to help with operational improvements."
- John Adams
Program Manager of Channel Enablement at Keysight 
