Smile CDR Guide: Uploading LOINC Codes

What to Expect

🕘 Reading time = 1 hour

By the end of this document, you’ll understand what code sets are and how to upload a version of them on their local Smile CDR instance. This document will be focused on SNOMED and LOINC.

Background

Many data elements in FHIR resources and profiles have coded values. A coded value is basically a fixed string (a sequence of characters) assigned elsewhere that identifies some defined "concept." The methods of defining coded values/ codes are collectively called "code systems."

For example, administrative gender is a value set referenced in the US Core patient profile that has four codes: male, female, other and unknown. The codes in this value set are contained collectively in this administrative gender code system. This code system in particular is defined by the FHIR project.

Now LOINC and SNOMED are also code systems but the difference is, they’re not defined by FHIR. It’s common for value sets to pull codes from external code systems like them as well. Hence, FHIR servers need to have these code systems pre-loaded to be able to contain resources that reference these external codes.

For example, if the FHIR server has been preloaded with the SNOMED codes in the US Core Encounter Type Value Set that’s referenced in the US Core Encounter Profile, only then can the US Core IG as a whole be recognised by the server and the said codes on the server can only then be interacted with using standard terminology operations such as $lookup. We’ll cover the $lookup operation ahead.

For more information please see the links below:

http://hl7.org/fhir/terminologies.html

http://hl7.org/fhir/terminology-service.html

Objectives

The intention of this document is to provide a step-by-step procedure of how to upload a code set on a local Smile CDR server. The procedure to upload SNOMED Code sets and LOINC code sets are not the same. We’ll cover the process separately. Refer to:

https://smilecdr.com/docs/terminology/uploading.html for additional context and understanding.

Prerequisites:

See the following document on installing and configuring Smile CDR prior to beginning this tutorial. You should have the latest Smile version downloaded.
Docker Installed (for Windows users).
Postman or Insomnia installed.

Instructions for Windows: LOINC Code Set

Start your Smile Instance by opening the Docker application and starting your Smile CDR container.
Go to the desired coding site to download a zip file of codes. For example, in the case of LOINC codes, use the following link to download the necessary version. On this site, you can choose between LOINC tables, RELMA or accessory files

If this is your first time using LOINC, you may be prompted to register for a free account (see below). Create your free account, then continue to download.

You may be prompted to accept terms and conditions prior to downloading. Click the small box, then continue to download:
Locate that directory location on the local command terminal. A quick way to do that is: type cmd in the location bar exactly where the zip folder is placed (Figure 1). Press enter and the command line will immediately open up referencing the right directory (Figure 5).

For example, to download LOINC version 2.71 look at the redbox to see how the file should be located on the local command terminal in Figure 1.

Figure 1. -Locating the directory on Windows

Figure 5. Immediate opening of the local command line
To upload the code file in the apt Docker location, copy and paste the command below in your local command terminal and hit enter. Within the bracket, be sure to put in your code set’s file name.

docker cp ./Loinc_2.71.zip smilecdr:/home/smile/smilecdr/

Note: the yellow highlighted region is specific to the code set you chose to download (in this case, LOINC version 2.71). Be sure to replace this package name with whichever code set and version you downloaded.

Figure 2. Uploading the LOINC zip file in Docker
Next, in Docker, click play on Smile CDR if it isn’t already running and click the CLI button.

Figure 3. - CLI in Docker
The following steps are specific to LOINC and will be conducted on the CLI shell NOT in the local command terminal:
1. Now we need to edit the code set properties file to state the correct version of the code set that we’re uploading. For that, we need to navigate to the directory where the file exists
  
  In the case of LOINC codes, the properties file is called loincupload.properties. It resides in the LOINC folder in the terminology directory. We need to navigate to the LOINC folder. To do so, run the following command:
  
  cd /home/smile/smilecdr/terminology/loinc
  
  Now we must edit the LOINC upload properties file that resides in this folder. To do so, first open the file by running the following command:
  
  # vi loincupload.properties
  
  Figure 4. Running the loincupload.properties file
2. We need to edit the file to match the code set version we are looking to upload
3. To edit the file, type i
4. Navigate to the section of this file titled “#loinc.codesystem.version=2.67”
  
  Note: we must set the value highlighted in yellow to the version number you downloaded.
  
  In the case of a LOINC code set of version 2.71, the line should be changed to the following (Figure 8). Ensure that the version number corresponds to the zip file you have downloaded.
  
  #loinc.codesystem.version=2.71
  
  Figure 8.
5. Once you have successfully changed the version number, you can save the file and quit by clicking escape, typing :wq and pressing enter
The next step is to navigate to the bin directory by running the command below. Be sure to put in the right zip file name, property file name and URL link at the tail end. This command calls needs smileutil upload-terminology, LOINC zip file and the loincupload.properties prior to other syntax to upload the LOINC codes.

/home/smile/smilecdr bin/smileutil upload-terminology -d /home/smile/smilecdr/Loinc_2.71.zip -d /home/smile/smilecdr/terminology/loinc/loincupload.properties -v r4 -t "http://localhost:8000" -b "admin:password" -u

http://loinc.org

Note: the yellow highlighted region is specific to LOINC. In the case of LOINC Code version of 2.71, the command like the above should be run. Be sure to put in the right zip file name, property file name and URL link at the tail end.

Make sure you use the apostrophe “ “ that is acceptable on the CLI shell, otherwise it could result in an error.
Your computer may take some time to upload the code set. Once complete, your CLI should look something like the following (Figure 9):

Figure 9.
Finally it’s important to check if the Code Set has been uploaded correctly. You can use POSTMAN or INSOMNIA to run a GET request.

http://localhost:8000/CodeSystem/loinc

Note: The section highlighted yellow is specific to LOINC codes. Make sure to replace this region with whichever code set you’re working with.

Don’t forget to add the username and password within Basic Authorization if required.

Once queried, the response body should look somewhat similar to the following:

Figure 10.

Instructions for Windows: SNOMED Code Set

Start your Smile Instance by opening Docker and starting your smilecdr container.
Go to the desired coding site to download a zip file of codes.
For example, in the case of SNOMED codes, use the following link to download the necessary version:

https://www.nlm.nih.gov/healthit/snomedct/us_edition.html.
Locate, copy and paste the directory location on the local command terminal.

A quick way to do that is by typing cmd in the location bar exactly where the zip folder is placed (Figure 11).

Figure 11. cmd in finders bar
In the command terminal, type cmd and press enter. The command line will immediately open up referencing the right directory (Figure 12).

Figure 12. Automatically opening the command line with appropriate directory
To upload the code file in the apt Docker location, copy and paste the command below in your local command terminal and press enter. Refer to Figure 13.
docker cp ./SnomedCT_USEditionRF2_PRODUCTION_20210901T120000Z.zip smilecdr:/home/smile/smilecdr

Note: the yellow highlighted region is specific to the code set you chose to download (in this case, SNOMED version 2021090). Be sure to replace this package name with whichever code set and version you downloaded

Figure 13

The following steps will be conducted on the CLI shell, not the local command terminal.
The next step is to navigate to the bin directory and run the command below. Be sure to put in the right zip file name, property file name and URL link at the tail end.
In the case of the SNOMED Code version of September 2021, the following command should be run:

smilecdr/bin/smileutil upload-terminology -d /home/smile/smilecdr/SnomedCT_USEditionRF2_PRODUCTION_20210901T120000Z.zip -v r4 -t “http://localhost:8000” -b “username:password” -u http://snomed.info/sct

Note: the yellow highlighted region is specific to the code set you chose to download (in this case, SNOMED version 2021090). The green highlighted region should be replaced with the username and password for your Smile instance.

It should take some time before the upload is complete, at which point your CLI should appear somewhat like the image below:
Finally it’s important to check if the code set has been uploaded accurately. You can use POSTMAN or INSOMNIA to run a GET request. In Figure 14 above, you can see the reference value is “Codesystem/1402.”

Run the following query to check if the SNOMED code set has been uploaded by referencing 1402. Your response should look like Figure 15 below.

http://localhost:8000/CodeSystem/1402

Note: the section highlighted yellow is specific to your server. Make sure to replace this value with whichever value you see adjacent to the reference value.

Don’t forget to add the username and password within basic authorization in Postman if required.

Note: the code system can be found, but the content is “not-present.” This is because SNOMED is a very large code system so the concepts may not exist in the resource body.
To look at concepts in a code system with content “not-present” it’s instead useful to use code system operations. Run a GET query like the following to find a specific code. Figure 15 is what the response should look like.

http://localhost:8000/CodeSystem/$lookup?system=http://snomed.info/sct&code=410016009

Note: in the SNOMED folder you downloaded, navigate to the sc2_Text Definition file from Full>Terminology. There you’ll see a column for language codes. Pick a code from there and replace the green value in the above query to search for a different code.

Figure 15. Postman response for Snomed

To look at concepts in a code system with content “not-present” it’s instead useful to use code system operations. Run a GET query like the following to find a specific code. Figure 16 is what the response should look like.

http://localhost:8000/CodeSystem/$lookup?system=http://snomed.info/sct&code=410016009

Note: in the SNOMED folder, navigate to the sc2_Text Definition file from Full>Terminology. There you’ll see a column for language codes. Pick up a code from there and replace the green value in the above query to search for a different code.

Figure 15. Postman response for Snomed

To look at concepts in a code system with content “not-present” it’s instead useful to use code system operations. Run a GET query like the following to find a specific code. Figure 16 is what the response should look like.

http://localhost:8000/CodeSystem/$lookup?system=http://snomed.info/sct&code=410016009

Note: in the SNOMED folder, navigate to the sc2_Text Definition file from Full>Terminology. There you’ll see a column for language codes. Pick up a code from there and replace the green value in the above query to search for a different code.

Figure 16. Code system operations

Instructions for MacOS

Go to the desired coding site to download a zip file of codes. In the case of LOINC codes, use the following link to download the necessary version: https://loinc.org/downloads/. On this site, you can choose between LOINC tables, RELMA or accessory files.

If this is your first time using LOINC, you may be prompted to register for a free account (see below). Create your free account, then continue to download.

You may be prompted to accept terms and conditions prior to downloading. Click the small box, then continue to download:
Once you’ve downloaded the zip file, place the file in your Smile CDR folder by running the following command:

sudo mv ~/downloads/Loinc_2.71.zip /usr/local/smilecdr
Note: the yellow highlighted region “Loinc_2.71.zip” is specific to the download file selected in Step 2. Make sure to consider which download file you’ve selected when replacing this region.

The green highlighted region “/usr/local/” of this command can be replaced with whichever directory you keep your Smile CDR instance, in this case, the computer’s local drive. For the remaining steps/commands, you’ll notice that the local drive directory will be used.
Now we need to open the code set properties file to be able to state within it the correct version of the code set that we are uploading. To accomplish this, we need to navigate to the directory where the file exists.

For example, in the case of LOINC codes, the properties file is called “loincupload.properties.” It resides in the LOINC folder, which can be found in the terminology directory of your Smile CDR folder.

cd /usr/local/smilecdr/terminology/loinc

Run the command below to view the LOINC properties file:

vi loincupload.properties

Note: steps 4 and 5 are specific to LOINC codes and as such, you may skip them if you chose to upload a different code set.
Now you are in the properties file. We are required to edit the file to match the code set version we are looking to upload.
To edit the file, type i.
Navigate to the section of this file titled “#loinc.codesystem.version=2.67”. We must set the value highlighted in yellow to the version number you have downloaded.

In the case of a LOINC code set of version 2.71, the line should be changed to the following:

#loinc.codesystem.version=2.71

Note: ensure that the version number corresponds to the zip file you have downloaded
Once you have successfully changed the version number, you can save the file and quit by clicking escape and typing :wq.
The next step is to navigate to the Smile CDR directory and run the command below.

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

Note: the yellow highlighted region is specific to LOINC. In the case of LOINC code version of 2.71, the command should be run. Be sure to put in the right zip file name, property file name and URL link at the tail end. The green highlighted region should be replaced with the username and password for your Smile instance.
It’s important to check if the code set has been uploaded accurately. You can use Postman or Insomnia to run a GET request. Make sure you add the name of the code system in brackets below:

http://localhost:8000/CodeSystem/loinc

Note: the green highlighted region is specific to LOINC.

Glossary

LOINC: a common language (set of identifiers, names and codes) for identifying health measurements, observations and documents. It stands for Logical Observation Identifiers Names and Codes. It’s a rich catalog of measurements, including laboratory tests, clinical measures like vital signs and anthropometric measures, standardized survey instruments and more. LOINC also contains codes for collections of these items, such as panels, forms and documents.

Useful Shell Commands for the CLI Docker Shell:

ls: used to check the existent files in a particular directory:
cd: used to change to a particular directory. For example, if you need to enter the LOINC folder, this is the syntax you would use:
cd ../..: when followed by two dots and a slash, it’s used to go back two directories. cd with only two dots is to go back one directory:
pwd: used to find out the present working directory. After entering pwd, the shell produces a response to state the directory you currently are in:

Smile Guide: Uploading LOINC Codes