Important HL7 Scenarios
This page describes some key HL7 scenarios that affect your choice of configuration settings.
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 a production upholds HL7 message conventions for sending ACK and NACK messages:
Commit ACK — The 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 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 business service does not send an ACK or NACK to the source application until one returns from the target application by way of the 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 your InterSystems product: 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 the InterSystems product to provide the expected ACKs.
InterSystems products provide 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 the InterSystems product, the dual acknowledgment sequence works as shown in the following figure:
-
The client application sends a message into the InterSystems product.
-
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.
-
The production 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 InterSystems products, 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.
HL7 Batch Messages
InterSystems products support nested child documents (batch formats) in HL7. Each of the child documents is a virtual document in its own right. This section discusses the details, which are controlled by two settings. It includes the following sections:
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.
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. |
Single-Session
or
Multi-Session |
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. |
Single-Session
or
Multi-Session |
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.