How XDR Works: Flows and Notifications

This section describes how XDR-based messages move across the Surescripts network, the roles each system plays, and how message notifications and tracking work. The message construction details for each direction are covered in Sending XDR Messages to Surescripts and Receiving XDR Messages from Surescripts.

XDR is based on the IHE Provide and Register Document Set-b transaction [ITI-41], which defines two roles: the Document Source (the system that initiates the transaction) and the Document Recipient (the system that receives it). On the Surescripts network, Surescripts operates as the Health Information Service Provider (HISP) that routes messages between the sending and receiving systems, and the roles shift depending on the direction of exchange:

When a customer sends a message, the customer's XDR interface is the Document Source and Surescripts is the Document Recipient.

When a customer receives a message, Surescripts is the Document Source and the customer's XDR interface is the Document Recipient.

Electronic message routing uses Hypertext Transfer Protocol over TLS (HTTPS), a request-response protocol. For each message that is sent, a response message is returned, and the status of the delivery is defined by the type of response (see Message Notifications and Tracking).

Surescripts places the following limitations on XDR as it is defined in the IHE ITI Technical Framework, Volume 2b, Section 3.41 (Provide and Register Document Set-b [ITI-41]):

The message must carry at least one document.

Each Provide and Register Document Set-b transaction uses the synchronous web services exchange model: the response is returned synchronously on the same connection, not as a separate asynchronously correlated message.

Only new document submissions are supported. There is no support for replacing or referencing documents from previous transactions.

XDS Folder definitions are not supported.

The Basic Patient Privacy Enforcement option is not supported.

Customers must follow all requirements in DirectTrust's XDR and XDM for Direct Secure Messaging Specification, Version 2.1.

XDR-based messages are addressed using the direct:addressBlock SOAP header defined in the XDR and XDM for Direct Secure Messaging Specification, Version 2.1. The address must be part of the Direct domain assigned to the customer on the network. The address block identifies the sender and one or more recipients:

A sending system is not required to include a separate text/plain message body document. An XDR message should include the clinical document(s), metadata, and routing and addressing information required by the applicable standards and this guide. Some implementations choose to represent user-authored message body text as a separate text/plain document; when they do, a classCode of 56444-3 (Healthcare Communication) may be used for that general communication content. This is an optional representation pattern, not a requirement for XDR exchange. Clinical documents (for example, a C-CDA) carry their own type codes appropriate to their content and use case. Because a plaintext body is not a required interoperability artifact, it is not guaranteed to be retained end-to-end. Senders should not rely on message body text surviving transmission, and should place any clinically or operationally significant information in the clinical document(s) and metadata. Receiving systems should not rely on plaintext body content as the authoritative clinical payload.

Message metadata may conform to either Minimal Metadata or Full XDS Metadata, as defined in the XDR and XDM for Direct Secure Messaging Specification, Version 2.1, Section 6.1. Guidance on choosing between them is provided in XDR-Based Messaging Best Practices.

This section describes the notification and tracking behavior that customers are expected to support in production. Two distinct responses are involved, and they occur at different times:

A synchronous Provide and Register Document Set-b Response acknowledges each transaction at the moment it is submitted (see Synchronous Response (Provide and Register Document Set-b Response)).

When delivery notifications are used, an asynchronous Delivery Status Notification (DSN) reports the final delivery outcome as a later, separate message (see Delivery Status Notification (DSN)).

The Provide and Register Document Set-b Response is the synchronous response exchanged between the customer's system and the Surescripts system. The system receiving the XDR message or DSN must generate the response to the system that sent it. The response value can be:

Success - the message is routable and addressed to a valid Direct domain.

Failure - the message has an invalid Direct domain or an invalid message format.

Important: A Success response means only that the message was accepted and has moved to the next stage in processing. It does not mean the message was delivered to the end recipient. Wait for the DSN to confirm the final delivery status.

A Delivery Status Notification (DSN) is an asynchronous message that reports the final outcome of a message's delivery to its intended recipient. It is returned after the synchronous response, once a final delivery disposition is known. See DSN Examples.

Whether a sender receives DSNs is governed by the sender's delivery notification configuration (opt-in or opt-out), not by the message alone. Surescripts determines DSN behavior from that configuration; a direct:notification element in a submitted message is not used as the opt-in toggle and does not control DSN behavior. (On the DSN itself, direct:notification is used to correlate the notification to the original message - see DSN Examples.) A sender that is not configured to receive delivery notifications receives the synchronous response but no later DSNs.

Because Surescripts routes across multiple connectivity methods, the final disposition that drives a DSN may originate from the downstream delivery path - for example, an XDR Success or Failure response, a Net2Net Verify or Error, or a Message Disposition Notification (MDN) from a destination HISP. Surescripts uses that disposition to generate the DSN it returns to the sender:

A DSN Success indicates the message was delivered to the recipient.

A DSN Failure indicates the message was not delivered; the failure body includes a reason.

If a final disposition is not received within 60 minutes, the message times out and Surescripts generates a DSN Failure indicating that the message was sent but final delivery confirmation timed out.

For multiple-recipient messages, a sender may receive more than one DSN, because each recipient or downstream message split can be processed independently. Design message tracking to handle multiple final outcomes for a single submission, including mixed results where one recipient succeeds and another fails or times out.

The workflows in this guide describe the exchange between the two endpoints of an XDR-based message. Surescripts, acting as a Health Information Service Provider (HISP), routes messages between these endpoints. Where the counterparty is served by a different HISP, Surescripts routes the message to that HISP, so a given endpoint may be a Surescripts customer or a system reached through another HISP.

The following workflows illustrate the requests and responses exchanged between the sending and receiving systems for XDR-based messages and Delivery Status Notifications. They do not represent a comprehensive list of all possible scenarios. Consolidated Message Examples consolidates every message example in the guide and walks through a complete end-to-end exchange in sequence.

When the sending system is not configured to receive delivery notifications, Surescripts confirms only that the Direct address is routable and returns a Success response. The sending system receives no further messages confirming delivery, and the final status must be obtained by contacting the recipient directly.

Surescripts supports addressing a single XDR-based message to multiple recipients, but splits the message for routing so that delivery and notification are handled per recipient. A separate Delivery Status Notification is returned for each recipient on the message.

Because of this routing behavior, Surescripts does not encourage multiple-recipient messaging for senders; sending a separate message per recipient is recommended (see Message Structure and Addressing and XDR-Based Messaging Best Practices). On the receiving side, each receiving system receives only the recipients it hosts, and each split is handled independently, including its responses and Delivery Status Notifications (see Message Structure).