Ensemble HL7 Version 2 Development Guide
Settings for HL7 Business Operations
Provides reference information for settings of an HL7 business operation.
HL7 business operations have the following settings:
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:
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.
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.
This text label permits configuration items to be sorted in the configuration diagram.
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.
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.
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.
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
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
indicates ODBC format date and time
(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
No Fail While Disconnected
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:
(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:
||Matches AA or CA values (Accept)
||Matches AE or CE values (Error)
||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=F)
||Matches replies that do not contain an MSA segment
||Matches where the reply MSA:2 ControlId does not match the ControlId of the original message
||Matches where the reply MSH:9 Type name does not match the schema’s declared reply type for the original message
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:
||Treat the message as Completed OK.
||Log a warning but treat the message as Completed OK.
||Retry the message according to the configured RetryInterval and FailureTimeout; finally Fail unless a different action is also specified
||Suspend the message, log an error, and move on to try the next message
||Disable the Operation, log an error and restore the outbound message to the front of the Operation’s queue
||Fail with an error and move on to try the next message
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.
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:
Repetition separator (RS)
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).
, 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.