Next section

Settings for HL7 Business Services

Provides reference information for settings for HL7 business services.

Summary

HL7 business services have the following settings:
Group Settings See
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:
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.

Ack Mode

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.
Ack Mode Meaning
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:
  • AL — Always
  • NE — Never
  • ER — Error or reject conditions only
  • SU — Successful completion only
MSH 15 (AcceptAcknowledgmentType) controls Commit ACK and MSH 16 (ApplicationAcknowledgmentType) controls Application ACK. Depending on how they are set in the incoming message MSH segment, one, both or neither may occur.
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.
For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.

Ack Target Config Names

(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.
See Ack Mode for more information. For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.

Add NACK ERR

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.
For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.

Batch Handling

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.”

Default Char Encoding

The character encoding of the inbound HL7 messages. Ensemble automatically translates the characters from this encoding.
Supported encoding values are
UTF-8
,
Latin1
, and any other NLS definitions installed on the Ensemble server. The value
Native
means 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:
!UTF-8
The default value depends on the adapter.
For background information on character translation in Caché, see “Localization Support” in the Caché Programming Orientation Guide.

DocTypeResolution

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.

Framing

Controls how the HL7 business service interprets the incoming HL7 message packet. If you are unsure what value to use, accept the default of
Flexible
framing 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
MSH
is 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:
Ascii2/3,4
Note:
ASCII values must be given as numeric values when you enter them in Framing fields. For example, enter lowercase
x
as
Ascii120
, not as
Ascii'x'
.

Ignore Inbound ACK

If True, the business service ignores any inbound ACK messages to avoid creating an ACK feedback loop.
For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.

Local Facility Application

Colon-separated LocalFacility
:
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.

Message Schema Category

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.”

NACK Error Code

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
E
for errors with the message content, and code
R
for 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.
Code Meaning
ContentE Use MSA error code
E
to report errors in message content and code
R
to reject due to (retryable) system errors
ContentR* Return
R
for content errors,
E
for system errors
AllE Return
E
for all content and system errors
AllR Return
R
for all content and system errors
*Earlier versions of Ensemble used the
ContentR
behavior exclusively.
For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.

Save Replies

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.

Use ACK Commit Codes

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
For a general discussion of ACK handling, see “HL7 Acknowledgment (ACK) Mode,” earlier in this book.
Next section