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.)
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. |
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.
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"
}
}
]
}
Smile CDR has the ability to ingest and process the distribution format for the ICD-10-CM vocabulary.
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/ |
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"
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.
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 |
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
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.
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.
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.
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. |
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.
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"
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.
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. |
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:
text/csv, application/zip, or a FHIR MIME type).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"
}
}
]
}
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"
}
]
}
]
}
}
]
}
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. |
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"
}
}
]
}
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"
}
]
}
}
]
}
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.
This file should have the following columns:
Example:
CODE,DISPLAY
CHEM,Chemistry
HB,Hemoglobin
NEUT,Neutrophils
MICRO,Microbiology
C&S,Culture and Sensitivity
This file contains optional hierarchy information if your codes have a parent-child hierarchy. This file should have the following columns:
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
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).
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.
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"
}