Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata


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.

Specific Objectives

  1. How to get the CIEL/MVP concept dictionary.
  2. Procedure for translating the dictionary (in our case into Spanish).
  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, spanish in our case)


  • These instructions were valid up to OpenMRS 1.9. From 1.9 onwards, the CIEL/MVP dictionary comes standard with the standalone version of OpenMRS.

Getting the latest concept dictionary

Currently the latest concept dictionary is saved in the CIEL dropbox. To get access to this folder you should email Andrew Kanter at CIEL ( or The dictionary is distributed as a SQL export from a particular version of OpenMRS. The SQL is designed to REPLACE all the concept* tables in an OpenMRS implementation. 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.

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

It is also possible to view a recent version of the CIEL/MVP dictionary at This website allows you to search the dictionary using names, mapping codes or list contents. You can then use the metadatasharing module to import a subset of the codes unto your dictionary (see below). However, the current method of overwriting the tables is the only way to do this for a large number of entries and to ensure that you are remaining in synch with the editorially-controlled CIEL dictionary.

Translating the concept dictionary

For translating it into Spanish, we used the SNOMED mappings which exist for English and Spanish (but not for other languages yet).

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.

Importing the dictionary

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.
  2. If you have any locally stored concepts you will lose them, so instead follow the strategy described in the child page. (See new concept proposal strategy from Darius on 05/2012).
  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= 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 Note if using the standalone version use:
  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= 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";"
    1. Please go to Administration - Maintenance - Search Index - Rebuild Search Index.

Keeping multiple OpenMRS instances with the same dictionary

To update the concept dictionary for multiple OpenMRS instances you will have to do them one by one (unless you are using the Sync Module). This can be both time consuming and you can have problems with the different concept dictionaries, so you should do this only when you need to have the latest version.

Getting local concepts to be added

The CIEL/MVP dictionary will probably not contain all of the concepts that you need, so you will have to add concepts to you local OpenMRS instance.  However, you should get these concepts to be entered into the CIEL/MVP 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 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 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

Things that need to be written

  1. Strategy for when you update a concept dictionary with the latest version how you remap the local concepts to either the ones that have been incorporated in the MVP/CIEL dictionary or keeping them locally
  2. How the translation was done into Spanish and if we (eHS) could do it
  3. Check to make sure that using mysql dump is the best way to get latest version of dictionary into your OpenMRS instance
  • No labels

1 Comment

  1. Unknown User (darius)

    Suggestions from Andy Kanter about the process to go through when mapping existing forms or data sets to the MVP/CIEL dictionary:

    High-level points:

    • We shouldn't just send MVP/CIEL a list of the missing concepts, but we should sent them a spreadsheet that also includes the concepts we've already found, so they can comment on whether our mappings seem right or not.
    • We should send them regular updates of our incomplete work, and not send them what we consider to be the complete request at the very end.
    • It is best to use a structured spreadsheet, and he's provided an example, which (I don't know how to attach here)


    1. To start, we should collect all of the concepts that we want to map, filling out the "Actual text on form" and "Other text" columns in the spreadsheet. (Possibly also Class and Datatype.)
    2. Look through instructions/documentation for the forms, and put any supporting information in the "Other text" column, and if available, SNOMED CT or ICD 10 maps.
      It ends up more accurate if we separate the above steps from the next one
    3. Take that entire spreadsheet, and use mcl:search to look for matching concepts that are already in the dictionary. For any that are found, fill in the "CIEL/MVP ID" and "CIEL/MVP Concept Name" columns.
    4. At this point (and actually several times before this point) share progress with everyone so we can make any necessary adjustments early.
    5. Ensure that Class, Datatype, and Submitter question/comments are all filled out for the remaining unmapped concepts.
    6. At this point (and several times beforehand) share progress with everyone, and we can decide whether to start creating the missing concepts immediately, or wait for feedback from CIEL/MVP.