NHIE Specification Outline · NHIN Trial Implementations Retrieve Documents Service Interface Specification v1.6.6 Security and Technology Working Group Page 6 of 19 Through the Query

5 NHIN Trial Implementations Retrieve Documents Service Interface Specification v1.6.6

Security and Technology Working Group Page 1 of 19

Nationwide Health Information Network (NHIN)

Service Interface Specifications

Retrieve Documents

V 1.6.6

01/30/2009



Contributors

Name Organization Area Guther Schadow Indiana Specification Bob Agamalian Specification Asad Khan WVA Specification Chris Voigt CareSpark Specification Ashish Shah Specification Richard Franck NCHICA Specification

Document Change History

Version Date Changed By Items Changed Since Previous Version 0.1 Tony Mallia Created template. 1.0 Guther Schadow Contents – first draft 1.0 Bob Agamalian Updates 1.0 Asad Khan Updates 1.0 Chris Voigt Updates 1.0 Richard Franck Updates 1.0 Ashish Shah Updates 1.6.4 Chris Voigt Inserted split WSDL and added this change history 1.6.5 Chris Voigt Relaxed document hash and size validation. 1.6.6 01/28/2009 David L. Riley Minor edits to prepare for publications

Document Approval

Version Date Approved By Role



Table of Contents 1 PREFACE ............................................................................................................................................................ 4

1.1 INTRODUCTION ............................................................................................................................................... 4 1.2 INTENDED AUDIENCE ..................................................................................................................................... 4 1.3 FOCUS OF THIS SPECIFICATION ....................................................................................................................... 4

1.3.1 Business Needs Supported by this Specification .................................................................................... 4 1.4 RELATED DOCUMENTS ................................................................................................................................... 4 1.5 RELATIONSHIP TO HITSP CONSTRUCTS ......................................................................................................... 5 1.6 RELATIONSHIP TO OTHER NHIN COOPERATIVE SPECIFICATIONS ................................................................... 5 1.7 ENFORCEMENT OF ACCESS CONSENT POLICIES .............................................................................................. 5

2 INTERFACE DESCRIPTION ........................................................................................................................... 5 2.1 DEFINITION..................................................................................................................................................... 5 2.2 TRIGGERS ....................................................................................................................................................... 7 2.3 TRANSACTION STANDARD .............................................................................................................................. 7 2.4 NHIE CORE SERVICES .................................................................................................................................... 7 2.5 TECHNICAL PRE-CONDITIONS ......................................................................................................................... 7 2.6 TECHNICAL POST-CONDITIONS ....................................................................................................................... 8

3 INTERFACE DEFINITION ............................................................................................................................... 8 3.1 MESSAGE SYNTAX ......................................................................................................................................... 8 3.2 LISTING OF BASE STANDARD(S) ...................................................................................................................... 9 3.3 RETRIEVE DOCUMENTS TRANSACTION .......................................................................................................... 9

3.3.1 Document Consumer.............................................................................................................................. 9 3.3.2 Initiating Gateway ................................................................................................................................. 9 3.3.3 Responding Gateway ........................................................................................................................... 10

3.4 CONTENT SEMANTICS................................................................................................................................... 10 3.4.1 Content Metadata Semantics ............................................................................................................... 10

3.5 CONSTRAINTS AND EXTENSIONS .................................................................................................................. 11 3.6 SAMPLE MESSAGES ...................................................................................................................................... 13

3.6.1 Sample Retrieve Document Set SOAP Request:................................................................................... 13 3.6.2 Sample Retrieve Document Set SOAP Response: ................................................................................ 14

4 ERROR HANDLING ........................................................................................................................................ 14 5 AUDITING ......................................................................................................................................................... 15

5.1.1 Listing of base standard(s) .................................................................................................................. 15 6 POTENTIAL FUTURE CONSIDERATIONS ............................................................................................... 17 7 APPENDIX A: WSDL ...................................................................................................................................... 18



1 Preface

1.1 Introduction The NHIN Trial Implementations Service Interface Specifications constitute the core services of an operational Nationwide Health Information Network. They are intended to provide a standard set of service interfaces that enable Nationwide Health Information Exchange (NHIE) to NHIE exchange of interoperable health information. These services provide such functional capabilities as patient look-up, document query and retrieve, notification of consumer preferences, and access to logs for determining who has accessed what records and for what purpose for use. These functional services rest on a foundational set of messaging and security services. The current set of defined core services includes the following:

1. NHIN Trial Implementations Message Platform Service Interface Specification, 2. NHIN Trial Implementations Authorization Framework Service Interface Specification, 3. NHIN Trial Implementations Subject Discovery Service Interface Specification, 4. NHIN Trial Implementations Document Query Service Interface Specification, 5. NHIN Trial Implementations Document Retrieve Service Interface Specification, 6. NHIN Trial Implementations Audit Log Query Service Interface Specification, 7. NHIN Trial Implementations Consumer Preferences Service Interface Specification 8. NHIN Trial Implementations Health Information Event Messaging Service Interface Specification 9. NHIN Trial Implementations NHIE Service Registry Interface Specification 10. NHIN Trial Implementations Authorized Case Follow-Up Service Interface Specification

It is expected that these core services will be implemented together as a suite since the functional level services are dependent on the foundational services. Specifications #1 through #7 were the focus of the August 2008 testing event and September AHIC demonstrations. Specifications #1 through #9 were included in the November testing and demonstrations during the December 2008 NHIN Trial Implementations Forum.

1.2 Intended Audience The primary audience for the NHIN Trial Implementations Service Interface Specifications is the individuals responsible for implementing software solutions that realize these interfaces for a NHIE. After reading this specification, one should have an understanding of the context in which the service interface is meant to be used, the behavior of the interface, the Web Services Description Language (WSDLs) used to define the service, any Extensible Markup Language (XML) schemas used to define the content and what “compliance” means from an implementation testing perspective.

1.3 Focus of this Specification This document presents the NHIN Trial Implementations Retrieve Documents Service Interface Specification. The purpose of this specification is to provide the ability to exchange documents between NHIEs.

1.3.1 Business Needs Supported by this Specification

A core service required of the NHIN Trial Implementations relates to the exchange of health information in the form of documents. Document Retrieve is the third step in the three-step process of retrieving data from another NHIE:

Arbitrate patient identity

Query for Documents

Retrieve Documents

1.4 Related Documents The following documents and standards were referenced during the development of this specification:



• WS Addressing (http://www.w3.org/Submission/ws-addressing/ ) The following specifications are included in the ITI Technical Framework and are foundational for the Cross Gateway Retrieve transaction:

• Complete IHE IT Infrastructure Technical Framework is available at http://www.ihe.net/Technical_Framework/index.cfm#IT

• The XCA profile addendum to the IT Infrastructure Technical Framework at http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Supplement_XCA_TI_2007_08_15.pdf

• ebRIM OASIS/ebXML Registry Information Model v3.0,

• ebRS OASIS/ebXML Registry Services Specifications v3.0,

• SOAP 1.1. http://www.w3.org/TR/soap/

• WSDL 1.1. http://www.w3.org/TR/wsdl

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

1.5 Relationship to HITSP Constructs The following HITSP Constructs are referenced in this specification:

• HITSP T16 Consistent Time

1.6 Relationship to other NHIN Cooperative Specifications This specification relies on the NHIN Subject Discovery Interface specification as a precondition.

This Specification relies on the NHIN Document Query Interface Service Specification as a precondition.

This specification utilizes the transmission and security standards identified in the NHIN Messaging Platform Interface Specification and NHIN Authorization Framework. Specifically, each transaction identified in this specification must contain assertions about the identity and role of the user or system initiating the request.

1.7 Enforcement of Access Consent Policies This specification does not describe the obligations of an NHIE to enforce a patient’s Consumer Preferences Profile that has been created in and retrieved from another NHIE. The enforcement of these Access Consent Policies is assumed to be a matter of NHIE policy.

2 Interface Description

2.1 Definition The Cross Gateway Retrieve request is used to request the retrieval of a specific set of healthcare information (a document or documents) from a remote location. (From IHE XCA.) In this Interface definition, a “document” refers to the form of clinical data as it is transferred between NHIEs, not as it is stored in an NHIE. Any NHIE may store clinical data in whatever format or repository it chooses, so long as the NHIE can respond to queries as described in the Query for Documents Interface, and respond to retrieve document requests as described in this interface. Specifically, a “document” transferred between NHIEs need not meet the criteria for persistence, stewardship, etc. as identified by the HL7 Structured Documents committee.

http://www.w3.org/Submission/ws-addressing/�

http://www.ihe.net/Technical_Framework/index.cfm#IT�

http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Supplement_XCA_TI_2007_08_15.pdf�

http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Supplement_XCA_TI_2007_08_15.pdf�

http://www.w3.org/TR/soap/�

http://www.w3.org/TR/wsdl�

http://www.w3.org/TR/soap12-mtom/�

http://www.w3.org/TR/soap12-mtom/�



Through the Query for Documents transaction, a NHIE will receive one or more references (or pointers) to documents for patient records that satisfied given query parameters for a given patient. This transaction will allow the requester to use that reference to request a patient record document; and allow the responder to securely return the document to the requestor and audit the retrieval of the document.

NHIEs that generate documents “on demand” by aggregating data from multiple sources must ensure that the generated document remains available (unaltered) once a document has been retrieved once. Specifically:

1. A document reference may “expire” within some time period (defined by the NHIE) after a Query for Documents request has been received and responded to if and only if no subsequent Retrieve Documents request has been received and responded to for that document

2. For documents that have been shared with another NHIE via a Retrieve Documents request, the document reference and the document itself must remain available for future Retrieve Documents requests.

The Retrieve Document transaction retrieves patient relevant medical data held by another NHIE (or community, in the language of the IHE specifications). A community is identifiable by a globally unique id called the homeCommunityId. Membership of a facility/enterprise in one community does not preclude it from being a member in another community. An NHIE may be an XDS Affinity Domain that defines document sharing using the XDS profile or another type of community with a different internal sharing structure.

The following information is included in the IHE XCA profile to define the use of the homeCommunityId. Annotations (not from IHE) related to the NHIN are included in square brackets:

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. Document Consumers process the value in the response 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. [This use does not apply to the findDocuments query, which is the only form of Query Registry supported by the NHIN]

It is used by Initiating Gateways [when retrieving documents] to direct requests to the community where the initial data originated.

Each NHIE shall use the homeCommunityId of the form “urn:oid:n.n.n.n” (using a globally unique OID assigned to the NHIE) when responding to a Cross Gateway Query. The Initiating Gateway is expected to use this homeCommunityId to correlate a subsequent Retrieve Document request to the NHIE that holds the requested data.



Figure 1: Retrieve Documents Actor Diagram (from XCA Detailed Transactions in IHE ITI TF Supplement XCA TI 8/15/2007) Detailed interaction diagrams are found in the IHE XCA Integration Profile.

2.2 Triggers N/A

2.3 Transaction Standard The transactions used to implement the retrieve documents service interface are the Retrieve Document Set (ITI-43), Cross Gateway Query (ITI-38) and the Cross Gateway Retrieve (ITI-39).

2.4 NHIE Core Services The following NHIE Core Services are addressed by this specification:

• Data Services :: 1.1. Secure data delivery and confirmation of delivery, to EHRs, PHRs, other systems and networks.

• Data Services :: 1.5 Summary patient record exchange

• Data Services :: 1.7 Audit logging and error handling for data access and exchange.

2.5 Technical Pre-conditions The following technical pre-conditions exist for this interface specification:

• Consistent Time construct is a pre-requisite for this Transaction HITSP T16

• Secure Nodes is a pre-condition to this Transaction

• A policy defining what is to be audited exists

• Audit record repository is active and designated as the destination for recorded audit events

• Policy defining the protection of the log and audit exists and is being enforced

• Identities are managed

• The patient was successfully identified unambiguously

• Sources and consumers of document(s) were effectively identified.

• Target Repository is identified



• Target Document is identified

• (from TP13) The communities providing access to each other need to have agreed to a patient identification cross-referencing process. This may be supported dynamically by using other HITSP Constructs such Patient ID Cross-Referencing (TP22) or Patient Demographics Query (T23) or other means agreed between pairs of communicating communities. Further development in this area may be expected in the future.

2.6 Technical Post-conditions • The following technical post-conditions will results after the execution of this interface

specification:

• Audit records are created, and stored by both the requesting and responding NHIE.

• Access Consent Directives were enforced by the responding NHIE. If the requester was not authorized to view a requested document, appropriate errors were returned.

o For documents where access consent directives allow the retrieval by the requester, the documents were successfully retrieved by the requesting community.

• At the NHIE’s discretion, the initiating NHIE may validate the document. Validation may occur in the initiating NHIE’s gateway, or within the document consumer in the initiating NHIE upon receiving the document from the gateway. The initiating gateway is responsible for any validation performed; handling of errors in validation is dependant on the specific implementation of that NHIE. Validation may be any or all of the following:

o Validate the document content against the schema dictated by the document type to ensure it is a compliant format

o Validate the size of the document content against the metadata returned in the prior Query for Documents response. Note that size returned in query response may be -1 if document size is not known at time of query (see NHIN Query for Documents specification for more information).

o Validate the hash value (SHA1 algorithm) of the document content against the metadata returned in the prior Query for Documents response. Note that hash returned in query response may be -1 if document hash is not known at time of query (see NHIN Query for Documents specification for more information).

o Validate the mimeType of the document content against the metadata returned in the prior Query for Documents response

Note above that validation of the Retrieve Document response transaction’s digital signature is expected to occur within the messaging platform stack, and is not thus included in this list.Interface Definition

3 Interface Definition

3.1 Message Syntax The messages defined in this specification utilize elements defined in several different places, as described in the following table. Readers and implementers are urged to pay careful attention to the XML namespaces used in this document.

The protocol for the Cross Gateway Retrieve is based on SOAP12 and MTOM.



Table 1: WSDL Namespace Definitions

Namespace prefix used in this document

Full namespace identifier Description

soap12 http://schemas.xmlsoap.org/wsdl/soap12/ SOAP Standard Wsaw http://www.w3.org/2006/05/addressing/wsdl/ WS-Addressing standard Xsd http://www.w3.org/2001/XMLSchema Defined by this specification in Appendix A Ihe urn:ihe:iti:xds-b:2007 Rs urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0 Lcm urn:oasis:names:tc:ebxml-

regrep:xsd:lcm:3.0

Query urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0

3.2 Listing of base standard(s) The Retrieve Documents transaction is the Cross Gateway Retrieve [ITI-39] transaction defined by the IHE Cross Community Access (XCA) profile. The use of this transaction is part of HITSP TP13. XCA is a part of (and relies on) the complete IHE IT Infrastructure Technical Framework is available at http://www.ihe.net/Technical_Framework/index.cfm#IT. The XCA profile is an addendum to the complete IT Infrastructure Technical Framework; it can be found at http://www.ihe.net/Technical_Framework/upload/IHE_ITI_TF_Supplement_XCA_TI_2007_08_15.pdf. The following specifications are included in the ITI Technical Framework and are foundational for the Cross Gateway Retrieve transaction:

ebRIM OASIS/ebXML Registry Information Model v3.0,

ebRS OASIS/ebXML Registry Services Specifications v3.0,

SOAP 1.1. (http://www.w3.org/TR/soap/),

WSDL 1.1. (http://www.w3.org/TR/wsdl),

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

3.3 Retrieve Documents Transaction The Retrieve Documents transaction can be described in the following three steps.

3.3.1 Document Consumer

Document Consumer initiates a Retrieve Document Set – Prior to issuing a Retrieve Document Set the Document Consumer shall issue a Registry Stored Query by patient id to the Initiating Gateway. The response to the Registry Stored Query by patient id or subsequent Registry Stored Query by UUID includes a) the document unique ID b) the repository unique ID c) the homeCommunityId attribute. The Document Consumer shall specify these three parameters in its Retrieve Document Set transaction to the Initiating Gateway.

3.3.2 Initiating Gateway

Initiating Gateway processes Retrieve Document Set – The Initiating Gateway determines which Responding Gateways to contact by using the previously created mapping from homeCommunityId to Responding Gateway. The Retrieve Document Set may contain more than one unique homeCommunityId so the Initiating Gateway shall be capable of initiating requests to more than one Responding Gateway and consolidating the results. The Initiating Gateway shall specify the



homeCommunityId in the Cross Gateway Retrieve which was previously returned by the Responding Gateway.

3.3.3 Responding Gateway

Responding Gateway processes Cross Gateway Retrieve – The Responding Gateway within an XDS Affinity Domain processes the Cross Gateway Retrieve by grouping as a Document Consumer and initiating a Retrieve Document Set transaction to the Document Repository identified by the repository unique ID within the request. If the Cross Gateway Retrieve requests multiple documents with different repository unique IDs, the Responding Gateway shall contact multiple Document Repositories and consolidate the responses.

A Responding Gateway may implement an architecture other than the XDS Affinity Domain. In this case, it will respond to the Cross Gateway Retrieve in a functionally equivalent manner to that described in the preceding paragraph: by acquiring the requested data (and formatting into a document if required), and consolidating the requested documents into a single response.

The scope of the Cross Gateway Retrieve transaction is semantically the same as the Retrieve Document Set transaction [ITI-43]. 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.

The XCA specification does not contain a mechanism for the Initiating Gateway to return partial results to the Document Consumer while it waits for additional results from other Responding Gateways. Likewise, the specification does not allow for the Responding Gateway to return a partial result to the Initiating Gateway while it retrieves additional documents from other Document Repositories in its Community. In both cases, only one response is allowed, and the Responding/Initiating Gateway must manage the latency implications of waiting for responses to consolidate. This specification recommends using the XDS error code “XDSRepositoryBusy” to indicate a document that could not be retrieved within the timeout period used by the Responding/Initiating Gateway. (Note: this is an area that the IHE Technical Infrastructure committee continues to evaluate for potential revisions to the XDS and XCA specifications.)

3.4 Content Semantics The content of the documents carried in the payload of the Retrieve Document transaction has been defined by the NHIN Cooperative Core Content working group. This specification is incorporated here by reference.

3.4.1 Content Metadata Semantics

The content metadata semantics for Retrieve Documents are as described by the IHE ITI Technical Framework.

The Cross Gateway Retrieve 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.

The homeCommunityId element that identifies the community holding the document. The homeCommunityId element must be specified in the Cross Gateway Retrieve request .

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



The Cross Gateway Retrieve 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 Cross Gateway Retrieve Request Message.

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 Cross Gateway Retrieve 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 Cross Gateway Retrieve Request Message. This value corresponds to the XDSDocumentEntry.uniqueId.

The retrieved document in base64binary encoded format

The MIME type of the retrieved document

Errors or warnings in case the document(s) could not be retrieved successfully

3.5 Constraints and Extensions These are the requirements for the Cross Gateway Retrieve transaction presented in the order in which they would appear in the 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:RetrieveDocumentSetResponse”

The /definitions/portType/operation/input/@wsaw:Action attribute for the Retrieve Document Set Request message shall be defined as “urn:ihe:iti:2007:CrossGatewayRetrieve”

The /definitions/portType/operation/output/@wsaw:Action attribute for the Retrieve Document Set Response message shall be defined as “urn:ihe:iti:2007:CrossGatewayRetrieveResponse”

The /definitions/binding/operation/soap12:operation/@soapAction attribute shall be defined as “urn:ihe:iti:2007:CrossGatewayRetrieve”

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 the IHE specification.

A WSDL for the Responding Gateway actor is included in Appendix A.

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.

A required <ihe:HomeCommunityId/> element that corresponds to the home attribute of the Identifiable class in ebRIM.



This allows the Initiating Gateway to specify one or more documents to retrieve from the Responding Gateway.

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.

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 in base64binary encoded format

A required <ihe:mimeType/> element that indicates the MIME type of the retrieved document

The /RetrieveDocumentSetResponse/rs:RegistryResponse/@status attributes provides the overall status of the request:

urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success:

all documents were retrieved successfully

if present, /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError elements shall only contain warnings

there shall be an equal number of /RetrieveDocumentSetResponse/DocumentResponse elements as /RetrieveDocumentSetRequest/DocumentRequest elements

urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure

some documents were returned successfully, others had errors

both /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError elements and /RetrieveDocumentSetResponse/DocumentResponse elements shall be present. The number of returned /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError elements where @errorCode is an error plus the number of /RetrieveDocumentSetResponse/DocumentResponse elements shall be the same as the number of /RetrieveDocumentSetRequest/DocumentRequest elements

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 base64binary encoded data. 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 base64binary encoded data.

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 included in IHE XCA Specification, Appendix W. A download URL is in Appendix A of this document.

3.6 Sample 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.

All of the samples presented in this section are also available online on the IHE FTP site at ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr5-2007-2008/Technical_Cmte/SupportMaterial/.

3.6.1 Sample Retrieve Document Set SOAP Request: <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://www.w3.org/2005/08/addressing/anonymous</a:Address> </a:ReplyTo> <a:To s:mustUnderstand="1" >http://localhost:2647/XdsService/IHEXDSRepository.svc</a:To> </s:Header> <s:Body> <RetrieveDocumentSetRequest xmlns="urn:ihe:iti:xds-b:2007"> <DocumentRequest> <homeCommunityId>urn:oid:1.2.3.4</homeCommunityId> <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>

ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr5-2007-2008/Technical_Cmte/SupportMaterial/�



<DocumentUniqueId>1.3.6.1.4...2301</DocumentUniqueId> </DocumentRequest> </RetrieveDocumentSetRequest> </s:Body> </s:Envelope>

3.6.2 Sample Retrieve Document Set SOAP Response: <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> <homeCommunityId>urn:oid:1.2.3.4</homeCommunityId> <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>

4 Error Handling Error codes used in the Retrieve Documents interface will conform to the error codes listed in Section 3.14.4.1.2.16 of the IHE_ITI_TF_Supplement_XDS-2B specification. The error codes and, a description of their use are presented below.

Transaction P = Provide and Register, Provide and Register-b R = Register, Register-b Q= Query SQ=Stored Query

RS=Retrieve Document Set

Error Code Description Transaction

XDSRegistryError

Internal Regsitry Error P R Q SQ

XDSRepositoryError Internal Repository Error P

RS



Error Code Description Transaction

XDSRegistryBusy Too Much Activity P R Q SQ

XDSRepositoryBusy Too Much Activity P

RS

XDSRegistryOutOfResources Resources Are Low P R Q SQ

XDSRepositoryOutOfResources Resources Are Low P

RS

XDSUnknownRepositoryID The repositoryUniqueId value could not be resolved to a valid document repository or the value does not match the repositoryUniqueId of the Document Repository

RS

5 Auditing 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.39.4.1.4 (IHE XDA).

In addition, shall audit the Cross Gateway Retrieve as if it were a Document Consumer except that for EventTypeCode the Initating Gateway shall specify EV(“ITI-39”, “IHE Transactions”, “Cross Gateway Retrieve”). See Section 3.39.4.1.4. (IHE XCA)

In addition, if interacting with a local Document Repository, shall audit as if it were a Document Consumer. See Section 3.39.4.1.4 (IHE XCA). 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 Initating Gateway shall specify EV(“ITI-39”, “IHE Transactions”, “Cross Gateway Retrieve”). See Section 3.39.4.1.4 (IHE XCA).

In addition, if interacting with a local Document Repository, shall audit as if it were a Document Consumer. See Section 3.39.4.1.4 (IHE XCA). One audit record shall be created for each Document Repository contacted.

5.1.1 Listing of base standard(s)

IHE ATNA (HITSP T17) - TLS

IHE ATNA (HITSP T15) – Collect and Communicate Security Audit Trail



IHE Authenticated Node() : Secured Communication Channel

TLS: X.509, RFC 2246

Audit Record: ASTM E2147, ISO 10164-7, RFC 3881, RFC 3164, DICOM Supplement 95

The transport protocol for audit record communication shall be BSD syslog, per the IHE ATNA specification

The “provisional format” for audit records defined in IHE ATNA shall not be used. The provisional format was defined for backward compatibility with the Basic Security Profile of the IHE Radiology technical framework, which has since been deprecated.



6 Potential Future Considerations No identified future considerations at this time.



7 Appendix A: WSDL IHE provides an example WSDL definition1

1 IHE’s WSDL may be downloaded from ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr5-2007-

2008/Technical_Cmte/SupportMaterial/wsdl/RespondingGateway.wsdl.

for the Responding Gateway actor, which includes the Cross Gateway Retrieve Transaction.

The WSDL for this NHIN interface specification has been split from the Document Query Transaction in order to facilitate the inclusion of MTOM support. This Document Retrieve interface supports MTOM.

. <?xml version="1.0" encoding="UTF-8"?>  <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ihe="urn:ihe:iti:xds-b:2007" xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0" xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0" targetNamespace="urn:ihe:iti:xds-b:2007" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" name="XCA_RespondingGateway" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsaws="http://www.w3.org/2005/08/addressing" xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization"> <documentation>NHIN Responding Gateway Retrieve</documentation> <types> <xsd:schema> <xsd:import namespace="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0" schemaLocation="../schemas/ebRS/rs.xsd"/> <xsd:import namespace="urn:ihe:iti:xds-b:2007" schemaLocation="../schemas/ihe/XDS.b_DocumentRepository.xsd"/> <xsd:import namespace="urn:oasis:names:tc:ebxml-regrep:xsd:query:3.0" schemaLocation="../schemas/ebRS/query.xsd"/> </xsd:schema> </types> <message name="CrossGatewayRetrieve_Message"> <documentation>Cross Gateway Retrieve</documentation> <part name="body" element="ihe:RetrieveDocumentSetRequest"/> </message> <message name="CrossGatewayRetrieveResponse_Message"> <documentation>Cross Gateway Retrieve Response</documentation> <part name="body" element="ihe:RetrieveDocumentSetResponse"/> </message> <portType name="RespondingGateway_Retrieve_PortType"> <operation name="RespondingGateway_CrossGatewayRetrieve"> <input message="ihe:CrossGatewayRetrieve_Message" wsaw:Action="urn:ihe:iti:2007:CrossGatewayRetrieve"/> <output message="ihe:CrossGatewayRetrieveResponse_Message" wsaw:Action="urn:ihe:iti:2007:CrossGatewayRetrieveResponse"/> </operation> </portType> <binding name="RespondingGateway_Retrieve_Binding_Soap11" type="ihe:RespondingGateway_Retrieve_PortType"> <wsp:PolicyReference URI="#RespondingGateway_Retrieve_Binding_Soap11Policy"/> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="RespondingGateway_CrossGatewayRetrieve"> <soap:operation soapAction="urn:ihe:iti:2007:CrossGatewayRetrieve"/>



<input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="RespondingGateway_Retrieve_Service"> <port name="RespondingGateway_Retrieve_Port_Soap11" binding="ihe:RespondingGateway_Retrieve_Binding_Soap11"> <soap:address location="http://localhost:${HttpDefaultPort}/RespondingGateway_Service"/> </port> </service> <wsp:Policy wsu:Id="RespondingGateway_Retrieve_Binding_Soap11Policy"> <wsp:ExactlyOne> <wsp:All> <wsoma:OptimizedMimeSerialization/> </wsp:All> </wsp:ExactlyOne> </wsp:Policy> </definitions>