Terminology Services Guide

Search

SNOMED CT Document Library

    Loading...
  

Overview

SNOMED CT release files include data that allows tracking of all changes between different versions of any edition of the terminology. In addition to a unique id, each row in every release file includes the following columns effectiveTime, active and moduleId. The effectiveTime column shows when the row became the effective version of that component or reference set member, either as a new component or as revision of the previous version of that component. The active column indicates whether the component is still intended for active use. The moduleId identifies the module that the component belongs to. A change to the moduleId indicates that a component has been moved to a different module. The new module may be another module maintained and distributed by the same organization. However, in some cases, a component may be moved to a module that is maintained and distributed by another organization.

Before an organization updates to use a newer SNOMED CT version, it is important to identify significant changes that have occurred between the two versions. As a minimum, it is essential to identify the inactivation of any concepts and descriptions that are used in data entry templates, picklists, reporting and analytics queries. Additionally, where reference sets are used to assist or constrain data entry, changes to the membership of those reference sets should be reviewed. A more extensive review covering changes to other reference set may also be necessary where these are used as part of data entry, reporting or analysis.

This section is concerned with services that identify and categorize these changes. A later section of the guide (4.11 Get History Data) addresses additional services that provide more information about some of these changes.

Requirements and Options

To identify changes, terminology services must be able to provide the following information about data in the full release of the new version:

  1. Identify components and reference set members1 with an effectiveTime greater than the date of the previously installed version2.
  2. For each component identified by step 1:
    1. Check the active status in the updated release (updated=active or updated=inactive)
    2. Check if the component was present in the previous release and if so whether it was active or inactive. (previous=active, previous=inactive or previous=none)
  3. Based on the results of step 2, use  Table 4.9-1 Terminology Component Update Types to determine:
    1. The type of update that has occurred;
    2. The actions that need to be considered.

The required services are listed in  Table 4.9-2.

Table 4.9-1: Terminology Component Update Types

PreviousUpdatedUpdate TypeCommentActions to Consider
noneactiveAdditionThis component has been added in since the previous release.

Concept or description: Consider including in data entry templates, picklists, etc.

Reference set member: May need to consider impact of addition if the reference set is used in constraints for data entry or queries used for reporting.

activeactiveChangeThe component has been changed but remains active. Changes have been made to one or more of the other mutable properties of the component. In some cases, the only change made may have been to the moduleId indicating a reorganization of components within the release package.Check the specific nature of change and consider if this has any impact.
activeinactiveInactivation

The component has been inactivated since the previous release.

  • For inactivated concepts and descriptions, information about the reason for inactivation should be reviewed.
  • For inactivated concepts, historical associations linking the inactive concept to relevant active concepts should also be reviewed.

Concept: Review and replace any direct use in data entry templates, picklists, constraints and queries. Use history data (see 4.11 Get History Data) to determine reason for inactivation and to find associations with potential active replacement concepts. Review impact on reporting or existing records using the concept.

Description: Review and replace any direct use in data entry templates, picklists. Use history data (see 4.11 Get History Data) to determine reason for inactivation

Reference set member: Review the impact of the change on data entry templates, picklists, constraints, queries, mapping, etc.


The following situations are unusual but may sometimes occur
inactiveactiveReactivation

The component has been reactivated. This may represent a correction of a previous inactivation.

If the component is a concept or description that caused an issue when inactivated, consider reversing changes made when it was inactivated.
inactiveinactiveRemains inactive

This component remains inactive but has changed in some way. This is an unusual situation, it may indicate a change in some other data since inactivation.

No action required.
noneinactiveInactivated addition

If this occurs, the likely cause is an addition in an intervening release, which has subsequently inactivated. From a practical perspective this is equivalent to no change. However, the concept may occur in a communication from another organization that used a version in which the component way active.

Concept or description: No action required locally, but be aware that communicated data might include this now inactive concept or description. This is possible in communicated data from a system that used an intermediate release in which the component was active.

Table 4.9-2: Services Required

Service Name and StatusInputOutput

Get components or reference set members that have changed since a specified previous release

REQUIRED

  • Edition

  • Version release date/time (snapshot of components and refset members at this date/time represents the updated state)

  • Previous version release date/time (snapshot of components and refset members at this date/time represents the previous state)

  • Component type or reference set type

  • Optional: refsetId

  • Optional: Language/dialect3

  • Identifiers of components or reference set members with the following characteristics:
    • specified component or reference set type
    • effectiveTime greater than previous release date/time (note that if only date is specified then component with any effectiveTime on that date must be excluded)
  • Indication of the update type (see Table 4.9-1). The update type indication should be applied either to:
    1. the set of identifiers to which it applies; or
    2. individually to each identifier.

Optionally other data associated with each changed component or reference set member could also be returned. However, requirements for additional data vary depending on the update type and the type of component or reference set. A service that returns sets of identifiers grouped by update type, and component or reference set type offers a more flexible solution. It allows additional data to be retrieved selectively by other services to support appropriate review of the changes.

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).

Table 4.9-3: Snowstorm API

Service Name

API Call4

Result

Get components or reference set members that have changed since a specified previous release

N/A

This service is not currently supported.

When Snowstorm is running with write access enabled it is possible to export SNOMED CT content selected by a range between two effective times. This process could be adapted to allow the relevant information to be processed in an application to identify the components and reference set members that have been updated. However, this would require the client application to process the selected data after it has been exported in the release file format.

Table 4.9-4: FHIR API

Service Name

API Call5

Result
Get components or reference set members that have changed since a specified previous release
N/A

This service is not supported.


Table 4.9-5: MySQL Example Database

Service Name

SQL Query 6

Result

Get components or reference set members that have changed since a specified previous release

SELECT * 
	FROM [snapshotTableName]
		WHERE effectiveTime > [previousVersionDate];

Example 1

SELECT *
	FROM `snap_concept`
		where `effectiveTime` > '2019-07-31';

Example 2
SELECT *
	FROM `snap_description`
		where `effectiveTime` > '2017-01-31';
Example 3
CALL setSnapshotTime(1, '2019-07-31);

SELECT *
	FROM snap1_refset_simple
		WHERE effectiveTime > '2018-07-31';

Returns all rows in the specified snapshot view of the named release file that have an effectiveTime is later than the specified previous version date7. The snapshot time for the snapshot view determines the date of the current version.

Example 1 returns all rows in the current snapshot of the concept release file that have an effectiveTime after 2019-07-31.

Example 2 returns all rows in the current snapshot of the description release file that have an effectiveTime after 2017-01-31.

Example 3 sets a specific snapshot time 1 as (2019-07-31). It then returns rows from the simple reference set table in that specific snapshot view that have an effectiveTime after 2018-07-31.

Footnotes
The significance of changes to membership of reference sets depends on the extent to which they are used by a particular application. For example, a change to language reference set membership may mean that a description is no longer acceptable in the language or dialect used in by an application. Similarly, a change to a the membership of a simple reference set used to constrain a searches, reports or analytics may alter the results of those actions.
A delta release file may be available to provide information about changes since the previous release. However, in cases where an organization does not update the version they are using regularly, there may not be a single set of delta release files covering all the changes made between the version in use and the current version.
Language and/or dialect should be specified if the service returns terms associated with referenced concepts.
In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of HL7 (www.hl7.org).
The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide. For instructions on how to build the example database refer to Appendix A: Building the SNOMED CT Example Database.
Note that to avoid issues if hours, minutes or seconds are included in previousVersionDate, the value should be set as 23:59:59 on the required date.

Feedback
  • No labels