IHE ITI Technical Framework
  • IHE IT Infrastructure (ITI) Technical Framework, Volume
    Revision 20.0, August 4, 2023 – Final Text
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.60 Retrieve Multiple Value Sets [ITI-60]

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

3.60.1 Scope

This transaction is used by the Value Set Consumer to retrieve Value Sets from the Value Set Repository.

3.60.2 Use case roles

Actors: Value Set Consumer

Role: Requests all Value Sets that match request parameters

Actor:   Value Set Repository

Role:   Provides matching Value Sets and associated metadata

3.60.3 Referenced Standards

The referenced standards are:

Table 3.60.3-1: 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
POSIX 1003.2 IEEE Std 1003.2 IEEE Standard for Information Technology — Portable Operating System Interface (POSIX®) — Part 2: Shell and Utilities — Amendment 1: Batch Environment -Description

3.60.4 Messages

Figure 3.60.4-1: Interaction Diagram

Figure 3.60.4-1: Interaction Diagram

3.60.4.1 Retrieve Multiple Value Sets Request

3.60.4.1.1 Trigger Events

The Value Set Consumer wants to retrieve value sets and has one or more element values to be matched in the metadata that describes value sets. This could be from pre-configuration or user input. The value sets that match these element values are needed for processing by the Value Set Consumer. The Value Set Consumer sends a Retrieve Multiple Value Sets Request to the Value Set Repository. Table 3.60.4.1.1-1 summarizes the metadata elements. See the schema for precise encoding details.

Table 3.60.4.1.1-1: Metadata Summary

Metadata Element Description Mandatory within Metadata returned Usable as Selection Criterion
id This is the unique identifier of the value set Mandatory Y
displayName This is the name of the value set Mandatory Y
Source This is the source of the value set, identifying the originator or publisher of the information Mandatory Y
Purpose Brief description about the general purpose of the value set Optional Y
Definition A text definition describing how concepts in the value set were selected Optional Y
Source URI Most sources also have a URL or document URI that provides further details regarding the value set. Optional N
Version A string identifying the specific version of the value set. Mandatory N
Status Active, Inactive, local extensions Mandatory N
Type

This describes the type of the value set. It shall be:

  • Intensional,
  • Extensional, or
  • Expanded

Note: This is the type of the value set in the repository. The ConceptList that will also be returned is the current expansion of the value set.

 Mandatory N
Binding Shall be “Static” or “Dynamic” Optional N
Effective Date The date when the value set is expected to be effective Optional Y
Expiration Date The date when the value set is no longer expected to be used Optional Y
Creation Date The date of creation of the value set Optional Y
Revision Date The date of revision of the value set Optional Y
Group The identifiers and keywords of the groups that include this value set. A group may also have an OID assigned. Optional Y
3.60.4.1.2 Message Semantics

The Retrieve Multiple Value Sets Request shall specify retrieval selection parameters as shown in the Table 3.60.4.1.2-1. It requests retrieval of all concept lists that have metadata matching the parameters used. At least one request parameter shall be provided.

Table 3.60.4.1.2-1: The Request Parameters in the RetrieveMultipleValueSets Request

Parameter Parameter Format Metadata Element Match Type Match Rules Note
id OID id OID equals
DisplayNameContains string Name Regex regex POSIX rules
SourceContains string Source Regex regex POSIX rules
PurposeContains string Purpose Regex regex POSIX rules
DefinitionContains string Definition Regex regex POSIX rules
GroupContains string Group Regex regex POSIX rules
GroupOID OID Group OID equals Equality match for OID attribute of a Group element
EffectiveDateBefore http-date EffectiveDate date Before or equal Date comparison to the day
EffectiveDateAfter http-date EffectiveDate date Equal or after Date comparison to the day
ExpirationDateBefore http-date ExpirationDate date Before or equal Date comparison to the day
ExpirationDateAfter http-date ExpirationDate date Equal or after Date comparison to the day
CreationDateBefore http-date CreationDate date Before or equal Date comparison to the day
CreationDateAfter http-date CreationDate date Equal or after Date comparison to the day
RevisionDateBefore http-date RevisionDate date Before or equal Date comparison to the day
RevisionDateAfter http-date RevisionDate date Equal or after Date comparison to the day
Format String n/a n/a n/a This specifies the format for the returned information. Shall be “CE-List” if present.
3.60.4.1.3 Expected Actions

The Value Set Repository shall perform matching in accordance with the rules in Table 3.60.4.1.2-1.

  • Regex matches shall compare the contents of the referenced metadata field with the regex using the POSIX matching rules. If the regex matches the field, the value set matches.
  • OID matching compares only for equal OIDs, ignoring leading zeroes.
  • Date comparisons convert the argument into a date, and compare it with the dates in the metadata using a date comparison. Equality means the same day.

Any value set that matches all of the request parameters shall be included in the response.

Note:   Multiple queries will sometimes be needed. Rather than specify a complex query mechanism, the Retrieve Multiple Value Sets request expects the client or user to locally eliminate any extra value sets and make additional queries. Value sets are relatively small and compress very well, so these extras are not a significant communications burden. Performing the final steps of selecting the value sets based on having the full metadata present locally allows a much richer and potentially interactive selection process. It also allows a simpler and more robust server.

3.60.4.2 Retrieve Multiple Value Sets Response

3.60.4.2.1 Trigger Events

This message will be triggered by completion of matching for a Retrieve Multiple Value Sets Request Message.

3.60.4.2.2 Message Semantics

The response shall be a Retrieve Multiple Value Sets Response as specified in the XML schema defining RetrieveMultipleValueSetsResponse which can be accessed online:  see ITI TF-2: Appendix W .

The RetrieveMultipleValueSetsResponse element shall have one DescribedValueSet element for each matching value set found. If no matching elements are found, it shall be empty.

Each DescribedValueSet element contains:

  • An id attribute, a mandatory OID, the OID for this value set
  • A displayName attribute, a mandatory string, the name of this value set
  • Source , an optional string, the source organization for this value set
  • SourceURI , an optional URI, a URI providing more description of this value set,
  • Purpose , an optional string, a description of the intended use of this value set
  • Definition , an optional string, a definition of the value set provided by the source
  • A version attribute, a mandatory string, a version in the format used by the source,
  • Status , an optional string, the status at time of retrieval (e.g., Active or Inactive)
  • Type, a mandatory string that indicates whether this is an intensional, extensional, or expanded value set.
  • Binding, an optional string, either static or dynamic .
  • EffectiveDate , an optional XML-date, the initial effective date for this value set
  • ExpirationDate , an optional XML-date, the intended expiration date for this value set
  • CreationDate , an optional XML-date, the creation date of this value set,
  • RevisionDate , an optional XML-date, the revision date of this value set,
  • Zero or more Group elements, where each Group element has
  • an optional id attribute containing the OID for the group.
  • An optional displayName attribute , containing the name for the group,
  • An optional sourceOrganization attribute , containing the name of the organization that defined the group.
  • Zero or more Keyword elements that contain keywords associated with the group.
  • One ConceptList , that contains
  • One or more Concept , encoded using the HL7 CE datatype. These are the codes that are members of the expanded form of the value set.
  • With an optional attribute xml:lang to indicate the language for the displayname for these concepts.

The ConceptList element and structure is the same in both the [ITI-48] and [ITI-60] transactions. The Identifier OID in the [ITI-60] response is the OID used in the [ITI-48] transaction when the value set is an expanded value set. It will not match in other cases.

A sample RetrieveMultipleValueSetsResponse is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<RetrieveMultipleValueSetsResponse xmlns="urn:ihe:iti:svs:2008" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:ihe:iti:svs:2008:SVS.xsd">
    <DescribedValueSet id="1.2.3" displayName="placeholder" version="version1">
            <ConceptList xml:lang="en-US">
                <Concept code="code1" codeSystem="2.3.4" codeSystemName="codeSystemName1" codeSystemVersion="codeSystemVersion1" displayName="displayName1">
                    </Concept>
                <Concept code="code7" codeSystem="2.3.4" codeSystemName="codeSystemName1" codeSystemVersion="codeSystemVersion1" displayName="displayName7">
                    </Concept>
         </ConceptList>
         <Source>Codingsource</Source>

         <SourceURI>http://www.codingsource.com/placeholder</SourceURI>
         <Purpose>Purpose0</Purpose>
         <Definition>Definition0</Definition>
         <Type>Expanded</Type>
         <Binding>Static</Binding>
         <Status>Status0</Status>
         <EffectiveDate>2006-05-04</EffectiveDate>
         <ExpirationDate>2011-09-04</ExpirationDate>
         <CreationDate>2006-05-04</CreationDate>
         <RevisionDate>2006-05-04</RevisionDate>
             <Group id="2.4.5" sourceOrganization="sourceOrganization1" displayName="displayName15">
                 <Keyword>Keyword0</Keyword>
                 <Keyword>Keyword1</Keyword>
             </Group>
             <Group id="2.4.54" sourceOrganization="sourceOrganization3" displayName="displayName17">
                 <Keyword>Keyword2</Keyword>
                 <Keyword>Keyword3</Keyword>
             </Group>
    </DescribedValueSet>
</RetrieveMultipleValueSetsResponse>

3.60.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.60.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.60.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 RetrieveMultipleValueSets 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:RetrieveMultipleValueSetsRequest”

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

The /definitions/portType/operation/input/@wsaw:Action attribute for the Retrieve Multiple Value Sets Request message shall be defined as “ urn:ihe:iti:2010:RetrieveMultipleValueSets”

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

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.

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

  • An optional /ihe:RetrieveMultipleValueSetsRequest@id element 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:RetrieveMultipleValueSetsRequest@DisplayNameContains element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@SourceContains element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@PurposeContains element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@DefinitionContains element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@GroupContains element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@GroupOID element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@EffectiveDateBefore element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@EffectiveDateAfter element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@ExpirationDateBefore element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@ExpirationDateAfter element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@CreationDateBefore element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@CreationDateAfter element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@RevisionDateBefore element
  • An optional /ihe:RetrieveMultipleValueSetsRequest@RevisionDateAfter element

Value Set Repositories shall include within the response message payload for the SOAP Binding Option the <ihe:RetrieveMultipleValueSetsResponse/> element which is described above in Section 3.60.4.2.2.

3.60.5.2 HTTP Binding

Value Set Consumers which support the HTTP Binding Option shall use the GET method as defined in IETF RFC2616 for the Retrieve Value Set Request. Each parameter to be used for selection shall be encoded as an HTTP Get parameter.

A sample URL for the HTTP binding for a query to retrieve all value sets for a reporting purpose, with either “stroke” or “JCAHO” in the value set name looks as follows:

  https://example.com/RetrieveMultipleValueSets?DisplayNameContains=”stroke|JCAHO”&PurposeContains=”report”

Value Set Repositories shall format the response to the HTTP GET operation as an HTTP response message as defined in 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 RetrieveMultipleValueSetsResponse, as described in Section 3.60.4.2.2.

3.60.6 Security Requirements

The value sets do not contain personal information. In some cases, the value sets are created by standards organizations with the intention that they be or publicly shared. In other cases, there may be licensing or other proprietary restrictions on their disclosure. These licenses or restrictions are at the organizational level, not at the level of individual users. This greatly reduces the security needs and eliminates privacy concerns.

For further security considerations please consult ITI TF-1: Appendix G .

Audit trails shall be configurable to record access to a selected list of Value Sets. In most cases, there is no need to audit the value set request activity, but there may be some exceptional cases where auditing will be needed. See Section 3.48.6.1 for audit record recommendations in those cases.

This profile does not attempt to establish rules for managing security on proprietary value sets with licensing or access restrictions.