HL7 QSX messages cancel a previously established publish/subscribe subscription or acknowledge a query/subscription control message. A QSX message is sent from the subscribing system to the publishing system (or integration engine) to declare that it no longer wishes to receive events for the specified subscription ID. This page explains what a QSX message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how a QSX cancellation relates to FHIR. Sample content is constructed for illustration with fictional identifiers.
What a QSX message represents
A QSX message — QSX stands for Query/Subscription Acknowledge — communicates a system's request to terminate or acknowledge a subscription. The core of the message is the MSA segment, which provides the transaction-level acknowledgement status, and the QAK segment, which carries the query/subscription tag from the originating subscription request to identify which feed is being cancelled.
The sender is the subscribing system that previously registered for notifications (for example, a laboratory information system that no longer needs real-time patient updates), and the receiver is the publishing system or integration engine that broadcasts events. QSX is used to clean up subscription channels and prevent unnecessary event broadcasts.
When a QSX message is sent
A QSX message is sent when a subscribing system terminates its connection, changes its interest profile, or is decommissioned. It fires when the subscribing system shuts down or when a user cancels a configured integration channel.
Trigger event
The QSX message type carries a single trigger event:
QSX^J02– Cancel subscription / acknowledge message.
The trigger J02 pairs with the QSB^Z83 (Create Subscription) message. The publishing system processes the cancellation using the subscription identifier carried in the query acknowledgment block.
Integration topology
The diagram shows the subscribing system sending a subscription cancellation through the integration engine to the publishing system.
{{diagram: subscribing system → QSX message → integration engine → publishing system}}
Typical senders: subscribing clinical system, departmental application, data warehouse, integration engine client.
Typical receivers: publishing system, master patient index, integration engine server.
Direction: unidirectional request to cancel an active event subscription.
Segments in a QSX message
The QSX_J02 message is compact: a required MSH header, a required MSA acknowledgement segment, optional ERR segments, and a required QAK query acknowledgement segment. Cardinality follows HL7 notation: [X] optional, {X} repeating, [{X}] optional and repeating; a bare code is required. Each segment code links to its canonical field-by-field reference.
| Segment | Description |
|---|---|
MSH | Message Header. Opens every QSX message. It names the sending and receiving applications, stamps the creation time, declares the trigger event in MSH-9 (QSX^J02), carries the message control id in MSH-10, and pins the HL7 version. |
MSA | Message Acknowledgement. Required. Echoes the original QSB message control id in MSA-2 and carries the acknowledgement code. |
[{ERR}] | Error. Details validation or application errors encountered when processing the cancellation. Optional and repeating. |
QAK | Query Acknowledgement. Required. Carries the unique subscription identifier tag in QAK-1 and the query result status (e.g., OK or NF if not found) in QAK-2. |
[ ] = optional, { } = repeating
Sample QSX message
Note. Constructed for illustration. Subscription tags and message identifiers are fictional.
MSH|^~&|SUBCNTL|MERCY|EHRSYS|MERCY|20260604090000||QSX^J02^QSX_J02|MSG00048|P|2.5.1
MSA|AA|MSG00047
QAK|SUB20260604001|OK
What this sample shows
The QSX^J02 in MSH-9 identifies the message as a subscription cancellation. MSA carries acknowledgement code AA (Application Accept) and acknowledges the original request control ID MSG00047. QAK identifies the subscription being cancelled as SUB20260604001 (QAK-1) and returns a status of OK (QAK-2).
Working with QSX messages
Matching and Verification
When a QSX message is received, the publishing system uses QAK-1 to locate the active subscription in its database and mark it as inactive or deleted. Once updated, the publisher ceases sending events to the subscriber's endpoint.
Handling Non-Existent Subscriptions
If a subscriber attempts to cancel a subscription that does not exist or has already been deleted, the publisher returns an acknowledgement showing a status of NF (Not Found) or AE (Application Error) in the response. Subscribers should handle these responses without failing, as the desired end state (subscription inactive) has already been reached.
Vendor variance. Different vendors use different structures for the subscription identifier in
QAK-1. Some use a UUID, while others use a compound business key (e.g.,ADT-FEED-01). Ensure your parsing logic handles the format expected by the publisher's registration database.
FHIR equivalent
A subscription cancellation corresponds conceptually to deleting or pausing a FHIR Subscription resource (for example, DELETE /Subscription/[id] or updating status to off).
The HL7 v2-to-FHIR Implementation Guide publishes no message map for QSX_J02 and no ConceptMap for the subscription segments. Therefore, any FHIR translation must be mapped manually, using QAK-1 to locate the corresponding Subscription resource and deleting it or setting its status to off.
Common pitfalls
Pitfall. Reusing subscription tags. If
QAK-1is not unique across all subscriptions, the publishing system might cancel the wrong feed, leading to event broadcast failures for other subscribing applications.
Pitfall. Failing to stop event broadcasts immediately. Delaying the deactivation of a subscription after receiving a QSX message can result in data leakage, sending patient records to an endpoint that is no longer authorized to receive them.
How Vorro handles QSX messages
Vorro ingests QSX messages over MLLP, validates the subscription tag in QAK, and updates its internal routing table to deactivate the corresponding event broadcast. Vorro ensures that no further events are sent to the subscriber's MLLP or REST endpoint. Where a FHIR destination is configured, Vorro deletes or deactivates the corresponding Subscription resource, since the HL7 v2-to-FHIR guide provides no published map for this message.
Related messages
- QSB — the message used to create or register a subscription.
- QCN — the message used to cancel a query.
- QBP — the query by parameter message.
