Skip to main content
Previous sectionNext section

Querying and Retrieving a Document from another Affinity Domain (XCA)

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.

InterSystems products can look up patient identifiers in other Affinity Domains via the XCPD Cross-Gateway Patient Discovery transaction. With the patient identifier, you may then query document registries and request a list of documents via the XCA Cross-Gateway Query transaction. It can then retrieve one or more stored documents from the specified repositories via the XCA Retrieve Document Set transaction.

From the outside, XCA is essentially the same as XDS, except for the patient discovery. It uses the same messaging infrastructure as XDS, and you can set up InterSystems products so that document queries search both the local repository and other Affinity Domains.

This chapter includes:

XCA Query Message Trace

Below is an annotated XCA Query message trace, illustrating the patient discovery (XCPD) and the document query.

The trace operations shown in the diagram is a utility that makes intermediate processing steps visible in the trace. The numbers in the diagram match the steps in the procedure below. The first 3 steps and last 3 steps in the procedure appear in a different session, and are basically identical to the steps in the XDS.b query transaction.

generated description: xca query trace

XCA Query Procedure

An XCA query transaction in InterSystems products begins with an XDS query request message. Rather than pointing the XDS Document Consumer to a particular repository, the consumer points instead to the XCA Initiating Gateway, which knows about both the local repository and the repositories in other Affinity Domains. The easiest way to set this up is to create a Service Registry entry that contains the URL of the Initiating Gateway service and call it, for example, “XCA.IG.” Then set the XDSbRegistryServiceName setting in your XCA Document Consumer to XCA.IG.

The full XCA query procedure is documented below. The first 3 steps and the last 3 steps occur in a separate session, and are basically identical to an XDS.b query transaction. They are not shown in the diagram.

  1. You provide an XDSb.QueryRequest message that contains an MPI ID and assigning authority to the XDS.b Document Consumer. The query request also specifies the document type and status (for example “approved”), and may also include a list of filters.

    You can obtain the MPI ID through a PIX or PDQ query (described above).

  2. The document consumer transforms the message into an IHE “XDSb_QueryRequest” message using the TransformRetrieveToXDSb setting.

  3. The document consumer then forwards the query to the XCA Initiating Gateway service that is indicated in the XDSbRegistryServiceName setting. The rest of the procedure takes place in a new session until the document consumer receives its response.

  4. The XCA Initiating Gateway service forwards the message to the XCPD Initiating Gateway process named in the XCPDInitiatingGatewayProcess setting.

  5. The XCA Initiating Gateway process transforms the message into an IHE “XCA_QueryRequest” message using an internally-specified transform, and forwards it to the XCPD Initiating Gateway process to begin the patient discovery.

  6. The XCPD Initiating Gateway process extracts the MPI ID from the request and constructs a Patient Search Request message.

  7. The XCPD Initiating Gateway process gets the patient’s demographics by sending the Patient Search Request to the PDQ consumer named in the PDQv3Consumer setting.

  8. The PDQ consumer returns the demographics.

  9. The XCPD Initiating Gateway process confirms that the <Root> element of the <LivingSubjectID> returned from the PDQ is the same as the assigning authority of the provided MPI ID.

  10. The XCPD Initiating Gateway process checks the XCPDQueryServiceNames setting. This setting should contain a comma-separated list of Service Registry entries that point to XCPD Responding Gateway endpoints in other Affinity Domains.

  11. The XCPD Initiating Gateway process sends one XCPD Patient Discovery Request to the XCPD Initiating Gateway operation for each known XCPD Responding Gateway.

  12. The XCPD Initiating Gateway operation forwards the discovery requests to the XCPD Responding Gateways in the other Affinity Domains. It then returns XCPD Patient Discovery Responses from the XCPD Responding Gateways to the XCPD Initiating Gateway process. Each response contains the MPI IDs and demographics of zero, one, or several possible patients that match the provided demographics. These are exactly like PDQ responses.

  13. The XCPD Initiating Gateway process transforms the responses and replaces the Home Community OIDs with Home Community IDs from the OID registry.

  14. The XCPD Initiating Gateway process extracts the MPI IDs and Home Communities (assigning authorities) for the unique matches, discarding any that match multiple patients within a Home Community.

  15. The XCPD Initiating Gateway process returns an IHE “XCA_QueryResponse” message to the XCA Initiating Gateway process that contains a list of MPI IDs and Home Community IDs, with at most a single entry for each Home Community.

  16. The XCA Initiating Gateway process uses the Home Community IDs to get the Home Community OIDs. In order to translate each OID into a URL, the following setup is required:

    • An OID registry entry of type “HomeCommunity” for each Home Community OID.

    • A Service Registry entry for each Home Community that provides the URL of the XCA Responding Gateway actor in that community:

      • Each Service Registry entry must include the OID registry code in the HomeCommunity field. This ties the OID and Service Registry entries together.

      • Each Service Registry entry must include XCA.Query in the Device Function field. This indicates that it is the “XCA query device” for this community.

  17. For each match returned by the XCPD Initiating Gateway process, the XCA Initiating Gateway process sends an XCA_QueryRequest message to the XCA Initiating Gateway operation named in the XCAInitiatingGatewayOperation setting.

    If there is a value in the XDSbQueryServiceName field, which should point to the local XDS registry, then the XCA Initiating Gateway process also sends an XDSb_QueryRequest to the XCA Initiating Gateway operation. This will trigger a document search in the local XDS registry.

  18. The XCA Initiating Gateway operation forwards the query requests to the XCA Responding Gateways (and possibly the local registry). It then returns the query responses from the XCA Responding Gateways (and local registry) to the XCA Initiating Gateway Process. Each response indicates the document metadata and location for each document available for the patient.

  19. The XCA Initiating Gateway Process combines the various responses.

  20. The XCA Initiating Gateway Process returns an XML message of the “XCA_QueryResponse” variety to the XCA Initiating Gateway service.

  21. The XCA Initiating Gateway service returns the combined responses to the XDS.b Document Consumer in the original session in an XML message of the “XDSb_QueryResponse” variety.

  22. The document consumer extracts the document metadata from the response using the transformation specified in the TransformToMetadata setting. It then constructs an HS.Message.IHE.XDSb.QueryResponse message.

  23. The document consumer returns the XDS.b Query Response message, which contains both the original XCA and XDS.b responses and the extracted metadata. This message can be used to initiate an XCA retrieve, as described in the XCA Retrieve procedure.

XCA Query Components and Settings

Components and Settings Used in XCA Query
Component Setting
Business Hosts XCA Document Consumer: HS.HC.IHE.XDSb.Consumer.Operations
Business Hosts XCA Initiating Gateway Service: HS.IHE.XCA.InitiatingGateway.Services
Business Hosts XCA Initiating Gateway Process: HS.IHE.XCA.InitiatingGateway.Process
Business Hosts XCA Initiating Gateway Operation: HS.IHE.XCA.InitiatingGateway.Operations
Business Hosts XCPD Initiating Gateway Process: HS.IHE.XCPD.InitiatingGateway.Process
Business Hosts XCPD Initiating Gateway Operation: HS.IHE.XCPD.InitiatingGateway.Operation
Business Hosts PDQ Consumer: HS.IHE.PDQv3.Consumer.Operations
Production Settings XDSbRegistryServiceName in the XDS.b Document Consumer:
  • Set to location of the XCA Initiating Gateway service.
Production Settings XCPDInitiatingGatewayProcess in the XCA Initiating Gateway service
Production Settings PDQv3Consumer in the XCPD Initiating Gateway process
Production Settings Service Name in the PDQ Consumer operation
Production Settings XCPDQueryServiceNames in the XCPD Initiating Gateway process:
  • A comma-separated list of Service Registry entries pointing to XCPD Responding Gateway endpoints on other systems.
Production Settings XCAInitiatingGatewayOperation in the XCA Initiating Gateway process
Production Settings XDSbQueryServiceName in the XCA Initiating Gateway process:
  • A Service Registry entry with the URL of your local XDS.b registry. If you enter a value here, then the XCA Initiating Gateway can be used for both XCA and XDS.b queries.
Production Settings TransformToMetadata in the XDS.b Document Consumer
Production Messages HS.Message.IHE.XDSb.QueryRequest
Production Messages HS.Message.IHE.XDSb.QueryResponse
Production Messages
  • XDSb_QueryRequest
  • XDSb_QueryResponse
  • XCA_QueryRequest
  • XCA_QueryResponse
  • XCPD_PatientDiscoveryRequest
  • XCPD_PatientDiscoveryResponse
Production Messages HS.Message.PatientSearchRequest (for PDQ query)
Production Messages HS.Message.PatientSearchResponse (for PDQ query)
XSL Transformations QueryRequestToXDSbQuery.xsl in the XDS.b Document Consumer
XSL Transformations IHE/PDQ/Version1/PatientSearchToPRPAIN201305UV.xsl in PDQ
XSL Transformations IHE/PDQ/Version1/PRPAIN201306UVToPatientSearchResponse.xsl in PDQ
XSL Transformations Message-To-Metadata.xsl in the XDS.b Document Consumer
Service Registry Entries XCA.IG (or similar)
  • points to the XCA Initiating Gateway service
Service Registry Entries PDQv3.Supplier (for PDQ query)
Service Registry Entries
XCPD.RespondingGateway.1
XCPD.RespondingGateway.2
...etc:
  • URLS of the various XCPD Responding Gateways in the Home Communities
Service Registry Entries An XCA.Query device entry for each Home Community that points to the URL of the XCA Responding Gateway endpoint in that community. The OID registry code for the community should appear in the HomeCommunity field, and XCA.Query should appear in the Device Function field.
OID Registry Entries A HomeCommunity OID for each Home Community
External IHE Actor Endpoints PDQ Supplier
External IHE Actor Endpoints XCPD Responding Gateway(s)
External IHE Actor Endpoints XCA Responding Gateway(s)

XCA Retrieve Message Trace

Below is an annotated XCA document retrieve message trace.

The trace operations shown in the diagram is a utility that makes intermediate processing steps visible in the trace. The numbers in the diagram match the steps in the procedure below. The first 3 steps and last 3 steps in the procedure appear in a different session, and are basically identical to the steps in the XDS.b retrieve transaction.

generated description: xca retrieve trace

XCA Retrieve Procedure

The XCA retrieve procedure is documented below. The first 3 steps and the last 3 steps occur in a separate session, and are basically identical to an XDS.b retrieve transaction. They are not shown in the diagram.

  1. Take the XDS.b query response (above) and construct an HS.Message.IHE.XDSb.RetrieveRequest message that contains the document unique ID and repository unique ID (OID) for one or more of the documents listed in the query response.

    Send the XDS.b Retrieve Request to the XDS.b Document Consumer.

  2. The document consumer transforms the message into an IHE “XDSb_RetrieveRequest” message using an internally-specified transform.

  3. The document consumer then forwards the request to the XCA Initiating Gateway service. This service is specified in the XDSbRepositoryServiceName field. For XCA, this field should contain a Service Registry entry containing the URL of the XCA Initiating Gateway service in your production. If you are using only XDS.b, this field is normally left empty.

    The rest of the procedure takes place in a new session until the document consumer receives its response.

  4. The XCA Initiating Gateway service forwards the request to the XCA Initiating Gateway process.

  5. The request may contain documents from different Home Communities, possibly including the local community. The XCA Initiating Gateway process separates them out. The <HomeCommunityId> in the message is specified as an OID. In order to translate the OID into a URL, the following setup is required:

    • An OID registry entry of type “HomeCommunity” for each Home Community OID.

    • A Service Registry entry for each non-local Home Community that provides the URL of the XCA Responding Gateway actor in that community:

      • Each Service Registry entry must include the OID registry code in the Home Community field. This ties the OID and Service Registry entries together.

      • Each Service Registry entry must include XCA.Retrieve in the Device Function field. This indicates that it is the “XCA retrieve device” for the Home Community.

    • A Service Registry entry for the local Home Community that provides the URL of the XDS repository:

      • This Service Registry entry must include the OID registry code in the Repository field. This ties the OID and Service Registry entries together.

      • This Service Registry entry must include XDSb.Retrieve in the Device Function field. This indicates that it is the “XDS.b retrieve device” for the local Home Community.

  6. The XCA Initiating Gateway process constructs an XCA_RetrieveRequest for each community.

  7. The XCA Initiating Gateway process sends the requests to the XCA Initiating Gateway operation.

  8. The XCA Initiating Gateway operation forwards the requests to the appropriate XCA Responding Gateway endpoints and returns their responses to the XCA Initiating Gateway process.

  9. The XCA Initiating Gateway process combines the responses from the various Home Communities.

  10. The XCA Initiating Gateway process constructs an XCA_RetrieveResponse message that contains a list of documents in the message body, and a set of MIME-encoded MTOM attachments, one for each document.

  11. The XCA Initiating Gateway process returns the query response to the XCA Initiating Gateway service.

  12. The XCA Initiating Gateway service returns the combined responses to the XDS.b Document Consumer in the original session in an XML message of the “XDSb_RetrieveResponse” variety.

  13. The document consumer separates out the attachments and translates them.

  14. The document consumer returns the list of documents and the MIME-encoded MTOM attachments in an XML message of the “XDSb_RetrieveResponse” variety with a <DocType> of “RetrieveDocumentSetResponse”.

XCA Retrieve Components and Settings

Components and Settings Used in XCA Retrieve
Component Setting
Business Hosts XCA Document Consumer: HS.HC.IHE.XDSb.Consumer.Operations
Business Hosts XCA Initiating Gateway Service: HS.IHE.XCA.InitiatingGateway.Services
Business Hosts XCA Initiating Gateway Process: HS.IHE.XCA.InitiatingGateway.Process
Business Hosts XCA Initiating Gateway Operation: HS.IHE.XCA.InitiatingGateway.Operations
Production Settings XDSbRepositoryServiceName in the XCA Document Consumer
  • Points to the local XCA Initiating Gateway service.
Production Settings XCAInitiatingGatewayOperation in the XCA Initiating Gateway process
Production Messages HS.Message.IHE.XDSb.RetrieveRequest
Production Messages HS.Message.IHE.XDSb.QueryResponse
Production Messages
  • XCA_RetrieveRequest
  • XCA_RetrieveResponse
  • XCA_QueryResponse
  • XDSb_RetrieveResponse
  • XDSb_RetrieveResponse (RetrieveDocumentSetResponse)
XSL Transformations RetrieveRequestToXDSbRetrieve.xsl in XCA Document Consumer
XSL Transformations Message-To-Metadata.xsl in XCA Document Consumer
Service Registry Entries XCA.IG (or similar)
  • points to the local XCA Initiating Gateway service
Service Registry Entries An XCA.Retrieve device entry for each foreign Home Community that points to the URL of the XCA Responding Gateway endpoint in that community. The OID registry code for the community should appear in the HomeCommunity field, and XCA.Retrieve should appear in the Device Function field.
Service Registry Entries
A Service Registry entry for the local Home Community that provides the URL of the XDS repository. This Service Registry entry must include the OID registry code in the Repository field. This ties the OID and Service Registry entries together. This Service Registry entry must include XDSb.Retrieve in the Device Function field. This indicates that it is the “XDS.b retrieve device” for the local Home Community.
OID Registry Entries A HomeCommunity OID for the local and each foreign Home Community
OID Registry Entries A repository OID for the local XDS repository
External IHE Actor Endpoints XCA Responding Gateway(s)
XDS Repository (in the local Home Community)

XCA Query and Retrieve Example

The method below sends a message that queries the document registry in each listed foreign Affinity Domain and then retrieves whatever documents are found. The user must enter G after the break command to continue.

/// XCA Query and retrieve///
ClassMethod XCAQuery()
{
  
  // Create an XDSb Query Request message
  s o=##class(HS.Message.IHE.XDSb.QueryRequest).%New()

  // Add the MPI ID, document status, type and creation date
  Do o.AddPatientId("100000001^^^&1.3.6.1.4.1.21367.2010.1.2.300&ISO")  //This is the format required by IHE

  Do o.AddStatusValues("Approved")

  Do o.AddCreationFrom("20110510102615-0400")

  Do o.AddDocumentType(1) // 1 is stable, 2 is on-demand, 3 is both

  Do o.AdditionalInfo.SetAt(1,"XCA")

  // Send the message to the test service (or directly to HS.IHE.XDSb.Consumer.Operations or
  // HS.HC.IHE.XDSb.Consumer.Operations)  
  w ##class(HS.Test.Service).SendSync(o,.pr)

  Break

  /// XCA Retrieve /// 

  // Assumes you are using the response from the previous query.
  
  // 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 

  // Required only for HS.Test.Service to distinguish between XCA and XDS.b
  Do obj.AdditionalInfo.SetAt(1,"XCA")

  // Send the message to the test service (or directly to XCA Document Consumer)  
  Write ##class(HS.Test.Service).SendSync(obj,.rr)

  Quit
}
Copy code to clipboard