MVP for using OCL to manage Bahmni concepts

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 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 are better off using a shared dictionary for most concepts, and only maintaining a small part of the dictionary on their own.

(Concepts are also key to designing forms, but that depends on ongoing work on a new Form tool, and is out of scope for this discussion.)

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 state, but ThoughtWorks and OpenMRS are investing time to get them ready for widespread use.

Minimum Viable Product

For purposes of this conversation, ThoughtWorks has a team working on extending OCL, and we want to define the smallest possible piece of work that will allow the Bahmni team to use OCL to improve concept management. (This team is currently working on the must-have of doing OpenMRS validation within OCL, so that users don’t inadvertently create concepts that would be invalid to import into OpenMRS.)

I propose that the MVP is to manage a “Bahmni Diagnoses Starter Set” collection in OCL, so that an upcoming implementation can start from this set, and:

  1. get a better-curated list of diagnoses (as opposed to the hospital saying “just give me all of ICD10”)
  • most diagnoses will come from CIEL, and have SNOMED mappings, synonyms, i18n, etc).

MVP Workflows

General Scenario

  • the CIEL dictionary is already loaded into OCL, so there are good concepts around
  • other early adopters (e.g. PIH) are starting to load their custom concepts into OCL
  • the Bahmni team and PIH want to create useful subsets of OCL, and combine them with custom concepts

Scenario 1 - Creating “Bahmni Diagnoses Starter Set” Collection


  • Coordinators of multiple Bahmni installations (BA/IE from core Bahmni team)
  • Clinical Domain Expert (working with Bahmni team)

Scenario 2 - Setting up Diagnoses for a Bahmni Implementation


  • Manager of one Bahmni installation (works for hospital)
  • IE setting up a Bahmni installation

Scenario 3 - Including Implementation Diagnoses in Bahmni Deployment

To be outlined later.

This depends on work on the OpenMRS OCL Subscription module. @raff and @SolDevelo are currently doing a sprint on this.

Next Steps

We’d like to get people’s opinions about whether (a) this is the right MVP to focus on, and (b) whether the activity diagrams are correct.

If we go ahead, then we’ll start doing UX analysis of how to improve the UI for these workflows. (I believe they are currently supported but require too much clicking for someone to reasonably do at scale.)

Thoughts? Please share!


Thanks for doing this Darius. I would like to make a couple of observations for your discussion:

  1. Even the process of picking and choosing a concept from several different sources can cause problems. There needs to be an editorial policy about selecting/defining concepts up front and there should be a minimal number of terminology managers in a facility and who participate in a local governance process. When at all possible, concepts should be chosen from one terminology source only (there are exceptions to this based on domain coverage, but it is dangerous to copy concepts from more than one source covering the same domain).

  2. It is usually better to build the initial concept list by searching OCL or CIEL. There are issues about modeling of concepts and even which concepts that might be most appropriate for the implementation that cannot be determined on paper. Forcing the searching to be from a paper list only is not a good idea. Looking at mapping codes from the concepts will help you understand the semantic space that the concept comes from and you want to be sure you are capturing the true intent of the user. Note that ICD-10 and other administrative code sets generally are NOT well suited for clinician entry and are meant primarily as classifications.

  3. There should be a very high bar for creating a new concept. CIEL, in particular, can help vet whether a proposed new concept is good to create (and whether it should be added to the CIEL shared dictionary). Good terminology practices are hard to maintain as you have mentioned and mixing good concepts from a curated source with potentially bad concepts is dangerous. It might make sense to think of Bahmni custom concepts as temporary proposals, that if pass a certain process get either added to CIEL and then copied down, or are formally approved to be added as custom source concepts, or are deprecated.

Happy to participate more in this discussion. I don’t want to raise the bar too high for your MVP, but remember that starting off with bad dictionary entries is a prescription for disaster as once legacy data is captured, its hard to recode it.

1 Like

@darius I am not a concept expert but I can relate to the issue of having bad concept entries, so I agree with @akanter the bar for creating new entries needs to be very high.

So a couple of other questions (apologies if I am going out of scope for the MVP):

  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

  2. 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.

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

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

All great questions, Stephen!

  1. As I understand it, if you make a collection using the “head” datasource, then it will automatically refresh with updates to the source. This is generally not a good idea unless you really trust the source. If you make a collection from a versioned source, then it will not change, ever, and it is necessary to run diff reports between versions to determine whether there have been changes. Perhaps that is a new requirement for following milestone/sprints.
  2. This is why I suggested there be a way to link new concepts to proposals so that when a new concept is created from the shared dictionary (other source), that it can be automatically replaced. The issue is the “instance data” in the EHR which would need to have its concept_IDs updated.
  3. Covered a bit above. We want to allow an automatic process for “proposal” to source concept dictionaries.
  4. This is a question for @paynejd and @darius, I think.

@darius - Well laid out. I’m not familiar with the acronym IE, but assume it represents “Implementation Engineer” and not Internet Explorer :wink:

I love the idea that PIH clinical staff can use OCL. When clinicians want a new diagnosis or procedure, we can share a URL, confirm that the concept matches their needs, and add to a collection. Is this a scenario for other implementations?

The PIH scenario is described in the master/slave section (but your flow diagrams are sweeter):

OCL should advance us to better-curated concepts and data model.

Thanks @akanter and @ssmusoke for engaging with this!

I intended to post about the bigger picture first, before focusing on the MVP, but ended up doing it the other way to meet a deadline. I will answer most of your questions on another thread that I’ll post in the next couple days.

Andy, I had over simplified to try to capture just the workflows a BA needs to know about for the MVP but you are right that (1) a back and forth between an IE and the facility staff, via OCL not paper, and (2) preferring concept prepaid to CIEL, are important to capture. I have revised my activity diagrams on paper, and I’ll update them on this thread once I’m not on an airplane.

I posted about the bigger picture of this project at Using OCL to Manage Bahmni Concepts

I also edited the diagrams inline in the first post in this thread, to better reflect (1) we prefer to propose concepts to CIEL rather than creating them, and (2) the BA/IE collaborate on reviewing existing collections, and existing concepts (rather than just “building a list”).

One more thing I noticed. The place where an IE can’t find the term in OCL should involve an iteration with a knowledge engineer more familiar with terminology in case the term IS present in OCL/CIEL but just was not found. This would eliminate an unnecessary concept creation loop.

1 Like