What is workflow OCL uses for updating a local OpenMRS implementation?

@raff and @paynejd, we have a few questions on the OCL module:

I think I am still trying to understand exactly how the OCL module will work.

Say we install the module into OpenMRS. We then select certain sources, say CIEL, for subscription purposes.

OCL then must:

  1. Identify which concepts need to be added/updated/removed from the local dictionary.
  2. Create the new concepts in the local dictionary
  3. Create the mappings for the new concepts in the local mapping table
  4. Update over time the dictionary, redo (1) - (3)

Could you explain the workflow of OCL in each of these cases?

Also, say we have an AMPATH concept mapped to the AMPATH source and also map it to CIEL. Could you please specifically discuss the workflow for what happens in a case where the CIEL concept is modified in some way, (say retired)? Ideally all AMPATH concepts will remain mapped to CIEL concepts but I’m worried this will introduce instances (perhaps rare though) of cases where we end up “losing” the mapping to the existing AMPATH concept.

Thanks for your help.

1 Like

This should be the basis for a session at the Implementer’s Conference :slight_smile: !

@raff & @paynejd , it looks like the only documentation for OCL Subscription is this page, which is outdated.

@jdick, my understanding is:

  • You currently subscribe to one collection (multiple subscriptions is a future feature)
  • When you ask it to (i.e., click on a button), the module will fetch any new or updated concepts from that collection and update them in your instance, which would include creating and/or updating concepts and mappings in your system.
  • Local concepts (e.g., AMPATH concepts mapped to a CIEL concept) would not be affected/modified (the concept or its mappings) by the OCL Subscription module.

Unconference topics can be proposed here

Thanks @burke.

What is the workflow for updating the local dictionary if a concept is modified in ciel? Or is that even possible? I’m worried that the revision may result in the mapping type no longer holding true, i.e. it needs to move from same-as to narrower than, etc.

Or let’s say a CIEL concept is retired (does that happen?). Will that retire the concept in the local dictionary? I can see many problems with that as it could affect downstream data collection forms relying on a retired concept.

Both the examples bring up concerns over workflow for modification/retiring of previously synchronized concepts. Clarity on that workflow would prove extremely helpful.


The organization managing the vocabulary would be in charge of maintaining it. If you have subscribed to CIEL or another collection on OCL, then the module will update any of those concepts when you ask it to. If you maintain local concepts, then you are responsible for maintaining them and they will not be changed by this module.

It would be unusual for CIEL to receive published concepts, but in the event a CIEL term was updated in a manner that would make you want to stop mapping to it, you would be responsible for deleting the mapping from your local concept. I don’t know if the module currently, after syncing, shows you all changed OCL-hosted concepts for which you have mappings from locally managed concepts to facilitate review, but, assuming it does not do this, it might be a reasonable feature request.

The primary purpose of the OCL Subscription module is to facilitate getting updates from a centrally managed collection of concepts and not to manage local concepts and mappings.

If you have a locally managed concept mapped to a CIEL concept and the CIEL concept was retired, then you would be responsible for deciding whether or not you wanted to retire the locally manage concept, delete the mapping, or leave it mapped.

Again, the point of OCL is not to manage your local concepts (including their mappings); rather, to allow you to have centrally managed concepts in your system and facilitate distributing updates for those centrally managed concepts.

In other words, the OCL Subscription module is primarily designed to help automate the process of using centrally managed concepts (like CIEL) in your server, not to manage your local concepts or their mappings to CIEL concepts.

This is an extremely helpful overview. I did not appreciate that this was modeled on a central authority.

It will be good to discuss this further at the conference and how to practically make this work in the setting where implementers need to maintain some way of managing a local dictionary.


1 Like

I have a different take on this from Burke’s.

I’ve been assuming that the biggest value add of OCL and the subscription module is to allow you to assemble your implementation’s dictionary from 90% shared content, and 10% local/custom content.

The general workflow there is that you would have an “AMPATH” organization on OCL, which would have an “AMPATH Custom Concepts” source. Then you would have a collection like “Combined Concept Dictionary” in which you would include the CIEL concepts that you want plus the AMPATH Custom Concepts that you want. And your OpenMRS servers would subscribe to this collection.

So you would use OCL (and not OpenMRS) to do concept management, including local ones, because it allows you to easily see when you could be pulling in an existing concept, vs when you need to create your own custom one.

I wrote more about this vision in the context of Bahmni a year ago: Using OCL to Manage Bahmni Concepts. We haven’t actually done any of this yet though, but I believe the OCL tooling is now ready to support this (which wasn’t true a year ago). AMPATH’s scenario is a bit less complex (because you’re not talking about having starter sets for multiple implementations) and is probably close to how PIH is drawn in the diagrams.

(I have not thought through what you’d do in the situation where you start off by using a CIEL concept but you then decide to fork it later.)

The way we at PIH are planning to use OCL is in line with what @darius is saying, I believe… Is this correct @ball?

Take care, Mark

I share the @darius vision. OCL will be a great help. It supports our vision of stealing concepts from CIEL, but not all of it while at the same time maintaining our current collection(s) and adding new concepts to our collection which don’t fit with CIEL. The other part of concept management which we should discuss – we support CIEL with adding new content (terms and translations). Not sure about that process.

I look forward to discussing in person and online.


I think I was thinking about a similar model as well as to what @darius had suggested.

@raff, does the OCL module presently support the ability create what Darius is describing as “collections”?

I’d like to better understand how PIH is thinking about their management workflow. My sense is that it goes something like this:

  1. Look in CIEL to see if the concept you need exists. If it exists, then use it.
  2. If concept not in CIEL, then create a local one, make a request to add to CIEL. In data collection forms, reference the local concept.
  3. Once concept created in CIEL, then, (ideally via OCL), update your implementations dictionary with new ciel concepts. Map your local to the CIEL concept.

4.?? Update data collection forms to use CIEL mapping or continue using local mapping? In the underlying dictionary, the same concept_id will be used in the obs table independent of which mapping is used (assuming the mapping is “SAME AS”. So this issue is related solely to data collection form management. I suppose you might end up with an issue if there ends up being a slight variation between local and CIEL.

Looking forward to discussing this further at conference.

A collection can be created in the OCL service and the subscription module can be configured to subscribe to it. In other words you maintain collections entirely in the OCL service and the module is a dumb import tool, which brings a curated collection into your OpenMRS instance.

Thanks @raff. This is good news. Could you provide more details on what you mean by dumb update?

By dumb I mean the import process is very simple as for example compared to the one implemented in the Metadata Sharing module. It is to be able to handle bulk imports of curated content. It includes a number of simplifications:

  1. It is importing concepts from OCL into local dictionary overwriting any concepts you may have had in the past with same UUIDs (same applies to mappings).
  2. It does not do any merges, so if you add for example translations locally, they will be lost with a next update, if you do not add them in OCL.
  3. It is possible to have some local concepts in addition to those imported from OCL, but you need to resolve any issues manually, if they use same preferred names as OCL concepts. No validation errors resolution is implemented.