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

    @grace, did a call get scheduled?


    1. Why couldn’t mappings be added for a concept to SNOMED if CIEL already has a mapping to to SNOMED?
    2. Is it fair to say adding an answer to a concept with an “Other” answer changes the meaning of the “Other” answer and not the question?

    We have to consider that multiple maps to the same source are like an expression. I noticed that it is hard to modify the expression in parts. Knowing whether something is a replacement, addition or modification to the expression is complicated. I think it is better to restrict changes that are not complete replacements for maps to a single source.

    As for changing the answers to a question, there are some that clearly change the definition of the question (coded answers of different forms, for example), but adding a new coded answer changes the meaning of other as it interprets the question. In this example, you are correct that the question meaning is not changed.

    Interesting. Can you give an example? I can understand how adding additional SAME-AS mappings to the same source could be nasty; however, it’s hard to believe CIEL would have every possible mapping. If, for example, an implementation needed to map acute bacterial pneumonia as BROADER-THAN streptococcal pneumonia for their custom module to work, couldn’t that be allowed without cloning the concept?

    Could you give an example of coded answers of different forms that would change the meaning of the question?

    We ended up not being able to make last week work with timing. Let’s try again, in addition to this Talk thread. In fact the hour immediately after the OCL Squad call looks ideal if that could work for others. @burke @akanter @mogoodrich @ball @michaelbontyes @muhima08 Do any of these times this week work for you?

    Turns out that tomorrow is now bad. I would like to do Friday morning if possible.

    Thanks @akanter and all who replied (again). Looks like Friday at 1pm UTC / 9am EDT worked best for all, and Wednesday was unworkable for Andy. Sent out the calendar invite. LMK if I’ve forgotten any key parties.

    @burke how important is it that @paynejd joins us for this call?

    We had a very productive call on this topic today. Here’s an updated list of breaking vs. non-breaking changes that came out of our discussion.

    Some significant updates:

    • Implementations can add or remove answers
    • Allowing implementations to control answer sorting order

    Examples of non-breaking changes

    • Adding or removing answers
      • OCL may need to store answers to be deleted locally in order to avoid re-adding them locally when CIEL concept is updated
      • We’d benefit from having answer_set ± answer_class (TRUNK-1515), so CIEL could define the space of “allowable” answers
    • Changing case of a name or synonym
    • Adding synonyms (alternative names, search terms, index terms)
    • Adding translations
    • Changing/adding short name
    • Changing which name is preferred in any locale
    • Retiring a concept (i.e., a decision to no longer use the source concept locally)
    • Changing answer order (i.e., sort weights)
    • Adding mappings to a source not yet mapped for the concept
    • Addendum to description (we’ll need a convention to add local text to a description without disturbing the source’s description)

    Examples of breaking changes

    • Changing a fully-specified name in any locale (except casing)
    • Changing any existing name/translation (except casing)
    • Changing an existing description (other than adding addendum or adding missing description)
    • Removing mappings
    • Adding/changing mappings to a source for which mappings already exist

    Please let me know if I got anything wrong. I think we’re getting close here to a set of requirements we can bring to an OCL Architecture call (i.e., an enumeration of customizations we’d like OCL to allow & persist for any given concept added to a collection).

    1 Like