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

10.1.2Uploading 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
ICD-10-CM (US Edition) http://hl7.org/fhir/sid/icd-10-cm XML 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.

10.1.2.1Performing the Upload with smileutil

The Smile CLI Tool (smileutil) Upload Terminology command can be used to upload standard and custom vocabulary. The sections below show examples of how to do this.

10.1.2.2Performing the Upload via REST operation

The Upload Terminology command is actually only performing a simple REST operation against the FHIR endpoint. It is also possible to invoke this endpoint directly.

To upload terminology via the REST endpoint, perform an HTTP POST to the following URL: http://localhost:8000/CodeSystem/$upload-external-code-system

The request body for this operation is a Parameters resource with the folowing parts:

  • system – This parameter should have a uri value containing the CodeSystem URI.
  • file – This parameter should have an attachment value containing the value of the file (encoded in Base64) in Attachment.data and the filename in Attachment.url.

An example request body is shown below:

{
   "resourceType":"Parameters",
   "parameter":[
      {
         "name":"system",
         "valueUri":"http://hl7.org/fhir/sid/icd-10-cm"
      },
      {
         "name":"file",
         "valueAttachment": {
            "data":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPElDRDEwQ00udGFidWxhcj4KICA8dmVyc2lvbj4yMDIxPC92ZXJzaW9uPgogIDxpbnRyb2R1Y3Rpb24+CiAgICA8aW50cm9TZWN0aW9uIHR5cGU9InRpdGxlIj4KICAgICAgPHRpdGxlPklDRC0xMC1DTSBUQUJVTEFSIExJU1Qgb2YgRElTRUFTRVMgYW5kIElOSlVSSUVTPC90aXRsZT4KICAgIDwvaW50cm9TZWN0aW9uPgogIDwvaW50cm9kdWN0aW9uPgogIDxjaGFwdGVyPgogICAgPG5hbWU+MTwvbmFtZT4KICAgIDxkZXNjPkNlcnRhaW4gaW5mZWN0aW91cyBhbmQgcGFyYXNpdGljIGRpc2Vhc2VzIChBMDAtQjk5KTwvZGVzYz4KICAgIDxzZWN0aW9uSW5kZXg+CiAgICAgIDxzZWN0aW9uUmVmIGZpcnN0PSJBMDAiIGxhc3Q9IkEwOSIgaWQ9IkEwMC1BMDkiPgogICAgICAgICBJbnRlc3RpbmFsIGluZmVjdGlvdXMgZGlzZWFzZXMKICAgICAgPC9zZWN0aW9uUmVmPgogICAgPC9zZWN0aW9uSW5kZXg+CiAgICA8c2VjdGlvbiBpZD0iQTAwLUEwOSI+CiAgICAgIDxkZXNjPkludGVzdGluYWwgaW5mZWN0aW91cyBkaXNlYXNlcyAoQTAwLUEwOSk8L2Rlc2M+CiAgICAgIDxkaWFnPgogICAgICAgIDxuYW1lPkEwMDwvbmFtZT4KICAgICAgICA8ZGVzYz5DaG9sZXJhPC9kZXNjPgogICAgICAgIDxkaWFnPgogICAgICAgICAgPG5hbWU+QTAwLjA8L25hbWU+CiAgICAgICAgICA8ZGVzYz5DaG9sZXJhIGR1ZSB0byBWaWJyaW8gY2hvbGVyYWUgMDEsIGJpb3ZhciBjaG9sZXJhZTwvZGVzYz4KICAgICAgICAgIDxpbmNsdXNpb25UZXJtPgogICAgICAgICAgICA8bm90ZT5DbGFzc2ljYWwgY2hvbGVyYTwvbm90ZT4KICAgICAgICAgIDwvaW5jbHVzaW9uVGVybT4KICAgICAgICA8L2RpYWc+CiAgICAgICAgPGRpYWc+CiAgICAgICAgICA8bmFtZT5BMDAuMTwvbmFtZT4KICAgICAgICAgIDxkZXNjPkNob2xlcmEgZHVlIHRvIFZpYnJpbyBjaG9sZXJhZSAwMSwgYmlvdmFyIGVsdG9yPC9kZXNjPgogICAgICAgICAgPGluY2x1c2lvblRlcm0+CiAgICAgICAgICAgIDxub3RlPkNob2xlcmEgZWx0b3I8L25vdGU+CiAgICAgICAgICA8L2luY2x1c2lvblRlcm0+CiAgICAgICAgPC9kaWFnPgogICAgICAgIDxkaWFnPgogICAgICAgICAgPG5hbWU+QTAwLjk8L25hbWU+CiAgICAgICAgICA8ZGVzYz5DaG9sZXJhLCB1bnNwZWNpZmllZDwvZGVzYz4KICAgICAgICA8L2RpYWc+CiAgICAgIDwvZGlhZz4KICAgICAgPGRpYWc+CiAgICAgICAgPG5hbWU+QTAxPC9uYW1lPgogICAgICAgIDxkZXNjPlR5cGhvaWQgYW5kIHBhcmF0eXBob2lkIGZldmVyczwvZGVzYz4KICAgICAgICA8ZGlhZz4KICAgICAgICAgIDxuYW1lPkEwMS4wPC9uYW1lPgogICAgICAgICAgPGRlc2M+VHlwaG9pZCBmZXZlcjwvZGVzYz4KICAgICAgICAgIDxpbmNsdXNpb25UZXJtPgogICAgICAgICAgICA8bm90ZT5JbmZlY3Rpb24gZHVlIHRvIFNhbG1vbmVsbGEgdHlwaGk8L25vdGU+CiAgICAgICAgICA8L2luY2x1c2lvblRlcm0+CiAgICAgICAgICA8ZGlhZz4KICAgICAgICAgICAgPG5hbWU+QTAxLjAwPC9uYW1lPgogICAgICAgICAgICA8ZGVzYz5UeXBob2lkIGZldmVyLCB1bnNwZWNpZmllZDwvZGVzYz4KICAgICAgICAgIDwvZGlhZz4KICAgICAgICAgIDxkaWFnPgogICAgICAgICAgICA8bmFtZT5BMDEuMDE8L25hbWU+CiAgICAgICAgICAgIDxkZXNjPlR5cGhvaWQgbWVuaW5naXRpczwvZGVzYz4KICAgICAgICAgIDwvZGlhZz4KICAgICAgICAgIDxkaWFnPgogICAgICAgICAgICA8bmFtZT5BMDEuMDI8L25hbWU+CiAgICAgICAgICAgIDxkZXNjPlR5cGhvaWQgZmV2ZXIgd2l0aCBoZWFydCBpbnZvbHZlbWVudDwvZGVzYz4KICAgICAgICAgICAgPGluY2x1c2lvblRlcm0+CiAgICAgICAgICAgICAgPG5vdGU+VHlwaG9pZCBlbmRvY2FyZGl0aXM8L25vdGU+CiAgICAgICAgICAgICAgPG5vdGU+VHlwaG9pZCBteW9jYXJkaXRpczwvbm90ZT4KICAgICAgICAgICAgPC9pbmNsdXNpb25UZXJtPgogICAgICAgICAgPC9kaWFnPgogICAgICAgICAgPGRpYWc+CiAgICAgICAgICAgIDxuYW1lPkEwMS4wMzwvbmFtZT4KICAgICAgICAgICAgPGRlc2M+VHlwaG9pZCBwbmV1bW9uaWE8L2Rlc2M+CiAgICAgICAgICA8L2RpYWc+CiAgICAgICAgICA8ZGlhZz4KICAgICAgICAgICAgPG5hbWU+QTAxLjA0PC9uYW1lPgogICAgICAgICAgICA8ZGVzYz5UeXBob2lkIGFydGhyaXRpczwvZGVzYz4KICAgICAgICAgIDwvZGlhZz4KICAgICAgICAgIDxkaWFnPgogICAgICAgICAgICA8bmFtZT5BMDEuMDU8L25hbWU+CiAgICAgICAgICAgIDxkZXNjPlR5cGhvaWQgb3N0ZW9teWVsaXRpczwvZGVzYz4KICAgICAgICAgIDwvZGlhZz4KICAgICAgICAgIDxkaWFnPgogICAgICAgICAgICA8bmFtZT5BMDEuMDk8L25hbWU+CiAgICAgICAgICAgIDxkZXNjPlR5cGhvaWQgZmV2ZXIgd2l0aCBvdGhlciBjb21wbGljYXRpb25zPC9kZXNjPgogICAgICAgICAgPC9kaWFnPgogICAgICAgIDwvZGlhZz4KICAgICAgICA8ZGlhZz4KICAgICAgICAgIDxuYW1lPkEwMS4xPC9uYW1lPgogICAgICAgICAgPGRlc2M+UGFyYXR5cGhvaWQgZmV2ZXIgQTwvZGVzYz4KICAgICAgICA8L2RpYWc+CiAgICAgICAgPGRpYWc+CiAgICAgICAgICA8bmFtZT5BMDEuMjwvbmFtZT4KICAgICAgICAgIDxkZXNjPlBhcmF0eXBob2lkIGZldmVyIEI8L2Rlc2M+CiAgICAgICAgPC9kaWFnPgogICAgICAgIDxkaWFnPgogICAgICAgICAgPG5hbWU+QTAxLjM8L25hbWU+CiAgICAgICAgICA8ZGVzYz5QYXJhdHlwaG9pZCBmZXZlciBDPC9kZXNjPgogICAgICAgIDwvZGlhZz4KICAgICAgICA8ZGlhZz4KICAgICAgICAgIDxuYW1lPkEwMS40PC9uYW1lPgogICAgICAgICAgPGRlc2M+UGFyYXR5cGhvaWQgZmV2ZXIsIHVuc3BlY2lmaWVkPC9kZXNjPgogICAgICAgICAgPGluY2x1c2lvblRlcm0+CiAgICAgICAgICAgIDxub3RlPkluZmVjdGlvbiBkdWUgdG8gU2FsbW9uZWxsYSBwYXJhdHlwaGkgTk9TPC9ub3RlPgogICAgICAgICAgPC9pbmNsdXNpb25UZXJtPgogICAgICAgIDwvZGlhZz4KICAgICAgPC9kaWFnPgogICAgPC9zZWN0aW9uPgogIDwvY2hhcHRlcj4KPC9JQ0QxMENNLnRhYnVsYXI+Cg==",
            "url":"icd10cm_tabular_2021.xml"
         }
      }
   ]
}

10.1.3Uploading ICD-10-CM

 

Smile CDR has the ability to ingest and process the distribution format for the ICD-10-CM vocabulary.

10.1.3.1Input 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
icd10cm_tabular_YYYY.xml This XML file contains the complete codeset and hierarchy for ICD-10-CM codes. It can be obtained at the following URL: https://ftp.cdc.gov/pub/health_statistics/nchs/publications/ICD10CM/

10.1.3.2Performing the Upload

In order to upload ICD-10-CM, the Smile CLI Tool (smileutil) Upload Terminology command can be used. An example command is shown below:

bin/smileutil upload-terminology -d icd10cm_tabular_2021.xml -v r4 -t "http://localhost:8000" -u "http://hl7.org/fhir/sid/icd-10-cm"

10.1.4Uploading 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.

10.1.4.1Input 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). The versions that are tested and verified at Smile CDR are 2.72 and 2.73.

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.73.zip Yes LOINC Distribution

10.1.4.1.1The 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

10.1.4.2Performing 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.73.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.

10.1.4.3Loading 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.73

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.

10.1.5Uploading 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.

10.1.5.1Input 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.

10.1.6Uploading 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.

10.1.6.1Performing 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"

10.1.7Applying 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.

10.1.8Delta 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 as the CodeSystem.status are ignored.

10.1.8.1Example 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"
      }
    }
  ]
}

10.1.8.2Example 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"
              }
            ]
          }
        ]
      }
    }
  ]
}

10.1.9Delta 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 to remove from the CodeSystem.

10.1.9.1Example Using CSV Files

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

The payload is shown below, which is for removing concepts with codes HB and NEUT, because the base64 encoded csv data in the payload contains these 2 codes.

{
	"resourceType": "Parameters", 
	"parameter": [
		{
			"name": "system", 
			"valueUri": "http://example.com/cs"
		}, 
		{
			"name": "file", 
			"valueAttachment": {
				"contentType": "text/csv", 
				"data": "Q09ERSxESVNQTEFZCkhCLApORVVULAo=", 
				"url": "file:/concepts.csv"
			}
		}
	]
}

10.1.9.2Example Using CodeSystem Resource

The following example shows an invocation of the Delta Remove operation using a CodeSystem resource as the payload. 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": "system",
			"valueUri": "http://example.com/cs"
		}, 
		{
			"name": "codeSystem", 
			"resource": {
				"resourceType": "CodeSystem", 
				"concept": [
					{
						"code": "HB"
					}, 
					{
						"code": "NEUT"
					}
				]
			}
		}
	]
}

10.1.10Reference: 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.

10.1.10.1Concepts 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

10.1.10.2Hierarchy 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

10.1.10.2.1Example:

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

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

10.1.10.2.3Adding Child Records

When using this file for the Delta Add Operation it 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.

10.1.10.3CodeSystem 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"
}