Skip to main content

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
Basic Settings 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
Additional Settings Override Segment Terminator, 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 production routing engine is not configured to forward back a response from any of its targets, InterSystems creates and returns ACK or NACK objects to return to the caller. If validation fails and the Ack Mode is Application, InterSystems 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.StandardOpens in a new tab without overriding the Ack Mode setting.

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

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

Add NACK ERR

If True, when generating NACK messages, append an ERR segment that containing the InterSystems 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.

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. InterSystems automatically translates the characters from this encoding.

Supported encoding values are UTF-8, Latin1, and any other NLS definitions installed on the InterSystems IRIS server. The value Native means to use the default encoding of the InterSystems IRIS server. You can also directly use an InterSystems 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, InterSystems uses that value rather than the setting. To force InterSystems products 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 information on character sets and translation tables, see Translation Tables.

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.

Override Segment Terminator

(FTP only) Comma-separated list of ASCII control characters to use as segment terminators. The values may be in decimal format or hex format preceded by an x. For example, to specify the line feed character as the segment terminator, enter 10 or x0A. The default value is the carriage return, which has a decimal value of 13 and a hex value of x0D.

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.
Flexible! Inbound Determine framing style from the content of received data of the first message and require subsequent messages to have that same framing style.
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, InterSystems 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, InterSystems products automatically detect extra carriage returns (ASCII 13) that occur in the message before the close framing. This indicates to InterSystems 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.

Per the HL7 standard, the segment terminator is the carriage return (CR). However, the carriage return/line feed (CRLF) characters are also accepted.

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.

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 InterSystems 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 InterSystems encounters while attempting to process the message.

This distinction is important because the production 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, InterSystems products provide four 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

For a general discussion of ACK handling, see HL7 Acknowledgment (ACK) Mode.

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.

FeedbackOpens in a new tab