Receiving XDR Messages from Surescripts

this section describes how a customer's xdr interface receives an xdr based message delivered from surescripts sending and receiving are documented independently; a customer that only receives messages can implement from this section without implementing sending xdr messages to surescripts docid\ xz0mts w6fvt5wxkvd q0 receiving flow overview receiving an xdr based message occurs when a customer's xdr interface accepts a message delivered from surescripts in this direction, surescripts is the document source and the customer's xdr interface is the document recipient (see roles and architecture docid\ daga7uw8atariylz3rtu9 ) surescripts delivers the message over the mutual tls connection described in connectivity and mutual tls (mtls) docid\ jfgzrl2j prosttsovza5 , and the customer's system returns a synchronous response (see sending the message response docid\ xyqrosgpz8458uzh0p8su ) customers should publish and maintain their direct addresses in the surescripts directory directory based addressing is the expected and strongly recommended routing model for surescripts direct messaging surescripts matches the recipient direct address to a registered provider or organization record, which identifies the customer interface for delivery publishing addresses to the directory is what makes recipients reliably discoverable and routable across the network, and surescripts expects customers to publish and keep their addresses current domain based routing routing on the recipient's direct domain rather than on an individually registered address is technically supported and can be enabled per domain it is not recommended it reduces recipient discoverability and tends to produce stale or unpublished addresses and other data quality and operational issues over time use domain based routing only when specific addresses genuinely cannot be published in the directory, and publish addresses to the directory wherever possible even where domain based routing is enabled for address publication, endpoint configuration, participant onboarding, and routing configuration, refer to the surescripts directory implementation guide message structure surescripts conforms to section 6 1 of the xdr and xdm for direct secure messaging specification , version 2 1, for the soap headers used in direct secure messaging an incoming message contains the following element contains direct\ addressblock (soap header) one direct\ from element (the sender) and one or more direct\ to elements (the recipients) xds metadata authorperson sender information intendedrecipient recipient address or addresses a received message carries the same xds metadata structure shown in the complete referral example docid\ xz0mts w6fvt5wxkvd q0 a submission set and one or more document entries, each with their classifications and identifiers the elements above are those most relevant when consuming a message for a complete received message as delivered to a receiving endpoint, see consolidated message examples docid 4psazf9ozz3bbph9nmob7 multiple recipients surescripts splits a message addressed to multiple recipients by receiving system an xdr receiving system receives a message addressed to the recipient(s) it hosts; recipients served by other systems are delivered separately and are generally not listed on the message your system receives when more than one recipient is hosted by the same receiving system, those recipients appear together as multiple direct\ to elements in the single message delivered to that system, as shown below each split is handled independently the responses and delivery status notifications for one receiving system are not shared with another illustrative incoming address block two recipients hosted by the same receiving system example \<direct\ addressblock soap\ role="urn\ direct\ addressing\ destination" soap\ relay="true" xmlns\ direct="urn\ direct\ addressing"> \<direct\ from>dr smith\@direct example clinic com\</direct\ from> \<direct\ to>intake\@direct example hospital com\</direct\ to> \<direct\ to>records\@direct example hospital com\</direct\ to> \</direct\ addressblock> note this example is illustrative and shows two recipients hosted by the same receiving system recipients served by other systems are delivered as separate messages and would not appear here patient identification surescripts forms the outbound xdr message using information available from the inbound clinical direct message after normalizing and processing it for routing because messages can originate through different entry points and formats, the patient identification available in xdr metadata can vary when the originating system supplies complete xdr or xdm metadata, that metadata is the most reliable source for patient identifiers and demographics in the outbound xdr message when it does not, some patient information may be present only within clinical attachments (such as c cda xml or html, hl7 v2 content, or pdfs), or may not be available in structured metadata at all receiving systems should not rely on xdr metadata alone for patient matching determine whether your workflows need to inspect the attachment types you expect to receive for additional demographics or identifiers, and provide review handling when patient data is missing, incomplete, or ambiguous note because patient identifiers are passed unchanged from external parties, the receiving system must not rely on the identifier alone to match the clinical information to a patient record see xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 for patient matching best practices, including verifying matches and allowing users to correct mismatches sending the message response when the customer's xdr interface receives a message, it must return a synchronous provide and register document set b response if the system can accept the message for delivery, it returns a success response if the system cannot accept the message, it returns a failure response containing a registryerrorlist element within the registryresponse element to interoperate with the surescripts network, the customer must implement, at a minimum, the same xdr extensions that surescripts implements from the xdr and xdm for direct secure messaging specification , version 2 1 this includes the direct address block and the minimal metadata specification surescripts also accepts full xds metadata note see xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 for best practices on handling temporary connectivity failures, queuing, and retries no delivery notification tracking when the receiving system is not configured to send delivery notifications, surescripts translates the synchronous responses into delivery status as follows if the message was received and delivered to the recipient, the success response is treated as a dsn success if the message was not successfully delivered, the failure response is treated as a dsn failure the message is then identified with its final status, and no further responses are expected dsn examples a delivery status notification (dsn) confirms whether a message was delivered successfully or failed it is sent asynchronously, after the synchronous response, as a separate provideandregisterdocumentset b transaction in the reverse direction (from the receiving side back toward the original sender) the disposition (success or failure) is base64 encoded in the document element, and the direct\ notification element in the address block links the dsn to the original message the examples below show the notification header, the success and failure disposition bodies, a complete dsn message, the sender's acknowledgement of the dsn, and where each part is located note the direct\ notification element in the address block links a dsn to its original message whether a sender receives dsns is governed by the sender's delivery notification configuration base64 decode the document content to read the disposition notification header direct\ notification in the address block, linking the dsn to the original message \<direct\ addressblock xmlns\ direct="urn\ direct\ addressing" s\ role="urn\ direct\ addressing\ destination" s\ relay="1"> \<direct\ from>intake\@direct example hospital com\</direct\ from> \<direct\ to>dr smith\@direct example clinic com\</direct\ to> \<direct\ notification relatesto="urn\ uuid 7f4d7c90 d803 4c33 b053 92f77a59c10f"/> \</direct\ addressblock> success disposition dsn success disposition (before base64 encoding) \<direct\ messagedisposition xmlns\ direct="urn\ direct\ addressing"> \<direct\ recipient>intake\@direct example hospital com\</direct\ recipient> \<direct\ disposition>success\</direct\ disposition> \</direct\ messagedisposition> failure disposition dsn failure disposition with a reason (before base64 encoding) \<direct\ messagedisposition xmlns\ direct="urn\ direct\ addressing"> \<direct\ recipient>intake\@direct example hospital com\</direct\ recipient> \<direct\ disposition>failure\</direct\ disposition> \<direct\ reasonforfailure>mailbox not found \</direct\ reasonforfailure> \</direct\ messagedisposition> the direct\ reasonforfailure element should contain a specific, actionable description examples of useful reason text include mailbox not found message exceeds the recipient's maximum size limit unsupported attachment type recipient system unavailable delivery timed out full dsn message a dsn is delivered as a complete provideandregisterdocumentset b transaction the a\ relatesto header and the direct\ notification element both carry the original message's messageid, and the document holds the base64 encoded disposition a complete success dsn is shown in consolidated message examples docid 4psazf9ozz3bbph9nmob7 , dsn acknowledgement because the dsn is itself a provideandregisterdocumentset b transaction, the system that receives it (the original sender) returns a synchronous registryresponse to acknowledge it, closing the workflow the a\ relatesto header carries the dsn's messageid acknowledgement of the dsn (synchronous response) \<s\ envelope xmlns\ s="http //www w3 org/2003/05/soap envelope" xmlns\ a="http //www w3 org/2005/08/addressing"> \<s\ header> \<a\ action s\ mustunderstand="1">urn\ ihe\ iti 2007\ provideandregisterdocumentset bresponse\</a\ action> \<a\ relatesto>urn\ uuid 2c8b0e13 9f1a 4b6e 8b5a 6d7e8f901234\</a\ relatesto> \</s\ header> \<s\ body> \<registryresponse status="urn\ oasis\ names\ tc\ ebxml regrep\ responsestatustype\ success" xmlns="urn\ oasis\ names\ tc\ ebxml regrep\ xsd\ rs 3 0"/> \</s\ body> \</s\ envelope> dsn locations in the message file part location in the message notification header envelope > header > direct\ addressblock > direct\ notification success or failure disposition envelope > body > provideandregisterdocumentsetrequest > document (base64 encoded) note an error description should be included in the direct\ reasonforfailure element of the failure disposition