Settings for HL7 Business Services
Provides reference information for settings for HL7 business services.
HL7 business services have the following settings:
|Basic Settings||Target Config Names||“Settings for Business Services” in Ensemble Virtual Documents|
|Ack Target Config Names, Message Schema Category||sections in this topic|
|Connection Settings||Framing||section in this topic|
|Additional Settings||Search Table Class||“Settings for Business Services” in Ensemble Virtual Documents|
|Local Facility Application, ACK Mode, Use ACK Commit Codes, Ignore Inbound ACK, Add NACK ERR, NACK Error Code, Batch Handling, Default Char Encoding, DocTypeResolution, Save Replies||sections in this topic|
The remaining settings are either common to all business services or are determined by the type of adapter. For information, see:
“Settings for All Business Services” in Configuring Ensemble Productions
“Settings for the File Inbound Adapter” in Using File Adapters with Ensemble
“Settings for the HTTP Inbound Adapter” in Using HTTP Adapters with Ensemble
“Settings for the FTP Inbound Adapter” in Using FTP Adapters with EnsembleThe difference for the special-purpose adapter called EnsLib.HL7.Adapter.TCPInboundAdapter is that it has JobPerConnection set to False, which is usually appropriate for HL7.
The most important settings for HL7 are as follows:
Pool Size — The default value of 1 makes it possible to support FIFO (First In, First Out) processing. In many cases, multiple patient demographic updates must be received in order. For example, many applications require receipt of an ADT Registration message before they can process an Order message, an Order message must be received before a Result message, and so on.
Category — This text label permits configuration items to be sorted in the configuration diagram.
Append Timestamp — (File only) Appends a time stamp to filenames in the Archive Path.
Archive Path — (File and FTP only) Specifies where to archive HL7 messages.
Call Interval — The number of seconds to wait before looking for more input. The default is 5 seconds. The minimum is 0.1 seconds.
Helps to establish the format and conventions for issuing HL7 acknowledgment messages in response to HL7 messages received. For business services, this setting can have one of the values shown in the following table.
|Never||Do not send back any ACK.|
|Immediate||Return a Commit ACK reply message immediately upon receipt of the inbound message. This is the default if nothing is specified.|
|Application||If message passes validation, wait for the ACK reply message from the target application and return this ACK when it arrives.
In the situation where the caller is requesting a response and the Ensemble routing engine is not configured to forward back a response from any of its targets, Ensemble creates and returns ACK or NACK objects to return to the caller. If validation fails and the Ack Mode is
Application, Ensemble does not contact the target application. Instead, it sends the caller an immediate Validation NACK.
|MSH-determined||Return ACK reply messages as requested in the MSH header fields 15 and 16. Either field may contain one of the following four control codes:
|Byte*||Send back a single ACK-code byte instead of an ACK message, immediately upon receipt of the inbound message. ASCII 6 means OK; ASCII 21 means Error. This option is not available for any of the built-in HL7 business services (TCP, File, HTTP, and so on) but it is available if you write a custom business service that subclasses EnsLib.HL7.Service.Standard without overriding the Ack Mode setting.|
* Ensemble business operations automatically treat a single byte ASCII 6 as an HL7 ACK with an AA commit code and ASCII 21 as an HL7 ACK with an AE commit code.
(File and FTP only) Unlike TCP business services, File and FTP business services have no persistent connection on which to send HL7 acknowledgment messages (ACK or NACK). For this reason, the default Ack Mode for File and FTP business services is
Never, which is usually appropriate. However, when you do want to send ACKs from a File or FTP business service, use the Ack Target Config Names setting to identify an Ensemble routing process or business operation to receive the ACK messages.
If True, when generating NACK messages, append an ERR segment that containing the Ensemble error codes and error text; otherwise do not embed internal error state information in NACK messages.
How to treat received message batches. The options are:
Whole Batch— Do not process message documents individually; accumulate and send the whole batch as one composite document.
Single-Session Batch— Forward all messages in the batch together in one session; the session includes objects representing the batch header and trailer segments. This is the default.
Multi-Session Batch— Forward each message in the batch in its own session; each session includes objects representing the batch header and trailer segments.
Individual— Forward each child message in the batch in its own session; do not forward objects representing the batch header and trailer segments.
For more about batch handling, see “HL7 Batch Messages.”
The character encoding of the inbound HL7 messages. Ensemble automatically translates the characters from this encoding.
Supported encoding values are
Latin1, and any other NLS definitions installed on the Ensemble server. The value
Nativemeans to use the default encoding of the Ensemble server. You can also directly use an Ensemble translation table; to do so, use the value
@tablename, where tablename is the name of the table.
By default, if an incoming HL7 message has a non-empty MSH:18 (Character Set) field, Ensemble uses that value rather than the setting. To force Ensemble to ignore MSH:18 and use this setting instead, place a
!(exclamation point) character at the beginning of the setting value. For example:
The default value depends on the adapter.
For background information on character translation in Caché, see “Localization Support” in the Caché Programming Orientation Guide.
Specifies how to resolve a DocType based on the message type from MSH:9. Choose one of the following:
Standard— Combine the effective Message Schema Category value with a message structure name looked up for the MSH:9 message type value in the corresponding schema category. This is the default.
Ignore 9.3— Like 'Standard' except that if MSH:9 has three or more pieces, ignore the additional ones. The standard behavior is to use piece 3 as part of the type name if it has no sub-pieces because some schemas contain three-part type names.
Use 9.3— Like 'Standard' except that if MSH:9 has three or more pieces, use the additional piece as the literal name of the document structure within the applicable schema category. Use with caution because messages may arrive with MSH:9.3 values for which no structure is present in the chosen schema category.
Literal— Combine the effective Message Schema Category value with the literal MSH:9 message type value interpreted as the name of a message structure. Use only with custom schemas where every message type has a corresponding structure definition.
Controls how the HL7 business service interprets the incoming HL7 message packet. If you are unsure what value to use, accept the default of
Flexibleframing for HL7 business services.
The following table lists the valid values for this setting.
|Framing Type||Inbound / Outbound||Meaning|
|Flexible||Inbound||Determine framing style from the content of received data.|
|None||Both||No framing; each line that begins with the string
MSHis the start of a new message.
|MLLP||Both||Minimal Lower Level Protocol — Frame each HL7 message with an ASCII 11 prefix and a suffix that consists of ASCII 28 followed by ASCII 13.|
|MLLP[nn]/[mm]||Both||MLLP using nonstandard ASCII values. Frame each HL7 message with a prefix that consists of the ASCII character value indicated by nn. Also provide a suffix that consists of the ASCII character value indicated by mm, followed by ASCII 13, the carriage return character.|
|AsciiLF||Both||Frame messages with ASCII 10, the line feed character, separating each message from the subsequent one.|
|AsciiCR||Both||Frame messages with an extra ASCII 13, the carriage return character, separating each message from the subsequent one.|
|Ascii[nn]||Both||Frame messages with a suffix separating each message from the subsequent one. This suffix consists of the ASCII character value indicated by nn.|
|Ascii[nn]/[mm]||Both||Frame messages with a prefix character before each message. This prefix consists of the ASCII character value indicated by nn. Also provide a suffix that consists of the ASCII character value indicated by mm, but with no trailing ASCII 13.|
|LLP||Both||(Obsolete) Lower Level Protocol — Frame each HL7 message in a redundant checksum block.|
|MsgEnvelope||Outbound||Use the message Envelope property verbatim if it is present. If the string
<!--HL72MSG-->is present in the envelope, Ensemble replaces it with the Message content; otherwise the Message follows the envelope text.
|MLLPMsgEnvelope||Outbound||Same as MsgEnvelope, but with the MLLP prefix and suffix also around the message inside the envelope.|
When the framing type is
MLLP, Ensemble automatically detects extra carriage returns (ASCII 13) that occur in the message before the close framing. This indicates to Ensemble that a blank line is not being used to separate messages, so it assumes that any blank line is part of the message content and can be safely ignored.
You can specify multiple characters. For example, if you require nonstandard framing such as $Char(2) for message start and $Char(3,4) for message end for your HL7 messages, you can use the Ascii[nn]/[mm] framing option as follows:
ASCII values must be given as numeric values when you enter them in Framing fields. For example, enter lowercase
Ascii120, not as
If True, the business service ignores any inbound ACK messages to avoid creating an ACK feedback loop.
:LocalApplication code that represents the facility and application that receive HL7 messages via this business service. If this business service creates its own ACK, Local Facility Application provides the SendingFacility
:SendingApplication codes for the ACK message; otherwise, this setting is ignored.
Category to apply to incoming message types to produce a complete DocType specification. Combines with the document type Name (MSH:9) to produce a MessageType specification which Ensemble then uses to look up a MessageStructure / DocType in the MessageTypes section of the given HL7 schema category.
This setting may also contain multiple comma-separated type Names followed by
=and then a DocTypeCategory or full DocType value to apply to HL7 messages containing that type Name. A trailing asterisk (
*) at the end of a given partial type Name matches any types beginning with the entry.
DocType property of an HL7 message object
For example: MessageSchemaCategory='2.3.1, ADT_*=2.5, BAR_P10=2.4, ORM_O01_6=2.4:RDE_O01'
Note that a DocType assignment may be needed for Validation or Search Table Class indexing.
If you have not yet prepared a custom schema definition for the HL7 business service, you may leave this field blank for now. However, do not leave it blank permanently unless you also disable validation for the routing process, or validation errors will automatically occur. See “Validation.”
Controls the error code in MSA:1 of the NACK message this service generates when there is an error processing the incoming message. The default is
ContentE, which is to return code
Efor errors with the message content, and code
Rfor system errors Ensemble encounters while attempting to process the message.
This distinction is important because Ensemble expects system errors to be solved so that if the remote client tries again at a later time they may not occur, while message content and validation errors are expected to require correction at the source and not to be worth retrying in the same form. Some client systems may expect or require a different error behavior; therefore, Ensemble provides three additional behaviors. The following table describes the four options.
|ContentE||Use MSA error code
Eto report errors in message content and code
Rto reject due to (retryable) system errors
Rfor content errors,
Efor system errors
Efor all content and system errors
Rfor all content and system errors
*Earlier versions of Ensemble used the
Specifies whether to save a copy of reply messages sent back to the remote system. Also optionally specifies whether to index them using the configured search table class, if any. Choose one of the following:
None — Do not save or index any reply messages.
NotOKs — Save only the replies that are not a simple OK ACK message, for example, save error NACKS and query responses.
All — Save a copy of all reply messages sent to the remote system.
IndexNotOKs — Save replies that are not a simple OK ACK message and index them using the configured search table. This is the default behavior, unless you have overridden the IndexReplies, SaveOKACKs, or IndexACKs parameters in this class. Note that IndexReplies, SaveOKACKs, and IndexACKs are now deprecated.
IndexAll — Save a copy of all reply messages and index them using the configured search table.
True or False. If True, when creating an ACK message for HL7 messages version 2.3 or higher, the business service places one of the enhanced-mode ACK commit codes in the MSA segment AcknowledgmentCode field.
HL7 business services have a Use ACK Commit Codes setting that applies if the Message Schema Category is 2.3 or higher. It can be True or False. If True, when creating an ACK message for HL7 messages version 2.3 or higher, the business service places one of the enhanced-mode ACK commit codes in the MSA segment AcknowledgmentCode field. This code may be one of the following two-letter sequences:
|Code||Meaning in Original Mode||Meaning in Enhanced Mode|
|AA||Application Accept||Application acknowledgment: Accept|
|AE||Application Error||Application acknowledgment: Error|
|AR||Application Reject||Application acknowledgment: Reject|
|CA||—||Accept acknowledgment: Commit Accept|
|CE||—||Accept acknowledgment: Commit Error|
|CR||—||Accept acknowledgment: Commit Reject|