IHE ITI TF Vol2

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>

</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 Role ID")
	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 Role ID")
	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

not specialized

AuditEnterpriseSiteID

not specialized

AuditSourceTypeCode

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 Role ID")
	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 Role ID")
	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

not specialized

AuditEnterpriseSiteID

not specialized

AuditSourceTypeCode

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>