Querying an XDS Registry and Retrieving a Document from a Repository
InterSystems products can query an XDS document registry requesting a list of documents for a patient via the IHE “XDS.b Registry Stored Query” transaction. It can then retrieve one or more stored documents from an XDS repository via the IHE “XDS.b Retrieve Document Set” transaction.
IHE supports the idea of an Affinity Domain of healthcare systems that share a common IHE infrastructure. An Affinity Domain might be a RHIO, an IDN, or some other organization. Each Affinity Domain has a single document registry, and may have multiple document repositories. Use the XDS.b profile to query and retrieve documents only within your Affinity Domain. To query and retrieve documents outside of an Affinity Domain as well, use the XCA profile instead.
XDS Query Message Trace
The following diagram is an annotated XDS query message trace.
The test service shown in the diagram is a simple message router. Trace operations is a utility that makes intermediate processing steps visible in the trace. The numbers in the diagram match the steps in the procedure below.
XDS Query Procedure
-
You provide an XDS.b Query RequestOpens in a new tab message that contains an MPI ID and assigning authority to the InterSystems Document Consumer. You can obtain the MPI ID through a PIX or PDQ query (described above). The query request also specifies the document type and status (for example “approved”), and may also include a list of filters.
-
The InterSystems Document Consumer transforms the message into an IHE “XDSb_QueryRequest” message using an internally-specified transform.
-
The InterSystems Document Consumer then forwards the query to the XDS document registry endpoint on another system that is named in the XDSbRegistryServiceName setting.
-
The XDS document registry on the other system returns a list of available documents along with their metadata and locations.
-
The InterSystems Document Consumer extracts the document metadata from the response using the transformation specified in the TransformToMetadata setting. It then constructs an XDS.b Query ResponseOpens in a new tab message.
-
The InterSystems Document Consumer returns the XDS.b Query ResponseOpens in a new tab message, which contains both the original XDS document registry response and the extracted metadata.
XDS Query Components and Settings
Component | Setting |
---|---|
Business Hosts | Document Consumer: HS.HC.IHE.XDSb.Consumer.OperationsOpens in a new tab |
Production Settings | XDSbRegistryServiceName in the Document Consumer |
Production Settings | TransformToMetadata in the Document Consumer |
Production Messages | HS.Message.IHE.XDSb.QueryRequestOpens in a new tab |
Production Messages | HS.Message.IHE.XDSb.QueryResponseOpens in a new tab |
XSL Transformations | QueryRequestToXDSbQuery.xsl |
XSL Transformations | MessageToMetadata.xsl |
Service Registry Entries | XDSb.Registry |
External IHE Actor Endpoint | XDS Document Registry |
XDS Retrieve Message Trace
The following diagram is an annotated XDS retrieve message trace.
The test service shown in the diagram is a simple message router. Trace operations is a utility that makes intermediate processing steps visible in the trace. The numbers in the diagram match the steps in the procedure below.
XDS Retrieve Document Set Procedure
-
Take the query response (above) and construct an HS.Message.IHE.XDSb.RetrieveRequestOpens in a new tab message that contains the document unique ID and repository unique ID (OID) for one or more of the documents listed in the query. Each retrieve request can go to only one repository, so if the query response refers to multiple repositories, you must split these out into separate retrieve requests, one for each repository.
Send the XDS.b Retrieve Request to the InterSystems Document Consumer.
-
The InterSystems Document Consumer transforms the message into an IHE “XDSb_RetrieveRequest” message using an internally-specified transform.
-
The InterSystems Document Consumer then forwards the request to the XDS document repository endpoint on another system that is indicated by the <RepositoryUniqueID> value in the message. This value is an OID. In order to translate the OID into a URL, the following setup is required:
-
An OID registry entry of type “Repository” for the OID.
-
A Service Registry entry that provides the URL of the repository:
-
The Service Registry entry must include the OID registry code in the Repository field. This ties the OID and Service Registry entries together.
-
Note:If there is a value in the XDSbRepositoryServiceName setting in the InterSystems Document Consumer, then the message will go to the repository specified there rather than to the repository specified in the message. This is useful for testing purposes, but this setting should be blank in a production application.
-
-
The XDS document repository on the other system responds by providing the requested document(s) as MIME encoded MTOM attachments.
-
The InterSystems Document Consumer separates out the attachments and translates them.
-
The InterSystems Document Consumer returns the MTOM attachments in an XML message of the “RetrieveDocumentSetResponse” variety.
XDS Retrieve Components and Settings
Component | Setting |
---|---|
Business Hosts | Document Consumer: HS.HC.IHE.XDSb.Consumer.OperationsOpens in a new tab |
Production Settings |
XDSbRepositoryServiceName in the Document Consumer
|
Production Messages | HS.Message.IHE.XDSb.RetrieveRequestOpens in a new tab |
Production Messages | HS.Message.XMLMessageOpens in a new tab:
|
XSL Transformations | RetrieveRequestToXDSbRetrieve.xsl |
Service Registry Entries | XDSb.Repository (or the repository specified in the message) |
External IHE Actor Endpoint | XDS Document Repository |
XDS Query and Retrieve Example
Below is a sample XDS query and retrieve:
ClassMethod XDSbQueryRetrieve()
{
// Create the XDSb Query Request message
Set MyQuery=##class(HS.Message.IHE.XDSb.QueryRequest).%New()
// Add the MPI ID, document status and type
Do MyQuery.AddPatientId("100000002^^^&1.3.6.1.4.1.21367.2010.1.2.300&ISO")
Do MyQuery.AddStatusValues("Approved")
Do MyQuery.AddDocumentType(3)
// Optionally insert other query parameters
// Do MyQuery.Parameters.Insert(##class(HS.Message.IHE.XDSb.QueryItem).CodedValue(
// "$XDSDocumentEntryFormatCode",code,scheme))
// Send the message to the test service (or directly to HS.IHE.XDSb.Consumer.Operations or
// HS.HC.IHE.XDSb.Consumer.Operations)
Write ##class(HS.Test.Service).SendSync(MyQuery,.pr)
Break
/// XDSbRetrieve ///
// Assumes you are using the response from the previous query.
// Currently this is limited to retrieval from a single repository,
// so if the query response contains multiple repositories, they should
// be split out into separate retrieve requests.
// Create the XDSb Retrieve Request message
Set obj=##class(HS.Message.IHE.XDSb.RetrieveRequest).%New()
// Use the results of the query to populate the message
Set obj.Documents=pr.Documents
// Send the message to the test service (or directly to HS.IHE.XDSb.Consumer.Operations or
// HS.HC.IHE.XDSb.Consumer.Operations)
Write ##class(HS.Test.Service).SendSync(obj,.rr)
Quit
}