How to handle local adjustments of CIEL concepts within OCL

@paynejd (and @akanter),

During our OCL for OpenMRS squad meeting today (notes from 2020-08-26), we are preparing for an MVP launch of the OCL for OpenMRS frontend client and working through some of the real life issues. Some questions came up that we thought you two might be able to help answer.

It’s common for implementations (e.g., PIH) to make adjustments to CIEL concepts for local use.

  • Adding an answer to a question with coded answers
  • Adding translations
  • Adding/changing the preferred name
  • Adding short names to meet local needs

Does OCL support the notion of using a CIEL concept with local adjustments like these? It seems like we would want to promote non-breaking changes (i.e., changes that don’t change the meaning of the concept, but just adapt it for local use) to use the CIEL concept with local adjustments rather than forking the concept.

(p.s., I know @paynejd is on holiday this week, but didn’t want to forget to ask this question… so posting here but not expecting a response this week)


Yes, lets’ discuss. We envisioned additions to local versions of concepts, but not edits. Not sure how changing preferred name works. The idea is that any changes to the source concept would be cascaded down to the local versions (such as changing and ICD-10 map, addition of a new concept_name, etc. If a change to a source was not wanted, the user would be able to not accept recommended changes. The version of the source would change, but the local concept would still be mapped to the prior version. If the user wanted to only accept certain changes but still upgrade to the latest version of the source concept, we would have to handle that somehow. All good discussion points.

Thanks @akanter… for reference, the “adding/changing the preferred name” I believe would be about changing with name is flagged as preferred, not necessarily editing the name that is currently preferred…

Here’s an attempt to represent the common scenario @ball described…

Let’s say CIEL defines a coded concept:

Concept ID 123
Fully specified name Civil Status ← preferred name
Alternative names Marital Status
Answers Single, Married, Divorced
Translations English, Italian

PIH uses this concept 123 in their forms, but makes some local changes:

  • Add French translations
  • Make “Marital Status” the preferred name
  • Add “Separated” as an answer

None of these are breaking changes (i.e., they don’t change the meaning of the concept). Some of the changes might eventually make it back into CIEL (translations, other possible answers), but other changes will remain specific to PIH needs (changing the preferred name).

It’s important to note that PIH doesn’t want to clone/fork the concept to a new local concept, because they’re already using CIEL 123 in all their forms, they want to incorporate future updates of this concept from CIEL, and they don’t want the headache of tracking a PIH-specific concept that is effectively the same CIEL concept with local adaptions.

For now, PIH manages their local changes to CIEL concepts within an instance of OpenMRS, forcing them to cherry pick updates from CIEL and limiting the likelihood of getting updates from CIEL. Also, the process for getting their local changes back into CIEL is a manual review process with Andy.

I’m assuming we’d want to work through steps something like:

  1. Explicitly enumerate/document what are breaking vs. non-breaking changes to a concept.
  2. Add a feature to OCL to allow local, non-breaking adaptations to concepts in a collection.
  3. Once supported by OCL, add this ability to the OCL for OpenMRS client.
  4. Verify that OCL and the OCL subscription module properly handle updates to CIEL concepts (e.g., merge CIEL updates without losing local adaptations)
  5. Create an import process to onboard OpenMRS dictionaries into OCL where any changes to CIEL concepts are stored as local adaptations during the import.



This sums it up @burke

An addition to this description – the ability to add a mapping. It should not require forking a concept. For reporting to a country’s Ministry of Health, we might want to add a custom mapping to the concept (for example, “Liberia MoH: 20 (Neo-natal Tetanus)” ).


I think with each of these “changes” we should identify where the changes are occurring:

  1. Source
  2. Collection
  3. Local server

If the change is a “non-breaking” change then the original UUID should stay as the link between source and collection and server. If the change is a breaking change, then a new UUID should be created where the break occurred.

Changes that occur above the change need to be addressed. Are these notifications followed by overwrite, or something else? For example, mappings are complicated. Are local mapping changes additions only, or replacements? Is the collection adding additional SNOMED codes or replacing others? I would suggest that adding a new mapping source is a non-breaking change, but that changing an existing mapping source/code is a breaking change. This would remove confusion about changes to a particular mapping source (e.g., SNOMED). Any changes are full replacements for the mapping source.

Thanks @burke and @ball… good summary.

@akanter I would think the only allowed “non-breaking” changes to mapping would be additions. In fact, in general, I think we really only need to support additive changes in a non-breaking way. That is, changes you can make in your collection without having to “fork” (which would mean creating a new concept with a new uuid):

  • Adding answers
  • Adding names
  • Adding mappings

… with the one exception that @burke mentions, setting the preferred name.

Take care, Mark

To be clear, the mapping additions have to be for a new source. So no adding of SNOMED, ICD-10, LOINC maps, etc. where there are already maps to those source. OK to add a local source map. Also, technically, where a concept has explicit answers and someone adds a new answer, it would be a breaking change. It actually changes the meaning of the answers. However, where no answers are populated in the source, adding them in the collection is OK. For example, a concept with these answers:

0 1 2 3 other

if someone adds 4, 5 and 6 as coded answers, the definition of “other” changes.

Also, if the coded answers were: Mild Moderate Severe

and someone added: blue or a non-ordinal concept it would change the meaning. So it would have to be carefully reviewed. We have allowed some additions (like adding unknown to yes/no coded responses). This will require more discussion.

While I suppose many of these distinctions could be helpful guidance for someone managing a source (i.e., when to change a concept vs. retire & clone a new one), but I think we’re talking about changes within a collection – i.e., what an implementation can do on their side with CIEL concepts without having to fork the concept. Implementations currently manage these changes within a local instance of OpenMRS (effectively performing the job of an OCL collection) until we have the capability to adapt concepts within a collection in OCL.

Why this constraint? Or would this only apply to SAME AS mappings?

While it might be technically correct to consider a new answer as a new concept, when adding an alternative answer (like “Separated” as a choice for “Civil Status” in my example above), implementations face a choice between:

Technically correct Fudging a little
  • Create a new concept with additional answer
  • Update forms that use the concept
  • Update any reports using the concept
  • Update existing data
  • Create scripts/processes to handle crosswalk when dealing data
  • Track & manually apply updates to the original CIEL concept
  • Add answer to CIEL concept
  • Update existing data if needed
  • Perhaps the middle ground is to try to help implementations navigate these subtleties between when an answer is a breaking change vs. a non-breaking change.

    I’ll try to summarize what we’ve got thus far…

    Examples of non-breaking changes

    • Adding translations
    • Adding alternative names
    • Changing the preferred name within any locale
    • Retiring a concept (i.e., a decision to no longer use the source concept locally)
    • Adding answers that do not change the meaning of the concept (we’ll need to flesh this out a bit)
    • Adding SAME AS mappings to a source not yet mapped for the concept
    • Adding mappings other than SAME AS (pending Andy’s response to my first question above)
    • Addendum to description (assuming we come up with a convention to add local information to a description without disturbing the source’s description)

    Examples of breaking changes

    • Changing a fully-specified name in any locale
    • Changing any name/translation
    • Changing a description
    • Removing answers or mappings
    1 Like

    Absolutely, that’s what I’ve been assuming.

    Let’s get together soon and have a focused discussion about this, so we can start planning out the work that’ll need to happen.

    Here’s a doodle with some times for when I’m back in action the week after next:

    @burke @mogoodrich @ball @akanter @michaelbontyes @muhima08