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 docid\ xz0mts w6fvt5wxkvd q0 and receiving xdr messages from surescripts docid\ xyqrosgpz8458uzh0p8su roles and architecture 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 docid\ daga7uw8atariylz3rtu9 ) differences from standard ihe xdr 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 note the synchronous exchange model governs the acknowledgement of each individual transaction the provide and register document set b response returned when a message is submitted it does not describe the final delivery outcome when delivery notifications are used, the outcome is communicated later and asynchronously through a delivery status notification (dsn), which is itself a separate provide and register document set b transaction sent in the reverse direction see message notifications and tracking docid\ daga7uw8atariylz3rtu9 for how the synchronous response and the asynchronous dsn work together message routing and addressing 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 address block element must contain direct\ from the direct address of the user or role that sent the message direct\ to at least one recipient direct address 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 docid\ za3pmlbsxejas5vduvf55 note while the standard, and surescripts, allows more than one direct\ to element, multiple recipient messages are discouraged for senders see message structure and addressing docid\ xz0mts w6fvt5wxkvd q0 for sending guidance and multiple recipients docid\ daga7uw8atariylz3rtu9 for how multiple recipient messages are handled message notifications and tracking 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) docid\ daga7uw8atariylz3rtu9 ) 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) docid\ daga7uw8atariylz3rtu9 ) synchronous response (provide and register document set b response) 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 delivery status notification (dsn) 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 docid\ xyqrosgpz8458uzh0p8su 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 docid\ xyqrosgpz8458uzh0p8su ) 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 important surescripts requires its customers to support delivery notification tracking however, a message may be routed to a recipient served by another hisp that does not support delivery tracking, in which case a final delivery confirmation is never returned when that happens, the message times out as described above and surescripts returns a dsn failure timeouts are therefore common for certain recipients, and there is no way to know in advance which recipients they will affect design message tracking to treat a timeout as an unconfirmed outcome rather than a definite delivery failure workflow glossary 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 term definition sending system the system that originates the xdr based message and submits it for delivery for a surescripts customer sending a message, this is the customer's xdr interface; a message may also originate from a system served by another hisp and reach the customer through surescripts receiving system the system to which the message is delivered for the recipient this may be a surescripts customer's xdr interface or a system reached through another hisp recipient the end user, provider, or organization for whom the message is intended, within the receiving system detailed xdr workflows 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 docid 4psazf9ozz3bbph9nmob7 consolidates every message example in the guide and walks through a complete end to end exchange in sequence note the workflows illustrate single recipient messaging multiple recipient messaging is handled similarly, but is discouraged for senders (see multiple recipients docid\ daga7uw8atariylz3rtu9 ) successful delivery with delivery notification the sending system sends an xdr based message to surescripts surescripts returns a success response to the sending system surescripts delivers the direct message to the receiving system the receiving system delivers the message to the recipient surescripts sends a delivery status notification (success) to the sending system the sending system returns a notification acknowledgement to surescripts sequencediagram participant ss as sending system participant sx as surescripts participant rs as receiving system participant r as recipient ss >>sx 1 xdr based message sx >>ss 2 success response sx >>rs 3 send direct message rs >>r 4 deliver to recipient sx >>ss 5 dsn (success) ss >>sx 6 notification acknowledgement timeout without receiving system response the sending system sends an xdr based message to surescripts surescripts returns a success response to the sending system surescripts delivers the direct message to the receiving system the receiving system does not return a follow up dsn within 60 minutes surescripts sends a delivery status notification (failure) to the sending system the sending system returns a notification acknowledgement to surescripts sequencediagram participant ss as sending system participant sx as surescripts participant rs as receiving system ss >>sx 1 xdr based message sx >>ss 2 success response sx >>rs 3 send direct message note over sx,rs 4 no dsn within 60 minutes sx >>ss 5 dsn (failure) timeout ss >>sx 6 notification acknowledgement synchronous failure response the sending system sends an xdr based message to surescripts surescripts (or the receiving system) cannot accept the message and returns a failure response containing a registryerrorlist the sending system processes the failure and does not receive a further dsn for the message sequencediagram participant ss as sending system participant sx as surescripts ss >>sx 1 xdr based message sx >>ss 2 failure response (registryerrorlist) note failure responses can originate at different points in the transport or processing flow see xdr based messaging errors docid 6daoszcli671qovlxx3ud for the distinction between transport/soap faults and application level errors no delivery notification tracking 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 the sending system sends an xdr based message to surescripts surescripts verifies the address is routable and returns a success response no further delivery confirmation is sent sequencediagram participant ss as sending system participant sx as surescripts ss >>sx 1 xdr based message sx >>ss 2 success response (routable) note over ss,sx 3 no further delivery confirmation multiple recipients 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 docid\ xz0mts w6fvt5wxkvd q0 and xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 ) 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 docid\ xyqrosgpz8458uzh0p8su )