T2.6: Applies ACK/NACK

Purpose of Acknowledgments

Acknowledgment messages (ACKs) are a fundamental component of reliable HL7 messaging, providing confirmation that messages have been successfully received and processed. When one system sends an HL7 message to another, it typically expects an ACK in response to confirm the message was received. Without acknowledgments, the sending system has no way to know if the message arrived, was lost in transmission, or was rejected due to errors.

ACK Message Structure

ACK messages are themselves standard HL7 messages with message type ACK. They contain an MSA (Message Acknowledgment) segment that includes a critical field - the acknowledgment code - which indicates whether the original message was accepted or rejected, and if rejected, why. The ACK also includes the message control ID from the original message, allowing the sender to correlate the ACK with the specific message it acknowledges.

NACK Terminology

NACK (Non-ACK or Negative Acknowledgment) is the informal term for an ACK message that indicates rejection or failure rather than acceptance. Technically, both positive and negative acknowledgments use the ACK message type - the distinction is in the acknowledgment code in the MSA segment. However, the term NACK is widely used in healthcare integration to refer to rejection acknowledgments, distinguishing them from acceptance ACKs.

Acknowledgment Timing Models

The HL7 standard defines two timing models for acknowledgments: immediate acknowledgment (also called commit acknowledgment or accept acknowledgment) and application acknowledgment. Immediate acknowledgments are sent as soon as the message is received and accepted, confirming that the receiving system has the message stored and will process it. Application acknowledgments are sent after the receiving application has actually processed the message, confirming that the business logic successfully handled the message content. Different integrations require different acknowledgment models based on reliability requirements and system capabilities.

Understanding the Distinction

The distinction between immediate and application acknowledgments reflects different reliability guarantees and different points in the message processing lifecycle. Immediate acknowledgments (also called commit acknowledgments) are sent as soon as the receiving system successfully receives the message and commits it to storage. At this point, the receiving system guarantees it has the message and will process it, but hasn't yet executed the business logic or updated application databases.

Immediate ACK Guarantees

Immediate acknowledgments provide transport-level reliability. They confirm that the message successfully traversed the network, was received by the target system, and is safely stored. The sending system can delete its copy of the message from the outbound queue because the receiving system now has it. However, an immediate ACK doesn't guarantee that the message content is valid or that the application can process it - it only confirms receipt and storage.

Application ACK Guarantees

Application acknowledgments are sent after the receiving application has attempted to process the message through its business logic. This might involve validating the message content, updating databases, performing business rule checks, and executing any required workflows. The application ACK confirms whether this processing succeeded or failed. If the application ACK indicates success, the message was not only received but also successfully processed by the receiving application.

Trade-offs Between Modes

The choice between immediate and application acknowledgments involves trade-offs. Immediate acknowledgments are faster - the ACK is sent within milliseconds of message receipt. Application acknowledgments can take seconds or even minutes if complex processing is involved, keeping the message in the sender's queue longer. However, application acknowledgments provide more comprehensive confirmation. An immediate ACK followed by later processing failures leaves the sending system unaware of the problem, while an application ACK would report the failure. Many integrations use immediate acknowledgments for efficiency, relying on other error handling mechanisms for processing failures.

Overview of ACK Codes

The HL7 acknowledgment framework defines six primary acknowledgment codes that appear in the MSA segment of ACK messages. Understanding these codes and their meanings is critical for configuring appropriate ACK behavior and troubleshooting integration issues. The codes are divided into two categories (immediate/commit and application) and three outcome types (accept, error, reject).

Accept Codes (CA and AA)

CA (Commit Accept) is the immediate success acknowledgment. It indicates that the message was successfully received, validated at a basic level, and committed to storage. The receiving system will process this message. This is the most common positive acknowledgment in integrations using immediate ACK mode. When a Business Service sends a CA, it's saying "I have your message safely stored and will process it."

AA (Application Accept) is the application success acknowledgment. It indicates that the receiving application successfully processed the message through its business logic. The patient was admitted, the order was placed, the result was stored - whatever the message was supposed to accomplish, it succeeded. This is the positive acknowledgment in integrations using application ACK mode.

Error Codes (CE and AE)

CE (Commit Error) is an immediate error acknowledgment indicating that the message itself has problems that prevent it from being stored or processed. Examples include invalid message structure, malformed segments, required fields missing, or values that violate datatype constraints. The problem is with this specific message - it's invalid and cannot be processed. Sending the same message again will get the same error. The sending system should suspend this message and move on to the next.

AE (Application Error) is an application error acknowledgment indicating that the receiving application cannot process this specific message due to business logic problems. For example, attempting to discharge a patient who isn't admitted, or placing an order for a patient who doesn't exist in the system. Like CE, the problem is with this specific message content, and retrying with the same message won't succeed. The message should be suspended and investigated.

Reject Codes (CR and AR)

CR (Commit Reject) is an immediate reject acknowledgment indicating that the receiving system cannot accept any messages right now. The system might be down, undergoing maintenance, or experiencing resource constraints. The problem isn't with the specific message - it's with the receiving system's current state. Retrying the same message later when the system recovers should succeed.

AR (Application Reject) is an application reject acknowledgment indicating that the receiving application cannot process messages right now. Perhaps the database is unavailable, or a critical service is down. Like CR, the problem is temporary and system-wide rather than message-specific. Retrying later should succeed once the application recovers.

Default Behavior Overview

InterSystems HealthConnect Business Operations have built-in default behavior for handling different ACK response codes, designed to implement appropriate retry and error handling based on the type of acknowledgment received. Understanding these defaults is essential for configuring reliable integrations and predicting system behavior when problems occur.

Handling Reject Codes (CR, AR)

When a Business Operation receives a reject acknowledgment (CR or AR), the default behavior is to retry sending the message. The operation continues retrying according to its retry settings until either the message is successfully acknowledged with an accept code (CA or AA), or the Failure Timeout is reached. This retry behavior makes sense because rejects indicate temporary system-level problems - the receiving system isn't ready right now, but will be later. Retrying gives the system time to recover.

Failure Timeout Setting

The Failure Timeout setting controls how long the operation continues retrying before giving up. The default for many HL7 TCP Business Operations is -1, meaning infinite retry. The operation will continue attempting to send the message indefinitely until it succeeds. When Failure Timeout reaches its limit (for positive timeout values), the operation executes the "fail" action, typically suspending the message and moving to the next message in the queue.

Handling Error Codes (CE, AE)

When a Business Operation receives an error acknowledgment (CE or AE), the default behavior is to immediately suspend the message without retrying. This behavior is appropriate because errors indicate problems with the specific message content - the message is invalid or cannot be processed by the receiving application. Retrying the same invalid message will just get the same error. The message needs human investigation to determine what's wrong and whether it can be corrected.

Customizing Default Behavior

These default behaviors can be customized through Reply Code Action settings, which allow you to specify different actions for each acknowledgment code. For example, you might configure the operation to fail immediately on rejects rather than retrying if your integration can't tolerate the message queue buildup that occurs during extended retry periods. Or you might configure error handling to send an alert and fail rather than suspend, depending on your workflow requirements.

Response Channel Concept

Different Business Service adapter types have different default ACK behaviors based on whether they have a response channel - a way to send an acknowledgment back to the sender. Understanding these defaults is important for configuring appropriate ACK handling and troubleshooting situations where expected ACKs aren't being sent or received.

File and FTP Adapters

File and FTP Business Services do not send ACKs by default. The reason is straightforward - when a Business Service reads a message from a file, there's no communication channel back to the sender. The file was written to a directory, the Business Service read it, but there's no connection to the system that created the file to send an ACK. While it's possible to configure these Business Services to generate ACKs and send them through a different channel (perhaps writing ACK files to a response directory, or routing ACKs through a Message Router to a different Business Operation), this requires explicit configuration and is not the default behavior.

TCP, HTTP, and SOAP Adapters

TCP, HTTP, and SOAP Business Services have response channels - the connection over which they received the message can be used to send a response. These Business Services send immediate ACKs (Commit ACKs with code CA) by default. When a message is received over TCP, HTTP, or SOAP, the Business Service sends back an ACK message before the connection closes, confirming to the sender that the message was received successfully. This default behavior implements the common pattern for real-time HL7 messaging where senders expect immediate acknowledgment.

ACK Mode Customization

The ACK Mode setting in Business Services allows you to customize this default behavior. You can configure TCP/HTTP/SOAP Business Services to not send ACKs if the integration doesn't require them, or to send application ACKs instead of immediate ACKs. You can configure File/FTP Business Services to generate ACKs and route them to a Business Operation for delivery. You can even configure ACK mode to be determined by the MSH segment in the incoming message, allowing the sender to specify what type of ACK it expects on a per-message basis.

Exam Considerations

Understanding which Business Service types can send ACKs directly versus which require additional configuration is important for exam questions about ACK behavior. If you see a question about a File Business Service that should be sending ACKs but isn't, remember that File Business Services don't have response channels and require explicit ACK routing configuration.

Overview of ACK Mode

ACK Mode is a critical configuration setting in both Business Services and Business Operations that controls how acknowledgments are handled. The appropriate ACK Mode depends on the requirements of the external system you're integrating with and the reliability guarantees needed for the integration. Understanding the available ACK modes and when to use each is essential for proper integration configuration.

Never ACK Mode

Never ACK mode disables acknowledgment handling entirely. For Business Services, this means no ACK is sent after receiving a message, even if the adapter type (like TCP) would normally send an ACK. For Business Operations, this means the operation doesn't wait for or expect an ACK after sending a message. This mode is appropriate when the external system doesn't support ACKs or when acknowledgments aren't needed for the integration. It reduces messaging overhead but provides no confirmation of message delivery or processing.

Immediate ACK Mode

Immediate ACK mode configures the component to use immediate (commit) acknowledgments. Business Services send CA (Commit Accept) ACKs immediately upon receiving and storing messages. Business Operations expect to receive CA or CR responses and handle them according to Reply Code Actions. This is the most common ACK mode for real-time HL7 integrations, providing rapid acknowledgment while maintaining basic reliability.

Application ACK Mode

Application ACK mode configures application-level acknowledgments where ACKs are sent only after the receiving application processes the message. For Business Services, this means the service doesn't send an immediate ACK; instead, it routes the message to a Business Process that sends an application ACK (AA or AE) after processing completes. For Business Operations, this means the operation waits for an application-level response rather than an immediate acknowledgment. Application ACK mode provides stronger reliability guarantees but increases latency.

MSH-Determined Mode

MSH-Determined ACK mode allows the incoming message to specify what type of acknowledgment is expected using fields in the MSH (message header) segment. MSH-15 (Accept Acknowledgment Type) and MSH-16 (Application Acknowledgment Type) can specify whether immediate and/or application acknowledgments are requested. This mode provides flexibility, allowing different messages to have different ACK requirements, but requires that sending systems properly populate these MSH fields.

Byte ACK

Byte ACK is an additional acknowledgment layer used by some systems, particularly older ones. It's a very low-level acknowledgment (often just a single byte value) sent immediately upon receiving the message bytes, before any HL7 parsing or processing occurs. Some systems require both a Byte ACK (to confirm message receipt at the network level) and a regular HL7 ACK (to confirm message processing). Byte ACK is less common in modern integrations but is still supported for compatibility with legacy systems.

Default Behavior

By default, ACK messages are not displayed in the message trace viewer in InterSystems HealthConnect. This keeps the message trace focused on the primary business messages (ADT, ORM, ORU, etc.) without cluttering the view with acknowledgments. However, when troubleshooting ACK-related issues or verifying that ACKs are being sent and received correctly, you need to see the ACK messages in the trace.

Save Replies Setting

Two configuration settings enable ACK visibility in the message trace. The first is the Save Replies setting, available on Business Operations. Setting Save Replies = All causes all reply messages, including ACKs, to be saved and displayed in the message trace. With this setting enabled, you can see exactly what ACK codes are being received in response to outbound messages, which is invaluable for troubleshooting why messages are being retried or suspended.

Archive IO Setting

The second option is the Archive IO setting, which archives input and output messages at a lower level than the standard message trace. When Archive IO is enabled, the message trace includes additional IO columns that show the raw input and output for each message exchange. ACK messages appear in these IO columns, allowing you to see both the outbound message and its ACK response, or an inbound message and the ACK that was sent in response.

Using ACK Visibility for Troubleshooting

When ACKs are visible in the message trace (through either Save Replies or Archive IO), the interface shows the relationship between messages and their acknowledgments. You can navigate from a primary message to its ACK, see the ACK code (CA, AA, CR, AR, CE, AE) in the ACK's MSA segment, and verify that acknowledgment handling is working as expected. This visibility is essential for diagnosing ACK-related integration issues and is a common topic in exam questions about troubleshooting ACK problems.

Purpose of Reply Code Actions

Reply Code Actions provide granular control over how Business Processes and Business Operations respond to different acknowledgment codes. Rather than using the built-in default behaviors, you can customize the action taken for each acknowledgment code to match your specific integration requirements and error handling workflows.

Configuration Options

Reply Code Actions are configured through settings in Business Processes and Business Operations. The configuration interface lists all possible acknowledgment codes (CA, AA, CR, AR, CE, AE, and others) and allows you to specify the action to take when that code is received. Available actions include Retry (attempt to resend the message), Suspend (place the message in the suspended queue for manual review), Fail (mark the message as failed and move to the next message), Commit (consider the message successfully processed), and various alert-sending options.

Default Behavior and Customization

The default Reply Code Actions implement sensible behavior for most integrations: rejects (CR, AR) trigger retry until Failure Timeout with eventual fail, errors (CE, AE) trigger immediate suspend, and accepts (CA, AA) trigger commit. However, some integrations have different requirements. For example, an integration that absolutely cannot have messages suspended might configure error codes to fail rather than suspend, ensuring messages always flow through the system even if some fail.

Common Customization Scenarios

Another common customization is modifying retry behavior for rejects. Some integrations prefer to fail immediately on rejects rather than retrying, perhaps because the downstream system failure requires manual intervention and retrying just creates message queue buildup without resolving the problem. Setting reject codes to fail rather than retry changes this behavior. Conversely, some integrations want to retry even on errors that would normally be suspended, perhaps because transient database issues could cause temporary errors that resolve on retry.

Alert Configuration

Reply Code Actions can also be configured to send alerts for specific acknowledgment codes. For example, you might configure the system to send an alert whenever a reject (CR or AR) is received, even while continuing to retry the message automatically. This provides proactive notification of downstream system issues while maintaining automated retry behavior. Understanding how to configure Reply Code Actions to implement specific error handling requirements is an important skill tested on the exam.