Sending XDR Messages to Surescripts

this section describes how a customer's xdr interface sends an xdr based message to surescripts sending and receiving are documented independently; a customer that only sends messages can implement the sending workflow here without implementing the full receiving workflow in receiving xdr messages from surescripts docid\ xyqrosgpz8458uzh0p8su note, however, that even a send only implementation must be able to accept an inbound provide and register document set b transaction and return its own valid synchronous response a success or failure provide and register document set b response a send only system should expect to receive not only the delivery notifications (dsns) it is configured to receive, but also replies and other valid xdr based messages addressed to it even when the system will not accept or process the document, it must still respond, rejecting the message with a failure response rather than leaving it unanswered, so that the message does not remain in an error delivery state a send only implementation must therefore support the synchronous response described in sending the message response docid\ xyqrosgpz8458uzh0p8su , even if it does not implement full inbound message processing receiving is otherwise covered in receiving xdr messages from surescripts docid\ xyqrosgpz8458uzh0p8su sending flow overview sending an xdr based message occurs when a customer's xdr interface initiates a provide and register document set b \[iti 41] transaction that submits a clinical document and its metadata to surescripts surescripts then routes the message toward the intended recipient in this direction, the customer's xdr interface is the document source and surescripts is the document recipient (see roles and architecture docid\ daga7uw8atariylz3rtu9 ) the high level flow is the customer's xdr interface constructs the message the soap envelope, the direct\ addressblock, message metadata, and one or more documents the customer submits the message to surescripts over the mutual tls connection surescripts returns a synchronous provide and register document set b response if delivery notifications are used, a delivery status notification follows asynchronously message structure and addressing an xdr based message must include the direct\ addressblock soap header defined in the xdr and xdm for direct secure messaging specification , version 2 1 the sending address must be part of the direct domain assigned to the customer on the network address block element m/c description direct\ from m the direct address of the user or role sending the message direct\ to m at least one recipient direct address the message body and its documents are then packaged into the provide and register document set b request body text (optional) a separate text/plain body document is not required, and message body text is not guaranteed to be retained end to end senders should not rely on it and should place clinically significant information in the clinical document(s) and metadata if a sender represents user authored message body text as a separate document, a classcode of 56444 3 (healthcare communication) may be used for that content clinical documents one or more clinical documents (for example, a c cda or pdf) are included as additional documents, each with metadata appropriate to its content metadata the customer may generate 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 see sending xdr messages to surescripts docid\ xz0mts w6fvt5wxkvd q0 for the key metadata elements and xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 for guidance on choosing between them note although surescripts accepts more than one direct\ to element, sending to multiple recipients in a single message is discouraged surescripts splits multiple recipient messages for routing, and sending a separate message per recipient produces more predictable delivery and tracking see xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 for the corresponding best practice message metadata xdr messages carry xds metadata defined by the applicable directtrust and ihe specifications this section is implementation guidance to help you construct messages that route and process across the network it does not restate or replace the authoritative directtrust/ihe metadata requirements, and surescripts does not enforce a separate metadata requirement model beyond those standards consult directtrust and ihe for the exact requirement level (required, required if known, or optional) of each element for the profile you implement, including limitedmetadata behavior the metadata profile is selected with the metadata level element in the address block minimal metadata (metadata level=minimal) is the profile used for most direct messaging on the surescripts network it relaxes some xds requirements and is flagged with the limitedmetadata classification node, per the standards it does not prevent a sender from including richer document classifications, and in practice many senders (for example, ehrs) do full xds metadata is the complete xds profile, used when integrating with an xds registry or repository, or when a use case or regulation requires it see xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 for guidance on choosing between them the tables below summarize the metadata elements most relevant to constructing a message and supporting routing, patient matching, and downstream processing for each element they give its practical purpose and the impact if it is missing they are not a substitute for the directtrust/ihe metadata requirement tables; follow the standards for the exact requirement level the classification and identification scheme identifiers (uuids) are the canonical ihe xds values in iti tf volume 3 the complete referral example docid\ xz0mts w6fvt5wxkvd q0 shows where each element appears in a complete message submission set metadata element practical purpose implementation guidance standards reference impact if missing submissiontime records when the submission was created populate in the xds time format iti tf vol 3 submission timing and audit ordering are lost submissionset uniqueid uniquely identifies the submission set assign a globally unique oid iti tf vol 3 the submission cannot be uniquely referenced; may be rejected submissionset sourceid identifies the submitting system use the source system's oid iti tf vol 3 the source system cannot be identified submissionset patientid ties the submission to a patient cx format with assigning authority ( message identification docid\ xz0mts w6fvt5wxkvd q0 ); match the document's patientid iti tf vol 3; directtrust xdr/xdm v2 1 patient association is weakened and matching is harder contenttypecode describes the clinical activity of the submission code the overall purpose (for example, a referral) iti tf vol 3 / affinity domain value set receiver has less context for triage and routing author (authorperson, authorinstitution, authortelecommunication, authorrole, authorspecialty) identifies who and what sent the submission populate the author details available iti tf vol 3 provenance is unclear to the receiver intendedrecipient identifies the intended recipient(s) include recipient identity and telecom where available iti tf vol 3 recipient context is reduced document entry metadata (per document) element practical purpose implementation guidance standards reference impact if missing objecttype marks the entry as a stable document use the stable documententry objecttype uuid iti tf vol 3 the entry may be invalid or rejected mimetype declares the document's media type set correctly (for example, text/xml for a c cda) iti tf vol 3 the receiver cannot parse or render the document documententry uniqueid uniquely identifies the document assign a globally unique oid iti tf vol 3 the document cannot be uniquely referenced; may be rejected documententry patientid ties the document to a patient cx format; match submissionset patientid iti tf vol 3; directtrust xdr/xdm v2 1 patient matching is weakened sourcepatientid patient identifier as known by the source system include when available iti tf vol 3 cross referencing to the source patient is harder sourcepatientinfo patient demographics (name, dob, gender, address) as hl7 pid fields include when available iti tf vol 3 fewer demographics for patient matching hash, size integrity check and size of the document compute from the document content iti tf vol 3 integrity and size validation are unavailable author (authorperson, authorinstitution) identifies who authored the document populate the author details available iti tf vol 3 document provenance is unclear description / title human readable label for the document provide a meaningful, phi free label iti tf vol 3 users have a harder time identifying the document classcode high level document class use the applicable class value set iti tf vol 3 / affinity domain value set coarser classification and filing typecode precise document type (for example, loinc 34133 9 or 57133 1) use the applicable type value set iti tf vol 3 / affinity domain value set the receiver cannot precisely categorize or file the document formatcode technical format (for example, the c cda format code) use the applicable format value set iti tf vol 3 / affinity domain value set the receiver cannot select the correct parser or renderer confidentialitycode confidentiality level of the document use the applicable confidentiality value set iti tf vol 3 confidentiality handling may default incorrectly healthcarefacilitytypecode type of facility where the document originated use the applicable value set iti tf vol 3 / affinity domain value set less routing and clinical context practicesettingcode clinical specialty or setting use the applicable value set iti tf vol 3 / affinity domain value set less routing and clinical context creationtime when the document was created populate in the xds time format iti tf vol 3 document timing is unknown languagecode language of the document for example, en us iti tf vol 3 language handling may default incorrectly note under full xds metadata, the document classifications (classcode, typecode, formatcode, confidentialitycode, healthcarefacilitytypecode, practicesettingcode) are required; under the minimal (limited) metadata profile they relax to required if known, so populate them when the values are available full featured senders commonly include them to improve downstream routing and filing (see complete referral example docid\ xz0mts w6fvt5wxkvd q0 ) note the limitedmetadata classification is defined by the ihe and directtrust specifications; consult those standards to determine when and how it applies it is attached as a classification carrying only a classificationnode (no code value or noderepresentation) its presence alone is the flag in the complete referral example docid\ xz0mts w6fvt5wxkvd q0 it appears on the submission set (urn\ uuid 5003a9db 8d8d 49e6 bf0c 990e34ac7707) and on each document (urn\ uuid\ ab9b591b 83ab 4d03 8f5d f93b1fb92e85) message identification the w3c web services addressing 1 0 core recommendation defines the messageid and relatesto headers surescripts uses these headers to uniquely identify each xdr based message and to associate replies with the messages they respond to at a minimum, customers must populate the messageid header messageid must be globally unique surescripts recommends a universally unique identifier (uuid) relatesto is populated on a reply or notification with the messageid of the original message, so the reply can be associated with the correct workflow item (such as an open referral) in the recipient's system message identification headers (messageid / relatesto) example \<wsa\ messageid>urn\ uuid 7f4d7c90 d803 4c33 b053 92f77a59c10f\</wsa\ messageid> \<wsa\ relatesto>urn\ uuid 1a2b3c4d 5e6f 4a7b 8c9d 0e1f2a3b4c5d\</wsa\ relatesto> note this example is for illustrative purposes only patient identification when a message concerns a specific patient, include a patient identifier in the xds metadata, formatted according to the applicable directtrust and ihe requirements (the hl7 cx data type) where available, include an assigning authority so receiving systems can interpret the identifier in the correct organizational context, because the same identifier value can mean different things across organizations the following illustrates one common way a patient identifier and assigning authority may be represented patid1234^^^&1 3 6 1 4 1 99999 1\&iso this example is illustrative and does not redefine the directtrust, ihe, or hl7 formatting requirements invalidly formatted or incomplete identifiers may be accepted for processing but may not translate cleanly downstream or be usable for patient matching note a single xdr based message should concern a single patient if a message is not related to a specific patient, do not populate patient identification because patient identifiers are passed unchanged from multiple parties, surescripts cannot guarantee that a patient identifier is unique see xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 for best practices on patient matching, including verifying matches and allowing users to correct mismatches managing attachment names messages may traverse different packaging and transport models as they move through surescripts processing for example, an originating message may package content as xdm while the final recipient is configured for xdr; in that case the xdr recipient receives an xdr message containing the extracted document(s), not the original xdm archive attachment file names are not preserved end to end between senders and receivers, and should not be used as the basis for document identification, workflow routing, document classification, patient matching, or reconciliation receiving systems should rely instead on metadata, document identifiers, mime/content type, document classification, and document content, and should expect file names to be generated, normalized, or transformed note the uri element of the extrinsic object may carry a document file name, and when messages are converted to xdm attachments the ihe xdm media file naming constraints (the iso 9660 convention eight uppercase characters plus a three character extension) may be applied treat this as packaging/interchange behavior, not a guarantee that file names persist or remains meaningful to the receiver common clinical attachment types and extensions document type extension consolidated cda (c cda) xml pdf pdf plain text txt continuity of care record (ccr) xml image jpg, png submitting the message an xdr based message is submitted to surescripts as an http post to the surescripts xdr document repository endpoint, over the mutual tls connection described in connectivity and mutual tls (mtls) docid\ jfgzrl2j prosttsovza5 the endpoint url differs by environment and is provided during onboarding; see the connectivity and authentication guide for the endpoint values for your environment packaging the request uses soap 1 2 with mtom/xop (message transmission optimization mechanism) and is sent as a multipart/related body the soap envelope is the root part binary document content may be either inlined as base64 inside the \<document> element, or carried in a separate mime part and referenced from \<document> using an \<xop\ include href="cid "/> element (mtom) mtom is recommended for larger attachments required header the request carries a single content type header describing the multipart/related mtom body content type multipart/related; type="application/xop+xml"; start="\<http //tempuri org/0>"; start info="application/soap+xml"; boundary="\<boundary>" the parameters must be consistent with the message body start must equal the content id of the root (soap) part for example, < \<http //tempuri org/0> > boundary may be any unique token, but it must exactly match the \<boundary> delimiter that precedes each mime part and the closing \<boundary> delimiter at the end of the body type and start info identify the root part as an mtom optimized soap 1 2 message and do not change the soap action is carried in the ws addressing \<a\ action> element inside the soap header (see the complete referral example docid\ xz0mts w6fvt5wxkvd q0 ); a separate soapaction http header is not required response a successful submission returns http 200 ok with a soap registryresponse in the body, indicating success or failure ( handling the synchronous response docid\ xz0mts w6fvt5wxkvd q0 ) a transport or tls problem may instead surface as an http level error or a soap fault; see xdr based messaging errors docid 6daoszcli671qovlxx3ud for the distinction between transport/soap faults and application level errors submitting a message with curl (mutual tls) example curl cert client cert pem key client key pem cacert surescripts ca chain pem \\ \ request post "https //\[xdr endpoint provided at onboarding]" \\ \ header 'content type multipart/related; type="application/xop+xml"; start="\<http //tempuri org/0>"; start info="application/soap+xml"; boundary="mimeboundary xdr example"' \\ \ data binary @referral message mtom note this example is for illustrative purposes only replace the certificate and key paths and the endpoint with the values for your environment (provided during onboarding; see the connectivity and authentication guide) the file referral message mtom is the mtom/multipart/related payload (see the complete referral example docid\ xz0mts w6fvt5wxkvd q0 ), and its internal boundary must match the boundary parameter above handling the synchronous response when the customer submits a message, surescripts returns a synchronous provide and register document set b response (see synchronous response (provide and register document set b response) docid\ daga7uw8atariylz3rtu9 ) success surescripts accepted the message for delivery the response contains a registryresponse with a status of success failure surescripts could not accept the message the response contains a registryresponse with a status of failure and a registryerrorlist element describing one or more errors important a success response confirms only that the message was accepted for delivery it does not confirm delivery to the recipient (see synchronous response (provide and register document set b response) docid\ daga7uw8atariylz3rtu9 ) delivery is confirmed by the dsn a failure response carries a registryresponse with a failure status and a registryerrorlist containing one or more registryerror elements each registryerror provides an errorcode, a severity, and a codecontext important in a failure that surescripts generates, errorcode carries a human readable description of the condition detected rather than a standards defined code, and codecontext carries a fixed general value do not branch programmatically on either one, and do not assume the text is stable across releases treat the registryresponse failure status as the machine readable outcome, log the complete registryerror for diagnosis, and surface the errorcode text to users or support staff see xdr based messaging errors docid 6daoszcli671qovlxx3ud and xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 synchronous failure response (registryresponse with a registryerrorlist) \<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 7f4d7c90 d803 4c33 b053 92f77a59c10f\</a\ relatesto> \</s\ header> \<s\ body xmlns\ xsi="http //www w3 org/2001/xmlschema instance" xmlns\ xsd="http //www w3 org/2001/xmlschema"> \<registryresponse status="urn\ oasis\ names\ tc\ ebxml regrep\ responsestatustype\ failure" xmlns="urn\ oasis\ names\ tc\ ebxml regrep\ xsd\ rs 3 0"> \<registryerrorlist> \<registryerror errorcode="recipient direct address not found in the directory intake\@direct example hospital com" codecontext="invalid xdr message" severity="error" location=""/> \</registryerrorlist> \</registryresponse> \</s\ body> \</s\ envelope> note this example is for illustrative purposes only in a surescripts generated failure, errorcode carries a description of the condition detected, codecontext carries a fixed general value such as invalid xdr message, and severity is the short token error rather than the full urn\ oasis\ names🇹🇨ebxml regrep\ errorseveritytype\ error urn the location attribute may contain a non meaningful placeholder value; ignore it the specific text returned depends on the condition detected and should not be parsed for the distinction between transport/soap faults and application level errors, and how to handle each, see xdr based messaging errors docid 6daoszcli671qovlxx3ud for error handling best practices, see xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 interpreting delivery status notifications when the sending system is configured to receive delivery notifications, surescripts returns a delivery status notification (dsn) asynchronously once delivery is determined a message addressed to multiple recipients may produce more than one dsn (see delivery status notification (dsn) docid\ daga7uw8atariylz3rtu9 ) a dsn success confirms the message was delivered to the recipient a dsn failure indicates the message was not delivered; the failure body includes a reason (see dsn examples docid\ xyqrosgpz8458uzh0p8su ) the sending system should use the dsn not the synchronous success response as the signal of final delivery, and should reflect that status in the user's workflow (see xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 ) no delivery notification tracking when the sending system is not configured to receive delivery notifications, surescripts verifies that the direct address is routable and, if it is, 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 synchronous success response (no delivery notification tracking) \<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 7f4d7c90 d803 4c33 b053 92f77a59c10f\</a\ relatesto> \</s\ header> \<s\ body xmlns\ xsi="http //www w3 org/2001/xmlschema instance" xmlns\ xsd="http //www w3 org/2001/xmlschema"> \<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> notes this example is for illustrative purposes only a success response indicates only that the message was accepted for delivery, not that it reached the recipient a send only direct address must still return a response to any valid xdr based message it receives (for example, an automatic acknowledgement or error) so that the message does not remain in an error delivery state (see sending the message response docid\ xyqrosgpz8458uzh0p8su ) complete referral example a complete clinical document submission a referral carrying a c cda clinical summary, modeled on a validated production style message is provided in consolidated message examples docid 4psazf9ozz3bbph9nmob7 , example c 3 1 it uses minimal metadata (note the limitedmetadata classification nodes) while still including the document classifications that full featured senders commonly send; the c cda payload is omitted, with a comment marking where it belongs in that example, addresses are shown without a uri scheme; some senders use the mailto scheme instead (mailto\ dr smith\@ ) the classification and identification scheme identifiers (uuids) are canonical ihe xds values (iti tf volume 3); code values are representative and should be chosen per use case see sending xdr messages to surescripts docid\ xz0mts w6fvt5wxkvd q0 for what each element means and submitting the message docid\ xz0mts w6fvt5wxkvd q0 for the http headers