Child pages
  • OCL for OpenMRS MVP v1.0.0 (September 24, 2018)
Skip to end of metadata
Go to start of metadata

Introduction & Context

One of OpenMRS’ strengths is its concept-based data model that allows each implementation to be configured in a suitable way for its own clinical scenario. (Learn more at the Concept Dictionary Basics OpenMRS wiki page.)

This approach also leads to a lot of chaos, as every installation is free to create their own concepts in isolation. Over the years we have created several methods for sharing concepts, but none of these have made it easy to follow best practices, or led to large-scale adoption of concept sharing.

Of note is the curated CIEL concept dictionary, which has been adopted by many OpenMRS sites, but given our current tooling, implementations are faced with an all-or-nothing choice where they can either create their own local concepts, or get updates to CIEL, but not both.

The ideal situation would be if every OpenMRS installation was managing their concepts in a shared service on the web, and the easiest path was for them to reuse existing concepts 90% of the time (either curated ones from preferred sources like CIEL, or crowdsourced ones from some other implementation), and to only create custom concepts when needed.

Open Concept Lab (OCL) promises to be this shared service, but its UI does not allow the typical user to actually carry out the standard workflows they need for proper OpenMRS dictionary management. (For some examples of this see posts 1, 2, and 4 in this thread.)

(See an in-depth description a proposed workflow of using OCL to manage Bahmni concepts, and the MVP set of workflows. I suggest clicking these links and peeking at the diagrams, but not trying to read the whole posts at this point.)

This project is about:

  • building a new UI from scratch called “OCL for OpenMRS”

  • It will be “official” and hosted on OCL servers

  • It will be built in a future-looking JS-based technology, and use the OCL REST API

  • It would specifically (and only) target the use case of managing OpenMRS dictionaries, so it will be less powerful but easier to use than the traditional OCL UI

Once this project is complete, a typical new OpenMRS implementation would no longer manage concepts via the OpenMRS UI at all. Instead your OpenMRS server would use the Open Concept Lab module to subscribe to a dictionary that you only manage on the cloud through this new application.

What is the Traditional OCL today?

Open Concept Lab runs at

Its backend ( is written in python/django.

The frontend ( is a mix of django web and Angular, but we think of this front end as old code that needs a rewrite on a new tech stack.

In this project we will probably make small changes to the OCL back end, but we will not touch the front end (except that we will include some links in our UI to take people to “traditional OCL”).[Done]

What is the OCL MVP today?

Open Concept Lab runs at

Its backend ( is written in python/django.

The frontend ( is a mix of React and Redux.

What is a “Dictionary” and how does this compare to OCL’s existing domain model?

We are trying to simplify things as much as possible for an entry-level OpenMRS user who just wants to manage a dictionary, and doesn’t really know anything about concept management, or OCL.

OCL’s domain model doesn’t actually have anything called a “Dictionary”. It has a “repository” which can be either a “source” or a “collection”.

We would introduce the idea of a “Dictionary” for this application, and it represents the main thing than an OpenMRS implementer would think about, i.e. it’s where you both create your own concepts and include other people’s concepts.

In the OCL domain, the “XYZ Dictionary” is represented by:

  1. A source called “XYZ Dictionary Custom Concepts”. (This could be optional, created on demand the first time that someone creates a custom concept.)

  2. A collection called “XYZ Dictionary”. This automatically includes all of the custom concepts from the source (not natively supported by OCL so we need custom code for this), and all concepts that the user manually adds.

We would likely add a REST API to OCL for this domain object, following the “backends for frontends” pattern). See the proposed REST API, and related Talk thread.

Note that in OCL, adding a concept and its mappings is independent, but in our application we will hide that from the user: when you add/remove a concept in the Dictionary, all its mappings are added/removed too. (Need to clarify exactly what “its mappings” means.)

Relationships between Concepts

In OpenMRS there are strong relationships between concept (Question/Answer, and Set/Set Member), whereas in the OCL API these are treated as mappings, which are weaker.

In our new UI we should treat these as stronger relationships. Specifically, if I add the “What is your favorite color” question to my dictionary, it should automatically also add the answers “blue” and “green”.

Starting From an Existing Dictionary

When you create a new dictionary by copying an existing one, this should:

  1. Add a reference to each custom concept from the other dictionary

  2. Add all references that are in the other dictionary

MVP 1.0.0

The “true” MVP is enough for a new implementation of OpenMRS to get started with a custom dictionary, using our new best-practice workflows.

  1. Create a new Implementation Dictionary, belonging to an organisation [Done]

  2. Add concepts from CIEL to an implementation dictionary [Done]

  3. Create custom concepts in an implementation dictionary [Done]

  4. Release a version of an implementation dictionary [Done]

  5. Subscribe to a released implementation dictionary from a fresh OpenMRS installation of Platform + Legacy UI. [Done]

However this is not a sufficient MVP for Bahmni and PIH, who are the most interested and engaged consumers of this application. So our initial target is actually a bit larger than this, i.e. an MVP+.

MVP+ (Soon After MVP Features)

These are the additional use cases needed by our likely early adopters.

  1. Start from an existing OpenMRS installation that already has a concept dictionary (e.g. “start managing my dictionary in OCL” with some kind of one-time upload)

  2. Download a released implementation dictionary so it can be uploaded to OpenMRS in code (leveraging the OCL Subscription module)

  3. Create an implementation dictionary with multiple Preferred Sources (e.g. CIEL and Bahmni Demo Concepts; or CIEL and PIH Custom Concepts)

  4. Start a new implementation dictionary by making a copy of an existing starter template

    • Organizations could indicate which of their collections are “starter templates”

    • E.g. Bahmni would have a “Bahmni Starter Dictionary” and some implementer might have its own “ACME TB Starter Set” and “ACME Generic Hospital Starter Set”.

  5.  Add multiple CIEL concepts to your implementation dictionary in bulk, by specifying many concept ids.

  6. Subscribe to a specific (non-latest) version

  7. [DONE] Create custom concepts in an implementation dictionary, using standard templates for Diagnosis, Symptom/Finding, Procedure, Q-and-A, Drug, Test, Set

  8. Prevent duplicate concepts by suggesting existing concepts to use, while the user creates a new concept

  9. Browse other people’s Dictionaries (may implement this early as part of the “make a copy” feature)

    1. Probably also support browsing OCL sources like CIEL

  10. Copy a dictionary, that supports both “clone custom concepts” and “refer to custom concepts in original dictionary”

Medium-term Features

  1. Manage historical released versions of a dictionary

  2. Propose a concept to CIEL

  3. “Fork a concept”

    1. Make a copy (e.g. of a CIEL concept) into your custom source;

    2. Should automatically add a link like “forked from CIEL/1234/version-uuid”

    3. (?) Ask if they are going to change the meaning or not. If so, need to change the mapping types. (SAME-AS => NARROWER THAN)

    4. (?) every time they edit a forked concept, ask “are you changing the meaning”

    5. (?) if they fork a CIEL concept add a mapping like NARROWER THAN CIEL 123

  4. Add concepts to your dictionary (searching across all your preferred sources)

Long-term Features

  1. Allow the CIEL dictionary to be primarily maintained in OCL using this UI [Andy Kanter]

  2. Compare dictionaries (e.g. “what’s different between ‘Bahmni Starter Set’ and ‘CIEL’?”) [Stephen Musoke]

  3. Add keywords or tags to concepts (e.g. to tag the HIV-related ones), and use this in search [Pramida Tumma]

MVP Screenshots


User Home

After login you see this home screen

Public Dictionaries

You can browse through all the public dictionaries, including those that belong to other people.

New Dictionary

A real-life user may be creating dictionaries for different reasons, e.g. they may be creating an implementation dictionary for a specific hospital, or a starter set that will eventually be used by multiple hospitals. The UI for these is the same.

Dictionary Overview

Dictionary Concepts

Note: Remove/delete will affect the current and future version of your dictionary, but it won’t affect past versions. (A nice-to-have future feature is to notify the admin of an OpenMRS server running the OCL Subscription module that something was removed on the server, and they may want to clean it up.)

Add Concepts (e.g. Add CIEL Concepts)

Bulk Add Concepts

Create another kind of concept

Although this is displayed last in the menu, this is the generic concept creation screen (and should be implemented first). This screen should also be the basis of the Edit Concept screen.

[Post-MVP] suggest similar concepts from preferred sources (“Are you sure you don’t want to use Xyz from the CIEL dictionary?”) as a background search as you type. (Would be based on a fuzzy text search based on names, and also based on mappings.)

Create Diagnosis concept

This screen should be implemented as some kind of template on top of the generic create concept screen. Each different type of concept (Diagnosis, Drug, Symptom/Finding, etc) gets it own template which would limit the possible datatypes and classes, and prepopulate the mappings table.

Create a set of concepts

Open Questions

Make a copy of an existing implementation dictionary

There is some complexity here because in some cases you might want to clone each of the custom concepts in the dictionary you’re copying, and in other cases you might want to convert those into references.

TODO: “Copy in another dictionary” in Dictionary Concepts

If I’m copying my own dictionary into the same organization, I might also want to pull some of the custom concepts up into a shared source across two implementations.

Fork a Concept

How does this work? (If you’re forking and changing the meaning vs if you’re forking and making cosmetic changes.)

Note that in OCL a concept and its mapping are separate entities (unlike in OpenMRS), so forking a concept likely means forking its mappings also.

Missing from OCL Server API

  • Make a copy of an entire collection/source version or of individual concept/mapping version

  • Bringing a collection’s references up-to-date in a semi-automated fashion


  • No labels