One of the key strengths of the OpenMRS platform is the concept dictionary, which allows for the mapping of real world health care data needs into concepts that provide the questions and answers.

The concept dictionary provides ability to map real life concepts to specializations across health care domains such as: SNOMED CT (clinical healthcare terminology), LOINC (laboratory observations), ICD-10/11 (disease classifications), RxNORM (normalized names for clinical drugs), CVX (vaccination codes) in addition to leaders in certain medical fields such as Partners In Health and AMPATH (HIV Care and treatment).

However with great power comes great responsibility, the concept dictionary coding can easily get out of hand, with duplicate concepts leading to inability to extract data for reporting and improving the efficiency clinical care that are key goals of health informatics activities.

This guide is based on my personal experience from working across multiple diverse implementations and the fact that Open Concept Lab (OCL) is not yet in widespread production usage which would alleviate most of the pains, which includes:

Supporting the upgrade, evolution and rollout of UgandaEMR in Uganda from 350 sites in 2016 to over 1000 sites (December 2019) including implementation of 2 major revisions of national Health Management Information Systems tools
Migration of 2 custom OpenMRS implementations in Uganda to align to and build on top of UgandaEMR
Namibia PTracker PMTCT program
Enhancements of the Reference Application

The key principles to this approach are as follows:

CIEL dictionary is the official source of concepts, and first place to check for concepts
Custom concepts must be setup in such a way that updates to CIEL or other custom modules used do not overwrite the customizations

Concept Server Setup

The setup involves using the following OpenMRS instances:

CIEL dictionary server running the latest reference application version - contains the latest version of the CIEL dictionary and helps for data export when needed. The complete concept dictionary however is not recommended to be loaded for an implementation due to slowdowns in concept lookup, as sample concept numbers are:
- Reference Application 2.9.0 - 446 concepts
- UgandaEMR - 5,500 concepts
- CIEL dictionary - 54,000 concepts
Custom Concepts Server - this one contains the custom concepts and CIEL concepts that exist, is the single source of truth for the project concepts. This needs to run similar modules to what the implementation is running. I would recommend the following additional steps:
- Set the autoincrement value of the concept table to 5,000,000. This ensure that the concepts created will never be overwritten by CIEL concepts, the last numeric ID as of April 2020 is 165900 due to retired concepts etc
- Set the auto increment values of the rest of the concept* tables to 10,000,000 (there are usually more values than so these tables grow)
- Create a custom mapping for your project or implementation, and use that to reference the custom and CIEL concepts that you use in your forms and reports. This adds a layer of redirection and consistency for access
Implementation Development, Staging and Demo Servers - as needed

Moving Concepts Across Servers

There are multiple options for moving concepts from the CIEL to the Custom Concepts Server and finally to the implementation servers

Approach	Description	Notes
Use of Metadata sharing and metadata deploy modules to build of metadata packages (zip files)	- Manually downloaded from the servers and uploaded where needed - faces the challenges of manual processes - Provide a dedicated url from source servers that clients can subscribe to get updates as the deploy packages are updated following the pub-sub model	- The creation of the metadata packages is manual - The metadata packages are zip files which are difficult to debug
Download the concept data into CSV or DB Unit compliant XML	The concept files are then loaded into the implementation using either Initializer or Data Exchange modules	- This requires developers to extract the concept data from the different tables, without making mistakes. - This is still a manual and error prone process
Open Concept Lab (OCL)	Allows creation of custom dictionaries and extraction of data through an online web interface	This tool is not yet production ready but would provide the automation that solves all issues

Data Export Tools

The following additional tools can be leveraged for this purpose

Dbunit XML data export plugin for Data Grip - https://ssmusoke.com/2017/04/17/techtip-dbunit-export-from-jetbrains-datagrip/