IHE ITI TF Vol2

3.38 Cross Gateway Query [ITI-38]

This section corresponds to transaction [ITI-38] of the IHE ITI Technical Framework. Transaction [ITI-38] is used by cooperating Initiating Gateway and Responding Gateway Actors.

3.38.1 Scope

The scope of the Cross Gateway Query transaction is based on the Registry Stored Query [ITI-18] transaction. The same set of stored queries is required to be supported and the options controlling what kind of data is returned are the same. Differences from the Registry Stored Query transactions are:

The Cross Gateway Query is between an Initiating Gateway and Responding Gateway.
Initiating Gateway shall specify the homeCommunityId attribute in all Cross-Community Queries which do not contain a patient identifier.
The homeCommunityID attribute shall be returned within all appropriate elements.
Responding Gateways shall support the Asynchronous Web Services Exchange Option on the Cross Gateway Query. Support for this function is required in order to enable use of Asynchronous Web Services Exchange in any cross-community interaction. Without this support an Initiating Gateway would require unique configuration, per Responding Gateway, to know if Asynchronous Web Services Exchange was supported. It is expected that Asynchronous Web Services Exchange will be desired by the majority of communities.
Asynchronous Web Services Exchange is an option on the Initiating Gateway, see ITI TF-1: 18.2.2 .
For stored queries that rely on concepts that a community may not support, namely associations, folders and submission sets, a Responding Gateway is allowed to respond with zero entries.

There shall be an agreed upon common coding/vocabulary scheme used for the Cross Gateway Query. For example, a common set of privacy consent vocabularies shall be used.

3.38.2 Use Case Roles

Actor: Initiating Gateway

Role: To formulate a Cross Gateway Query on behalf of a user.

Actor: Responding Gateway

Role: To respond to a Cross Gateway Query based on the internal configuration of the community.

3.38.3 Referenced Standard

Implementers of this transaction shall comply with all requirements described in ITI TF-2: Appendix V Web Services for IHE Transactions.

ebRIM	OASIS/ebXML Registry Information Model v3.0
ebRS	OASIS/ebXML Registry Services Specifications v3.0
ITI TF-3:4	Metadata used in Document Sharing profiles

3.38.4 Messages

Figure 3.38.4-1: Interaction Diagram

3.38.4.1 Cross Gateway Query

This is a query request between an Initiating Gateway and a Responding Gateway. The query request contains:

A reference to a pre-defined query defined by the Registry Stored Query [ITI-18]. transaction
Parameters to the query. The query parameters are defined by the Registry Stored Query transaction. The homeCommunityId attribute is required for every Registry Stored Query which does not specify a patient identity.

3.38.4.1.1 Trigger Events

This message is initiated when the Initiating Gateway has determined that it must interact with the Responding Gateway to satisfy a Registry Stored Query [ITI-18] request received from an XDS.b Document Consumer or a query request from other internal non-IHE actor. When initiating this message to satisfy a Registry Stored Query [ITI-18] request the Initiating Gateway shall pass all parameters, either known or unknown, into the Cross Gateway Query.

3.38.4.1.2 Message Semantics

The message semantics are based on the Registry Stored Query. See ITI TF-2: 3.18.4.1.2 .

Initiating Gateways which support the On-Demand Documents Option shall be capable of querying for an On-Demand Document Entry either through internal mechanisms or, when the XDS Affinity Domain Option is also declared, through interaction with an XDS Document Consumer which supports the On-Demand Documents Option.

Responding Gateways which support the On-Demand Documents Option shall be able to respond to a query of an On-Demand Document Entry, either through internal mechanisms or, when grouped with a Document Consumer, through interaction with appropriate XDS actors which support On-Demand Documents. Of special note are the use of homeCommunityId, specifying the patient identifier and special handling of some stored queries. These are explained below.

3.38.4.1.2.1 homeCommunityId

The homeCommunityId is a globally unique identifier for a community and is used to obtain the Web Services endpoint of services that provide access to data in that community. homeCommunityId is structured as an OID limited to 64 characters and specified in URI syntax, for example the homeCommunityId of 1.2.3 would be formatted as urn:oid:1.2.3.

Its use is as follows:

It is returned within the response to Cross Gateway Query and Registry Stored Query transactions to indicate the association of a response element with a community. It is specified as the ebRIM 'home' attribute within the relevant response elements. Document Consumers process the value as an opaque unique identifier.
It is used by optional parameters to Registry Stored Query, Cross Gateway Query, and Retrieve Document Set requests, and by a required parameter to Cross Gateway Retrieve requests, to indicate which community to direct the request.

For stored queries which do not require the patient id as a parameter, meaning query by EntryUUID or UniqueID:

If the Cross Gateway Query is being addressed to a Responding Gateway then the Initiating Gateway or the client on whose behalf it is forwarding the request may have previously sent a Cross Gateway Query to the Responding Gateway which included a patient id and saved the homeCommunityId which was returned on the element containing the EntryUUID or uniqueID. If this is not the case the Initiating Gateway shall have access to the correct homeCommunityId through some other means.
The homeCommunityId value is specified as the home attribute on the AdhocQuery element of the query request, as in:
Each query request can have at most one homeCommunityId value. If the Document Consumer specifies multiple entryUUID or uniqueID values they must all be associated with the same homeCommunityId value. Multiple individual query requests can be used to retrieve data associated with different homeCommunityIds.

For stored queries which do require the patient id as a parameter:

The homeCommunityId values are specified in the $targetCommunityIdList query parameter. This parameter is respected by XCA Initiating Gateway and XCA Responding Gateway actors that support the Target Communities option. It may be ignored by actors which do not support the Target Communities option.
A single homeCommunityId value can instead be specified in the home attribute on the AdhocQuery element of the query request, as in: . However, it may be ignored by all other actors.
If the query contains the $targetCommunityIdList parameter, then the home attribute on the AdhocQuery element of the query request shall not be populated.

3.38.4.1.2.2 Specifying patient identifier

The Initiating Gateway shall specify in relevant queries a patient identifier known to the Responding Gateway. The mechanism used by the Initiating Gateway to determine the correct patient identifier to use is outside the intended scope of this transaction. The Responding Gateway can expect to be able to resolve the patient identifier. If the patient identifier is unknown by the Responding Gateway’s community, the Responding Gateway shall return either a successful response with no elements or an error with errorCode XDSUnknownPatientId, depending on local policy.

3.38.4.1.2.3 Special handling of some stored queries

Some stored queries rely on the support of concepts which may not be used within a community. It is also possible that a Responding Gateway community may have policies which restrict the sharing of information related to those concepts. The concepts of concern are submission sets, folders and associations. In either case a Responding Gateway shall respond to the appropriate stored queries by returning zero results. Table 3.38.4.1.2.3-1 lists all the stored queries which rely on specialized concepts.

Table 3.38.4.1.2.3-1: Stored Queries

Query Name	Concepts	Requirement
FindDocuments	None	Required by all
FindSubmissionSets	Submission Set	Zero elements when no submission set concept in community
FindFolders	Folder	Zero elements when no folder concept in community
GetAll	Submission Set, Folder, Association	Return all appropriate document entries and other entries depending on which of the other concepts the community supports
GetDocuments	None	Required by all
GetFolders	Folder	Zero elements when no folder concept in community
GetAssociations	Association	Zero elements when no association concept in community
GetDocumentsAndAssociations	Association	Return only document entries if no association concept
GetSubmissionSets	Submission Set	Zero elements when no submission set concept in community
GetSubmissionSetAndContents	Submission Set	Zero elements when no submission set concept in community
GetFolderAndContents	Folder	Zero elements when no folder concept in community
GetFoldersForDocument	Folder	Zero elements when no folder concept in community
GetRelatedDocuments	Association	Zero elements when no association concept in community

3.38.4.1.3 Expected Actions

Actors supporting this transaction shall support the Expected Actions described in ITI TF-2: 3.18.4.1.3 .

In addition, the Responding Gateway shall:

Return an XDSUnknownCommunity error code if the value of the $homeCommunityId parameter is specified and is not known by the Responding Gateway.
Verify the $homeCommunityId parameter is specified on relevant queries and return an XDSMissingHomeCommunityId error code if missing.
If the Responding Gateway supports the Target Communities option and both the $targetCommunityIdList parameter and AdhocQuery home attribute are populated, return an XDSRegistryError.
If the Responding Gateway supports the Target Communities option and the $targetCommunityIdList parameter is specified, then return an XDSUnknownCommunity error code for each value which is not known by the Responding Gateway. Note that the Responding Gateway MAY continue to process the query if any values are those of communities that are known.
If the AdhocQuery home attribute is populated on a query for which the $homeCommunityId parameter is not defined per ITI-2 3.18.4.1.2.3.7, then the Responding Gateway may ignore the value, or it may only query the community specified by that homeCommunityId.
Route the query to local XDS Document Registries or perform equivalent action to form a query response for communities that are in scope according to the query parameters. When routing to a local XDS Document Registry, the Responding Gateway shall pass all parameters into the Registry Stored Query [ITI-18] transaction except the $targetCommunityIdList parameter, which it may omit.
If configured to forward on to other Responding Gateways and those Responding Gateways serve communities that are in scope based on the query parameters, then route the query to those Responding Gateways. When routing to a remote Responding Gateway, the Responding Gateway shall pass all parameters into the Cross Gateway Query [ITI-38] transaction including the $targetCommunityIdList parameter.
When routing a response from a local XDS Document Registry, the Responding Gateway shall pass all entities received in the Registry Stored Query response into the response to the Cross Gateway Query.
Ensure that the response contains a value identifying one of the Responding Gateway's communities for the homeCommunityId attribute in every appropriate element. The elements that shall include the ebRIM home attribute are:

If returnType='LeafClass' the ExtrinsicObject and RegistryPackage elements shall contain the home attribute.
If returnType='ObjectRef' the ObjectRef element shall contain the home attribute.
Ensure that every RegistryError element returned in the response shall have the location attribute set to one of the homeCommunityIds of the Responding Gateway.

If the Delayed Document Assembly Option is supported and a document's assembly is being delayed until the document is retrieved, return the following values of hash and size to indicate this:

size = 0 (zero)
hash = da39a3ee5e6b4b0d3255bfef95601890afd80709 (SHA1 hash of a zero length file)
creationTime = should be the time that the information to be included in the document content was produced

The Initiating Gateway shall:

On receiving the response from the Responding Gateway, verify the homeCommunityId is present where appropriate. If homeCommunityId is not present in any of the ExtrinsicObject, RegistryPackage or ObjectRef elements the Initiating Gateway shall reflect an XDSMissingHomeCommunityId to the initiator of the transaction - either the Document Consumer or the internal actor. All XDSMissingHomeCommunityId errors generated by the Initiating Gateway shall include, in the context of the message, identification of the Responding Gateway that returned the invalid response and the element or elements that were in error.
If the XDS Affinity Domain Option is supported and if needed, consolidate results from multiple Responding Gateways. This includes reflecting in the consolidated results returned in response to the originating Registry Stored Query [ITI-18] all successes and failures received from Responding Gateways. If both successes and failures are received from Responding Gateways, the Initiating Gateway shall return both RegistryObjectList and RegistryErrorList in one response and specify PartialSuccess status. If an XDSUnknownPatientId error is returned from a Responding Gateway then the Initiating Gateway shall not include this error in the consolidated results sent to the Document Consumer. The removal of the XDSUnknownPatientId is done to maintain compatibility with the XDS Profile's use of Registry Stored Query since Document Consumers are not expecting to receive this error. Other than removal of the XDSUnknownPatientId, the Initiating Gateway shall pass all entities received in the Cross Gateway Query response into the response to the Registry Stored Query [ITI-18].
If the Delayed Document Assembly Option is supported, accept the following values of hash and size to indicate that the assembly of the document content has been delayed until the document is retrieved:

size = 0 (zero)
hash = da39a3ee5e6b4b0d3255bfef95601890afd80709 (SHA1 hash of a zero length file)

3.38.4.1.3.1 Compatibility of Options

Compatibility of Options supported by Actors are defined as follows:

The presence or absence of the optional $XDSDocumentEntryType parameter triggers the behaviors on the Responding Gateway. If this value is specified, and the Responding Gateway (or XDS community supported by the Responding Gateway) does not support it, it shall be ignored. If it is specified, and the Responding Gateway (or underlying XDS community) does support it, the proper information is returned. See ITI TF-2: 3.18.4.1.2.5 for more details regarding compatibility of the Registry Stored Query transaction.
The presence or absence of the optional “$targetCommunityIdList” parameter triggers the behaviors on the Responding Gateway. If this value is specified, and the Responding Gateway does not support it, it will be ignored. If it is specified, and the Responding Gateway does support it, it shall accept the query and direct the request to the communities specified in the “$targetCommunityIdList” that it supports. See ITI TF-2: 3.18.4.1.2.5 for more details regarding compatibility of the Registry Stored Query transaction.

3.38.4.1.3.2 Assigning homeCommunityID to Responding Gateway

As described in ITI TF-2: 3.18.4.1.2.3.8 , the homeCommunityId is used to identify a community. Initiating Gateways and Responding Gateways use this value to route requests, normally through lookup in a directory. As an identifier of a community, the homeCommunityId is a larger concept than a single Responding Gateway, which may represent one or more communities. In fact, a community may be represented by several Responding Gateways and a Responding Gateway may represent many communities. Thus, the relationship between Responding Gateways and homeCommunityIds is a multiple to multiple relationship. But the following rules do apply:

An Initiating Gateway may route query and retrieve requests either by looking up the homeCommunityId in a directory or by sending the request to the Responding Gateway from which it received the homeCommunityId. If the Initiating Gateway looks up the homeCommunityId in a directory, the Responding Gateway that it finds may not be the Responding Gateway that returned the value.
The Responding Gateway shall accept and properly route all query and retrieve requests containing any homeCommunityId that it returned in a prior query response.
If the deployment requires that the Initiating Gateway and Responding Gateway use a common directory, then all homeCommunityIds returned by a Responding Gateway should be available for lookup in the common directory. If a community is represented by more than one Responding Gateway, the directory may map the homeCommunityId to one or more of the associated Responding Gateways.

3.38.4.1.4 Security Considerations

Both the Initiating Gateway and Responding Gateway shall audit the Cross Gateway Query. The audit entries shall be equivalent to the entries required for the Registry Stored Query.

The Initiating Gateway:

If receiving a Registry Stored Query transaction from a Document Consumer, shall audit as if it were a Document Registry. See ITI TF-2: 3.18.5.1.2 .
In addition, shall audit the Cross Gateway Query as if it were a Document Consumer except that for EventTypeCode the Initiating Gateway shall specify EV(“ITI-38”, “IHE Transactions”, and “Cross Gateway Query”) (see ITI TF-2: 3.18.5.1.1 ).
In addition, if interacting with a local Document Registry, shall audit as if it were a Document Consumer (see ITI TF-2: 3.18.5.1.1 ).

The Responding Gateway:

Shall audit the Cross Gateway Query as if it were a Document Registry except that for EventTypeCode the Responding Gateway shall specify EV(“ITI-38”, “IHE Transactions”, “Cross Gateway Query”). See ITI TF-2: 3.18.5.1.2 .
In addition, if interacting with a local Document Registry, shall audit as if it were a Document Consumer. See ITI TF-2: 3.18.5.1.1 .

3.38.5 Protocol Requirements

The Cross Gateway Query request and response will be transmitted using Synchronous or WS-Addressing based Asynchronous Web Services Exchange, according to the requirements specified in ITI TF-2: Appendix V.3. The protocol requirements are identical to the Registry Stored Query except as noted below.

XML namespace prefixes are for informational purposes only and are documented in ITI TF-2: Appendix V , Table V.2.4-1.

Responding Gateway: These are the requirements for the Cross Gateway Query transaction presented in the order in which they would appear in the Responding Gateway WSDL definition:

The following types shall be imported (xsd:import) in the /definitions/types section:

namespace=" urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0", schemaLocation="query.xsd"

The /definitions/message/part/@element attribute of the Cross Gateway Query Request message shall be defined as “query:AdhocQueryRequest”

The /definitions/message/part/@element attribute of the Cross Gateway Query Response message shall be defined as “query:AdhocQueryResponse”
Refer to Table 3.38.5-2 below for additional attribute requirements

Table 3.38.5-2: Additional Attribute Requirements

Attribute	Value
/definitions/portType/operation@name	RespondingGateway_CrossGatewayQuery
/definitions/portType/operation/input/@wsaw:Action	urn:ihe:iti:2007:CrossGatewayQuery
/definitions/portType/operation/output/@wsaw:Action	urn:ihe:iti:2007:CrossGatewayQueryResponse
/definitions/binding/operation/wsoap12:operation/@soapActionRequired	false

These are the requirements that affect the wire format of the SOAP message. The other WSDL properties are only used within the WSDL definition and do not affect interoperability. Full sample request and response messages are in Section 3.38.5.1 Sample SOAP Messages .

For informative WSDL for the Responding Gateway see ITI TF-2: Appendix W .

3.38.5.1 Sample SOAP Messages

The samples in the following two sections show a typical SOAP request and its relative SOAP response. The sample messages also show the WS-Addressing headers <Action/>, <MessageID/>, <ReplyTo/>…; these WS-Addressing headers are populated according to the W3C WS-Addressing standard. The body of the SOAP message is omitted for brevity; in a real scenario the empty element will be populated with the appropriate metadata.

Samples presented in this section are also available online: see ITI TF-2: Appendix W .

3.38.5.1.1 Sample Cross Gateway Query SOAP Request

3.38.5.1.1.1 Synchronous Web Services Exchange


      <s:Envelope
      xmlns:s="http://www.w3.org/2003/05/soap-envelope"
      xmlns:a="http://www.w3.org/2005/08/addressing">
          <s:Header>
              <a:Actions:mustUnderstand="1">urn:ihe:iti:2007:CrossGatewayQuery</a:Action>
              <a:MessageID>urn:uuid:def119ad-dc13-49c1-a3c7-e3742531f9b3</a:MessageID>
              <a:ReplyTo>
                  <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
              </a:ReplyTo>
              <a:To s:mustUnderstand="1">http://localhost/service/IHEXCARespondingGateway.svc</a:To>
          </s:Header>
          <s:Body>
              <query:AdhocQueryRequest xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0"/>
          </s:Body>
      </s:Envelope>

3.38.5.1.1.2 Asynchronous Web Services Exchange


      <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:CrossGatewayQuery</a:Action>
              <a:MessageID>urn:uuid:def119ad-dc13-49c1-a3c7-e3742531f9b3</a:MessageID>
              <a:ReplyTo>
                  <a:Address>http://192.168.2.4:9080/XcaService/InitiatingGatewayReceiver.svc</a:Address>
              </a:ReplyTo>
              <a:To s:mustUnderstand="1">http://localhost/XcaService/RespondingGatewayReceiver.svc</a:To>
           </s:Header>
           <s:Body>
              <query:AdhocQueryRequest xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0"/>
          </s:Body>
      </s:Envelope>

3.38.5.1.2 Sample Cross Gateway Query SOAP Response

3.38.5.1.2.1 Synchronous Web Services Exchange


      <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:CrossGatewayQueryResponse</a:Action>
              <a:RelatesTo>urn:uuid:def119ad-dc13-49c1-a3c7-e3742531f9b3</a:RelatesTo>
          </s:Header>
          <s:Body>
              <query:AdhocQueryResponse xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0"/>
          </s:Body>
      </s:Envelope>

3.38.5.1.2.2 Asynchronous Web Services Exchange


      <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:CrossGatewayQueryResponse</a:Action>
              <a:MessageID>urn:uuid:D6C21225-8E7B-454E-9750-821622C099DB</a:MessageID>
              <a:RelatesTo>urn:uuid:def119ad-dc13-49c1-a3c7-e3742531f9b3</a:RelatesTo>
              <a:To s:mustUnderstand="1">http://localhost:2647/XcaService/InitiatingGatewayReceiver.svc</a:To>
      </s:Header>
          <s:Body>
              <query:AdhocQueryResponse xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0"/>
          </s:Body>
      </s:Envelope>