Ensemble HL7 Version 2 Development Guide
Important HL7 Scenarios
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes some key HL7 scenarios that affect your choice of configuration settings. Topics include:

HL7 Acknowledgment (ACK) Mode
An HL7 acknowledgment (ACK) message acknowledges that a destination has received an HL7 message. A negative ACK (NACK) message acknowledges that the destination is aware of the transmission but did not capture the message.
The following figure illustrates how Ensemble upholds HL7 message conventions for sending ACK and NACK messages:
Commit ACK — The Ensemble business service returns an ACK to the source application as soon as it commits the transaction that saves the data received from that source. It sends a NACK if this proves impossible for some reason. The Ensemble business operation may be set up to interpret an ACK or NACK from the target application, but it does not return those messages to the source.
Application ACK — The Ensemble business service does not send an ACK or NACK to the source application until one returns from the target application by way of the Ensemble business operation. The business service returns the ACK or NACK that it receives from the business operation.
* Commit and Application ACK — The third option only occurs in the rare condition where you set the Ack Mode to be MSH-determined and the MSH segment contains a value in both field 15 and 16 that requires an ACK. InterSystems recommends you avoid this condition.
You use these acknowledgment conventions to send one of the three main types of ACK message content:
Use the following configuration settings to control ACK processing in a business service:
Use the following configuration settings of a business operation to control ACK processing:
HL7 Dual Acknowledgment Sequences
Some systems require a dual acknowledgment sequence from Ensemble: an immediate 1-byte ACK, followed later by the full ACK message. One such system is the dual-channel iSoft iCM application. If your configuration includes a client system such as iCM that requires a dual acknowledgment sequence, you must set up a paired business service and business operation to enable Ensemble to provide the expected ACKs.
Ensemble provides specialized business host classes that you can use to define a dual acknowledgment sequence over TCP and HTTP.
Dual ACK Sequence for Incoming Messages
For messages entering Ensemble, the dual acknowledgment sequence works as shown in the following figure:
  1. The client application sends a message into Ensemble.
  2. The inbound ACK business service sends an immediate 1-byte ACK to the client application.
  3. The inbound ACK business service sends the message to its routing process.
  4. The routing process routes the message to its target via a business operation.
  5. The target application returns an ACK message to the business operation.
  6. Ensemble relays the ACK to the inbound ACK business service.
  7. The business service relays the ACK to its paired business operation.
  8. The business operation relays the ACK to the client application.
  9. The client application acknowledges the ACK message by returning a 1-byte ACK.
Dual ACK Sequence for Outgoing Messages
For messages leaving Ensemble, the dual acknowledgment sequence works as shown in the following figure:
  1. A business service sends a message to its routing process.
  2. The routing process routes the message to the outbound ACK business operation.
  3. The outbound ACK business operation relays the message to the target application.
  4. The target application acknowledges the message by returning a 1–byte ACK.
  5. The target application returns an ACK message to the inbound ACK business service.
  6. The business service sends an immediate 1–byte ACK to the target application.
  7. The business service relays the ACK to its paired business operation.
  8. The business operation relays the ACK message back to the business service.
  9. The business service receives the ACK to its original message.
Configuring a Dual ACK Sequence
To configure an Ensemble routing production to use the dual acknowledgment feature:
  1. Add a business service to the production.
    Choose EnsLib.HL7.Service.TCPAckInService or EnsLib.HL7.Service.HTTPAckInService as the business service class. It is not one of the standard HL7 Input options available from the Business Service Wizard, but you can choose it by selecting the Other option and identifying the class.
  2. Add a business operation to the production.
    Choose EnsLib.HL7.Operation.TCPAckOutOperation or EnsLib.HL7.Service.HTTPAckOutOperation as the business operation class. It is not one of the standard HL7 Output options available from the Business Operation Wizard, but you can choose it by selecting the Other option and identifying the class.
  3. Configure the following settings for the business service:
  4. Configure the following setting for the business operation:
HL7 Batch Messages
Ensemble supports nested child documents (batch formats) in HL7. Each of the child documents is an Ensemble virtual document in its own right. This section discusses the details, which are controlled by two settings. It includes the following sections:
Supported Batch Formats
Ensemble supports the following HL7 batch formats:
Processing Incoming Batch Documents
HL7 business services have the Batch Handling configuration setting, which determines how to process incoming batch documents. The options are:
In responding to received messages, the default behavior is to send an acknowledgment to the sender as a batch document that contains an ACK message for each child document. This works for most situations. However, HL7 business services also have a property, not exposed as a configuration setting, called NoBatchReply. Its default value is 0 (false), which provides the default behavior. If you edit your business service’s OnInit() method to include this statement:
Set ..NoBatchReply = 1
Then batch replies are inhibited; each individual message gets a separate unwrapped ACK. Alternatively, you could set the value by overriding the definition of the property in a subclass by including the following code:
 Property NoBatchReply As %Boolean [ InitialExpression = 1 ]; 
Sending Batch Messages
On the outgoing side, HL7 File and FTP business operations have the Auto Batch Parent Segs configuration setting. When Auto Batch Parent Segs is False (the default) the business operation outputs child documents, but does not output the batch headers and trailers. When Auto Batch Parent Segs is True, while outputting a message that has a batch parent, the business operation outputs the batch headers first, then the child documents, then follows up with the batch trailers when triggered by the final batch header message or by a file name change.
Batch Modes
The combination of Batch Handling and Auto Batch Parent Segs enables the following modes of operation for HL7 batch documents:
Batch Handling Auto Batch Parent Segs Results
Whole Batch (any) Business service sends only the parent document; all child documents are referenced to it but not sent individually. Operation outputs entire batch at one time when it receives the parent document.
or
True Service sends each child document as it receives and parses it, followed by the parent document when all children have been sent. The business operation outputs parent headers when it receives the first child document, then finishes up with trailers when it receives the parent document object. Trailer segments automatically contain the correct child count values.
or
False This results in double output: the business operation sends out each child document individually, followed by the parent document containing each child document (again).
Individual False Business service forwards each child document in the batch in its own session and does not forward objects representing the batch headers and trailers. On the outgoing side, the business operation does the same.
Custom Outbound Batch Handling
If you wish to add custom code to your routing process to handle batch documents specially on the output side, you can do so. The following are two possibilities: