IHE ITI Technical Framework
The Final Text ITI Technical Framework is published here in HTML format and is no longer published as PDF. Trial Implementation supplements are available from the Volume 1 Table of Contents.

3.43Retrieve Document Set [ITI-43]

This section corresponds to transaction [ITI-43] of the IHE Technical Framework. The Document Consumer, Document Repository, On-Demand Document Source, and Initiating Gateway Actors use transaction [ITI-43].

 

Integration Profiles using this Transaction
Cross-Enterprise Document Sharing-b (XDS.b)
Cross-Community Access (XCA)

 

Actors that support the Asynchronous Web Services Exchange Option shall support Asynchronous Web Services Exchange on all XDS.b transactions they implement. Refer to Section ITI TF-2 x: V. 3 Synchronous and Asynchronous (WS-Addressing based) Web Services Exchange for an explanation of Asynchronous Web Services Exchange.

3.43.1 Scope

This transaction is used by the Document Consumer to retrieve a set of documents from the Document Repository, On-Demand Document Source, or Initiating Gateway. The Document Consumer has already obtained the XDSDocumentEntry uniqueId and the Document Repository repositoryUniqueId from the Document Registry/Initiating Gateway by means of the Registry Stored Query transaction.

3.43.2 Use Case Roles

 

Actor: Document Consumer

Role: Obtains document.

Actor: Document Repository or Integrated Document Source/Repository

Role: Provides documents.

Actor : Initiating Gateway

Role : An Initiating Gateway which implements the XDS Affinity Domain Option retrieves a set of documents by using the Cross Gateway Retrieve transaction and/or a Retrieve Document Set transaction.

Actor :   On-Demand Document Source

Role :   Creates documents in response to a request for retrieval of an on-demand document entry.

Note: Within this transaction, the Document Repository and Integrated Document Source/Repository Actors can be used interchangeably.

3.43.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 in Document Sharing profiles
MTOM

SOAP Message Transmission Optimization Mechanism http://www.w3.org/TR/soap12-mtom/

XOP XML-binary Optimized Packaging http://www.w3.org/TR/2005/REC-xop10-20050125/

3.43.4 Messages

Figure 3.43.4-1: Interaction Diagram

3.43.4.1 Retrieve Document Set Request

3.43.4.1.1Trigger Events

The Document Consumer obtains document(s) uniqueId via the Registry Stored Query transaction. If the Registry Stored Query was sent to the Initiating Gateway the Document Consumer shall address the Retrieve Document Set to the Initiating Gateway. In this case no resolution of repositoryUniqueId is needed by the Document Consumer. The Document Consumer shall specify the homeCommunityId element in the Retrieve Document Set transaction if it was found in the entry containing the uniqueId of the document being retrieved. For more information regarding the homeCommunityId, see Section 3.38.4.1.2.

Once the document(s) uniqueId have been obtained, the Document Consumer will start the Retrieve Document Set Request with the Document Repository.

3.43.4.1.2 Message Semantics

The Retrieve Document Set Request shall carry the following information:

  • A required repositoryUniqueId that identifies the repository from which the document is to be retrieved. This value corresponds to XDSDocumentEntry.repositoryUniqueId.
  • A required documentUniqueId that identifies the document within the repository. This value corresponds to the XDSDocumentEntry.uniqueId.
  • If available, the homeCommunityId element that identifies the community holding the document. The homeCommunityId element shall be specified if the XDSDocumentEntry containing the uniqueId of the document contains the homeCommunityId attribute. See ITI TF-2: 3.18.4.1.2 for details.

The repositoryUniqueId associated to each document requested can be different therefore allowing a single request to identify multiple repositories.

3.43.4.1.3 Expected Actions

When receiving a Retrieve Document Set Request, a Document Repository or an Initiating Gateway shall generate a Retrieve Document Set Response containing the requested documents or error codes if the documents could not be retrieved.

An XCA Initiating Gateway receiving the Retrieve Document Set Request shall use the homeCommunityId to obtain the Web Services endpoint of the Responding Gateways or, in the case where homeCommunityId identifies the local community, use the repositoryUniqueId to obtain the Web Services endpoint of the Document Repositories. The process of obtaining the Web Services endpoint is not further specified in this transaction. The Initiating Gateway shall send Cross Gateway Retrieves/Retrieve Document Set transactions to each appropriate Responding Gateway/Document Repository, consolidate the results, and return them to the Document Consumer.

3.43.4.1.3.1 Basic Patient Privacy Enforcement Option

If the Basic Patient Privacy Enforcement Option is implemented:

  • The Document Consumer shall abide by the XDS Affinity Domain Policies represented by the confidentialityCode in the metadata associated with the document. The Document Consumer likely will have user access controls or business rule capabilities to determine the details of how confidentiality codes apply to query results. The details of this are product specific and not specified by IHE. These rules shall reduce the query results to only those that are appropriate to the current situation for that actor and user.
  • The Document Consumer shall be able to be configured with Patient Privacy Policies, Patient Privacy Policy Identifiers (OIDs) and associated information necessary to understand and enforce the XDS Affinity Domain Policy. The details of this are product specific and not specified by IHE.
3.43.4.1.3.2 Delayed Document Assembly Option

If an Integrated Document Source/Repository supports the Delayed Document Assembly Option and has registered the document being retrieved with

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

then it shall:

  • Assemble into a complete document the content identified at the time the Integrated Document Source/Repository registered the associated Stable Document Entry in the Document Registry.
  • Return the assembled document in response to the Retrieve Document Set Request
  • Save the assembled document for future retrievals since all future retrievals shall return the identical content.
  • Update the Stable Document Entry in the Document Registry with the size and hash values consistent with the assembled document. This update shall be accomplished by grouping with the Document Administrator in the XDS.b Profile and using the Update Document Set [ITI-57] transaction.

3.43.4.2 Retrieve Document Set Response

3.43.4.2.1 Trigger Events

This message will be triggered by a Retrieve Document Set Request Message

3.43.4.2.2 Message Semantics

The Retrieve Document Set Response Message shall carry the following information, for each of the returned documents:

  • A homeCommunityId. This value shall be the same as the homeCommunityId value in the Retrieve Document Set Request Message. If the homeCommunityId value is not present in the Retrieve Document Set Request Message, this shall not be present.
  • A required repositoryUniqueId that identifies the repository from which the document is to be retrieved. This value shall be the same as the value of the repositoryUniqueId in the original Retrieve Document Set Request Message. This value corresponds to XDSDocumentEntry.repositoryUniqueId.
  • A required documentUniqueId that identifies the document within the repository. This value shall be the same as the documentUniqueId in the original Retrieve Document Set Request Message. This value corresponds to the XDSDocumentEntry.uniqueId.
  • The retrieved document as a XOP Infoset
  • The MIME type of the retrieved document
  • Errors or warnings in case the document(s) could not be retrieved successfully

If the documentUniqueId is associated with an On-Demand Document Entry, the Retrieve Document Set Response Message shall contain a NewDocumentUniqueId element that identifies the document that is returned in the Retrieve Document Set Response. This identifier shall be different than the DocumentUniqueId element which identifies the On-Demand Document Entry. The Retrieve Document Set Response Message may also include a NewRepositoryUniqueId element that identifies the Document Repository which holds the document returned in the Retrieve Document Set Response. If this element is not included, the document returned in the response has not been persisted for later retrieval. If the On-Demand Document Source implements the Persistence of Retrieved Documents Option, this element shall be specified. If a future Retrieve Document Set Message for the same DocumentUniqueId returns the same NewDocumentUniqueId, the content of the document shall be identical to the prior returned content. On-Demand Document Source Actors are encouraged to re-use Document uniqueId’s whenever content has not changed in order to facilitate identification of new content by Document Consumers.

3.43.4.2.3 Expected Actions

A Document Repository or On-Demand Document Source shall return the document(s) indicated in the request.

The Document Repository shall return the document or an error code in case the document could not be return. The conditions of failure and possible error messages are given in the ebRS standard and detailed in ITI TF-3: 4.2.4 Error Reporting.

An On-Demand Document Source which supports the Persistence of Retrieved Documents Option shall save the document content returned in the retrieve response and issue a Register Document Set-b [ITI-42] transaction to register a Stable Document Entry which describes the saved document. The On-Demand Document Source shall complete the registration of the Stable Document Entry prior to responding to the Retrieve Document Set request. The registration of the new Stable Document Entry shall include:

  • A Submission Set
  • A DocumentEntry representing the Stable DocumentEntry.
  • A HasMember association linking DocumentEntry to SubmissionSet.
  • An IsSnapshotOf Association which identifies the sourceObject as the new Stable Document Entry and the targetObject as the On-Demand Document Entry which contains the uniqueID used in the Retrieve Document Set request. See ITI TF-3: 4.2.2.2 for information about the IsSnapshotOf Association.

If the On-Demand Document Source has previously registered a snapshot of the On-Demand DocumentEntry, the registration of the new Stable DocumentEntry may also include a RPLC association, identifying the new Stable DocumentEntry as a replacement of the previously-registered Stable DocumentEntry.

If this is not the first request for this on-demand document and a prior document was replaced, a Replace Association which identifies the prior document.

3.43.4.2.3.1 Compatibility of Options

If the Document Consumer does not support the On-Demand Documents Option it will never send a Retrieve Document Set request for an On-Demand Document entry. In this case, none of the new attributes will be included in the response.

If the Document Consumer does support the On-Demand Documents Option, it will only direct requests for On-Demand Document Entries to responders which have specified their unique repositoryUniqueId in the On-Demand Document Entry from the registry. Thus, unless there is an error in the metadata, there are no compatibility concerns with this transaction.

3.43.4.2.3.2 Delayed Document Assembly Option

If a Document Consumer supports the Delayed Document Assembly Option, it shall not use the size=0 and hash=SHA1 hash of a zero length file values to verify documents. If verification is desired the Document Consumer shall use an appropriate stored query from the Registry Stored Query [ITI-18] transaction to get the updated size and hash values.

3.43.5 Protocol Requirements

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

The Retrieve Document Set transaction shall use SOAP12 and MTOM with XOP encoding (labeled MTOM/XOP in this specification). See ITI TF-2: Appendix V.8 for details.

The Document Repository shall:

  • Accept the Retrieve Document Set Request message in MTOM/XOP format.
  • Generate the Retrieve Document Set Response message in MTOM/XOP format

The Document Consumer shall:

  • Generate the Retrieve Document Set Request message in MTOM/XOP format.
  • Accept the Retrieve Document Set Response message in MTOM/XOP format.

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

Document Repository: These are the requirements for the Retrieve Document Set transaction presented in the order in which they would appear in the Document Repository 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 Retrieve Document Set Request message shall be defined as “ ihe:RetrieveDocumentSetRequest
  • The /definitions/message/part/@element attribute of the Retrieve Document Set Response message shall be defined as “ ihe:RetrieveDocumentSet Response”
  • Refer to Table 3.43.5.b below for additional attribute requirements

To support the WS-Addressing Asynchronous Web Services Exchange Option on the Document Consumer, the Document Repository shall support the use of a non-anonymous response EPR in the WS-Addressing replyTo header.

Table 3.43.5.b: Additional Attribute Requirements

Attribute Value
/definitions/portType/operation@name DocumentConsumer_RetrieveDocumentSet
/definitions/portType/operation/input/@wsaw:Action urn:ihe:iti:2007:RetrieveDocumentSet
/definitions/portType/operation/output/@wsaw:Action urn:ihe:iti:2007:RetrieveDocumentSetResponse
/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.

An informative WSDL for the Document Repository is available online: see ITI TF-2: Appendix W.

The <ihe:RetrieveDocumentSetRequest/> element is defined as:

  • One or more <ihe:DocumentRequest/> elements, each one representing an individual document that the Document Consumer wants to retrieve from the Document Repository. Each <ihe:DocumentRequest/> element contains:
  • A required <ihe:RepositoryUniqueId/> element that identifies the repository from which the document is to be retrieved. This value corresponds to XDSDocumentEntry.repositoryUniqueId.
  • A required <ihe:DocumentUniqueId/> that identifies the document within the repository. This value corresponds to the XDSDocumentEntry.uniqueId.
  • An optional <ihe:HomeCommunityId/> element that corresponds to the home attribute of the Identifiable class in ebRIM.

This allows the Document Consumer to specify one or more documents to retrieve from the Document Repository.

The <ihe:RetrieveDocumentResponse/> element is defined as:

  • A required /ihe:RetrieveDocumentSetResponse/rs:RegistryResponse element
  • An optional sequence of <ihe:DocumentResponse/> elements containing
  • A <ihe:HomeCommunityId/> element. The value of this element shall be the same as the value of the /RetrieveDocumentSetRequest/DocumentRequest/HomeCommunityId element in the Retrieve Document Set Request Message. If the <ihe:HomeCommunityId/> element is not present in the Retrieve Document Set Request Message, this value shall not be present.
  • A required <ihe:RepositoryUniqueId/> that identifies the repository from which the document is to be retrieved. The value of this element shall be the same as the value of the /RetrieveDocumentSetRequest/DocumentRequest/RepositoryUniqueId element in the original Retrieve Document Set Request Message. This value corresponds to XDSDocumentEntry.repositoryUniqueId.
  • A required <ihe:DocumentUniqueId/> that identifies the document within the repository. The value of this element shall be the same as the value of the /RetrieveDocumentSetRequest/DocumentRequest/DocumentUniqueId element in the original Retrieve Document Set Request Message. This value corresponds to XDSDocumentEntry.uniqueId.
  • A required <ihe:Document/> element that contains the retrieved document using the xsi:base64Binary data type. (Note: This is the logical representation of the document in the XML. The wire format may be different; see ITI TF-2: Appendix V.8.)
  • A required <ihe:mimeType/> element that indicates the MIME type of the retrieved document
  • An optional <ihe:NewDocumentUniqueId/> element that identifies the document returned in the request when retrieval is of an On-Demand Document. This is required when retrieval is of an On-Demand Document.
  • An optional <ihe:NewRepositoryUniqueId/> element that identifies the Document Repository that will support retrieval of the document created as a result of retrieval of the On-Demand Document. This is required when the On-Demand Document Source supports the Persistence of Retrieved Documents Option.

The /RetrieveDocumentSetResponse/rs:RegistryResponse/@status attributes provides the overall status of the request. It shall contain one of the following values:

urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success
urn:ihe:iti:2007:ResponseStatusType:PartialSuccess
urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure

See ITI TF-3: 4.2.4 Error Reporting for the interpretation of these values.

For each document requested in a /RetrieveDocumentSetRequest/DocumentRequest element:

  • If a warning is reported when retrieving the document, then a /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:
  • @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Warning
  • @errorCode is specified
  • @codeContext contains the warning message
  • @location contains the DocumentUniqueId of the document requested
  • The document shall be returned in an instance of /RetrieveDocumentSetResponse/DocumentResponse/Document as a XOP Infoset. The returned document and warning are correlated via the DocumentUniqueId.
  • If an error is reported when retrieving a document, then a /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:
  • @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error
  • @errorCode is specified
  • @codeContext contains the error message
  • @location contains the DocumentUniqueId of the document requested
  • No corresponding RetrieveDocumentSetResponse/DocumentResponse element shall be returned
  • If the document is successfully retrieved (without warning) then no /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be present and a /RetrieveDocumentSetResponse/DocumentResponse/Document element shall be returned containing the document as a XOP Infoset.

The /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:ResponseSlotList element is not used in this transaction.

The /RetrieveDocumentSetResponse/rs:RegistryResponse/@requestId attribute is not used in this transaction.

A full XML Schema Document for the XDS.b types is available online: see ITI TF-2: Appendix W.

3.43.5.1 Sample SOAP Messages

The samples in the following two sections show a typical request and its relative response. The sample messages also show the WS-Addressing headers <Action/>, <MessageID/>, <ReplyTo/>…; these WS-Addressing headers are populated according to ITI TF-2: Appendix V : Web Services for IHE Transactions.

3.43.5.1.1 Sample Retrieve Document Set SOAP Request
3.43.5.1.1.1 Synchronous Web Services Exchange

POST /tf6/services/xdsrepositoryb HTTP/1.1

Content-Type: multipart/related;

    boundary=MIMEBoundaryurn_uuid_3448B7F8EA6E8B9DFC1289514997517;

    type="application/xop+xml";

    start="<0.urn:uuid:3448B7F8EA6E8B9DFC1289514997518@apache.org>";

    start-info="application/soap+xml"

User-Agent: Axis2

Host: ihexds.nist.gov:5000

--MIMEBoundaryurn_uuid_3448B7F8EA6E8B9DFC1289514997517

Content-Type: application/xop+xml; charset=UTF-8;

    type="application/soap+xml"

Content-Transfer-Encoding: binary

Content-ID: <0.urn:uuid:3448B7F8EA6E8B9DFC1289514997518@apache.org>

<?xml version='1.0' encoding='UTF-8'?>

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">

    <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">

        <wsa:To soapenv:mustUnderstand="1"

            >http://localhost:5000/tf6/services/xdsrepositoryb</wsa:To>

        <wsa:MessageID soapenv:mustUnderstand="1"

            >urn:uuid:3448B7F8EA6E8B9DFC1289514997508</wsa:MessageID>

        <wsa:Action soapenv:mustUnderstand="1"

            >urn:ihe:iti:2007:RetrieveDocumentSet</wsa:Action>

    </soapenv:Header>

    <soapenv:Body>

        <RetrieveDocumentSetRequest xmlns="urn:ihe:iti:xds-b:2007">

            <DocumentRequest>

                <RepositoryUniqueId>1.19.6.24.109.42.1.5</RepositoryUniqueId>

                <DocumentUniqueId>1.42.20101110141555.15</DocumentUniqueId>

            </DocumentRequest>

        </RetrieveDocumentSetRequest>

    </soapenv:Body>

</soapenv:Envelope>

--MIMEBoundaryurn_uuid_3448B7F8EA6E8B9DFC1289514997517--

This request message is in MTOM/XOP format because request/response message pairs must always be in the same format (MTOM/XOP vs. SIMPLE SOAP) and the response requires MTOM/XOP: one part for descriptive metadata and a second part for document contents.             

3.43.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:RetrieveDocumentSet</a:Action>

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

   <a:ReplyTo>

    <a:Address> http://192.168.2.4:9080/XdsService/ DocumentConsumerReceiver.svc </a:Address>

   </a:ReplyTo>

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

  </s:Header>

  <s:Body>

   <RetrieveDocumentSetRequest xmlns="urn:ihe:iti:xds-b:2007">

    <DocumentRequest>

     <RepositoryUniqueId>1.3.6.1.4...1000</RepositoryUniqueId>

     <DocumentUniqueId>1.3.6.1.4...2300</DocumentUniqueId>

    </DocumentRequest>

    <DocumentRequest>

     <RepositoryUniqueId>1.3.6.1.4...1000</RepositoryUniqueId>

     <DocumentUniqueId>1.3.6.1.4...2301</DocumentUniqueId>

    </DocumentRequest>

   </RetrieveDocumentSetRequest>

  </s:Body>

</s:Envelope>

3.43.5.1.2 Sample Retrieve Document Set SOAP Response
3.43.5.1.2.1 Synchronous Web Services Exchange

In the following example, the HTTP header Transfer-Encoding: chunked and the corresponding chunk annotations were removed for readability.

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Content-Type: multipart/related;

    boundary=MIMEBoundaryurn_uuid_E910375860336E2B8F1289514978310;

    type="application/xop+xml";

    start="0.urn:uuid:E910375860336E2B8F1289514978311@apache.org";

    start-info="application/soap+xml";

Date: Thu, 11 Nov 2010 22:36:15 GMT

--MIMEBoundaryurn_uuid_E910375860336E2B8F1289514978310

Content-Type: application/xop+xml; charset=UTF-8;

    type="application/soap+xml"

Content-Transfer-Encoding: binary

Content-ID: <0.urn:uuid:E910375860336E2B8F1289514978311@apache.org>

<?xml version='1.0' encoding='UTF-8'?>

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"

    xmlns:wsa="http://www.w3.org/2005/08/addressing">

    <soapenv:Header>

        <wsa:Action soapenv:mustUnderstand="1"

             >urn:ihe:iti:2007:RetrieveDocumentSetResponse</wsa:Action>

        <wsa:RelatesTo>urn:uuid:3448B7F8EA6E8B9DFC1289514997508</wsa:RelatesTo>

    </soapenv:Header>

    <soapenv:Body>

        <xdsb:RetrieveDocumentSetResponse xmlns:xdsb="urn:ihe:iti:xds-b:2007">

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

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

          <xdsb:DocumentResponse>

                <xdsb:RepositoryUniqueId

                  >1.19.6.24.109.42.1.5</xdsb:RepositoryUniqueId>

                <xdsb:DocumentUniqueId

                  >1.42.20101110141555.15</xdsb:DocumentUniqueId>

                <xdsb:mimeType>text/plain</xdsb:mimeType>

                <xdsb:Document>

                    <xop:Include

                   href="cid:1.urn:uuid:E910375860336E2B8F1289514978312@apache.org"

                        xmlns:xop="http://www.w3.org/2004/08/xop/include"/>

                </xdsb:Document>

          </xdsb:DocumentResponse>

        </xdsb:RetrieveDocumentSetResponse>

    </soapenv:Body>

</soapenv:Envelope>

--MIMEBoundaryurn_uuid_E910375860336E2B8F1289514978310

Content-Type: text/plain

Content-Transfer-Encoding: binary

Content-ID: <1.urn:uuid:E910375860336E2B8F1289514978312@apache.org>

Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.

--MIMEBoundaryurn_uuid_E910375860336E2B8F1289514978310--

This example shows the ‘wire format’ for MTOM/XOP. The Document element contains a <xop:Include> element that points to the document contents as a separate attachment.

Note: In some systems, the ‘in memory’ format replaces the <xop:Include> with the Base64 encoded contents of the document. This is done so the entire message contents fits into an XML parse tree.

A second form of the response is possible, an un-optimized MTOM/XOP message. In this form the message is still formatted as a multipart but the document contents is not split out into a separate part of the multipart. Some popular Web Service toolkits generate this form for very small documents. The same response in this form looks like:

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Content-Type: multipart/related;

    boundary=MIMEBoundaryurn_uuid_E910375860336E2B8F1289514978310;

    type="application/xop+xml";

    start="0.urn:uuid:E910375860336E2B8F1289514978311@apache.org";

    start-info="application/soap+xml";

Date: Thu, 11 Nov 2010 22:36:15 GMT

--MIMEBoundaryurn_uuid_E910375860336E2B8F1289514978310

Content-Type: application/xop+xml; charset=UTF-8;

    type="application/soap+xml"

Content-Transfer-Encoding: binary

Content-ID: <0.urn:uuid:E910375860336E2B8F1289514978311@apache.org>

<?xml version='1.0' encoding='UTF-8'?>

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"

    xmlns:wsa="http://www.w3.org/2005/08/addressing">

    <soapenv:Header>

        <wsa:Action soapenv:mustUnderstand="1"

             >urn:ihe:iti:2007:RetrieveDocumentSetResponse</wsa:Action>

        <wsa:RelatesTo>urn:uuid:3448B7F8EA6E8B9DFC1289514997508</wsa:RelatesTo>

    </soapenv:Header>

    <soapenv:Body>

        <xdsb:RetrieveDocumentSetResponse xmlns:xdsb="urn:ihe:iti:xds-b:2007">

          <rs:RegistryResponse

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

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

          <xdsb:DocumentResponse>

                <xdsb:RepositoryUniqueId

                  >1.19.6.24.109.42.1.5</xdsb:RepositoryUniqueId>

                <xdsb:DocumentUniqueId

                  >1.42.20101110141555.15</xdsb:DocumentUniqueId>

                <xdsb:mimeType>text/plain</xdsb:mimeType>

                <xdsb:Document>

                    Base64 encoded contents of document go here

                </xdsb:Document>

          </xdsb:DocumentResponse>

        </xdsb:RetrieveDocumentSetResponse>

    </soapenv:Body>

</soapenv:Envelope>

--MIMEBoundaryurn_uuid_E910375860336E2B8F1289514978310--

3.43.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:RetrieveDocumentSetResponse</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/XdsService/DocumentConsumerReceiver.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"/>

    <DocumentResponse>

     <RepositoryUniqueId>1.3.6.1.4...1000</RepositoryUniqueId>

     <DocumentUniqueId>1.3.6.1.4...2300</DocumentUniqueId>

     <mimeType>text/xml</mimeType>

     <Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

    </DocumentResponse>

    <DocumentResponse>

     <RepositoryUniqueId>1.3.6.1.4...1000</RepositoryUniqueId>

     <DocumentUniqueId>1.3.6.1.4...2300</DocumentUniqueId>

     <mimeType>text/xml</mimeType>

     <Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

    </DocumentResponse>

   </RetrieveDocumentSetResponse>

  </s:Body>

</s:Envelope>

3.43.5.1.3 Sample Retrieve Document Set Response from On-Demand Document Entry

The following example shows the response to retrieval of a dynamic document entry where the responder supports later retrieval of the document created.

<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:RetrieveDocumentSetResponse</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"/>

      <DocumentResponse>

        <RepositoryUniqueId>1.3.6.1.4...1000</RepositoryUniqueId>

        <DocumentUniqueId>1.3.6.1.4...2300</DocumentUniqueId>

      <NewDocumentUniqueId>1.3.6.1.4...2897</NewDocumentUniqueId>

      <NewRepositoryUniqueId> 1.3.6.1.4...1000 </NewRepositoryUniqueId>

        <mimeType>text/xml</mimeType>

        <Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

      </DocumentResponse>

      <DocumentResponse>

        <RepositoryUniqueId>1.3.6.1.4...1000</RepositoryUniqueId>

        <DocumentUniqueId>1.3.6.1.4...2300</DocumentUniqueId>

        <mimeType>text/xml</mimeType>

        <Document>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</Document>

      </DocumentResponse>

    </RetrieveDocumentSetResponse>

  </s:Body>

</s:Envelope>

3.43.6 Security Considerations

Relevant XDS Affinity Domain Security background is discussed in the XDS Security Considerations Section (see ITI TF-1: 10.7 ).

3.43.6.1 Audit Record Considerations

The Retrieve Document Set transaction is either a PHI-Import event or a PHI-Export event, depending on the actor, as defined in ITI TF-2: Table 3.20.4.1.1.1-1, with the following exceptions.

The Document Repository Actor, On-Demand Document Source, and Initiating Gateway shall generate an “Export” event. This may be an event for each Retrieve Document transaction, or multiple transactions for the same patient may be heuristically combined. The heuristics for this combination are not specified by IHE. It is intended to reduce the volume of audit records. Combination is permitted when the active participants and patient are the same, and the time difference is considered insignificant.

The Document Consumer shall generate an “Import” event. This may be one event per transaction, or multiple transactions may be reported as a single event using a heuristic for combining transactions. Combination is permitted when the active participants and patient are the same, and the time difference is considered insignificant.

If some documents were retrieved successfully and others were not, the actors involved shall record a “success” audit event for those documents retrieved successfully and a “failure” audit event for those documents not retrieved successfully.

3.43.6.1.1 Document Consumer audit message:
Field Name Opt Value Constraints

Event

AuditMessage/
EventIdentification

EventID M EV(110107, DCM, “Import”)
EventActionCode M “C” (Create)
EventDateTime M not specialized
EventOutcomeIndicator M not specialized
EventTypeCode M EV(“ITI-43”, “IHE Transactions”, “Retrieve Document Set”)
Source (Document Repository) (1)
Destination (Document Consumer) (1)
Human Requestor (0..n)
Audit Source (Document Consumer) (1)
Patient (0..1)

Document (1..n) (see combining rules above)

Where:

Source

AuditMessage/
ActiveParticipant

UserID M SOAP endpoint URI
AlternativeUserID U not specialized
UserName U not specialized
UserIsRequestor M “false”
RoleIDCode M EV(110153, DCM, “Source”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Destination

AuditMessage/
ActiveParticipant

UserID M If Asynchronous Web Services Exchange is being used, the content of the <wsa:ReplyTo/> element. Otherwise, not specialized.
AlternativeUserID M the process ID as used within the local operating system in the local system logs.
UserName U not specialized
UserIsRequestor U not specialized
RoleIDCode M EV(110152, DCM, “Destination”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Human Requestor (if known)

AuditMessage/
ActiveParticipant

UserID M Identity of the human that initiated the transaction.
AlternativeUserID U not specialized
UserName U not specialized
UserIsRequestor U not specialized
RoleIDCode U Access Control role(s) the user holds that allows this transaction.
NetworkAccessPointTypeCode U not specialized
NetworkAccessPointID U not specialized

Audit Source

AuditMessage/
AuditSourceIdentification

AuditSourceID U not specialized
AuditEnterpriseSiteID U not specialized
AuditSourceTypeCode U not specialized

Patient

(if-known)

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “1” (Person)
ParticipantObjectTypeCodeRole M “1” (Patient)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M not specialized
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The patient ID in HL7 CX format.
ParticipantObjectName U not specialized
ParticipantObjectQuery U not specialized
ParticipantObjectDetail U not specialized

Document

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “2” (System)
ParticipantObjectTypeCodeRole M “3” (report)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M not specialized
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The value of <ihe:DocumentUniqueId/>
ParticipantObjectName C not specialized
ParticipantObjectQuery U not specialized
ParticipantObjectDetail M

The ParticipantObjectDetail element shall occur at least once.

   type: "Repository Unique ID" (literal string>

   value: the value of <ihe:RepositoryUniqueId/>

If the homeCommunityId is known, another element shall contain:

   type: ihe:homeCommunityID” (literal string)

   value: value of the homeCommunityId

Note: The specification of the ‘type’ element is inconsistent with the ITI-18 audit message, and others. This inconsistency remains because fixing it would be a ‘breaking change’ to this Final Text specification.

3.43.6.1.2 Document Repository, On-Demand Document Source, and Initiating Gateway audit message:
Field Name Opt Value Constraints

Event

AuditMessage/
EventIdentification

EventID M EV(110106, DCM, “Export”)
EventActionCode M “R” (Read)
EventDateTime M not specialized
EventOutcomeIndicator M not specialized
EventTypeCode M EV(“ITI-43”, “IHE Transactions”, “Retrieve Document Set”)
Source (Document Repository) (1)
Destination (Document Consumer) (1)
Audit Source (Document Repository) (1)

Document (1..n) (see combining rules above)

Where:

Source

AuditMessage/
ActiveParticipant

UserID M SOAP endpoint URI
AlternativeUserID M the process ID as used within the local operating system in the local system logs.
UserName U not specialized
UserIsRequestor M “false”
RoleIDCode M EV(110153, DCM, “Source”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Destination

AuditMessage/
ActiveParticipant

UserID M If Asynchronous Web Services Exchange is being used, the content of the <wsa:ReplyTo/> element. Otherwise, not specialized.
AlternativeUserID U not specialized
UserName U not specialized
UserIsRequestor U not specialized
RoleIDCode M EV(110152, DCM, “Destination”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Audit Source

AuditMessage/
AuditSourceIdentification

AuditSourceID U not specialized
AuditEnterpriseSiteID U not specialized
AuditSourceTypeCode U not specialized

Document URI

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “2” (System)
ParticipantObjectTypeCodeRole M “3” (report)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M not specialized
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The value of <ihe:DocumentUniqueId/>
ParticipantObjectName C not specialized
ParticipantObjectQuery U not specialized
ParticipantObjectDetail M

The ParticipantObjectDetail element shall occur at least once.

   type: "Repository Unique ID" (literal string>

   value: the value of <ihe:RepositoryUniqueId/>

If the homeCommunityId is known, another element shall contain:

   type: ihe:homeCommunityID” (literal string)

   value: value of the homeCommunityId

Note: The specification of the ‘type’ element is inconsistent with the ITI-18 audit message, and others. This inconsistency remains because fixing it would be a ‘breaking change’ to this Final Text specification.