3.11 Retrieve Specific Information for Display [ITI-11]
This section corresponds to transaction [ITI-11] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-11] is used by the Information Source and Display Actors.
3.11.1 Scope
This transaction involves the query of information for presentation purposes. This may occur when a user attempts to lookup information associated with certain patient that is stored on a different system. Note that the retrieved information is always related to a well-identified patient (Patient ID), but its content, although of a specific type (lab summary, or radiology summary, list of allergies), is generally dynamic (i.e., retrieving the same type of specific information at a different point in time is likely to result in different content); for example, a list of allergies may have been updated between two requests.
To support a wide range of display capabilities, the information provided is formatted into well-formed XHTML. Such formatting shall be done using XHTML Basic and W3C HTML Compatibility Guidelines provided in the Appendix C of the W3C XHTML 1.0 Recommendation.
3.11.2 Use Case Roles
Actor: Display
Role: A system that requests specific information 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.11.3 Referenced Standards
RFC1738, Uniform Resource Locators (URL), December 1994, http://www.faqs.org/rfcs/rfc1738.html
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 .
XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition).A Reformulation of HTML 4 in XML 1.0. W3C Recommendation 26 January 2000, revised 1 August 2002. http://www.w3.org/TR/xhtml1 .
XHTML™ Basic. W3C Recommendation 19 December 2000. http://www.w3.org/TR/xhtm-basic.
http://www.w3.org/TR/xhtml-basic
3.11.4 Messages
Figure 3.11.4-1: Request For Specific Information – Summary sequence
3.11.4.1 Request For Specific Information - Summary
3.11.4.1.1 Trigger Events
The following event will trigger a Request for Specific Information:
- User of the Display needs to review a summary list of information/ reports that are part of a patient’s clinical history (i.e., summary of lab reports, summary of radiology exam reports, etc.) with the intent of selecting a specific item off the list for subsequent retrieval as a persistent object via the Retrieve Document for Display Transaction
3.11.4.1.2 Message Semantics
The Retrieve Specific Information for Display transaction is performed by the invocation of a web service. The Display shall generate a web service request whenever a user needs to review the information stored as part of a patient’s clinical history on the Information Source Actor.
To specify the type of information that needs to be returned, a web service request shall include the following parameters (keys) to filter the subset of information (see Table 3.11.4-1). All parameter names and values (see Table 3.11.4-2) are case-sensitive.
Table 3.11.4-1: Web Service Request Keys
| Parameter Name | REQ | Description | Notes |
| requestType | R | requestType specifies what type of information shall be retrieved. This parameter shall always be valued. | See Table 3.11.4-2 for the list of possible values. |
| patientID | R | This attribute identifies the subject of the results being queried for. Its value shall include identification of assigning authority. | PatientID value shall be formatted as HL7 CX data type (including assigning authority) according to the requirements specified for the Patient Identity Feed transaction (see Section 3.8.4.1.2.3) |
| lowerDateTime | O | Used to constrain the earliest date/time of creation of information. | This value shall be encoded in the XML primitive dateTime format. |
| upperDateTime | O | Used to constrain the latest date/time of creation of information. | This value shall be encoded in the XML primitive dateTime format. |
| mostRecentResults | R | The numeric value that indicates the number of most recent results to be included into the response, i.e., 1 indicates to provide the latest result. | Value of 0 indicates that all available results shall be returned. |
Table 3.11.4-2: Web Service Request Types
| requestType value | Description |
| SUMMARY | Summary of all reports known to the Information Source |
| SUMMARY-RADIOLOGY | Summary of radiology reports |
| SUMMARY-CARDIOLOGY | Summary of cardiology reports |
| SUMMARY-LABORATORY | Summary of laboratory reports |
| SUMMARY-SURGERY | Summary of surgery reports |
| SUMMARY-EMERGENCY | Summary of emergency reports |
| SUMMARY-DISCHARGE | Summary of discharge reports |
| SUMMARY-ICU | Summary of intensive care reports |
| SUMMARY-RX | Summary of Prescriptions |
Note: parameter values that contain reserved characters need to be encoded using %<hex><hex> notation. Reserved characters include slash (/, encode as %2f) and ampersand (&, encode as %26).
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:
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 IHERetrieveSummaryInfo and the following request parameters are specified by the WSDL and may not be changed.
More specifically, using the definitions from RFC1738, the <location> part of the URL must match the production for location from the figure below:
location = hostport [ "/" hpath ]
hostport = host [ ":" port ]
host = hostname | hostnumber
hostname = *[ domainlabel "." ] toplabel
domainlabel = alphadigit | alphadigit *[ alphadigit | "-" ] alphadigit
toplabel = alpha | alpha *[ alphadigit | "-" ] alphadigit
alphadigit = alpha | digit
hostnumber = digits "." digits "." digits "." digits
port = digits
hpath = hsegment *[ "/" hsegment ]
hsegment = *[ uchar | ";" | ":" | "@" | "&" | "=" ]
lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |"q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |"y" | "z"
hialpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" |"J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" |"S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
alpha = lowalpha | hialpha
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |"8" | "9"
safe = "$" | "-" | "_" | "." | "+"
extra = "!" | "*" | "'" | "(" | ")" | ","
hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f"
escape = "%" hex
unreserved = alpha | digit | safe | extra
uchar = unreserved | escape
The following location values are legal according to this specification:
| <location> value | Resulting URL |
| myhost | http://myhost/IHERetrieveSummaryInfo?… |
| myhost:8080 | http://myhost:8080/IHERetrieveSummaryInfo?… |
| myhost/MyAspPageThatLooksLikeItCouldBeAFolder.aspx | http://myhost/MyAspPageThatLooksLikeItCouldBeAFolder.aspx/IHERetrieveSummaryInfo?… |
| myhost:8080/MyAspPageThatLooksLikeItCouldBeAFolder.aspx | http://myhost:8080/MyAspPageThatLooksLikeItCouldBeAFolder.aspx/IHERetrieveSummaryInfo?… |
| myhost/MyJspPage.jsp | http://myhost/MyJspPage.jsp/IHERetrieveSummaryInfo?… |
| myhost:8080/MyJspPageThatLooksLikeItCouldBeAFolder.jsp | http://myhost/MyJspPage.jsp/ IHERetrieveSummaryInfo?… |
The following location values are not legal:
| <location> value | Resulting URL |
| My+Computer | ‘+’ is not a legal character in a host name. |
| myhost:99999 | 99999 is not a valid port. |
| myhost/myPath.jsp?request= | ‘?’ is not valid in a path. |
In addition, the Display shall support the following field of the HTTP request:
Table 3.11.4-3: HTTP Request and Response Fields
| HTTP Field | REQ | Description | Values |
| Accept-Language | O | This field restricts the set of natural languages that are preferred as a response to the request. | Any valid value according to RFC2616 |
The Information Source shall support the following field of the HTTP response.
Table 3.11.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 | Shall be 0. This is now deprecated usage, but it is the widely supported means of specifying no caching. |
| Cache-Control | R | This field indicates that this response should not be cached. | Shall be no-cache |
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.11.4.1.3 Expected Actions
Upon reception of the Request for Specific Information, the Information Source shall parse the request and if there are no errors, return the Response with Specific Information as specified in Section 3.11.4.2, and HTTP response code 200 - OK.
To specify the type of information that needs to be processed, an Information Source shall support the following parameters (keys) to filter the subset of information (see Table 3.11.4-5).
Table 3.11.4-5: Web Service Request Keys
| Parameter Name | REQ | Description | Notes |
| requestType | R | requestType specifies what type of information shall be retrieved. This parameter shall always be valued. | See Table 3.11.4-2 for the list of possible values. |
| patientID | R | This attribute identifies the subject of the results being queried for. Its value shall include identification of assigning authority. | PatientID value shall be formatted as HL7 CX data type (including assigning authority) according to the requirements specified for the Patient Identity Feed transaction (see Section 3.8.4.1.2.3) |
| lowerDateTime | R | Used to constrain the earliest date/time of creation of information. | This value shall be encoded in the XML primitive dateTime format. |
| upperDateTime | R | Used to constrain the latest date/time of creation of information. | This value shall be encoded in the XML primitive dateTime format. |
| mostRecentResults | R | The numeric value that indicates the number of most recent results to be included into the response, i.e., 1 indicates to provide the latest result. | Value of 0 indicates that all available results shall be returned. |
If the requestType specified is not supported, the Information Source shall return HTTP response-code 404 (not found) 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 Patient ID specified by the Display is not known to the Information Source Actor, it shall return HTTP response-code 404 (not found) with the suggested reason-phrase “Patient ID not found”. If the Display provides the Patient ID from a different domain than the one the Information Source belongs to, and the Information Source is grouped with the Patient ID Consumer Actor, it may attempt to obtain a mapping of the provided Patient ID into its domain before responding.
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 the 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.
If lowerDateTime and/or upperDateTime parameters are specified, they shall define the lower and/or upper inclusive boundary of the temporal range in which returned information should have been created. The value of the mostRecentResults parameter shall be interpreted within such specified date/time range.
3.11.4.2 Response with Specific Information - Summary
3.11.4.2.1 Trigger Events
This message is sent by the Information Source in response to the Request For Specific Information web service request.
3.11.4.2.2 Message Semantics
Information Source shall support at least one of the values of the requestType parameter specified in Table 3.11.4-2.
The Information Source shall set an expiration of zero to ensure no caching. The message shall be formatted using XHTML Basic and W3C HTML Compatibility Guidelines provided in the Appendix C of the W3C XHTML 1.0 Recommendation.
The Display may request the Information Source to provide any specific information including a summary of reports of different types pertaining to a particular patient. The exact content of the summary is determined by the Information Source and may be regulated by the institution policy. For example, it may contain the hyperlink to a persistent object so that it can be retrieved by using the Retrieve Document for Display [ITI-12] transaction. In the case of retrieving a summary of documents (requestType of SUMMARY[-xx]), it is strongly recommended to include a link to the relevant documents, for each item of the summary. If present, the link will have to be formatted as a web service request in accordance to the requirements in Section 3.12. It may also contain a hyperlink representing the invocation of the Request for Specific Information for display, as specified in this Section.
3.11.4.2.3 Expected Actions
The Display shall render the received response for the user. It shall not assume that the content of the document may be meaningfully parsed beyond determination of XHTML tags necessary for accurate presentation of provided information.
When the summary responses include links to documents or other specific information, Information Source Actors are strongly encouraged to format them according to the requirements stated in Section 3.11 and 3.12, to facilitate retrieval of information from other information sources.
3.11.4.3 Request For Specific Information - List
3.11.4.3.1 Trigger Events
The following event will trigger a Request for Specific Information:
- User of the Display needs to review a particular subset of information that is part of a patient’s clinical history (i.e., lab report, radiology exam report, list of medications, etc.) that is stored on the Information Source system.
3.11.4.3.2 Message Semantics
The Retrieve Specific Information for Display transaction is performed by the invocation of a web service. The Display shall generate a web service request whenever a user needs to review the information stored as part of a patient’s clinical history on the Information Source Actor.
To specify the type of information to be returned, a web service request shall include the following parameters (keys) to filter the subset of information (see Table 3.11.4-7). All parameter names and values (see Table 3.11.4-7) are case-sensitive.
Table 3.11.4-6: Web Service Request Keys
| Parameter Name | REQ | Description | Notes |
| requestType | R | requestType specifies what type of information shall be retrieved. This parameter shall always be valued. | See Table 3.11.4-7 for the list of possible values. |
| patientID | R | This attribute identifies the subject of the results being queried for. Its value shall include identification of assigning authority. | PatientID value shall be formatted as HL7 CX data type (including assigning authority) according to the requirements specified for the Patient Identity Feed transaction (see Section 3.8.4.1.2.3) |
Table 3.11.4-7: Web Service Request Types
| requestType value | Description |
| LIST-ALLERGIES | List of allergies and adverse reactions for a patient known to the Information Source |
| LIST-MEDS | List of medications currently taken by or administered to a patient |
Formal definition of the web service in WSDL is provided in the ITI TF-2: Appendix A .
The only binding required for both Display and Information Source is the binding to the HTTP-GET. In this binding the sample message will be formatted as follows:
http://<location>/IHERetrieveListInfo?requestType=LIST-MEDS&patientID=99998410^^^%26www.mlhlife.com%26DNS
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 IHERetrieveListInfo 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 field of the HTTP request:
Table 3.11.4-8: HTTP Request and Response Fields
| HTTP Field | REQ | Description | Values |
| Accept-Language | O | This field restricts the set of natural languages that are preferred as a response to the request. | Any valid value according to RFC2616 |
The Information Source shall support the following field of the HTTP response.
Table 3.11.4-9: HTTP Request Fields
| HTTP Field | REQ | Description | Values |
| Expires | R | This field gives the date/time after which the response is considered stale | Shall be 0. This is now deprecated usage, but it is the widely supported means of specifying no caching. |
| Cache-Control | R | This field indicates that this response should not be cached. | Shall be no-cache |
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.11.4.3.3 Expected Actions
Upon reception of the Request for Specific Information, the Information Source shall parse the request and if there are no errors, shall return the Response with Specific Information as specified in Section 3.11.4.2, and HTTP response code 200 - OK.
If the requestType specified is not supported, the Information Source shall return HTTP response-code 404 (not found) 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 Patient ID specified by the Display is not known to the Information Source Actor, it shall return HTTP response-code 404 (not found) with the suggested reason-phrase “Patient ID not found”. If the Display provides the Patient ID from a different domain than the one the Information Source belongs to, and the Information Source is grouped with the Patient ID Consumer Actor, it may attempt to obtain a mapping of the provided Patient ID into its domain before responding.
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.11.4.4 Response with Specific Information - List
3.11.4.4.1 Trigger Events
This message is sent by the Information Source in response to the Request For Specific Information web service request.
3.11.4.4.2 Message Semantics
Information Source shall support at least one of the values of the requestType parameter specified in Table 3.11.4-7.
The Information Source shall set an expiration of zero to ensure no caching. The message shall be formatted using XHTML Basic and W3C HTML Compatibility Guidelines provided in the Appendix C of the W3C XHTML 1.0 Recommendation.
The Display may request the Information Source to provide a list of information items (pertaining to a particular patient) that the Information Source has presently recorded. The exact content of the list is determined by the Information Source Actor.
The Display shall not use the lowerDateTime, upperDateTime or mostRecentResults parameters in a query. The Information Source shall ignore them if they are specified.
3.11.4.4.3 Expected Actions
The Display shall render the received response for the user. It shall not assume that the content of the document may be meaningfully parsed beyond determination of XHTML tags necessary for accurate presentation of provided information.