Settings for HL7 Business Operations
Summary
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 |
Additional Settings | 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:
-
Settings for the TCP Outbound Adapter
EnsLib.HL7.Adapter.TCPOutboundAdapterOpens in a new tab has the following settings configured appropriately for HL7:
-
Get Reply is set to True. This means the adapter will wait to read a reply message from the socket before returning.
-
Connect Timeout has its usual default of 5 seconds, but has a maximum limit of 30,000 seconds.
-
Response Timeout has a default of 30 instead of its usual 15, and has a maximum limit of 30,000 seconds.
-
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. InterSystems 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 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.
Framing
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.
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.
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:
:?R=RF,:?E=S,:~=S,:?A=C,:*=S,:I?=W,:T?=C
This default indicates that InterSystems 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.
Retry Interval
Number of seconds to wait between attempts to connect with a destination outside InterSystems products.
Separators
HL7 separator characters to use in the outgoing message. If you leave this field blank, the default is:
|^~\&
Basics
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:
-
Field separator (FS)
-
Component separator (CS)
-
Repetition separator (RS)
-
Escape character (ESC)
-
Subcomponent separator (SS)
A sixth character, the segment terminator character, is not specified in MSH. Unless otherwise specified, the segment terminator is the carriage return (CR) per the HL7 standard. However, the carriage return/line feed (CRLF) characters are also accepted by default.
Details
For Separators, you must supply a string of characters which InterSystems 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.