Using OCL with Existing OMRS Dictionaries

Scenario: As a developer for an existing set of OpenMRS implementations with legacy concepts already being used in the field, I want to start using OCL & the Dictionary Manager tools to manage our concepts ASAP, but I need to be able to use my legacy concepts so that we can use OCL with no impact to our current forms and reports. 


As learned by the UgandaEMR team at the 2022 UCSF/OpenMRS Mombasa Hackathon: 

Step 0: Check if you are breaking any OpenMRS validation rules

Try running the Concept Validation Queries to see if there are any cases of concepts or names that break OpenMRS concept validation rules.

Step1: Get your SQL payload

Get a SQL dump from your EMR: Use this SQL Script: Note: This runs the script in a docker container. You will need docker installed, as the script starts up a docker container. 

mysqldump -u root -p"$MYSQL_ROOT_PASSWORD" \
  concepts concept concept_answer concept_attribute concept_attribute_type concept_class \
  concept_complex concept_datatype concept_description concept_map_type \
  concept_name concept_name_tag concept_name_tag_map concept_numeric \
  concept_reference_map concept_reference_source concept_reference_term concept_reference_term_map concept_set \
  concept_stop_word > pih-concepts-db-20210503.sql

Step 2: Get your JSON payload

Step 3: Create your source on Open Concept Lab

Create a source within the OCL Staging Environments ( When creating the source, be sure to select the OpenMRS Custom Validation Schema to ensure you don't introduce new concepts that break OpenMRS validation rules.

Step 4: Bulk Import

Use the OCL Bulk Import JSON was bulk imported into the PIH source on OCL using the OCL app's bulk import feature.Workflow

Current Issues & Blockers


Technical steps for PIH example: Migrating to OCL: PIH Use Case

CIELocl_omrs Dictionary Conversion Script
(converts DB dump into OCL import file)
OCL Bulk ImportOCL TermBrowserDM WebAppOCL Subscription ModuleOMRS EMR
OMRS Nuance
(created b/c Bulk Import doesn't support OMRS SQL - script converts from OMRS model and OMRS DB to OCL model)

Export your existing content (use SQL script here)
Sort Weight

Being created in version of OMRS that doesn't have sort weight on concept answers

Burke to work with Andy

Sort Weight on Concept Answers is not consistently populated, and frequently does not match the expected value. So either this isn't getting imported correctly into OCL, isn't getting exported correctly from OCL, or isn't getting imported correctly in the subscription module

Add column for CSV format "sort_weight" and apply to correct mapping

Add support for importing sort_weight

Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.

Matching Sources
The ocl_omrs script hardcodes the OpenMRS and OCL versions of these names (e.g., "SNOMED CT" in OpenMRS is "SNOMED-CT" in OCL)

The subscription module creates new concept sources if needed, and has no way to match up against existing concept sources if they are named slightly differently. (No validation step.) For whatever reason, in our existing system we have "SNOMED CT" whereas in OCL this is "SNOMED-CT", so these are all getting associated with a different source. Also all of the expected "PIH" mappings are imported as "PIH-temp" mappings, which makes the diffs hard to use to find actual differences.

OCL Module should prompt user: "I'm about to create a new source. Is this what you want? Or, pick one to map to/use."

2 Yes Concepts

Where are the 2 yes's coming from? To investigate...
Different Concept Total

PIH experience: Before the import there were 5713 concepts in the dictionary, and afterwards there were 5884 concepts. I will try to dig into this different

Need codes

Respect new map type called "Code":

Respect new map type called "Code":