Smile Guide: Uploading LOINC Codes
UPLOADING A CODESET TO YOUR LOCAL SMILE CDR INSTANCE
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.
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:
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.
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).
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:
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:
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
We need 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”
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.
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
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):
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.
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: