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:
Explicitly enumerate/document what are breaking vs. non-breaking changes to a concept.
Add a feature to OCL to allow local, non-breaking adaptations to concepts in a collection.
Once supported by OCL, add this ability to the OCL for OpenMRS client.
Verify that OCL and the OCL subscription module properly handle updates to CIEL concepts (e.g., merge CIEL updates without losing local adaptations)
Create an import process to onboard OpenMRS dictionaries into OCL where any changes to CIEL concepts are stored as local adaptations during the import.
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:
Source
Collection
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.
@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.
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)
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?
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?
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).