3.12 Retrieve Document for Display [ITI-12]

This section corresponds to transaction [ITI-12] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-12] is used by the Information Source and Display Actors.

3.12.1 Scope

This transaction involves the retrieval of a document (persistent object) for presentation purposes. The uniquely identifiable persistent object means that retrieving the same document instance at a different point in time will provide the same semantics for its presented content. The information content of the document is immutable even if the presentation of such content is provided with the use of different formats, stylesheets, etc.

3.12.2 Use Case Roles

Actor: Display

Role: A system that requests a document/object for display, and displays it.

Actor: Information Source

Role: A system that provides specific information in response to the request from the Display Actor, in a presentation-ready format.

3.12.3 Referenced Standards

RFC2616 HyperText Transfer Protocol HTTP/1.1

Extensible Markup Language (XML) 1.0 (Second Edition). W3C Recommendation 6 October 2000. http://www.w3.org/TR/REC-xml .

Web Services Description Language (WSDL) 1.1. W3C Note 15 March 2001. http://www.w3.org/TR/wsdl .

3.12.4 Messages

3.12.4.1 Request for Persistent Document

3.12.4.1.1 Trigger Events

The request for a document is triggered when a user of the Display needs to review a particular document that is stored by the Information Source Actor.

3.12.4.1.2 Message Semantics

The Retrieve Document for Display transaction is performed by the invocation of a web service. The Display shall generate the web service request whenever a user needs to review the document stored as part of a patient’s clinical history on the Information Source Actor.

The web service request shall include the following parameters (keys) to identify the document to be returned and its format (see Table 3.12.4-1). All parameter names and values are case-sensitive.

Table 3.12.4-1: Query Keys

Parameter Name	REQ	Description	Values
requestType	R	This parameter is required to have a value of DOCUMENT.	DOCUMENT
documentUID	R	Identifies document’s UID as known to both actors.	This value shall be a properly defined Object identifier (OID) as specified in ITI TF-2: Appendix B .
preferredContentType	R	This parameter is required to identify the preferred format the document is to be provided in (as MIME content type).	Display may specify one of the following formats: image/jpeg application/x-hl7-cda-level-one+xml (see note) application/pdf (see note)

Note: see IANA registry for details about hl7-cda-level-one and PDF, such as version. Applications creating PDF may use this MIME type for other versions of PDF up to 1.3. Receivers shall support document encoded in this version and previous versions.

Note: see HL7 CDA framework release 1.0 for details about application/x-hl7-cda-level-one+xml.

Formal definition of the web service in WSDL is provided in ITI TF-2: Appendix A .

The only binding required for both the Display and Information Source is the binding to the HTTP-GET. In this binding the sample message will be formatted as follows:

http://<location>/IHERetrieveDocument?requestType=DOCUMENT&documentUID=1.2.3&preferredContentType=application%2fpdf

The <location> part of the URL is configurable by the implementation, and must contain the host name, an optional port address, and may be followed by an optional path. The path if present may not contain a ‘?’ character. The remainder of the URL, including IHERetrieveDocument and the following request parameters are specified by the WSDL and may not be changed. See the discussion about location in Section 3.11.4.1.2 Message Semantics above.

In addition, the Display shall support the following fields of the HTTP request:

Table 3.12.4-3: HTTP Request and Response Fields

HTTP Field	REQ	Description	Values
Accept	O	This field may be used to specify certain media types which are acceptable for the response	At least one of the following values: image/jpeg application/x-hl7-cda-level-one+xml application/pdf */* Other values may be included as well
Accept-Language	O	This field is similar to Accept, but restricts the set of natural languages that are preferred as a response to the request.	Any valid value according to RFC2616
Expires	R	This field gives the date/time after which the response is considered stale	Any valid value according to RFC2616, or 0

The Information Source shall support the following field of the HTTP response.

Table 3.12.4-4: HTTP Response Fields

HTTP Field	REQ	Description	Values
Expires	R	This field gives the date/time after which the response is considered stale	Any valid value according to RFC2616, or 0

The Display may provide list of content types it supports in the HTTP Accept field. If the HTTP Accept Field is absent, it means that any content type is acceptable by the Display Actor.

The preferredContentType parameter shall specify the content type desired by the Display Actor. The value of the preferredContentType parameter of the request shall be one of the values from the Table 3.12.4-1 and shall not contradict values specified in the HTTP Accept field.

The Information Source shall provide info in preferredContentType if capable, otherwise it shall only use a type specified in the Accept Field as appropriate given the information to be returned.

If necessary, the Display may perform the request to the web service utilizing HTTPS protocol.

Information Source Actors may return HTTP redirect responses (responses with values of 301, 302, 303 or 307) in response to a request. Display Actors can expect to receive an error response, or the data requested, or a request to look elsewhere for the data. A Display must follow redirects, but if a loop is detected, it may report an error.

3.12.4.1.3 Expected Actions

Upon reception of the Request for Specific Information, the Information Source shall parse the request and shall return the retrieved document as specified in Section 3.12.4.2, and HTTP response code 200 - OK.

If the requestType specified is a not a legal value according to this profile, the Information Source shall return HTTP response-code 403 (forbidden) with the suggested reason-phrase “requestType not supported”.

If the Information Source is not able to format the document in any content types listed in the 'Accept' field, it shall return HTTP response code 406 – Not Acceptable.

If the specified documentUID is not known to the Information Source Actor, it shall return HTTP response-code 404 (not found) with the suggested reason-phrase “Document UID not found”.

If the documentUID, preferredContentType or requestType parameters are missing, the Information Source shall return HTTP response code 400 - Bad Request.

If the documentUID or preferredContentType parameters are malformed, the Information Source shall return HTTP response code 400 - Bad Request.

If the specified preferredContentType is not consistent with the setting of the HTTP Accept field, the Information Source shall return HTTP response code 400 – Bad Request.

Note: Other HTTP response codes may be returned by the Information Source Actor, indicating conditions outside of the scope of this profile, for example, 401 – Authentication Failed might be returned if Information Source is grouped with the Kerberized Server Actor.

Note:  It is recommended that the Information Source complement returned error code with a human readable description of the error condition.

If an error condition cannot be automatically recovered, at a minimum, the error should be displayed to the user by the Display Actor.

3.12.4.2 Delivery of Persistent Document

3.12.4.2.1 Trigger Events

The Delivery of Persistent Document message is the transmission of the requested document in specified format from the Information Source to the Display. This transmission will happen if such document, identified by the documentUID parameter in the request, has been successfully located by the Information Source Actor.

3.12.4.2.2 Message Semantics

In response to the request from the Display Actor, the Information Source shall format the document according to the preferredContentType specified, and return it in the HTTP response. See Section 3.12.4.1.2 for a discussion of the rules related to preferredContentType.

The Information Source shall maintain global uniqueness of object identifiers.

The Information Source shall set an expiration date compatible with the policies associated with the possible removal of instances of persistent documents (no more than a week).

3.12.4.2.3 Expected Actions

The Display shall render the received document for the user.