Using OCL to Manage Bahmni Concepts

[A lot of the Background section is the same as MVP for using OCL to manage Bahmni concepts. If you read that, you can skip straight to the “plan” section here.]

Background on dictionary management

“Concepts” are at the core of the OpenMRS platform, and being able to configure the system’s clinical content via user-controlled metadata makes Bahmni and OpenMRS very powerful. That is the key to making lots of the system configurable by non-programmers.

It is (deceptively) easy to create new concepts, and this allows implementations to get up an running fast, but the long-run management and maintenance of a concept dictionary is much harder, in ways that are not evident as you get started. It’s easy to create a concept that will look correct on one form, but harder to think about how to model it for reuse on multiple forms. It’s easy to skip the work of mapping a concept to other standard terminologies, but this is a required step if you’re going to use those concepts for decision support, or be able to exchange data with external systems and HIEs. (An implementation should know that Systolic Blood Pressure is 271649006 in SNOMED CT, and 53665-6 in LOINC, but they shouldn’t have to spend their own time figuring this out.)

In the long run, maintaining a high-quality dictionary requires a significant time investment, and most implementations find this hard to justify on their own.

Every implementations does need to be able to create concepts to capture the local variation inherent to healthcare, but the vast majority of concepts that an implementation uses are not unique, and they would be much better off using a shared dictionary for most concepts, and only maintaining a small part of the dictionary on their own.

One weakness in Bahmni is that we have coupled “form building” and “dictionary management” too tightly. Today, when doing a new Bahmni implementation, an implementation engineer works with facility staff to create a spreadsheet of concepts, and loads this into their implementation. This works well at first glance (people are good at collaborating on spreadsheets) but it’s not a good way of capturing a concept’s synonyms, or its mappings to standard terminologies, and it doesn’t help make subsequent implementations faster to do.

A better vision

In a better world, there would be a shared space where:

  1. a few “authorities” (like CIEL) invest in creating high-quality curated concepts
  2. Bahmni and other large-scale implementers create convenient subsets of (1), e.g. “WHO essential medications (structured for OpenMRS)” or “Diagnosis Starter Set for PIH Implementations”
  3. Individual implementations can create concepts specific to their own needs
  4. Individual implementations compose their specific dictionary by taking over 90% of their concepts from (1) and (2), and the rest from (3).

The Open Concept Lab (OCL) is a tool that wants to provide that shared space, and preliminary work has been done to create an OCL Subscription module for OpenMRS. Both OCL and the subscription module are in a beta stage, but ThoughtWorks and OpenMRS are investing time to get them ready for widespread use.

Building forms will become a separate step, which depends on the new Form Builder tool being worked on in parallel, so we mostly don’t discuss it here.


  1. Managers of one Bahmni installation
  • one per Bahmni implementation, will typically work for the hospital/MOH/NGO
  • Implementation Engineers who set up and maintain a Bahmni installation
  • Bahmni IE team
  • IEs at implementing partners
  • tech lead for self-service implementers
  • Coordinators of multiple Bahmni installations
  • core Bahmni Team
  • Implementation Partners
  • Large-scale self-service implementers (e.g. PIH medical informatics team)
  • Clinical and Program Domain Experts (who are specifically interested in Bahmni)
  • domain expert contracted to build content for a clinical area for a Bahmni project
  • domain experts at NGOs (e.g. PIH clinicians)
  • Terminology Experts (not specific to Bahmni)
  • @akanter, @judy, and others at CIEL

Our plan

Implementers should use a purpose-built Terminology Management Service (OCL) to manage concept dictionaries for Bahmni implementations. This will replace using spreadsheets and the OpenMRS concept dictionary screens. (We recognize that in practice, changes still sometimes need to be made on the ground, when offline, but we hope to minimize this.)

OCL should be seeded with high-quality curated, relevant content, which includes:

  • (a) concepts
  • primarily maintained by terminology experts and domain experts
  • Bahmni implementations should prefer CIEL, though other dictionaries may arise in domains not well covered by CIEL
  • (b) drug formulations
  • some maintained by terminology experts and domain experts, e.g. WHO essential meds
  • some maintained by coordinators of multiple implementations, e.g. Ayurvedic Meds for Bahmni implementations in India
  • © starter sets, and collections, drawn from (a) and (b)
  • primarily maintained by coordinators of multiple implementations

The content ecosystem would look something like this:

Then, the workflow of an IE doing a single implementation is:

  • Pick the appropriate starter sets for the implementation’s context (80% of content)
  • may decide to fork the starter sets, or to include them by reference (forking allows removing unwanted concepts from the implementation copy)
  • Review current state of content with the implementation and identify gaps
  • Pick additional concepts from curated sources like CIEL (10% of content)
  • Propose new concepts to CIEL, when the implementation timeline permits it
  • Create any missing concepts, for site-specific requirements, or if timeline doesn’t permit waiting for CIEL (10% of content)
  • Create forms based off of these concepts

The IE would repeat this workflow iteratively with hospital stakeholders. (In practice, in early iterations new concepts will be proposed to CIEL, while in later iterations a time crunch may prevent this.)

Embedded in the ecosystem describe above, it would look like this:


OCL, OpenMRS, and Bahmni do not currently support all the workflows we need to carry out this plan. High-level gaps we see are:

OCL Gaps

  • Support “OpenMRS Validation” of OCL sources and collections, so that users don’t inadvertently create concepts or dictionaries they cannot import into OpenMRS/Bahmni [in progress]
  • Good UX for the “search for a concept (preferring CIEL), and add it to my collection” workflow
  • Tool to review current state of a collection (e.g. using SNOMED or ICD-10 maps to help visualize the semantic space being covered)
  • “Propose a concept” workflow

OpenMRS Gaps

  • Subscription module support for collections
  • Subscription module support for loading a downloaded artifact (e.g. ZIP file) rather than live sync

Bahmni Gaps

  • Use the OpenMRS OCL Subscription module to load concepts during deployment
  • new Form Designer technology so that we don’t need implementation-specific concepts to achieve desired visual layout

Next Steps

The immediate next step we are pursuing is to work on an MVP to cover the highest-priority gaps. This is described at MVP for using OCL to manage Bahmni concepts

We don’t have further steps mapped out yet, but we welcome:

  • input into and suggestions about this approach
  • individuals or groups willing to contribute to further development of OCL
  • Bahmni and the rest of the OpenMRS Ecosystem will really benefit from this!
  • OCL is a Python/Django stack, and you can reach out to me or to @paynejd privately if you are interested in contributing.

@ssmusoke asked some questions in MVP for using OCL to manage Bahmni concepts that I am going to answer in this thread instead:

  1. I am assuming the collections are by value not by reference - in that the concepts are copied into the collection rather than holding a reference to the base definition, so that when the base concept changes the copy becomes stale. So what is the support to sync and find out-of-date definitions

Collections are by reference, and this reference is to a concept version, so they won’t “drift” after you create them. (It may eventually be allowed to have a collection refer to the head version of a concept, but that’s not a priority for me.)

OCL eventually needs tools to help you see when the concepts your collections refer to have updates, but this is not a foreseeable priority for work that I’m directing.

  1. While the baseline concepts CEIL, SNOMED etc are there, what is the support for namespaced concepts - say for a Hospital XYZ which may conflict with later CEIL/SNOMED concepts? So that custom concepts “do not pollute” the defined and curated lists.

The idea is that OCL is a shared space that everyone (whether they’re a recognized authority or just an implementation) can create concepts in their own namespace, and/or copy concepts from others.

CIEL and SNOMED are only “special” insofar as there’s a web of trust around them that leads people to look at these first. So, given today’s OCL code, when you search for “Diabetes” you’ll find matches from CIEL and from Hospital Xyz with no indication of which you should be looking at.

I guess that OCL will eventually weight its search results to boost concepts/sources with more references. But in the short run this doesn’t matter much since the early adopters are most interested in using CIEL subsets, and not so much in creating their own concepts.

  1. What is the process and support for adding a custom namespaced concept to the curated list? If not yet then still okay

You just create your own user account, or your own organization, and create your concepts. There’s no special process.

  1. How can the collection be downloaded from OCL for application without an online connection - MDS, SQL script?

That’s being worked on in this sprint. It’s going to be a new packaging mechanism (not MDS or SQL, but rather based on the REST representations in OCL.)

1 Like

As a doctor, I’m not really understand the technical things. But I’m glad to contribute my knowledge for terminology work.

not sure how can I help but don’t hesitate to ask.

Thanks Pi

1 Like

Hi all, a brief update that several of the above gaps have been addressed (OpenMRS validation in OCL, subscription module, workflow for finding a concept and adding it to a collection). We are forming an “early adopters” group to test out the OpenMRS-OCL subscription module to keep a local OpenMRS instance up to date with a source or collection in OCL. We will be doing this over the next several months. I’ll start a new conversation in OpenMRS Talk in a few days, but please let us know if you’d like to be an early adopter and help test!


Hi Jonathan,

I would like to test the module. Please let me know the details once the instance is up.


Hi Pramida,

Thank you for your interest! Will you be attending the OpenMRS conference in Malawi by chance? There will be a few others there that are also beginning to test the module that we can connect you with to get started.

Let me work with Rafal to put together some information and instructions for those who are ready to test.

Thanks, Jon

Thank you Jon. Sorry that I am not attending the conference. We are trying to see how we can integrate OCL with Bahmni, so, I think testing it would help us knowing OCL better.

Please, I need to contact you because I have a problem understanding the matter on my email I am waiting for you as soon as possible

Hamad, Darius is rarely on this channel any more. There is quite a lot of discussion on talk about OCL and I believe it might be a good idea to attend the squad calls on Wednesdays: Notes :

When : Wednesday 7:30pm IST | 5pm Nairobi | 4pm Cape Town | 2pm UTC | 9am Boston | 6am Seattle

Where : Join from computer or mobile:

1 Like