IHE ITI TF Vol2

3.39 Cross Gateway Retrieve [ITI-39]

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

3.39.1 Scope

The scope of the Cross Gateway Retrieve transaction is semantically the same as the Retrieve Document Set [ITI-43] transaction. Differences from the Retrieve Document Set transactions are:

The Cross Gateway Retrieve is between an Initiating Gateway and a Responding Gateway.
The ‘homeCommunityId’ parameter is required. This means that the homeCommunityId parameter which is optional on the Retrieve Document Set transaction is required by this transaction.
Responding Gateways shall support the Asynchronous Web Services Exchange Option on the Cross Gateway Retrieve. 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 .

3.39.2 Use Case Roles

Actor: Initiating Gateway

Role: To formulate a Cross Gateway Retrieve in response to Retrieve Document Set transactions or other internal interaction.

Actor: Responding Gateway

Role: To return the documents requested.

3.39.3 Referenced Standard

Implementors 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
MTOM	SOAP Message Transmission Optimization Mechanism http://www.w3.org/TR/soap12-mtom/

3.39.4 Messages

Figure 3.39.4-1: Interaction Diagram

3.39.4.1 Cross Gateway Retrieve Request

The Cross Gateway Retrieve Request uses the same syntax and standards as the Retrieve Document Set Request. See Section ITI TF-2: 3.43.4.1 .

3.39.4.1.1 Trigger Events

This message is initiated by the Initiating Gateway to retrieve a set of documents from another community represented by a Responding Gateway. The Initiating Gateway may be responding to a Retrieve Document Set transaction or may use a proprietary mechanism for triggering the Cross Gateway Retrieve.

3.39.4.1.2 Message Semantics

The message semantics for Cross Gateway Retrieve are the same as Retrieve Document Set (s Section 3.43.4.1.2). The Initiating Gateway shall specify the homeCommunityId parameter within the Retrieve Document Set. The homeCommunityId shall contain the value that identifies the community associated with the Responding Gateway.

Initiating Gateways which support the On-Demand Documents Option shall be capable of retrieving 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 retrieval 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. Responding Gateways which support the Persistence of Retrieved Documents Option shall specify the NewRepositoryUniqueId element indicating the document is available for later retrieval and be able to return exactly the same document in all future retrieve requests for the document identified by NewDocumentUniqueId.

3.39.4.1.3 Expected Actions

Actors supporting this transaction shall support the Expected Actions described in the Section 3.43.4.1.3.

The Responding Gateway shall determine the local system or systems which hold the documents requested and interact with those systems. The Responding Gateway may use a Retrieve Document Set transaction or other internally defined interaction, to retrieve the document or documents. If more than one system is contacted the Responding Gateway shall consolidate the results from the multiple systems into one response to the Initiating Gateway. If both successes and failures are received the Responding Gateway may choose to use PartialSuccess status to reflect both failure and success. The Responding Gateway may alternatively choose to suppress the failures and report only successes.

If the Responding Gateway returns any Registry Error elements, the Responding Gateway shall include in the location attribute all the requirements stated in Section 3.43 plus the homeCommunityId of the Responding Gateway.

If the XDS Affinity Domain Option is supported, the Initiating Gateway shall, if needed, consolidate results from multiple Responding Gateways. This includes reflecting in the consolidated results returned to the originating Retrieve Document Set [ITI-43] all successes and failures received from Responding Gateways. If both successes and failures are received from Responding Gateways, the Initiating Gateway shall return both DocumentResponse and RegistryErrorList elements in one response and specify PartialSuccess status.

3.39.4.1.3.1 Compatibility of Options

If the Initiating Gateway does not support the On-Demand Document Option, it will never send a Cross Gateway Retrieve request for an On-Demand Document. In this case, none of the attributes specific to On-Demand Documents will be included in the response.

If the Initiating Gateway does support the On-Demand Document Option, it will only direct Cross Gateway Retrieve requests for On-Demand Documents to responders which have returned an On-Demand Document Entry in a Cross Gateway Query response. Thus there are no compatibility concerns with this transaction.

3.39.4.1.3.2 Delayed Document Assembly Options

If a Responding Gateway supports the Delayed Document Assembly Option and the Stable Document Entry being retrieved currently has:

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

then the Responding Gateway shall:

Assemble the content into a complete document.
Return the assembled document in response to the Cross Gateway Retrieve Request.
Save the assembled document for future retrievals since all future retrievals shall return the identical content.
Calculate and save the size and hash values of the assembled document and return these if this Stable Document Entry is included in any subsequent Cross Gateway Query Responses.

and the Responding Gateway should save the current time and return this as the creationTime if this Stable Document Entry is included in any subsequent Cross Gateway Query Responses.

3.39.4.2 Cross Gateway Retrieve Response

3.39.4.2.1 Trigger Events

This message will be triggered by a Cross Gateway Retrieve Message.

3.39.4.2.2 Message Semantics

The message semantics for Cross Gateway Retrieve are the same as Retrieve Document Set. See Section 3.43.4.2.2.

3.39.4.2.3 Expected Actions

Actors supporting this transaction shall support the Expected Actions described in Section 3.43.4.2.3.

3.39.5 Protocol Requirements

The Cross Gateway Retrieve 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 Retrieve Document Set 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 Retrieve 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:ihe:iti:xds-b:2007", schema="IHEXDS.xsd"

The /definitions/message/part/@element attribute of the Cross Gateway Retrieve Request message shall be defined as “ ihe:RetrieveDocumentSetRequest ”
The /definitions/message/part/@element attribute of the Cross Gateway Retrieve Response message shall be defined as “ ihe:RetrieveDocumentSet Response”

Refer to Table 3.39.5-2 below for additional attribute requirements

Table 3.39.5-2: Requirements for portType and Binding attributes

Attribute	Value
/definitions/portType/operation@name	RespondingGateway_CrossGatewayRetrieve
/definitions/portType/operation/input/@wsaw:Action	urn:ihe:iti:2007:CrossGatewayRetrieve
/definitions/portType/operation/output/@wsaw:Action	urn:ihe:iti:2007:CrossGatewayRetrieveResponse
/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.43.5.1 Sample SOAP Messages.

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

The <ihe:RetrieveDocumentSetRequest/> element is defined in Section 3.43.5. When used within the Cross Gateway Retrieve the <ihe:HomeCommunityId/> element is required.

The <ihe:RetrieveDocumentSetResponse/> element is defined in Section 3.43.5.

3.39.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.39.5.1.1 Sample Cross Gateway Retrieve SOAP Request

3.39.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:Action s:mustUnderstand="1">urn:ihe:iti:2007: CrossGatewayRetrieve </a:Action>

<a:MessageID>urn:uuid:0fbfdced-6c01-4d09-a110-2201afedaa02</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:2647/XcaService/IHEXCAGateway.svc</a:To>

</s:Header>

<s:Body>

</DocumentRequest>

</DocumentRequest>

</RetrieveDocumentSetRequest>

</s:Body>

</s:Envelope>

3.39.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: CrossGatewayRetrieve </a:Action>

<a:MessageID>urn:uuid:0fbfdced-6c01-4d09-a110-2201afedaa02</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:2647/XcaService/RespondingGatewayReceiver.svc</a:To>

</s:Header>

<s:Body>

</DocumentRequest>

</DocumentRequest>

</RetrieveDocumentSetRequest>

</s:Body>

</s:Envelope>

3.39.5.1.2 Sample Cross Gateway Retrieve SOAP Response

3.39.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:CrossGatewayRetrieveResponse </a:Action>

<a:RelatesTo>urn:uuid:0fbfdced-6c01-4d09-a110-2201afedaa02</a:RelatesTo>

</s:Header>

<s:Body>

<RetrieveDocumentSetResponse

xmlns="urn:ihe:iti:xds-b:2007"

xmlns:lcm="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:3.0"

xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0"

xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0"

xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0">

<rs:RegistryResponse status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"/>

<Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

</DocumentResponse>

<Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

</DocumentResponse>

</RetrieveDocumentSetResponse>

</s:Body>

</s:Envelope>

3.39.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:CrossGatewayRetrieveResponse </a:Action>

<a:MessageID>urn:uuid:D6C21225-8E7B-454E-9750-821622C099DB</ a :MessageID>

<a:RelatesTo>urn:uuid:0fbfdced-6c01-4d09-a110-2201afedaa02</a:RelatesTo>

<a:To s:mustUnderstand="1">http://localhost:2647/XcaService/InitiatingGatewayReceiver.svc</a:To>

</s:Header>

<s:Body>

<RetrieveDocumentSetResponse

xmlns="urn:ihe:iti:xds-b:2007"

xmlns:lcm="urn:oasis:names:tc:ebxml-regrep:xsd:lcm:3.0"

xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0"

xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0"

xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0">

<rs:RegistryResponse status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"/>

<Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

</DocumentResponse>

<Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

</DocumentResponse>

</RetrieveDocumentSetResponse>

</s:Body>

</s:Envelope>

3.39.6 Security Considerations

Both the Initiating Gateway and Responding Gateway shall audit the Cross Gateway Retrieve. The audit entries shall be equivalent to the entries required for the Retrieve Document Set.

The Initiating Gateway:

If receiving a Retrieve Document Set transaction from a Document Consumer, shall audit as if it were a Document Repository (see Section 3.43.6).
In addition, shall audit the Cross Gateway Retrieve as if it were a Document Consumer except that for EventTypeCode the Initiating Gateway shall specify EV(“ITI-39”, “IHE Transactions”, and “Cross Gateway Retrieve”) (see Section 3.43.6).
In addition, if interacting with a local Document Repository, shall audit as if it were a Document Consumer (see Section 3.43.6). One audit record shall be created for each Document Repository contacted.

The Responding Gateway:

Shall audit the Cross Gateway Retrieve as if it were a Document Repository except that for EventTypeCode the Responding Gateway shall specify EV(“ITI-39”, “IHE Transactions”, “Cross Gateway Retrieve”) (see Section 3.43.6).
In addition, if interacting with a local Document Repository, shall audit as if it were a Document Consumer (see Section 3.43.6). One audit record shall be created for each Document Repository contacted.