Important HL7 Scenarios
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:
Accept — The message arrived, and was accepted.
Reject — The message arrived, but has been rejected.
Error — The message did not arrive successfully; try again.
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.
EnsLib.HL7.Service.TCPAckInService is a specialized HL7 business service that receives ACKs on behalf of a paired HL7 TCP business operation. It also depends on this partner to send ACKs on its behalf.
EnsLib.HL7.Operation.TCPAckOutOperation is a specialized HL7 TCP business operation that sends out ACKs on behalf of a paired HL7 TCP business service. It also depends on this partner to collect ACKs on its behalf. Each of these configuration items plays its usual role in addition to the work it does for its partner item.
Dual ACK Sequence for Incoming Messages
For messages entering Ensemble, the dual acknowledgment sequence works as shown in the following figure:
The client application sends a message into Ensemble.
The inbound ACK business service sends an immediate 1-byte ACK to the client application.
The inbound ACK business service sends the message to its routing process.
The routing process routes the message to its target via a business operation.
The target application returns an ACK message to the business operation.
Ensemble relays the ACK to the inbound ACK business service.
The business service relays the ACK to its paired business operation.
The business operation relays the ACK to the client application.
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:
A business service sends a message to its routing process.
The routing process routes the message to the outbound ACK business operation.
The outbound ACK business operation relays the message to the target application.
The target application acknowledges the message by returning a 1–byte ACK.
The target application returns an ACK message to the inbound ACK business service.
The business service sends an immediate 1–byte ACK to the target application.
The business service relays the ACK to its paired business operation.
The business operation relays the ACK message back to the business service.
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:
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.
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.
Configure the following settings for the business service:
Set Immediate Byte ACK to True. Then, in addition to forwarding a full ACK message according to the Ack Mode setting, the business service also returns an immediate 1-byte ACK on its TCP or HTTP connection.
For a Partner Operation, choose the business operation that you added in Step 2. Whenever you specify a Partner Operation value, the business service ignores any inbound ACK messages that it receives directly, to avoid creating an ACK feedback loop.
Configure the following setting for the business operation:
Set the Partner ACK Timeout to the number of seconds for the business operation to wait for its partner business service to supply an ACK that corresponds to the normal outbound message that the business operation sent. The default is 600 seconds (10 minutes).
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:
BHS MSH ... MSH ... BTS
Ensemble recognizes BHS as a batch header segment, and BTS as a batch trailer segment. Within this container, Ensemble recognizes each MSH message header segment as the beginning of a child document.
FHS MSH ... MSH ... FTS
Ensemble recognizes FHS as a batch header segment, and FTS as a batch trailer segment. Within this container, Ensemble recognizes each MSH message header segment as the beginning of a child document.
FHS BHS MSH ... MSH ... BTS BHS MSH ... MSH ... BTS FTS
When FHS and BHS begin the message together, Ensemble recognizes FHS as the first-level parent document and each BHS as the beginning of a child document. BHS then becomes a second-level parent and the contents following each MSH segment become its child documents.
Processing Incoming Batch Documents
HL7 business services have the Batch Handling configuration setting, which determines how to process incoming batch documents. The options are:
Whole Batch — Do not process child documents individually; accumulate and send the whole batch as one composite document.
Single-Session Batch — Forward all child documents in the batch together in one session; the session includes objects representing the batch headers and trailers. Single-Session Batch is the default if no Batch Handling value is specified.
Multi-Session Batch — Forward each child document in the batch in its own session, with a unique session ID.
Individual — Forward each child document in the batch in its own session; do not forward objects representing the batch headers and trailers.
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.
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.|
|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.|
|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:
Your routing process code creates new parent and child documents and links them, then sends each child to the business operation. The business operation must have Auto Batch Parent Segs set to True. 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.
Your routing process code creates new parent and child documents and links them, but sends only the parent object via the business operation.