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 an optional parameter to Registry Stored Query requests, not requiring a patient id parameter, and Retrieve Document Set requests to indicate which community to direct the request.

The Initiating Gateway shall specify the homeCommunityId parameter within all queries which do not include a patient identifier parameter. These would be queries which specify an entryUUID or uniqueID. The homeCommunityId shall contain the value that identifies the community associated with the Responding Gateway. The homeCommunityId value is specified as the home attribute on the AdhocQuery element of the query request, as in: <AdhocQuery id=”…” home=”urn:oid:1.2.3” … >

Each Cross Gateway Query request can have at most one homeCommunityId value. If multiple entryUUID or uniqueID values are specified they must all be associated with the same homeCommunityId value. Multiple individual query requests can be used to retrieve data associated with different homeCommunityIds.

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 homeCommunityId is specified and is not known by the Responding Gateway.
Verify the homeCommunityId is specified on relevant queries and return an XDSMissingHomeCommunityId error code if missing.
Route the query to the local XDS Document Registry or perform equivalent action to form a query response. When routing to a local XDS Document Registry, the Responding Gateway shall pass all parameters into the Registry Stored Query [ITI-18] transaction.
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

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.

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>