XDR-Based Messaging Best Practices

this section describes best practices that improve message reliability, interoperability, and workflow continuity they complement the application certification requirements docid\ wsfitp7dv6u1yrn7zbxd8 by reducing operational risk and improving end user outcomes customers are encouraged, but not required, to follow them message submission and retry xdr based messaging operates across multiple systems and networks, so temporary outages can occur design for retry and resiliency to prevent message loss and reduce manual rework retry submissions when temporary connection failures occur, using a controlled schedule with exponential backoff (for example, after 5, 15, 30, and 60 minutes) over a bounded window of roughly two hours distinguish retryable errors (network timeouts, 503 service unavailable) from non retryable errors (authentication failures, invalid message format) do not retry non retryable errors; surface them for correction queue outbound messages that cannot be sent immediately so users can continue working without resending manually treat retry as an operational safeguard, not an error state; users should only be involved when retries are ultimately exhausted delivery status notifications synchronous responses confirm processing, not final delivery use dsns ( delivery status notification (dsn) docid\ daga7uw8atariylz3rtu9 ) as the signal of delivery outcome, and reflect that status in the user's workflow ensure your account is configured (opt in) to receive delivery notifications; dsn behavior is governed by that configuration, not by the message alone ( delivery status notification (dsn) docid\ daga7uw8atariylz3rtu9 ) surface delivery status clearly to users, using a state model such as the one below, and display the reasonforfailure text on failures distinguish a timeout driven dsn failure from a genuine delivery failure a timeout means no delivery confirmation was returned often because the recipient is served by a hisp that does not support delivery tracking so the message may still have been delivered treat it as unconfirmed rather than definitively failed ( delivery status notification (dsn) docid\ daga7uw8atariylz3rtu9 ) process a dsn for each recipient when a message was addressed to multiple recipients the following state model reconciles the synchronous response and the dsn into a single delivery status you can present to users state meaning source submitted the message has been sent to surescripts; no synchronous response yet local (sending workflow) accepted surescripts accepted the message for delivery; not yet delivered synchronous success response rejected surescripts could not accept the message synchronous failure response delivered the message reached the recipient dsn success failed the message was not delivered; a reason is provided dsn failure with a delivery error unconfirmed no delivery confirmation was returned within the timeout; the message may still have been delivered dsn failure due to timeout partially delivered for a multi recipient message, outcomes differ across recipients (some delivered, some failed or unconfirmed) per recipient dsns note "retrying" is a useful transient state while a submission is being retried after a temporary connection failure ( message submission and retry docid\ za3pmlbsxejas5vduvf55 ), before it reaches accepted or rejected message context and threading many clinical workflows rely on back and forth communication proper message identification keeps replies associated with the right conversation populate messageid on every message and relatesto on every reply or notification ( message identification docid\ xz0mts w6fvt5wxkvd q0 ) associate replies with the originating request so follow up actions referral responses, care coordination questions, public health clarifications can be tracked accurately patient matching accurate patient identification is essential when exchanging documents across organizations even when identifiers are present, downstream systems must verify and reconcile them include patient identifiers and demographics whenever available to support accurate association do not rely on xdr metadata alone for matching; when metadata is insufficient, inspect the attachment types you expect to receive (c cda xml or html, hl7 v2, pdfs, and other supported documents) for additional demographics or identifiers use object identifiers (oids) as the assigning authority for patient identifiers where possible for example, a cx formatted identifier is patid1234^^^&1 3 6 1 4 1 99999 1\&iso, where 1 3 6 1 4 1 99999 1 is the assigning authority's oid organizations can obtain an oid from the hl7 oid registry (see document references docid\ zt9op0w2lvchwqv38e85w ) design workflows that let users review and confirm patient matches when identifiers originate from external systems, and correct mismatches without re sending route messages with missing or ambiguous patient data to a triage or review queue rather than silently failing or misrouting clinical attachments participants vary in the document types they can send and receive supporting multiple formats improves interoperability accept common clinical document types, in roughly this priority c cda, pdf, plain text, ccr, and images (png, jpg) at minimum, support c cda and pdf for the best user experience, provide direct viewing support for common clinical attachment types where practical regardless of viewing capability, applications must still satisfy the attachment download requirements in acr c 205 when an attachment is filtered or removed, notify the recipient that it was removed, in accordance with acr c 205 a sender facing notification may also be implemented as a workflow enhancement, but it does not substitute for recipient facing notification do not rely on attachment file names for document identification, routing, classification, or patient matching; file names are not preserved end to end use metadata, document identifiers, mime/content type, and document content instead treat the clinical document(s) and their metadata as the authoritative content of a message; do not rely on plaintext message body text as a clinical payload, since it is optional and is not guaranteed to be retained end to end metadata metadata supports routing, matching, and downstream processing richer metadata improves interoperability even when document content varies follow the applicable directtrust/ihe metadata requirements for the profile you implement; surescripts does not enforce metadata beyond the standards include the common document classifications ( message metadata docid\ xz0mts w6fvt5wxkvd q0 ) when your system can produce them, as they improve downstream routing and filing use full xds metadata when integrating with an xds registry or repository, or when a use case or regulation requires it preserve metadata consistently as messages pass through systems to avoid data loss or misinterpretation error management handling errors you receive handle soap faults and xdr application level errors as distinct failure types ( xdr based messaging errors docid 6daoszcli671qovlxx3ud ) do not assume a soap success implies message acceptance or delivery do not branch programmatically on registryerror/@errorcode or codecontext in a surescripts generated failure errorcode carries descriptive text that can change between releases, and codecontext carries a fixed general value; neither is a stable identifier use the registryresponse failure status as the machine readable signal and treat the rest as diagnostic detail log complete registryerror details for troubleshooting, and display user friendly messages rather than raw soap faults or raw errorcode text producing errors your system returns (see sending the message response docid\ xyqrosgpz8458uzh0p8su ) when you cannot accept a message, return a valid registryresponse with a failure status and a registryerrorlist; do not fail silently or return a success you cannot honor populate a specific, standards based errorcode and an actionable codecontext, so the sender can respond programmatically and a person can understand the cause for delivery failures reported by dsn, provide a specific reasonforfailure (for example, "mailbox not found ") rather than a generic message do not include phi or other sensitive detail in error text, consistent with acr c 203, which keeps phi out of message subjects keep your error semantics consistent so trading partners can rely on them directory management to support consistent, searchable, high quality direct address directory data publish and maintain your direct addresses in the surescripts directory; directory publication is the expected routing model ( receiving flow overview docid\ xyqrosgpz8458uzh0p8su ) see the surescripts directory implementation guide for details, and relationship to your surescripts agreement docid\ pmvq7uy 7ymakt3xdroa1 for the corresponding directory obligations keep the addresses you publish synchronized with your source systems and accurate and up to date; stale or incorrect entries cause misrouting and delivery failures support manual entry of direct addresses not every valid direct address is published in the directory, so let users enter and save an address they have obtained directly and send to recipients who are not listed display key provider information alongside each direct address so users can confidently identify the intended recipient clearly distinguish individual provider addresses from organizational (non provider) addresses to reduce misrouting support intuitive search (provider name, direct address, specialty, organization, npi) and filtering, and provide data quality or verification indicators prefer single recipient messages although surescripts accepts multiple direct\ to recipients on one message, it splits multiple recipient messages for routing sending a separate message per recipient produces more predictable delivery and tracking, and simplifies per recipient dsn handling reserve multiple recipient messages for cases where the sending workflow genuinely requires them