Getting and Using the CIEL Concept Dictionary

Owned by Joaquin Blaya
Last updated: Jul 05, 2024 by Grace Potma
5 min read

 

CIEL Home Page on the Open Concept Lab platform, July 2024

Objectives

Describe the strategy for how to manage the default concept dictionary used by OpenMRS which has mappings to international standards such as ICD-10, SNOMED CT, LOINC, RxNORM and CVX.

As of 2024, we are using a more dynamic subscription method to CIEL via using Open Concept Lab and the OCL Module (aka OCL Subscription Module). OCL (Open Concept Lab) is a cloud-based dictionary management platform which can publish a subset of curated concepts from CIEL (or another source dictionary) which can then be subscribed to via the OCL Module.

Specific Objectives

  1. How to get the CIEL concept dictionary (Previously known as the MVP or MVP/CIEL dictionary).

  2. Procedure for translating the dictionary.

  3. How to import the dictionary into OpenMRS and how to keep all of your OpenMRS instances updated with the latest dictionary

  4. How to get concepts added in the local dictionary added to the default dictionary (especially if they are in another language)

Versions

  • These instructions are valid from OpenMRS 1.6.6 on. From 1.9 onwards, the CIEL dictionary comes standard with the standalone version of OpenMRS.

Getting the latest concept dictionary

  • As of 2024, seeing the latest CIEL concept dictionary is much easier: Simply go to https://app.openconceptlab.org/#/orgs/CIEL. This website allows you to search the dictionary using names, mapping codes or list contents. You can then use the OCL Module to import codes into your dictionary.

    • For the most stable and consistent version control, we encourage storing your concepts in the /ocl subdirectory which is then used by the OpenMRS Initializer Module. Learn more here.

  • Previously, the latest concept dictionary was saved in the CIEL dropbox. To get access to that folder you can email Andrew Kanter at CIEL (andrew.kanter@columbia.edu or ask2164@cumc.columbia.edu).

    • The dictionary was distributed as a SQL export from a particular version of OpenMRS. The SQL was designed to REPLACE all the concept* tables in an OpenMRS implementation. Legacy note: Within the dropbox are a number of zip files with the prefix OpenMRS_concepts_xx.xx.xx_yyyymmdd which includes the version number of openmrs as xx.xx.xx. You can use the 1.6.x versions for all versions of 1.6. The same is true for 1.9, with 1.9.x covering 1.9.7. There also is a 1.7.3 and 1.8.3 version in the dropbox and now 2.0, 2.1, etc. also in the dropbox.

    • Download and unzip the .sql file. Be sure to read the README file about changing properties files and connection string before importing.

Translating the concept dictionary

For translating it into Spanish, one group used the SNOMED mappings.

There are several ways to get translations of the concept dictionary (and these are documented on the OpenMRS wiki as well at Terminology Service Bureau). The best way to ensure that concepts are properly translated is to work directly with Dr. Kanter's team and the TSB to include them in the dictionary. In the case of the initial Spanish translations, these were done by looking at where there was a SAME-AS map to a SNOMED CT concept and then using the SNOMED CT term in Spanish.

How to Request New Concepts in CIEL

The CIEL dictionary will probably not contain all of the concepts that you need, so you will have to add concepts to your local OpenMRS instance.  However, you should get any additional concepts to be added into the CIEL dictionary. This will ensure that the dictionary is consistent, properly mapped and can be used by others. Do not add local concepts to your forms in production if you intend to replace them with approved concepts from the international dictionary.  The easiest way to do this is to send an email to ask2164@cumc.columbia.edu with a spreadsheet of the concepts requested, or that need changes.:

  1.  This spreadsheet should have at least the following columns:

    1. Concept name in English

    2. Concept definition (paragraph) in English

    3. Concept datatype

    4. Concept class

    5. Concept maps (to ICD-10, SNOMED, etc. if you know them)

    6. Concept names in other languages, concept definition in other languages

  2. If the concept is similar to an existing concept, please include the concept it is similar to. 

  3. If the concept is part of a set, or part of a question-answer pair, please note this

Importing the dictionary using the previous SQL overwrite method

Whether you have a new installation or are updating an already existing implementation, you should do the following.

  1. The sql file that you get for the concept dictionary should have only the tables for the concepts. Inserting them will overwrite all the concept* tables except for the concept_proposal tables. Separate drug table exports will be available when updates to those tables are included.

  2. If you have any locally stored concepts you will lose them, so instead follow the strategy described in the child page.

  1. Check to make sure you have the correct dictionary for the OpenMRS version that you are using. If you have a different version, email Andy to get the right one.

  2. Make a backup of your current database (if you're updating the dictionary via MySQL dump. In your server type "mysqldump -uUSERNAME -p --port=PORTNUMBER --host=HOST DATABASENAME > FILENAME.sql" 

    example: mysqldump -uopenmrs -p --port=3316 --host=127.0.0.1 openmrs > dump.sql

    1. USERNAME is a user name for MySQL that has privileges to the OpenMRS database

    2. DATABASENAME is the name of your database, usually openmrs

    3. FILENAME is whatever you want the export file to be

  3. Be sure that mysql has been configured for large packets. If in doubt, check that the MAX_ALLOWED_PACKET variable in the my.ini file is set to a high number like 128M.

  4. When prompted for a password, use the password from openmrs-runtime.properties. Note if using the standalone version use: openmrs-standlone-runtime.properties

  5. Then import the updated concept dictionary that you have by typing "mysql -uUSERNAME -p --port=PORTNUMBER --host=HOST DATABASENAME < DICTIONARYFILENAME.sql"
     example: mysql  -u openmrs -p --port=3318 --host=127.0.0.1 openmrs < openmrs_concepts_2.0_20170703.sql

    1. USERNAME is a user name for MySQL that has privileges to the OpenMRS database

    2. DATABASENAME is the name of your database, usually openmrs

    3. FILENAME is the name of the sql file that contains the concept dictionary you received

  6. If you are running OpenMRS Platform 1.11.x and above, and the CIEL SQL file does NOT include "Update global_property set `property_value` = "" where `property` = "search.indexVersion";" (This is usually included)

    1. Please go to Administration - Maintenance - Search Index - Rebuild Search Index.

Keeping multiple OpenMRS instances with the same dictionary

The preferred method for doing this is to use Open Concept Lab and the OCL Subscription module.