# 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](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.9-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](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.9-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:

* Information about the reasons for inactivation of each description should be accessed from the [900000000000490003 | Description inactivation indicator attribute value reference set|](http://snomed.info/id/900000000000490003)
* Information about the reasons for inactivation of each concept should be accessed from the [900000000000489007 | Concept inactivation indicator attribute value reference set|](http://snomed.info/id/900000000000489007)
* Associations between each inactivated concepts and active concepts which represent similar meanings must be accessed from one of the < [900000000000522004 | Historical association reference set|](http://snomed.info/id/900000000000522004) subtypes.

The required services are listed in the following table.

#### Services Required

<table data-full-width="true"><thead><tr><th>Service Name and Status</th><th>Input</th><th>Output</th></tr></thead><tbody><tr><td><strong>Get reason for description inactivation</strong></td><td><ul><li>Edition and version Identifier of an inactive description</li><li>Optional: Language/dialect1</li></ul></td><td>Identifier and term representing the reason for inactivation of the description.</td></tr><tr><td><strong>Get reason for concept inactivation</strong></td><td><ul><li>Edition and version Identifier of an inactive concept</li><li>Optional: Language/dialect1</li></ul></td><td>Identifier and term representing the reason for inactivation of the concept.</td></tr><tr><td><strong>Get historical associations between an inactive concept and one or more active concepts</strong></td><td><ul><li>Edition and version Identifier of an inactive concept</li><li>Optional: Language/dialect 1</li></ul></td><td>Identifiers and term(s) of related active concept(s) and the nature of the historical association between the inactive and active concept.</td></tr></tbody></table>

## Interdependencies

### Required By

* **Use Cases**
  * [Manage Impact of Changes on EHR Applications](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/terminology-change-management#manage-impact-of-changes-on-ehr-applications)
  * [Manage Impact of Changes on Extensions](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/terminology-change-management#manage-impact-of-changes-on-extensions)

### Depends On

* [Select Edition and Version](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.1-select-edition-and-version)
* [Identify Changes to the Terminology](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.9-identify-changes-to-the-terminology)
* [Get Data from a Reference Set](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.10-get-data-from-a-reference-set)

## 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](https://www.ietf.org/rfc/rfc1738.txt)).

### Snowstorm API

<table data-full-width="true"><thead><tr><th width="116.24609375">Service Name</th><th>API Call 2</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get reason for description inactivation</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branchPath]/members?active=true&#x26;referenceSet=900000000000490003|Description inactivation indicator attribute value reference set |&#x26;referencedComponentId=[inactiveDescriptionId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&#x26;referenceSet=900000000000490003|Description inactivation indicator attribute value reference set |&#x26;referencedComponentId=78334016
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&#x26;amp;amp;referenceSet=900000000000490003%7CDescription+inactivation+indicator+attribute+value+reference+set+%7C&#x26;amp;referencedComponentId=78334016
</code></pre></td><td><p>Returns a JSON representation of data related to the specified description.</p><p>A single reference set member is returned and the targetComponentId refers to a concept that indicates the reason for inactivation of the concept:</p><ul><li>The referencedComponentId returned is the inactive concept to which the inactivation reason applies.</li><li><p>The additionalFields / valueId refers to the concept that indicates the reason for inactivation.</p><ul><li>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 <a href="https://confluence.ihtsdotools.org/display/DOCTSG/4.3+Get+Terms+for+a+Concept#Table-snowstorm-api">4.3 Get Terms for a Concept: Table 2 Snowstorm API</a>.</li></ul></li></ul></td></tr><tr><td><strong>Get reason for concept inactivation</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branchPath]/members?active=true&#x26;referenceSet=900000000000489007|Concept inactivation indicator attribute value reference set|&#x26;referencedComponentId=[inactiveConceptId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referenceSet=900000000000489007|Concept inactivation indicator attribute value reference set|&#x26;referencedComponentId=20559007
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&#x26;amp;amp;referenceSet=900000000000489007%7CConcept+inactivation+indicator+attribute+value+reference+set%7C&#x26;amp;referencedComponentId=20559007
</code></pre></td><td><p>Returns a JSON representation of data related to the specified concept.</p><p>A single reference set member is returned and the targetComponentId refers to a concept that indicates the reason for inactivation of the concept:</p><ul><li>The referencedComponentId returned is the inactive concept to which the inactivation reason applies.</li><li><p>The additionalFields / valueId refers to the concept that indicates the reason for inactivation.</p><ul><li>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 <a href="../4.3-get-terms-for-a-concept#snowstorm-api">Get Terms for a Concept</a></li></ul></li></ul></td></tr><tr><td><strong>Get historical associations between an inactive concept and one or more active concepts</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branchPath]/members?active=true&#x26;referenceSet=&#x3C;900000000000522004|Historical association reference set|&#x26;referencedComponentId=[inactiveConceptId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referenceSet=&#x3C;900000000000522004|Historical association reference set|&#x26;referencedComponentId=20559007
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&#x26;amp;amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C&#x26;amp;referencedComponentId=20559007
</code></pre></td><td><p>Returns a JSON representation of the historical association(s) of the specified inactive concept.</p><p>Each reference set member returned represents a historical association of the inactive concept with an active concept:</p><ul><li><p>The refsetId indicates the specific historical reference set(s) in which associations are found. This represents the nature of the association.</p><ul><li>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 <a href="../4.3-get-terms-for-a-concept#snowstorm-api">Get Terms for a Concept</a></li><li>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.</li></ul></li><li>The referencedComponentId returned is the inactive concept to which the association applies.</li><li>The additionalFields / targetComponentId represents associated active concept.</li><li>In the case of an ambiguous concept, each reference set member represents one possible meaning of the inactive concept.</li></ul></td></tr></tbody></table>

### FHIR API

<table data-full-width="true"><thead><tr><th>Service Name</th><th>API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get reason for description inactivation</strong></td><td>N/A</td><td>The FHIR TS API does not provide a service for this purpose</td></tr><tr><td><strong>Get reason for concept inactivation</strong></td><td>N/A</td><td>The FHIR TS API does not provide a service for this purpose</td></tr><tr><td><strong>Get historical associations between an inactive concept and one or more active concepts</strong></td><td><p>The FHIR TS API supports retrieval of targets for specific SNOMED CT reference sets. Please refer to this document for detailed guidance: <a href="https://www.hl7.org/fhir/snomedct.html">https://www.hl7.org/fhir/snomedct.html</a>. Thus, the ConceptMap/$translate operation enables the retrieval of targets for a specific referenced component.</p><pre data-overflow="wrap"><code><strong>GET [fhir]/ConceptMap/$translate?code=[componentId] &#x26;system=http://snomed.info/sct &#x26;source=http://snomed.info/sct?fhir_vs &#x26;target=http://snomed.info/sct?fhir_vs &#x26;url=[version]?fhir_cm=[refesetId]
</strong></code></pre><p>for example,</p><pre data-overflow="wrap"><code>GET [snowstorm]/ConceptMap/$translate?code=134811001&#x26;system=http://snomed.info/sct&#x26;source=http://snomed.info/sct?fhir_vs&#x26;target=http://snomed.info/sct?fhir_vs&#x26;url=http://snomed.info/sct?fhir_cm=900000000000527005
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code><strong>GET [snowstorm]/ConceptMap/$translate?code=134811001&#x26;amp;amp;amp;amp;system=http%3A%2F%2Fsnomed.info%2Fsct&#x26;amp;amp;amp;source=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs&#x26;amp;amp;target=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs&#x26;amp;url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_cm%3D900000000000527005
</strong></code></pre></td><td><p>Returns a JSON representation of data about each of the target components.</p><p>The data returned for each concept includes:</p><ul><li><strong>boolean:</strong> True if the concept could be translated successfully. The value can only be true if at least one returned match</li><li><strong>match:</strong> 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</li><li><strong>system</strong>: the codesystem of the mapTarget</li><li><strong>code:</strong> The identifier of the mapTarget</li></ul><p><strong>The example</strong> 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)|.</p></td></tr></tbody></table>

#### MySQL Example Database

<table data-full-width="true"><thead><tr><th width="171.4140625">Service Name</th><th>SQL Query</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get reason for description inactivation</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">CALL setDeltaRange(1,[deltaStartTime], [deltaEndTime]);
SELECT * FROM delta_inactive_descriptions;
</code></pre><p>For example:</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">CALL setDeltaRange(1,'2019-07-31', '2020-01-31');
SELECT * FROM delta_inactive_descriptions;
</code></pre></td><td>Returns a row of data for each description inactivated after the deltaStartTime up to and including the deltaEndTime. Each row contains the following columns:</td></tr><tr><td></td><td></td><td></td></tr><tr><td><strong>Columns</strong></td><td><strong>Description</strong></td><td></td></tr><tr><td><strong>id</strong></td><td>Identifier of the inactivated description.</td><td></td></tr><tr><td><strong>effectiveTime</strong></td><td>Effective time of the row that inactivated the description</td><td></td></tr><tr><td><strong>active</strong></td><td>Active state of description. Should always be zero (0)</td><td></td></tr><tr><td><strong>conceptid</strong></td><td>Identifier of the concept to which the description applies</td><td></td></tr><tr><td><strong>term</strong></td><td>Term of the inactivated description</td><td></td></tr><tr><td><strong>concept_fsn</strong></td><td>The fully specified name of the concept.</td><td></td></tr><tr><td><strong>concept_active</strong></td><td>Active state of the concept.</td><td></td></tr><tr><td><strong>reason</strong></td><td>The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the description inactivation reference set.</td><td></td></tr><tr><td><strong>Get reason for concept inactivation &#x26; historical associations</strong></td><td></td><td><p>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:</p><p>id, effectiveTime, active, definitionStatusId, FSN, reason, assoc_type, ref_conceptId, ref_concept_FSN</p><p>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</p></td></tr><tr><td></td><td></td><td></td></tr><tr><td><strong>Columns</strong></td><td><strong>Description</strong></td><td></td></tr><tr><td><strong>id</strong></td><td>Identifier of the inactivated concept</td><td></td></tr><tr><td><strong>effectiveTime</strong></td><td>Effective time of the row that inactivated the concept</td><td></td></tr><tr><td><strong>active</strong></td><td>Active state of concept. Should always be zero (0)</td><td></td></tr><tr><td><strong>definitionStatusId</strong></td><td>Definition status of the inactivated concept</td><td></td></tr><tr><td><strong>FSN</strong></td><td>Fully specified name of the inactivated concept</td><td></td></tr><tr><td><strong>reason</strong></td><td>The reason for inactivation represented by the preferred term associated with the valueId concept in the relevant row of the concept inactivation reference set.</td><td></td></tr><tr><td><strong>assoc_type</strong></td><td>The preferred term for the name of the association reference set containing the association between the inactive and active concept.</td><td></td></tr><tr><td><strong>ref_conceptId</strong></td><td>The identifier of the active concept (or one of the active concepts) with which the inactive concept is associated.</td><td></td></tr><tr><td><strong>ref_concept_FSN</strong></td><td>The fully specified name of the active concept with which the inactive concept is associated.</td><td></td></tr></tbody></table>

<a href="https://docs.google.com/forms/d/e/1FAIpQLScTmbZIf0UEQwYDkY27EEWBkaiYkHSbR0_9DmFrMLXoQLyL7Q/viewform?usp=pp_url&#x26;entry.1767247133=SNOMED+Terminology+Services+Guide&#x26;entry.670899847=Get%20History%20Data" class="button primary">Provide Feedback</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.11-get-history-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.