Ensemble HL7 Version 2 Development Guide
Settings for HL7 Business Services
 [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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