SNOMED International Website

Get History Data

Overview

With each new release version of SNOMED CT there are requirements to manage changes in the terminology. One key element of this was covered by the requirements in section Identify Changes to the Terminology. However, in addition to this there is a requirement access data that indicates the reasons for each of those changes and data that, where possible, provides links to active content that replaces components that have been made inactive. This data is distributed in historical reference sets.

An historical reference set is a reference set that provides information about concepts or descriptions that have been inactivated.

Notes

  • There are two types of historical reference sets :

    • Inactivation Reference Sets which indicate the reason for inactivation of a particular component.

    • Historical Association Reference Sets which associate inactive concepts with one or more active concepts that represent the same, similar or a possible meaning of an inactive concept.

Requirements and Options

As noted in section Identify Changes to the Terminology it is important to identify concepts and descriptions that have been inactivated since an earlier version. Once this has been done:

The required services are listed in the following table.

Services Required

Service Name and Status
Input
Output

Get reason for description inactivation

  • Edition and version Identifier of an inactive description

  • Optional: Language/dialect1

Identifier and term representing the reason for inactivation of the description.

Get reason for concept inactivation

  • Edition and version Identifier of an inactive concept

  • Optional: Language/dialect1

Identifier and term representing the reason for inactivation of the concept.

Get historical associations between an inactive concept and one or more active concepts

  • Edition and version Identifier of an inactive concept

  • Optional: Language/dialect 1

Identifiers and term(s) of related active concept(s) and the nature of the historical association between the inactive and active concept.

Interdependencies

Required By

Depends On

Service Examples

The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).

Snowstorm API

Service Name
API Call 2
Result

Get reason for description inactivation

GET [snowstorm]/[branchPath]/members?active=true&referenceSet=900000000000490003|Description inactivation indicator attribute value reference set |&referencedComponentId=[inactiveDescriptionId]

for example

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=900000000000490003|Description inactivation indicator attribute value reference set |&referencedComponentId=78334016

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=900000000000490003%7CDescription+inactivation+indicator+attribute+value+reference+set+%7C&referencedComponentId=78334016

Returns a JSON representation of data related to the specified description.

A single reference set member is returned and the targetComponentId refers to a concept that indicates the reason for inactivation of the concept:

  • The referencedComponentId returned is the inactive concept to which the inactivation reason applies.

  • The additionalFields / valueId refers to the concept that indicates the reason for inactivation.

Get reason for concept inactivation

GET [snowstorm]/[branchPath]/members?active=true&referenceSet=900000000000489007|Concept inactivation indicator attribute value reference set|&referencedComponentId=[inactiveConceptId]

for example

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=900000000000489007|Concept inactivation indicator attribute value reference set|&referencedComponentId=20559007

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&referenceSet=900000000000489007%7CConcept+inactivation+indicator+attribute+value+reference+set%7C&referencedComponentId=20559007

Returns a JSON representation of data related to the specified concept.

A single reference set member is returned and the targetComponentId refers to a concept that indicates the reason for inactivation of the concept:

  • The referencedComponentId returned is the inactive concept to which the inactivation reason applies.

  • The additionalFields / valueId refers to the concept that indicates the reason for inactivation.

    • The preferred term and fully specified name associated with the valueId describe the reason for inactivation. These terms can be looked up using Snowstorm services listed in Get Terms for a Concept

Get historical associations between an inactive concept and one or more active concepts

GET [snowstorm]/[branchPath]/members?active=true&referenceSet=<900000000000522004|Historical association reference set|&referencedComponentId=[inactiveConceptId]

for example

GET [snowstorm]/MAIN/2020-01-31/members?active=true&referenceSet=<900000000000522004|Historical association reference set|&referencedComponentId=20559007

Encoded URL

GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&amp;amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C&amp;referencedComponentId=20559007

Returns a JSON representation of the historical association(s) of the specified inactive concept.

Each reference set member returned represents a historical association of the inactive concept with an active concept:

  • The refsetId indicates the specific historical reference set(s) in which associations are found. This represents the nature of the association.

    • The preferred term and fully specified name associated with the refsetId describe the association. These terms can be looked up using Snowstorm services listed in Get Terms for a Concept

    • If required, the refsetId returned can looked up using the get concept service to find the preferred term or fully specified name of the association reference set.

  • The referencedComponentId returned is the inactive concept to which the association applies.

  • The additionalFields / targetComponentId represents associated active concept.

  • In the case of an ambiguous concept, each reference set member represents one possible meaning of the inactive concept.

FHIR API

Service Name
API Call
Result

Get reason for description inactivation

N/A

The FHIR TS API does not provide a service for this purpose

Get reason for concept inactivation

N/A

The FHIR TS API does not provide a service for this purpose

Get historical associations between an inactive concept and one or more active concepts

The FHIR TS API supports retrieval of targets for specific SNOMED CT reference sets. Please refer to this document for detailed guidance: https://www.hl7.org/fhir/snomedct.html. Thus, the ConceptMap/$translate operation enables the retrieval of targets for a specific referenced component.

GET [fhir]/ConceptMap/$translate?code=[componentId] &system=http://snomed.info/sct &source=http://snomed.info/sct?fhir_vs &target=http://snomed.info/sct?fhir_vs &url=[version]?fhir_cm=[refesetId]

for example,

GET [snowstorm]/ConceptMap/$translate?code=134811001&system=http://snomed.info/sct&source=http://snomed.info/sct?fhir_vs&target=http://snomed.info/sct?fhir_vs&url=http://snomed.info/sct?fhir_cm=900000000000527005

Encoded URL

GET [snowstorm]/ConceptMap/$translate?code=134811001&amp;amp;amp;amp;system=http%3A%2F%2Fsnomed.info%2Fsct&amp;amp;amp;source=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs&amp;amp;target=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs&amp;url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_cm%3D900000000000527005

Returns a JSON representation of data about each of the target components.

The data returned for each concept includes:

  • boolean: True if the concept could be translated successfully. The value can only be true if at least one returned match

  • match: Each match represents data for the map or associated target. Note that there may be multiple matches, where each element represents a mapTarget. For each mapTarget, following data is provided

  • system: the codesystem of the mapTarget

  • code: The identifier of the mapTarget

The example shows the retrieval of the active replacement for the inactive concept 134811001 |Anaesthetist (occupation)|. The historical association reference set is the 900000000000527005 |SAME AS association reference set (foundation metadata concept)|, and the request result shows the concept Id of the active concept 88189002 |Anesthesiologist (occupation)|.

MySQL Example Database

Service Name
SQL Query
Result

Get reason for description inactivation

CALL setDeltaRange(1,[deltaStartTime], [deltaEndTime]);

SELECT * FROM delta_inactive_descriptions;

For example:

CALL setDeltaRange(1,'2019-07-31', '2020-01-31');
SELECT * FROM delta_inactive_descriptions;

Returns a row of data for each description inactivated after the deltaStartTime up to and including the deltaEndTime. Each row contains the following columns:

Columns

Description

id

Identifier of the inactivated description.

effectiveTime

Effective time of the row that inactivated the description

active

Active state of description. Should always be zero (0)

conceptid

Identifier of the concept to which the description applies

term

Term of the inactivated description

concept_fsn

The fully specified name of the concept.

concept_active

Active state of the concept.

reason

The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the description inactivation reference set.

Get reason for concept inactivation & historical associations

Returns one or more rows of data for each concept inactivated after the deltaStartTime up to and including the deltaEndTime. Each row contains the following columns:

id, effectiveTime, active, definitionStatusId, FSN, reason, assoc_type, ref_conceptId, ref_concept_FSN

Columns

Description

id

Identifier of the inactivated concept

effectiveTime

Effective time of the row that inactivated the concept

active

Active state of concept. Should always be zero (0)

definitionStatusId

Definition status of the inactivated concept

FSN

Fully specified name of the inactivated concept

reason

The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the concept inactivation reference set.

assoc_type

The preferred term for the name of the association reference set containing the association between the inactive and active concept.

ref_conceptId

The identifier of the active concept (or one of the active concepts) with which the inactive concept is associated.

ref_concept_FSN

The fully specified name of the active concept with which the inactive concept is associated.

Note that in the case of a concept that has been inactivated due to ambiguity, there will usually be two or more rows in the results, one for each possible meaning represented by an active concepts. However, in some cases it is possible that only one of the possible meanings is represented by an active concept

PreviousGet Data from a Reference SetNextGet Mapping Data

Last updated