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.
Open Concept Lab runs at https://openconceptlab.org/.
Its backend (https://github.com/OpenConceptLab/oclapi) is written in python/django.
The frontend (https://github.com/OpenConceptLab/ocl_web) 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]
Open Concept Lab runs at https://openmrs.qa.openconceptlab.org
Its backend (https://github.com/OpenConceptLab/oclapi) is written in python/django.
The frontend (https://github.com/openmrs/openmrs-ocl-client/) is a mix of React and Redux.
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:
A source called “XYZ Dictionary Custom Concepts”. (This could be optional, created on demand the first time that someone creates a custom concept.)
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.
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.)
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”.
When you create a new dictionary by copying an existing one, this should:
Add a reference to each custom concept from the other dictionary
Add all references that are in the other dictionary
The “true” MVP is enough for a new implementation of OpenMRS to get started with a custom dictionary, using our new best-practice workflows.
Create a new Implementation Dictionary, belonging to an organisation [Done]
Add concepts from CIEL to an implementation dictionary [Done]
Create custom concepts in an implementation dictionary [Done]
Release a version of an implementation dictionary [Done]
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+.
These are the additional use cases needed by our likely early adopters.
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)
Download a released implementation dictionary so it can be uploaded to OpenMRS in code (leveraging the OCL Subscription module)
Create an implementation dictionary with multiple Preferred Sources (e.g. CIEL and Bahmni Demo Concepts; or CIEL and PIH Custom Concepts)
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”.
Add multiple CIEL concepts to your implementation dictionary in bulk, by specifying many concept ids.
Subscribe to a specific (non-latest) version
[DONE] Create custom concepts in an implementation dictionary, using standard templates for Diagnosis, Symptom/Finding, Procedure, Q-and-A, Drug, Test, Set
Prevent duplicate concepts by suggesting existing concepts to use, while the user creates a new concept
Browse other people’s Dictionaries (may implement this early as part of the “make a copy” feature)
Probably also support browsing OCL sources like CIEL
Copy a dictionary, that supports both “clone custom concepts” and “refer to custom concepts in original dictionary”
Manage historical released versions of a dictionary
Propose a concept to CIEL
“Fork a concept”
Make a copy (e.g. of a CIEL concept) into your custom source;
Should automatically add a link like “forked from CIEL/1234/version-uuid”
(?) Ask if they are going to change the meaning or not. If so, need to change the mapping types. (SAME-AS => NARROWER THAN)
(?) every time they edit a forked concept, ask “are you changing the meaning”
(?) if they fork a CIEL concept add a mapping like NARROWER THAN CIEL 123
Add concepts to your dictionary (searching across all your preferred sources)
Allow the CIEL dictionary to be primarily maintained in OCL using this UI [Andy Kanter]
Compare dictionaries (e.g. “what’s different between ‘Bahmni Starter Set’ and ‘CIEL’?”) [Stephen Musoke]
Add keywords or tags to concepts (e.g. to tag the HIV-related ones), and use this in search [Pramida Tumma]
After login you see this home screen
You can browse through all the public dictionaries, including those that belong to other people.
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.
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.)
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.)
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.
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.
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.
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