MLLP channel configuration reference

Every field of an MLLP channel, with its default and what it changes.

An MLLP channel runs with nothing configured beyond a name - every other field has a default that follows the MLLP standard. The sections below list each field with its default and what changing it does.

To create a channel and see it accept messages, follow the receiving guide. Every field here also has an enmasse YAML key of the same name - the enmasse reference holds the schema.

There is no port field. All MLLP channels share one listener - port 11553, or 11554 over TLS - and the Match criteria decide which channel receives each message. Ports and TLS covers reachability and certificates.

Name, Active and Default

Three fields identify the channel and control whether it receives messages at all:

Field	Default	What it does
Name	-	Identifies the channel in the Dashboard, in logs and in the audit log. With the REST bridge on, the companion REST channel is named `hl7.rest.<channel-name>`.
Active	on	An inactive channel keeps its configuration but receives no messages.
Default	off	The channel receives every message no other channel matches. One default channel is allowed at a time - without one, an unmatched message is answered with AR.

Protocol options

These fields control how the channel reads frames off the wire and decodes their bytes. The defaults are the values the MLLP standard prescribes, so they change only when a sender deviates from it. A sender that omits the start byte and opens straight with MSH is accepted as it comes, and a frame larger than the size limit is answered with AE and the connection closes, because past the limit the channel can no longer locate the start of the next frame.

Field	Default	What it does
Start separator	`0b`	The byte a frame opens with, in hex - `0b` is the vertical tab the standard prescribes.
End separator	`1c 0d`	The bytes a frame closes with, in hex - `1c 0d` is the standard's file separator plus carriage return.
Receive timeout (ms)	250	How long one read on the socket waits for data. The connection itself stays open between messages.
Max message size	2 MB	The largest frame accepted, as a value plus a kB or MB unit. Raise it for messages carrying embedded documents, such as PDFs in OBX segments.
Encoding	UTF-8	The codec raw bytes decode with when MSH-18 is empty, unrecognized or not consulted - one of UTF-8, ISO-8859-1, Windows-1252 and US-ASCII. Acknowledgments are always encoded with this value.
Use MSH-18 first	on	Reads the character set from each message's own MSH-18 field and decodes the message with it, falling back to the Encoding value above.

With Use MSH-18 first on, the character set names below decode with the matching codec - any other value falls back to the Encoding field:

The MSH-18 character set mapTable

MSH-18 value	Codec
`ASCII`	`ascii`
`UNICODE`	`utf-8`
`UTF-8`	`utf-8`
`UNICODE UTF-8`	`utf-8`
`8859/1`	`iso-8859-1`
`ISO IR6`	`ascii`
`ISO IR100`	`iso-8859-1`
`ISO IR101`	`iso-8859-2`
`ISO IR144`	`iso-8859-5`
`ISO IR127`	`iso-8859-6`
`ISO IR126`	`iso-8859-7`

REST options

With REST on, the channel accepts the same messages over HTTP - a companion REST channel is created and removed together with it. The fields hold the endpoint's URL path and the security definitions HTTP senders authenticate with, and turning MLLP off leaves REST as the only transport. The REST bridge shows the endpoint in use.

Field	Default	What it does
Path	-	The URL path the REST endpoint listens on, e.g. `/api/hl7/v2`.
Security	on	The security definitions incoming HTTP requests authenticate with, one row per definition. Turning security off accepts requests from anyone who knows the address.

Match criteria

All MLLP channels share one listener, and these MSH fields decide which channel receives each incoming message. Only filled fields are checked, an empty field matches any value, all comparisons are case-insensitive, and the first channel whose criteria all match receives the message. For a two-channel example, see Route by MSH fields.

Field	MSH position	Example values
Sending application	MSH-3	`WARD_APP`, `LAB_SYS`
Sending facility	MSH-4	`MAIN_FAC`, `EAST_CLINIC`
Receiving application	MSH-5	`SCHEDULING`, `HIS`
Receiving facility	MSH-6	`MAIN_FAC`
Message type	MSH-9.1	`ADT`, `ORM`, `ORU`
Trigger event	MSH-9.2	`A04`, `O01`, `R01`
Processing ID	MSH-11	`P` (production), `T` (training), `D` (debugging)
Version	MSH-12	`2.5`, `2.9`

Destinations and the service

Each accepted message is delivered to destinations, to a service or to both, and one of them produces the reply the sender receives:

Field	Default	What it does
Incoming messages go to	-	The destinations each message is delivered to - MLLP, REST, FHIR or SMTP connections picked from a panel, no code required.
Service invoked	-	The service receiving each message. A channel needs a service, destinations or both.
The destinations receive it	all at once	Whether the destinations receive the message at the same time or one after another, in the order they were picked.
The reply is produced by	the service	What the sender receives back - what the service returns or the response of one, synchronously delivered, destination.

Tolerance and message fixups

Real-world feeds deviate from the standard in recurring ways, and the tolerance toggles repair each deviation before it can fail a message. The wire-level fixups run on the raw text in a fixed order - line endings normalize, a truncated MSH is restored, a payload holding several messages splits into them and non-standard delimiters become ^~\& - and the content-level fixups run inside the parser as it reads the fields. Everything is on by default except the off-by-one repair, which only fits senders with that specific defect.


Field	Group	Default	What it does
Parse each message on input	Parsing	on	Parses each message into a typed `HL7Message` object before the service receives it. Off, the service receives the raw ER7 text instead.
Validate each message	Parsing	off	Validates each parsed message against the HL7 v2 grammar and rejects a failing one with AE. Applies only while parsing is on.
Normalize line endings to CR	Wire-level	on	Converts LF and CRLF segment separators to the CR the standard requires - the usual repair for senders on Windows.
Force the standard delimiters	Wire-level	on	Rewrites MSH-2 to `^~\&` and translates the delimiters used throughout the message body to the standard set.
Restore a truncated MSH header	Wire-level	on	Pads an MSH segment arriving with fewer fields than routing needs - some senders drop optional trailing fields such as the version.
Split concatenated messages	Wire-level	on	Splits a payload holding several `MSH` segments into individual messages, each routed and acknowledged separately.
Fill empty OBX-2 value type	Content-level	on	Fills an empty OBX-2 with `ST` when OBX-5 carries data, so the observation value stays accessible - common with lab systems that omit the type for string results.
Replace invalid OBX-2 value type	Content-level	on	Replaces an unrecognized OBX-2 data type with `ST` instead of failing the parse on a non-standard code.
Strip orphan escape characters	Content-level	on	Removes stray backslashes that do not form a valid HL7 escape sequence.
Clear OBX-8 literal null values	Content-level	on	Clears OBX-8 when it holds the literal string `null` instead of an abnormal flag - seen in some EHR exports.
Strip multi-quote empty values	Content-level	on	Strips runs of two or more double quotes that some systems emit as empty-field placeholders.
Pad short encoding characters	Content-level	on	Pads MSH-2 with standard encoding characters when the sender provides fewer than the required four.
Fix an off-by-one field index	Content-level	off	Removes a spurious empty first field from non-MSH segments, repairing senders whose leading separator shifts every field index by one.
No matches

Deduplication

A sender that receives no acknowledgment in time retransmits the message, so the same MSH-10 control ID can arrive more than once. With a window set, the channel answers a control ID it has already seen with AA at once, and the duplicate reaches neither the service nor the destinations.

Field	Default	What it does
Remember control IDs for	0	How long a control ID stays remembered, as a value plus a minutes, hours or days unit. Zero turns deduplication off.

Logging and errors

HL7 messages carry patient data, so the server log receives message bodies only when its toggle is on, while the audit log, built to hold clinical traffic, records them by default.

Field	Default	What it does
Return error details in NAK responses	off	Puts the actual error text in the ERR segment of each negative acknowledgment. Off, the sender receives the code alone - keep it off when senders are outside your organization.
Log each message to the server log	off	Writes each message body and its routing decision to the server log. Message bodies carry patient data, so turn it on for troubleshooting and back off after.
Record each message in the audit log	on	Records each message and its acknowledgment in the audit log, searchable by patient identifier.

Page	What it covers
Receiving over MLLP	Write the service, create the channel and send a test message
The HL7 MLLP tutorial	Route a feed end to end, with test messages and the audit log
Enmasse reference	The same fields as YAML keys, for version-controlled deployments
Acknowledgments	What AA, AE and AR mean and who sees the error details