Skip to main content

Settings for HL7 Business Operations

Provides reference information for settings of an HL7 business operation.


HL7 business operations have the following settings:

Group Settings See
Basic Settings File Name section in this topic
Connection Settings Get Reply, Framing sections in this topic
Additional Settings Search Table Class Settings for Business Operations” in Ensemble Virtual Documents
Auto Batch Parent Segs, Separators, Default Char Encoding, Reply Code Actions, No Fail While Disconnected, Retry Interval sections in this topic

The remaining settings are either common to all business operations or are determined by the type of adapter. For information, see:

For an HL7 business operation, the most important settings are these:

  • Pool Size — The default Pool Size value of 1 makes it possible to support FIFO (First In, First Out) processing. FIFO processing is important to ensure correct data in the receiving applications. Multiple patient demographic updates must be received in order; otherwise, obsolete, incorrect data may appear in the receiving application. Also, 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.

  • Failure Timeout — The number of seconds during which to continue retry attempts. HL7 business operations automatically set this value to -1 for “never time out” to ensure that no HL7 message is skipped.

  • Category — This text label permits configuration items to be sorted in the configuration diagram.

  • Reconnect Retry — (TCP only) Number of retries at which to drop the connection and try reconnecting again. A value of 0 (zero) means never disconnect. The default is 5.

  • Stay Connected — The default of -1 means to stay permanently connected, even during idle times. Adapters are assumed idle at startup and therefore only auto-connect if they are configured with a StayConnected value of -1.

Auto Batch Parent Segs

(File and FTP only) If True, when writing a message that has a batch parent, output the batch headers first, then child documents, then follow up with the batch trailers when triggered by the final batch header message or by a file name change. If False, omit headers and trailers and output child documents only. The default is False.

For more about batch handling, see “HL7 Batch Messages.”

Default Char Encoding

The desired character encoding of the outbound HL7 messages. Ensemble automatically translates the characters to this encoding. See “Default Char Encoding” for business services.

File Name

(File and FTP only) The target file name. The File Path adapter setting determines the path for this file; File Name determines the name. File Name can include Ensemble time stamp specifiers. If you leave File Name blank, the default uses the time stamp specifier %f_%Q where:

  • %f is the name of the data source, in this case the input filename

  • _ is the literal underscore character, which will appear in the output filename

  • %Q indicates ODBC format date and time

For full details about time stamp conventions, including a variety of codes you can use instead of the default %f_%Q, see “Time Stamp Specifications for Filenames” in Configuring Ensemble Productions.


Controls how the HL7 business operation creates the outgoing HL7 message packet. For a list of framing options, see “Framing” in “Settings of an HL7 Business Service.” If you are unsure what value to use, accept the default of MLLP framing for HL7 business operations.

Get Reply

(TCP business operations only) If True, the business operation waits to read an ACK or other reply message from the socket before returning. It also applies any defined Reply Code Actions.

For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.

No Fail While Disconnected

(TCP only) If True, suspend counting seconds toward the Failure Timeout while disconnected from the TCP server. This setting does not apply if Failure Timeout is –1 or if Stay Connected is 0.

Reply Code Actions

Allows you to supply a comma-separated list of code-action pairs, specifying which action the business operation takes on receipt of various types of ACK response messages. The format of the list is:

code=action,code=action, ... code=action

Where code (starting with a :) represents a literal value found in the MSA:1 (Acknowledgment Code) field of the response message, or one of the following special code values:

Code Meaning
:?A Matches AA or CA values (Accept)
:?E Matches AE or CE values (Error)
:?R Matches AR or CR values (Reject)
:_ Matches replies with an empty MSA:1 field. An empty or whitespace code value is the same as _ (underscore)
:* Matches any MSA:1 value not matched otherwise (default=S)
:~ Matches replies that do not contain an MSA segment
:I? Matches where the reply MSA:2 ControlId does not match the ControlId of the original message
:T? Matches where the reply MSH:9 Type name does not match the schema’s declared reply type for the original message

You can also use the standard codes described in “Reply Code Actions” in the reference section of Configuring Ensemble Productions.

The following values for action may be used alone or combined to form strings. F is the default action if no other is given, except for :?A whose default action is C:

Action Meaning
C Treat the message as Completed OK.
W Log a warning but treat the message as Completed OK.
R Retry the message according to the configured RetryInterval and FailureTimeout; finally Fail unless a different action is also specified
S Suspend the message, log an error, and move on to try the next message
D Disable the Operation, log an error and restore the outbound message to the front of the Operation’s queue
F Fail with an error and move on to try the next message

code=action,code=action, ... code=action

The default value for Reply Code Actions is:


This default indicates that Ensemble retries messages with acknowledgment codes AR or CR; for those with codes AE or CE, it suspends the current message, logs an error, and moves on to the next message. The default also treats any message with codes AA or CA as Completed OK and suspends messages that have a value in field MSA:1 that is not matched by any other listed reply code.


The default for retry is ?R=RF. In most cases, this fails immediately after an error, but if the error is "ERROR #5005: Cannot open file", the operation continues to retry until it reaches the FailureTimeout. In many cases this error is caused by a transient problem and retrying fixes the problem, but, in some cases, such as an incorrect directory, the operation fails repeatedly.

For batch ACK messages, the business operation determines the correct Reply Code Actions based on the first child ACK found within the batch.

For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.

Retry Interval

Number of seconds to wait between attempts to connect with a destination outside Ensemble.


HL7 separator characters to use in the outgoing message. If you leave this field blank, the default is:



An HL7 message uses special characters to organize its raw contents. These characters may vary from one clinical application to another. For this reason, the HL7 standard requires that each HL7 message list the five specific characters that it is using as separators at the start of the MSH segment, in order from left to right:

  1. Field separator (FS)

  2. Component separator (CS)

  3. Repetition separator (RS)

  4. Escape character (ESC)

  5. Subcomponent separator (SS)

A sixth character, the segment terminator character, is not specified in MSH and is generally assumed to be a carriage return (ASCII 13).


For Separators, you must supply a string of characters which Ensemble assigns to HL7 separators in left to right order: FS, CS, RS, ESC, SS as described in the previous list.

Beyond positions 1 through 5 of the Separators string, you can supply additional characters to override the default segment terminator character, the carriage return (ASCII 13). After position 5, use \r for the carriage return (ASCII 13) and \n for the line feed (ASCII 10).

You can use \x in positions 1 through 5 if you need to specify segment terminators in positions 6 and higher but want your output messages to use fewer than 5 separators. Separators designated by \x in positions 1 through 5 are not used. The purpose of \x is simply to extend the length of the list of separators so that position 6 is interpreted correctly as the first segment terminator.

FeedbackOpens in a new tab