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

3.48 Retrieve Value Set [ITI-48]

This section corresponds to transaction [ITI-48] of the IHE IT Infrastructure Technical Framework. The Value Set Consumer and Value Set Repository Actors use transaction [ITI-48].

3.48.1 Scope

This transaction is used by the Value Set Consumer to retrieve an Expanded Value Set from the Value Set Repository. The Value Set Consumer has previously obtained the Expanded Value Set OID by means outside of the scope of this transaction. ITI TF-2: Appendix B has further information about obtaining and managing OIDs which are used as the Value Set Unique ID.

3.48.2 Use case roles

SVS Actors:

Actor: Value Set Consumer

Role: Obtains an Expanded Value Set

Actor: Value Set Repository

Role: Provides an Expanded Value Set

3.48.3 Referenced Standards

Appendix V

ITI TF-2: Appendix V Web Services for IHE Transactions

Contains references to all Web Services standards and requirements of use

HL7 v3 Data Type XML ITS HL7 Version 3 Standard: XML Implementation Technology Specifications – Data Types, R1
HTTP 1.1 IETF RFC2616: Hypertext Transfer Protocol – HTTP 1.1

 

3.48.4 Messages

Figure 3.48.4-1: Interaction Diagram

3.48.4.1 Retrieve Value Set Request

3.48.4.1.1 Trigger Events

Having obtained the Value Set OID, the Value Set Consumer will send the Retrieve Value Set Request to the Value Set Repository.

3.48.4.1.2 Message Semantics

The Retrieve Value Set Request shall carry the following information:

  • A required id, representing the Value Set OID that identifies the Expanded Value Set within the Repository.
  • An optional version that identifies a specific version of the Expanded Value Set. If no version is specified, the Value Set Consumer is requesting the most recent version of the Value Set
  • An optional lang parameter indicating the requested language locale for the displayName of the Value Set Concepts. (Note: in the SOAP binding, this parameter is represented via the xml:lang XML attribute)

Section 3.48.5 describes the Web Services protocol requirements and the format of the message in full detail.

3.48.4.1.3 Expected Actions

When receiving a Retrieve Value Set Request, a Value Set Repository shall generate a Retrieve Value Set Response containing the Expanded Value Set that corresponds to the request parameters or an error code if the Value Set could not be retrieved. If no version is specified in the Request, then the most recent version shall be returned.

The Value Set Repository shall support both the SOAP and HTTP bindings for this transaction. If the Value Set Consumer sends the request using the SOAP binding, the Value Set Repository shall respond using the SOAP binding. If the Value Set Consumer sends the request using the HTTP binding, the Value Set Repository shall respond using the HTTP binding.

3.48.4.2 Retrieve Value Set Response

3.48.4.2.1 Trigger Events

This message will be triggered by a Retrieve Value Set Request Message.

3.48.4.2.2 Message Semantics

The Retrieve Value Set Response Message shall carry the following information for the returned Expanded Value Set:

  • A required id, representing the Value Set OID that identifies the Value Set within the Value Set Repository. This OID shall be the same as the Value Set OID in the received Retrieve Value Set Request Message.
  • A required displayName that can be used for display purposes.
  • An optional version that shall be present if the Expanded Value Set has a version, that identifies the specific version of the Value Set returned.
  • An optional cacheExpirationHint indicating that the Value Set Consumer is not expected to change before this date and time. If the request and the response use the HTTP binding, this information shall be also present in the HTTP Expire header of the response. For details, please see Section 14.21 of IETF RFC2616.
  • One or more ConceptList, which provides the Concepts of the Expanded Value Set. If there are multiple translations of the Value Set, each translation is returned as a separate ConceptList, where only the displayName of each Concept, and the language locale represented by xml:lang are different.

For each Value Set Concept, the following is returned. These requirements override the requirements of the HL7 schema rules for the CE data type where they conflict.

  • A required code (a code that uniquely identifies a class or concept within the context of a code system)
  • A required displayName (the name of the concept)
  • A required codeSystem (the OID for the terminology the concept comes from)
  • An optional codeSystemName (the common name for the codeSystem)
  • An optional codeSystemVersion. (the version of the terminology the concept comes from)

Section 3.48.5 describes the Web Services requirements and the format of the message in full detail.

3.48.4.2.3 Expected Actions

A Value Set Repository shall return the Expanded Value Set indicated in the request.

If the Value Set Consumer requested a specific language locale, the Value Set Repository shall return only the requested translation of the Expanded Value Set. If the Value Set Consumer did not request a specific language locale, the Value Set Repository shall return all known translations of the Expanded Value Set. This is the only case where more than one ConceptList XML element shall be permitted. The ConceptList shall have the same code values for the Value Set in question; the displayName may have a different value appropriate to the locale.

The Value Set Repository shall return the Expanded Value Set or an error code in case the Value Set could not be expanded. The following error responses may be returned:

  • For the SOAP binding:
    • A SOAP fault, whose code value is NAV, with the reason being: “Unknown value set”.
    • A SOAP fault, whose code value is VERUNK, with the reason being: “Version unknown”.
  • For the HTTP binding:
    • An HTTP status code of 404, with an HTTP Warning header containing warn-code of 111, and warn-text of “NAV: Unknown value set”. See sections 10.4.5 and 14.46 of IETF RFC2616 for more information.
    • An HTTP status code of 404, with an HTTP Warning header containing warn-code of 112, and warn-text of “VERUNK: Version unknown”. See sections 10.4.5 and 14.46 of IETF RFC2616 for more information.

3.48.5 Protocol Requirements

The protocol for the Retrieve Value Set transaction describes two bindings. The first is based on SOAP 1.2, and the second is an HTTP binding. The relevant XML namespace definitions can be seen in Table 3.48.5-1 WSDL Namespace Definitions.

Table 3.48.5-1: WSDL Namespace Definitions

soap12 http://schemas.xmlsoap.org/wsdl/soap12/
wsaw http://www.w3.org/2006/05/addressing/wsdl/
xsd

http://www.w3.org/2001/XMLSchema

ihe urn:ihe:iti:svs:2008

3.48.5.1 SOAP Binding

Value Set Consumers which support the SOAP Binding Option shall follow the rules for Web Services transactions outlined in ITI TF-2: Appendix V. These are the requirements for the Retrieve Value Set 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:svs:2008", schema="SVS.xsd"

The /definitions/message/part/@element attribute of the Retrieve Value Set Request message shall be defined as “ ihe:RetrieveValueSetRequest

The /definitions/message/part/@element attribute of the Retrieve Value Set Response message shall be defined as “ ihe:RetrieveValueSetResponse

The /definitions/portType/operation/input/@wsaw:Action attribute for the Retrieve Value Set Request message shall be defined as “ urn:ihe:iti:2008:RetrieveValueSet

The /definitions/portType/operation/output/@wsaw:Action attribute for the Retrieve Value Set Response message shall be defined as “ urn:ihe:iti:2008:RetrieveValueSetResponse

The /definitions/binding/operation/soap12:operation/@soapActionRequired attribute shall be defined as “false

These are the requirements that affect the wire format of the SOAP message. The other WSDL properties are only used within the WSDL definition and do not affect interoperability. Full sample request and response messages are in Section 3.48.5.3 Sample SOAP Message.

Within the request message payload the <ihe:RetrieveValueSetRequest/> element is defined as:

  • A required /ihe:RetrieveValueSetRequest/ihe:ValueSet element
  • A required /ihe:RetrieveValueSetRequest/ihe:ValueSet@id attribute that contains the ID of the requested Value Set within the Value Set Repository. The Value Set ID shall be formatted as an ISO OID.
  • An optional /ihe:RetrieveValueSetRequest/ihe:ValueSet@displayName attribute
  • An optional /ihe:RetrieveValueSetRequest/ihe:ValueSet@version attribute.
  • An optional /ihe:RetrieveValueSetRequest/ihe:ValueSet@xml:lang attribute.

Value Set Repositories shall include within the response message payload for the SOAP Binding Option the <ihe:RetrieveValueSetResponse/> element which contains:

An optional /ihe:RetrieveValueSetResponse@cacheExpirationHint attribute, indicating that the Value Set Consumer should obtain a new copy before this date and time.

A required /ihe:RetrieveValueSetResponse/ihe:ValueSet element, containing

  • a required /ihe:RetrieveValueSetResponse/ihe:ValueSet@id attribute
  • a required /ihe:RetrieveValueSetResponse/ihe:ValueSet@displayName attribute
  • an optional /ihe:RetrieveValueSetResponse/ihe:ValueSet@version attribute
  • one or more /ihe:RetrieveValueSetResponse/ihe:ValueSet/ihe:ConceptList element, containing:
  • /ihe:RetrieveValueSetResponse/ihe:ValueSet/ihe:ConceptList/xml:lang attribute, representing the language locale of the Concept’s display names
  • one or more /ihe:RetrieveValueSetResponse/ihe:ValueSet/ihe:ConceptList/ihe:Concept elements, representing the concepts within the value set.

The <ihe:Concept/> element is defined as being of the HL7 V3 CE data type.

The only occurrence of more than one ConceptList element in a response message shall be for the purpose of returning multiple language representations of the same value set.

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

3.48.5.2 HTTP Binding

Value Set Consumers which support the HTTP Binding Option shall use the GET method as defined in RFC2616 for the Retrieve Value Set Request.

3.48.5.2.1 Request Parameters

There are three input parameters, to be provided as part of the URL in the GET request. The parameter values have identical meaning to the ones described in the SOAP binding. These are described in Table 3.48.5.2.1-1.

Table 3.48.5.2.1-1: The Request Parameters in the RetrieveMultipleValueSets request

Parameter Optionality Note
Id Required Unique identifier of the Value Set.
Version Optional The Value Set version.
lang Optional The language locale of the Value Set. If present, it shall be encoded as a string from the set of languages listed in IETF RFC5646 (identical to the values of xml:lang, described in the SOAP binding). If present, the Accept-Language field of the HTTP Header may also contain the same value (see Section 14.4 of IETF RFC2616).

The full URL for the HTTP binding looks as follows:

https://example.com/RetrieveValueSet?id=1.2.840.10008.6.1.308&version=20061023&lang=en-US

Note:   “en-US” will not match “en”. For applications that need a more sophisticated user sensitive language matching capability, omitting the lang parameter will return all languages so that the application can make a determination of which language best fits the current user.

3.48.5.2.2 HTTP Response

Value Set Repositories shall format the response to the HTTP GET operation as an HTTP response message as defined in IETF RFC2616.

The Content-Type field of the HTTP header shall be “text/xml” (see Section 14.4 of IETF RFC2616).

The content of the HTTP response message shall be an XML encoded Expanded Value Set that complies with the SVS schema. The XML format shall be identical to the body of the SOAP response described in the SOAP binding. The Expanded Value Set shall correspond to the Values Set identified by the Value Set Unique ID in the id parameter, the Value Set Version in the version parameter, and the language in the lang parameter.

An informative WSDL file containing both SOAP and HTTP bindings for the Value Set Repository can be found online : see ITI TF-2: Appendix W.

3.48.5.3 Sample SOAP Messages

The samples in the following two sections show a typical SOAP request and its corresponding 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.

All of the samples presented in this section are also available online:  see ITI TF-2: Appendix W.

3.48.5.3.1 Sample Retrieve Value Set SOAP Request

<?xml version="1.0" encoding="UTF-8"?>
<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:2008:RetrieveValueSet</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://valuesetrepository/</a:To>
    </s:Header>
    <s:Body>
        <RetrieveValueSetRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns="urn:ihe:iti:svs:2008">
            <ValueSet id="1.2.840.10008.6.1.308" xml:lang="en-EN"/>
        </RetrieveValueSetRequest>
    </s:Body>
</s:Envelope>

3.48.5.3.2 Sample Retrieve Value Set SOAP Response

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

<s:Envelope xmlns:a="http://www.w3.org/2005/08/addressing"

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

    <s:Header>

        <a:Action s:mustUnderstand="1">urn:ihe:iti:2008:RetrieveValueSetResponse</a:Action>

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

    </s:Header>

    <s:Body>

        <RetrieveValueSetResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

            xmlns="urn:ihe:iti:svs:2008" cacheExpirationHint="2008-08-15T00:00:00-05:00">

            <ValueSet id="1.2.840.10008.6.1.308"

                displayName="Common Anatomic Regions Context ID 4031">

                <ConceptList xml:lang="en-US">

                    <Concept code="818981001" displayName="Abdomen" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="818982008" displayName="Abdomen and Pelvis" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="85856004" displayName="Acromioclavicular joint" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="70258002" displayName="Ankle joint " codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="86598002" displayName="Apex of Lung" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="28273000" displayName="Bile Duct" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="89837001" displayName="Bladder" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="76752008" displayName="Breast" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="9559009" displayName="Bronchus" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="8014404" displayName="Calcaneus" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                    <Concept code="122494005" displayName="Cervical spine" codeSystem="2.16.840.1.113883.6.96" codeSystemName="SCT"/>

                </ConceptList>

            </ValueSet>

        </RetrieveValueSetResponse>

    </s:Body>

</s:Envelope>

3.48.6 Security Requirements

For security considerations please consult ITI TF-1: 21.4.

Audit trails shall be configurable to record access to a selected list of Value Sets.

3.48.6.1 Audit Record Considerations

The Retrieve Value Set transaction is an Import/Export event as defined in ITI TF-2: Table 3.20.4.1.1.1-1with the following exceptions.

3.48.6.1.1 Value Set Consumer audit message:
Field Name Opt Value Constraints

Event

AuditMessage/
EventIdentification

EventID M EV(110107, DCM, “Import”)
EventActionCode M “C” (Create) or “U” (Update)
EventDateTime M not specialized
EventOutcomeIndicator M not specialized
EventTypeCode M

EV(“ITI-48”, “IHE Transactions”, “Retrieve Value Sets”) or

EV(“ITI-60”,”IHE Transactions”,”Retrieve Multiple Value Sets”)

Source (Value Set Repository) (1)
Human Requestor (0..n)
Destination (Value Set Consumer) (1)
Audit Source (Value Set Consumer) (1)
ValueSetInstance (1)

Where:

Source

A uditMessage/
ActiveParticipant

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

Destination

AuditMessage/
ActiveParticipant

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

Human Requestor (if known)

AuditMessage/
ActiveParticipant

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

Audit Source

AuditMessage/
AuditSourceIdentification

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

Value Set Instance

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “2” (System)
ParticipantObjectTypeCodeRole M “3” (Report)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M not specialized
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The value of <Value Set Unique ID>
ParticipantObjectName O The value of <Value Set name>
ParticipantObjectQuery U not specialized
ParticipantObjectDetail O The value of <Value Set Version>
3.48.6.1.2 Value Set Repository audit message:
Field Name Opt Value Constraints

Event

AuditMessage/
EventIdentification

EventID M EV(110106, DCM, “Export”)
EventActionCode M “R” (Read)
EventDateTime M not specialized
EventOutcomeIndicator M not specialized
EventTypeCode M

EV(“ITI-48”, “IHE Transactions”, “Retrieve Value Sets”) or

EV(“ITI-60”,”IHE Transactions”,”Retrieve Multiple Value Sets”)

Source (Value Set Repository) (1)
Human Requestor (0..n)
Destination (Value Set Consumer) (1)
Audit Source (Value Set Source) (1)
ValueSetInstance (1)

Where:

Source

AuditMessage/
ActiveParticipant

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

Destination

AuditMessage/
ActiveParticipant

UserID U not specialized
AlternativeUserID U not specialized
UserName U not specialized
UserIsRequestor U not specialized
RoleIDCode M EV(110152, DCM, “Destination”)
NetworkAccessPointTypeCode M “1” for machine (DNS) name, “2” for IP address
NetworkAccessPointID M The machine name or IP address.

Human Requestor (if known such as through XUA)

AuditMessage/
ActiveParticipant

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

Audit Source

AuditMessage/
AuditSourceIdentification

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

Value Set Instance

(AuditMessage/
ParticipantObjectIdentification)

ParticipantObjectTypeCode M “2” (System)
ParticipantObjectTypeCodeRole M “3” (Report)
ParticipantObjectDataLifeCycle U not specialized
ParticipantObjectIDTypeCode M not specialized
ParticipantObjectSensitivity U not specialized
ParticipantObjectID M The value of <Value Set Unique ID>
ParticipantObjectName O The value of <Value Set name>
ParticipantObjectQuery U not specialized
ParticipantObjectDetail M The value of <Value Set Version>