Query+for+Documents


 * 1) Introduction
 * 2) Background
 * 3) Purpose
 * 4) Interface Description
 * 5) Definition
 * 6) Design Principles and Assumptions
 * 7) Transaction Standard
 * 8) Standards Documentation
 * 9) Interface Definition
 * 10) Overview of XCA
 * 11) Transaction Components

Background
The Nationwide Health Information Network (NHIN) Web Service Interface specifications define the core set of standard services to be implemented by each node on the NHIN network in order to exchange interoperable health information over the Internet. Health Information Organizations (HIOs) which act as nodes on the NHIN are termed NHIOs. These functional services provide discovery and information exchange capabilities and rest upon a foundational set of messaging, security, and privacy services.

This document presents the NHIN Query for Documents Web Service Interface specification. Together with the Retrieve Documents Service Interface Specification, Query for Documents enables the NHIN’s Query/Retrieve information exchange pattern.

Intended Audience
The primary audiences for NHIN Specifications are the individuals responsible for implementing software solutions that realize these interfaces at Health Information Organizations (HIOs) who are, or seek to be, nodes on the NHIN network. This specification document is intended to provide an understanding of the context in which the web service interface is meant to be used, the behavior of the interface, the Web Services Description Language (WSDLs) used to define the service, and any Extensible Markup Language (XML) schemas used to define the content.

Business Needs Supported by this Specification
Query for documents is the second in the three-step process which defines the Query/Retrieve information exchange pattern in the NHIN: 1) Arbitrate patient identity 2) Query for list of available documents 3) Retrieve documents

Purpose
The purpose of this document is to capture the XCA specifications for Querying of Documents with the goal of aiding implementers to understand the ITI-38 in the context of its use in the NHIN. We highly recommend that implementers of this NHIN specification review IHE’s XCA in order to gain a more complete understanding of the transactions described and their relationship to other IHE transactions and profiles.

The primary audiences for NHIN Specifications are the individuals responsible for implementing software solutions that realize these interfaces at Health Information Organizations (HIOs) who are, or seek to be, nodes on the NHIN network. This specification document is intended to provide an understanding of the context in which the web service interface is meant to be used, the behavior of the interface, the Web Services Description Language (WSDLs) used to define the service, and any Extensible Markup Language (XML) schemas used to define the content

Interface Description
This section defines the NHIN Query for Documents web service, reviews its design principles and assumptions, triggers, and provides an explanation of underlying standards and protocols. Further descriptions, including pre and post conditions and usage scenarios can be found in Appendix XX.

Definition

 * A query initiated from one NHIO to another, requesting a list of available documents meeting the given query parameters for a particular patient for later retrieval.**

Query for Documents is used when a Document Consumer wants to query and retrieve standardized document metadata. In this Interface definition, a “document” refers to the form of clinical data as it is transferred between NHIOs, not as it is stored in an NHIO. An NHIO may store clinical data in whatever format or repository it chooses, so long as the NHIO can respond to queries as described in this interface, and respond to “retrieve document” requests as described in the “Retrieve Documents Service Interface specification

Design Principles and Assumptions
The primary assumption in the context of the NHIN is that documents are formatted as XML data following the HL7 Clinical Document Architecture (CDA) standard, but nothing precludes this interface from being used to query for other kinds of documents, such as Adobe Portable Document Format files or images.

The following assumptions or design principles also underlie this specification:
 * The means by which an NHIO determines which other NHIOs to direct queries is not specified. This is a local NHIO decision.
 * An NHIN Gateway directs a query to other individual NHIOs. This specification does not define a central or federated service that performs transactions across multiple NHIOs.
 * An authorization decision evaluates each request against local consumer preferences and local polices and permissions to determine which document(s) can be made available for retrieval.
 * Patient Identifiers (PIDs), once shared with another NHIO will NEVER be reassigned to another person.

NHIN Query for Documents allows an Initiating Gateway to query a Responding Gateway for a list of patient specific documents which meets query parameters.

Transaction Standard
NHIN Query for Documents utilizes the IHE Cross Community Access (XCA) ITI-38: Cross Gateway Query transaction, which is part of HITSP TP13. The XCA Profile is an addendum to the complete IHE IT Technical Infrastructure Technical Framework (ITI-TF). The location of these documents, as well as other foundational standards for this transaction, is listed in Section 1.4 “Referenced Documents and Standards”.

The XCA ITI-38 specification has been relaxed within this NHIN specification as needed to support the query for, and retrieval of, dynamically generated document content. As described further in sections 2.6 “Technical Post-conditions” and 3.3 “Query Parameters”, for documents whose creation has been deferred until retrieve time, the metadata values for document hash and document size are not required to be the actual hash and size of the later retrieved document, as mandated by XCA. In addition availabilityStatus=”urn:ihe:iti:2010:StatusCode:DeferredCreation” is used to identify this special status. This modification to XCA is expected to be adopted by IHE at some future time. A WSDL for the Responding Gateway actor and a full XML Schema can be accessed via a URL provided in Appendix B of this document.

Standards Documentation
NHIN Query for Documents adopts IHE’s ITI-38, which in turn references and relies upon several other standards and profiles. The diagram below lists and illustrates the relationships among the primary documents which define the underlying standards for this transaction. The location of these documents, as well as other foundational standards for this transaction, is listed in Section X.X “Referenced Documents and Standards”.



The standards and protocols specified for this transaction were developed by several different standards organizations. They and are defined in upwards of 100 pages of reference material across a multitude of documents, which successively build upon one another. In an effort to increase implementer ease of use, the authors of this document have endeavored to provide a walkthrough of transaction components, as well as an explanation and context as source material is referenced.

Interface Definition
This section details the components of the NHIN Query for Documents transaction, providing details regarding message semantics, examples of syntax and sample messages, and some other stuff.

Overview of XCA
The Cross-Community Access (XCA) profile supports the means to query and retrieve patient relevant medical data held by other communities. A community is defined as a coupling of facilities/enterprises that have agreed to work together using a common set of policies for the purpose of sharing clinical information via an established mechanism. A community is identifiable by a globally unique id called the homeCommunityId.

NHIN Query for Documents utilizes the IHE Cross Community Access (XCA) ITI-38: Cross Gateway Query transaction, which is part of HITSP TP13. The Cross Gateway Query transaction is described in IHE ITI XCA Supplement Section 3.38. Figure 1.1 below illustrates the actors and transactions involved in the ITI-38 Cross Gateway Query transaction. Note that the diagram represents the Initiating Community (NHIO in this context) as an IHE XDS-based community. The NHIN Query for Documents transaction does not require the XDS architecture; it is merely presented in the diagram for illustrative purposes. A sample query and response is provided in Appendix A “Sample Messages”

.



Transaction Components
NHIN Query for Documents consists of an AdhocQueryRequest and AdhocQueryResponse, as documented in ebXML Registry Services and Protocols sections 6.3.2 and 6.3.3 respectively. As the Standards Documentation diagram in Section X.X suggests, the ebRS AdhocQuery protocol is foundational to ITI-18, ITI-38, and NHIN Query for Documents, each which successively elaborate its use. The terminology used to describe transaction components varies with each successive document. As a reference, the terminology used in each referenced standard is provided below:
 * ebRS 3.0 – AdhocQueryRequest
 * ebRS 3.0 – AdhocQueryResponse
 * ITI-18 – Registry Stored Query / Acknowledgment
 * ITI-38 – Cross Gateway Query / Response
 * NHIN – Query for Documents Query / Response
 * AdhocQuery Request (Registry Stored Query)
 * FindDocuments
 * GetAll
 * GetDocuments

Message Semantics
NHIN Query for Documents adopts IHE Transaction 38, Cross Gateway Query, which is specified in ITI-TF6_XCA Supplement (8/10/2009). Message semantics are defined across several underlying specifications. The information contained in this section is NOT intended to serve as a substitute for careful review of those referenced documents and sections. Instead, it is intended to enable implementers to more efficiently locate information.
 * Section 3.38.4.1.2 of the XCA Supplement explains that Cross Gateway Query message semantics are based on those specified for IHE Transaction 18, Registry Stored Query. Of special note in 3.38.4.1.2 are:
 * Use of Home Community ID
 * Specifying patient identifier
 * Special handling of stored query
 * ITI-TF6-2a Section 3.18.4.1.2 explains that Registry Stored Query message semantics are defined in Section 6.3.2 and 6.3.3 of ebXML Registry Services and Protocols (ebRS) version 3.0, published by OASIS. Of special note in ITI-TF6-2a Section 3.18.4.1.2 are:
 * Guidance provided regarding the version 3.0 ebXML Registry Standard
 * A Sample Query Request
 * Coding style requirements for Query Request Parameters

Query Request Parameteres
Query Request Parameters are those which pertain to the request and should be distinguished from Query Parameters, which are those which pertain to the query itself. Parameters to be included in Stored Query Requests are described below.
 * 1) **returnComposedObjects** - This optional parameter specifies whether the RegistryObjects returned should include composed objects as defined by Figure 1 in [ebRIM]. The default is to return all composed objects.
 * 2) **returnType** – ‘LeafClass’ or ‘ObjectRef’
 * 3) The ‘LeafClass’ return type is intended for use when anticipating the return of a small number of fully specified registry objects. This type of query result is self-contained, everything known about the object(s) is returned. As such, is not appropriate for queries which anticipate the return of hundreds of objects. Additionally, ObjectRefs (UUIDs) may also be returned. These represent objects that are referenced by, but not included among objects in the returned list.
 * 4) The ‘ObjectRef’ return type returns references (UUIDs) to registry objects matching the query. This type is recommended when the returned list could be large, as far less data per object is returned. ObjectRef can be used to manage queries in which the return of hundreds or thousands of objects is anticipated. To construct a page for display, a small subset of the referenced objects can be retrieved via a second query and repeated for each page. Refer to IHE TF-2a: 3.18.4.1.2.6 for examples.**QueryID** – A UUID from among those defined for each Stored Query in Table X.

**3. QueryID** – A UUID from among those defined for each Stored Query in Table X. **4. Query Parameters** – parameters from among those in the set associated with each Stored Query. Parameters for each Stored Query are detailed in section 3.18.4.1.2.3.7 of ITI TF-2a

Specific information detailing the coding style for Date/Time, Code/Code-Scheme, and the coding of multiple values is presented in Sections 3.18.4.1.2.3.3 – 5 of ITI TF-2a. All Date/time values are to be inclusive, interpreted as: $XDSDocumentEntryCreationTimeFrom <= XDSDocumentEntry.creationTime $XDSDocumentEntryCreationTimeTo for example. The ‗From‘ time or the ‗To‘ time may be omitted.
 * xx.xx Query Request Parameter Coding**

A community (NHIO) 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. The following information is included in the IHE XCA profile to define the use of the homeCommunityId. NHIN specific annotations are included in square brackets The homeCommunityId is a globally unique identifier for a community used to assist in subsequent requests for locating the data held by that community. homeCommunityId is structured as an OID limited to 64 characters and specified in URI syntax, for example the homeCommunityId of 2.16.840.1.113883.3.166 would be formatted as urn:oid: 2.16.840.1.113883.3.166. · [Each NHIO shall use the homeCommunityId of the form “urn:oid:n.n.n.n” using a globally unique OID assigned to the NHIO when responding to a Cross Gateway Query. The Initiating Gateway is expected to use this homeCommunityId to correlate a subsequent Retrieve Document request with the HIO that holds the requested data.] It is returned within the response to Cross Gateway Query to indicate the association of a response element with a community. It is specified as the ebRIM home attribute within the relevant response elements. Document Consumers process the value in the response as an opaque unique identifier. It is used by Initiating Gateways [when retrieving documents] to direct requests to the community where the data originated.
 * xx.xx Home Community ID**

FindDocuments queries a repository for Documents with a matching PatientID and Status attributes. The remaining parameters are optional and can be used to restrict the set of documents returned. Each of the parameters listed below correspond to XDS Metadata attributes, which are detailed in [|ITI TF-3], Table 4.1-5. The metadata elements in Table 4.1-5 are used to describe an XDS Document. They shall be provided by the Document Repository Actor in the Register Document Set Transaction either directly if grouped with a Document Source Actor or forwarded from a Provide and Register Document Set Transaction. Some key Attributes are: Approved available for patient care Deprecated obsolete This attribute is always set to Approved as part of the submission of new XDS Documents. It may be changed to Deprecated under the primary responsibility of the Document Source with possible patient supervision. || Represents the time the author created the document in the Document Source. Shall have a single value. || An event can further specialize the act inherent in the typeCode, such as where it is simply "Procedure Report" and the procedure was a "colonoscopy". If one or more eventCodes are included, they shall not conflict with the values inherent in the classCode, practiceSettingCode or typeCode, as such a conflict would create an ambiguous situation. This short list of codes is provided to be used as “key words” for certain types of queries. If present, shall have one or more values. ||
 * ** XDSDocumentE ntry Attribute ** || ** Definition ** ||
 * availabilityStatus || An XDS Document shall have one of two availability statuses:
 * classCode || The code specifying the particular kind of document (e.g. Prescription, Discharge Summary, Report). It is suggested that the XDS Affinity Domain draws these values from a coding scheme providing a coarse level of granularity (about 10 to 100 entries). Shall have a single value. ||
 * creationTime || creationTime
 * eventCodeList || This list of codes represents the main clinical acts, such as a colonoscopy or an appendectomy, being documented. In some cases, the event is inherent in the typeCode, such as a "History and Physical Report" in which the procedure being documented is necessarily a "History and Physical" act.

IHE ITI-18 defines 13 Stored Queries outlined in section 4.2.1 and the query parameters associated with each. Among those 13 Stored Queries, it is anticipated that FindDocuments will be the primary query to be used in the NHIN Query for Documents transaction. A detailed overview and implementation guidance for the FindDocuments query is contained in section 4.2.6.1. Information pertaining to the remaining 12 Stored Queries can be found in ITI-18: 3.18.4.1.2.3.7.

The Patient ID (PID) is the technical identifier used to represent the subject (patient) for whom documents are sought. This identifier shall originate from an Assigning Authority Domain supporting the NHIO. This specification **//does not//** constrain who the Assigning Authority is, whether it is the same as the Home Community ID, whether more than one might be utilized within an HIO, or whether a given Assigning Authority may be referenced by more than one HIO. The Patient ID shall contain two parts:
 * Patient Identity Assigning Authority in the form of an OID
 * An identifier in the above Assigning Authority domain

Within the query request and response, these components of the patient ID are to be specified in the HL7 CX format, which is described in Volume 3 of the [|IHE ITI Technical Framework] Section 4.1.7 Table 4.1-3. The HL7 CX data type consists of several components, but this specification allows the use of only two: ID Number, and Assigning Authority (AA). The Assigning Authority identifies the "domain" over which the ID Number represents a unique entity and is represented using a Universal ID and Universal ID Type, which must be ISO. The required format is: ‘IDNumber^^^&OIDofAA&ISO’. No other values/modifications in other components or subcomponents are allowed. In the context of the NHIN, these values are exchanged during Patient Discovery; the Assigning Authority is the //root// of the patient identifier and the Patient ID is the //extension.// An explicit example is: ‘543797436^^^&1.2.840.113619.6.197&ISO’. Note that the '&' character must be properly encoded and the patient identifier must be surrounded by single quotes.

The allowed values for the $XDSDocumentEntryStatus parameter are: urn:oasis:names:tc:ebxml-regrep:StatusType:**Submitted** urn:oasis:names:tc:ebxml-regrep:StatusType:**Approved** urn:oasis:names:tc:ebxml-regrep:StatusType:**Deprecated** urn:ihe:iti:2010:StatusCode:**DeferredCreation** The DeferredCreation value is an extension to ITI-38. It supports the query for, and retrieval of, dynamically generated document content. Such a document may be included in the list of returned objects, but is not actually created until such time as it is retrieved via an NHIN Retrieve Documents transaction.

Efficient document searches can best be facilitated by limiting search parameters to a few elements, each with a coarse granularity. Beyond the required PatientID and Status attributes, the following elements are recommended as the primary query parameters: Table X.x in section 4.6.2.1, reproduced from IHE ITI TF 2a: 3.18.4.1.2.3.7.1 contains a complete list of FindDocuments query parameters. For more detailed information, refer to Table 4.1-4 in ITI TF Vol3.
 * **Class Code** –specifies the particular kind of document (e.g., Prescription, Discharge Summary, Report, etc.). This value set is comprised of LOINC codes and is defined in Table 2-144 in HITSP C80 V2.0.1, which has been reproduced in Appendix X.x of this document.
 * **Practice Setting Code** – specifies the clinical specialty where the documented act was performed (e.g. Family Practice, Laboratory). This value set is comprised of SNOMED CT codes and is defined in Table 2-149 of HITSP C80 mV2.0.1, which has been reproduced in Appendix x.x of this document.
 * **Healthcare Facility Type** – specifies the type of organizational setting in which the documented act was performed. This value set is compromised of a set of SNOMED CT codes and is defined in Table 2-147 in HITSP C80 V2.0.1, which has been reproduced in Appendix X.x of this document.
 * **Document Creation Time –** represents the time the author created the document. Format and syntax are defined in Table 4.1-5 in ITI TF Volume 3.

A responding NHIO will respond to a FindDocuments (or other Registry Stored Query request) with a list of available documents. If the returnType on the query request was ObjectRef, the responder will return references (UUIDs) to available documents matching query parameters. If the returnType was LeafClass, the responder will return a list of documents with fully specified document metadata.

NHIN Query for Documents adopts Cross Gateway Query (ITI-38), which inherits message semantics from Registry Stored Query (ITI-18), which inherits message semantics from AdhocQuery. AdhocQuery message semantics are defined in Section 6.3.2 and 6.3.3, respectively of ebXML Registry Services and Protocols (ebRS) version 3.0, published by OASIS. Message semantics are elaborated in much greater detail throughout the components of Section 3.18.4.1.2 of IHI TF-2a. Portions of that material are included below, but should not be considered as a substitute for a careful review of the reference documentation.

Details can be found in 2.1.3.2 of [|ebXML Registry Services and Protocols Version 3.0] ResponseStatusType – indicates the status of the request and contains the following values: · Success – indicates that the request was successful · Failure – indicates that the request encountered a failure. One or more errors MUST be included in the RegistryErrorList · Unavailable – indicates that the response is not yet available. Attributes The following canonical values are defined for the ResponseStatusType ClassificationScheme: · Success - This status specifies that the request was successful. · Failure - This status specifies that the request encountered a failure. One or more errors MUST be included in the RegistryErrorList in this case or returned as a SOAP Fault. · Unavailable – This status specifies that the response is not yet available. This may be the case if this RegistryResponseType represents an immediate response to an asynchronous request where the actual response is not yet available. requestId – specifies the ID of the request for which this is the response. It must match the AdhocQueryID included in the query request.
 * status**: The status attribute is used to indicate the status of the request. The value of the status attribute MUST be a reference to a ClassificationNode within the canonical ResponseStatusType ClassificationScheme as described in [ebRIM]. A Registry MUST support the status types as defined by the canonical ResponseStatusType ClassificationScheme. The canonical ResponseStatusType ClassificationScheme may be extended by adding additional ClassificationNodes to it.
 * requestId**: This parameter specifies the id of the request for which this is a response. It matches value of the id attribute of the corresponding RegistryRequestType.
 * ResponseSlotList**: This parameter specifies a collection of Slot instances. A RegistryResponseType MAY include Slots as an extensibility mechanism that provide a means of adding dynamic attributes in form of Slots. The use of registry implementation specific slots MUST be ignored silently by a Registry Client that does not support such Slots and MAY not be interoperable across registry implementations.
 * RegistryErrorList**: This parameter specifies an optional collection of RegistryError elements in the event that there are one or more errors that were encountered while the registry processed the request for this response. This is described in more detail in 6.9.4