On this page:

7.1Uploading CodeSystems

 

Smile CDR ships with internal support for all CodeSystems that are distributed as a part of the FHIR release itself. These codes can be pre-loaded at startup by enabling the Seed Base Validation Resources configuration. For example, if the CodeSystems have been preloaded the Administrative Gender can be interacted with using standard terminology operations such as $lookup.

In many cases, it is useful to upload your own CodeSystems for use in validation and search operations. This might mean uploading standard vocabularies such as LOINC or loading custom vocabularies such as local CodeSystems defined for organizational use.

This page describes methods for uploading External CodeSystems (also called Not-Present CodeSystems. See CodeSystem Resources for more information on what this means.)

7.1.1Uploading External CodeSystems

 
Uploading external terminologies requires the FHIR_UPLOAD_EXTERNAL_TERMINOLOGY permission.

Smile CDR has the ability to import several standard terminology code systems using their native distribution formats. It is also possible to upload external terminology containing custom or locally defined codes. This is done using the $upload-external-code-system operation, and can be automated using the Smile CLI Tool (smileutil) command.

The following table lists the Standard CodeSystems supported by Smile CDR, as well as their URL and required input format.

CodeSystem URL File Format
LOINC http://loinc.org LOINC Complete Download ZIP
SNOMED CT http://snomed.info/sct RF2 Distribution in ZIP
All Others Any Any CodeSystem may be uploaded using the CSV Vocabulary Input Files format described below.

7.1.2Uploading LOINC

 

Smile CDR has the ability to ingest and process the distribution format for the LOINC vocabulary. LOINC is a rich set of codes related to health measurements, observations, and documents. LOINC is most commonly known for its rich set of codes to describe laboratory testing orders and results.

In order to upload LOINC, the LOINC and RELMA Complete Download File download should be selected from the LOINC website. This file will have a filename similar to Loinc_N.NN.zip. It is available from the LOINC Downloads page.

Input Files

The following input files are supported (note that version numbers given are only examples; newer and older versions of these files may also be supported).

Filename Required? Description
loincupload.properties This optional file is not a part of the LOINC distribution and must be created manually. It contains version information about the upload.
LOINC_2.68.zip Yes LOINC Distribution

The loincupload.properties File

If present, this file should contain contents similar to the following:

# This is the version identifier for the AnswerList file
answerlist.version=Beta.1
# This is the version identifier for uploaded ConceptMap resources
conceptmap.version=Beta.1

Performing the Upload

The Smile CLI Tool (smileutil) Upload Terminology command can be used to upload LOINC files. An example command is shown below:

bin/smileutil upload-terminology -d Loinc_2.68.zip -d loincupload.properties -v r4 -t "http://localhost:8000" -u "http://loinc.org"

The easiest way to use this tool is to adapt the provided script, upload-loinc.sh in the terminology/loinc directory within the Smile CDR distribution.

Loading Multiple Versions

By default, the Upload Terminology command loads the LOINC code system without specifying a version and subsequent loads will similarly overwrite the non-versioned CodeSystem resources. If there is a need to support multiple versions of the LOINC CodeSystem, the following parameter can be added/enabled in the loincupload.properties file:

# This is the version for an uploaded code system (i.e. `CodeSystem.version`).
loinc.codesystem.version=2.68

Enabling or adding the above property will cause the configured version value to be appended to the IDs of the resources created for the loaded LOINC code system, allowing for multiple versions of the LOINC code system to exist in the CDR. Subsequent loads with the same version will overwrite previously created resources with the same version. Loads with a new version will create a new set of resources, which will be distinct from previously loaded resources.

To access a specific version of a LOINC terminolgy resource via a FHIR search request or operation, the client will need to identify the version. If no version parameter is provided, the CDR will default to the latest (i.e. most recently loaded or updated) version of the code system.

7.1.3Uploading SNOMED CT

 

Smile CDR has the ability to ingest and process the distribution format for the SNOMED CT vocabulary. SNOMED CT is a very large and complex set of vocabulary covering almost all areas of healthcare.

Input Files

The following input files are supported (note that version numbers given are only examples; newer and older versions of these files may also be supported).

Filename Description
SnomedCT_RF2Release_INT_20160731.zip This file contains a complete release of SNOMED CT in the "RF2" format. The filename shown here is the international release of SNOMED CT, but national editions may be used instead as they share the same release format.

7.1.4Uploading Custom Vocabularies

 

If you have a set of concepts that is not already supported by one of the formats above, you can convert it into a standard HAPI FHIR custom vocabulary format and then upload it.

This approach uses one or more CSV files that are required to be in a specific format; therefore converting your content to this format (or authoring it natively in this format) is a prerequisite.

Performing the Upload

In order to upload custom terminology using the standard HAPI FHIR import format, the file(s) described above should be packaged into a ZIP file.

The Smile CLI Tool (smileutil) Upload Terminology command can be then be used to upload this file. An example command is shown below:

bin/smileutil upload-terminology -d myfiles.zip -v r4 -t "http://localhost:8000" -u "http://example.com/labCodes"

7.1.5Applying Deltas to External CodeSystems

 

A pair of FHIR operations can be used to add or remove codes from external CodeSystems. These operations directly add or remove the codes from the tables that are used for live processing without triggering a new version of the related CodeSystem resource. As such they are useful for maintaining terminology that is being used in a live environment.

Note: In cases where multiple versions of an external CodeSystem are loaded in the CDR, the delta operations will only affect the current (i.e. most recently loaded or updated) version of the CodeSystem.

7.1.6Delta Add Operation: $apply-codesystem-delta-add

 

The $apply-codesystem-delta-add operation can be used to add concepts to an existing external Codeystem. This operation takes the following parameters:

Name Cardinality Type Description
system 1..1 uri Specifies the CodeSystem URL to apply the delta to.
file 0..* Attachment Specifies the files that are to be uploaded. Files may be included in the attachment as raw CSV/JSON/XML files, or may also be combined into a compressed ZIP file which is included in the attachment instead.
codeSystem 0..* resource(CodeSystem) Specifies raw CodeSystem resources, containing concepts and relationships apply as a delta. Note that the codes in the CodeSystem are treated as a delta and not a snapshot, meaning that they will be added to any codes that are already present in the CodeSystem and properties such a the CodeSystem.status are ignored.

Example Using CSV Files

The following example shows an invocation of the Delta Add operation. This payload should be a POST to the following URL: http://serverbase/CodeSystem/$apply-codesystem-delta-add

The payload is shown below. Note that the following fields must be populated in the file Attachment elements:

  • contentType: Specifies the payload type (should be text/csv, application/zip, or a FHIR Mimeype).
  • data: Contains the raw Base64 encoded payload.
  • url: Used by the upload processor to determine the type of file being uploaded (e.g. concepts.csv vs hierarchy.csv). See CSV Vocabulary Input Files below for descriptions of the files to upload.
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "system",
      "valueUri": "http://example.com/cs"
    },
    {
      "name": "file",
      "valueAttachment": {
        "contentType": "text/csv",
        "data": "Q09ERSxESVNQTEFZCgpDSEVNLENoZW1pc3RyeQpIQixIZW1vZ2xvYmluCk5FVVQsTmV1dHJvcGhpbHMKCk1JQ1JPLE1pY3JvYmlvbG9neQpDJlMsQ3VsdHVyZSBhbmQgU2Vuc2l0aXZpdHkK",
        "url": "file:/concepts.csv"
      }
    },
    {
      "name": "file",
      "valueAttachment": {
        "contentType": "text/csv",
        "data": "UEFSRU5ULENISUxECgpDSEVNLEhCCkNIRU0sTkVVVAoKTUlDUk8sQyZTCg==",
        "url": "file:/hierarchy.csv"
      }
    }
  ]
}

Example Using CodeSystem Resource

The following example shows an invocation of the Delta Add operation. This payload should be a POST to the following URL: http://serverbase/CodeSystem/$apply-codesystem-delta-add

The request body is shown below. Note that the hierarchy is preserved (just as it is when using CSV files as input) but unlike the CSV method, root concepts such as CHEM and MICRO below must be placed at the root of the hierarchy.

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "system",
      "valueUri": "http://example.com/cs"
    },
    {
      "name": "codeSystem",
      "resource": {
        "resourceType": "CodeSystem",
        "concept": [
          {
            "code": "CHEM",
            "display": "Chemistry",
            "concept": [
              {
                "code": "HB",
                "display": "Hemoglobin"
              },
              {
                "code": "NEUT",
                "display": "Neutrophils"
              }
            ]
          },
          {
            "code": "MICRO",
            "display": "Microbiology",
            "concept": [
              {
                "code": "C&S",
                "display": "Culture And Sensitivity"
              }
            ]
          }
        ]
      }
    }
  ]
}

7.1.7Delta Remove Operation: $apply-codesystem-delta-remove

 

The $apply-codesystem-delta-remove operation can be used to remove concepts from an existing external Codeystem. This operation takes the following parameters:

Name Cardinality Type Description
system 1..1 uri Specifies the CodeSystem URL to apply the delta to.
file 0..* Attachment Specifies the files that are to be uploaded. Files may be included in the attachment as raw CSV/JSON/XML files, or may also be combined into a compressed ZIP file which is included in the attachment instead.
codeSystem 0..* resource(CodeSystem) Specifies raw CodeSystem resources, containing concepts and relationships apply as a delta. Note that the codes in the CodeSystem are treated as a delta and not a snapshot, meaning that they will be added to any codes that are already present in the CodeSystem and properties such a the CodeSystem.status are ignored.

Example

The following example shows an invocation of the Delta Remove operation. This payload should be a POST to the following URL: http://serverbase/CodeSystem/$apply-codesystem-delta-remove

The payload is shown below:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "value",
      "resource": {
        "resourceType": "CodeSystem",
        "url": "http://example.com/labCodes",
        "concept": [
          {
            "code": "HB"
          },
          {
            "code": "NEUT"
          }
        ]
      }
    }
  ]
}

7.1.8Reference: CSV Vocabulary Input Files

 

A zip file should be created that has the following file(s) listed below as contents. Note that all CSV files are required to have a header line containing the column names as the first line. This is shown in the examples below.

Concepts File: concepts.csv

This file should have the following columns:

  • CODE – contains the concept code
  • DISPLAY – contains the concept display name

Example:

CODE,DISPLAY

CHEM,Chemistry
HB,Hemoglobin
NEUT,Neutrophils
MICRO,Microbiology
C&S,Culture and Sensitivity

Hierarchy File: hierarchy.csv

This file contains optional hierarchy information if your codes have a parent-child hierarchy. This file should have the following columns:

  • PARENT – contains the concept code for the parent
  • CHILD – contains the concept code for the child

Example:

In the example below, the HB and NEUT concept will be children of the CHEM concept. The C&S concept will be a child of the MICRO concept.

PARENT,CHILD

CHEM,HB
CHEM,NEUT
MICRO,C&S

Omitting hierarchy.csv

The hierarchy.csv file is always optional; if it is missing, all codes defined in concepts.csv are treated as root concepts (concepts with no parents).

Adding Child Records

When using this file for the Delta Add Operation is is possible to specify PARENT codes that do not exist in concepts.csv but are already present in the existing CodeSystem. In this case, the child code is added as a child to the existing PARENT code, whether it is a root concept itself, or is a child as well.

CodeSystem Definition: codesystem.json or codesystem.xml

This file contains the CodeSystem definition. If this file is not supplied and a CodeSystem resource already exists for the given CodeSystem URL, the existing CodeSystem resource is not modified. If no resource already exists, a simple CodeSystem resource is automatically generated.

Example:

{
	"resourceType": "CodeSystem",
	"url": "http://example.com/labCodes",
	"name": "Example Lab Codes",
	"description": "A set of lab codes",
	"status": "active",
	"publisher": "Example Organization Corporation Worldwide",
	"date": "2019-07-30",
	"content": "not-present"
}