Protocol
HL7 v2.x support in Smile CDR is based on HL7 v2.5. The transaction, segment, and field definitions are described in the following sections.
Any data found in segments or fields not explicitly listed in this documentation will be ignored by Smile CDR.
Smile CDR supports both the HL7 ER7 (pipe-delimited) and XML encoding formats.
As allowed in the HL7 v2.x specifications, any characters may be chosen as the special and/or delimiter characters specified in MSH-1 and MSH-2. By convention the following characters are generally chosen:
| (pipe)^ (caret)~ (tilde)\ (backslash)& (ampersand)The segment delimiter is expected to be a \r (ascii-13) character; however, Smile CDR will also accept \r\n (ascii-13 followed by ascii-10) in order to be lenient.
Smile CDR allows the use of the MLLP protocol for transmission. This protocol consists of a simple TCP socket with the following payload:
[0x0b] [message payload] [0x1c] [0x0d]
As an alternative to the MLLP protocol, the HL7 over HTTP transport may also be used.
This transport expects that requests and responses will be transmitted as plain text, using the MIME type of: application/hl7-v2
Character encoding problems are a common pitfall in dealing with HL7 v2.x messages. It is common for non-US-ASCII characters to be lost when transmitting data using this format.
HL7 FHIR mitigates this issue by requiring the use of UTF-8 encoding; however, this is not a common approach for HL7 v2.x.
By default, Smile CDR will parse incoming messages using the US-ASCII charset. There are two strategies that may be used to override this behaviour, and these should be considered if you are deploying in an environment where non-US-ASCII data is expected.
Sending systems are expected to provide their encoding charset as a value in MSH-18 (Character Set). For example, the following MSH header declares that the message is encoded using ISO 8859/1:
MSH|^~\&|||||20171114141219||ADT^A08|001||2.3|||||DE|8859/1
This field is often misused in real world applications due to the blend of transport protocol and payload encoding in the HL7 v2.x design. If you know that MSH-18 will be populated correctly in your system, the charset.respect_msh18 property may be used. When this property is set to true, the message will be parsed using the value in MSH-18.
Note: This option is not used by HL7 over HTTP.
If the sending systems are known to use a specific charset in all messages, another approach is to force the use of a specific charset.
The charset.forced property allows you to specify a charset that will be used in all cases for the given listener.
Note: This option is not supported with HL7 over HTTP.
For HL7 over HTTP, if an incoming message includes a valid Charset with the Content-Type header, the message will be decoded using the specified Charset.
Since 2024.05, Smile CDR will encode all outgoing HL7 v2 messages as UTF-8.
Since 2024.05, in almost all cases, Smile CDR will send outgoing messages with MSH-18 (Character Set) populated with UNICODE UTF-8. The only exception is when the forward-persisted-messages property is set to true, in which case the existing value of MSH-18 is preserved.