Expectations for OpenMRS Dictionary Management Squad Meeting Notes

We use the OpenMRS Wiki - Edit Mode for real time. This means that everyone attending a meeting monitors and contributes to the note taking!

Notes Directory

• Concept Template idea - "Add concept" can be improved to become "Add a lab" - A shortcut to making a certain type of concept. Note that this drives data type, mappings, custom/extra attributes. (Lower technical effort but needs to be requirements-driven - need some examples of concept types with the best practice attributes and rules)

• Bulk Mapping Workaround brainstorming - Start from this slide

• Source update notifications - If I'm using a collection that has CIEL concepts that got updated lately, I should be able to address those updates

• Version management between OCL and OpenMRS (see here, Started 19 Sep 2022)

  • Think through versioning of releases for deployed OpenMRS dictionaries that are managed in OCL

  • Incl. best practices e.g. "Although OCL's dynamic references might be the default, it is not best practice to refer to something which is changing. Most collections used in production should refer to a versioned source."

• OCL Search Optimization - can’t always find what you’re looking for (Abuse concept, for example) (can be related to scoring/ranking related to “trusted sources” and to “walled garden / public domain” resources) - might be able to mark content as “curated” to make it appear in public searches

  • May also include the display of information when searching e.g. showing more of the concept's model

  • "Walled Garden" approach - having groups of approved, recommended, or otherwise preferred reference vocabularies, dictionaries, and other sources/collections

  • Document bad search results here: https://chat.openconceptlab.org/t/ocl-searches-gone-wrong/41

• Concept/Mapping Modifications (waiting on development on OCL side)

• Use case for expansions in OpenMRS dictionaries - see this comment (may need some user interviews and walkthroughs from MSF or PIH?)

• OCL's "Remove Reference" prompt is confusing

• Management of Drug table and maps to standard medication terminologies (including link to concept table).

  • Jon to reach out to see if PCMT team can join the conversation

• UUID Management - Within OpenMRS and OCL, when should a UUID (e.g. external IDs) be kept the same vs. when should it change

• Managing collections - How might we better use collections with MSF and PIH?

• Fuzzy matching workflow / mapping tool - Start with a long list of concepts, and start a workflow to make mappings and connections with other content - Started 15Aug22 and 24Jan23

• Collection Management

  • Tell Ian that all concepts need to get the sourcemappings cascade so that ICD-11 gets into the collections, not just the versioned references

  • Plan for resolving validation logic as part of the collection version locking and cleaning initiative: https://docs.google.com/document/d/1DHSz3PFPY0WLSP9DfAijxqrMGLBxeteenOYxEWcbYQM/edit?tab=t.0#heading=h.tojqg938fog5

• Recommendations made to OpenMRS/DRC work:

1. If you're running low on time: Continue to use the OpenMRS Cascade with Transform for now.

   1. Be vigilant! If you encounter errors i.e. concepts/mappings that didn't get added when using this cascade option:

      1. Note them down if they failed because of an existing versioned reference

      2. Remove and re-add those individual references (particularly concept references, since mapping references are less likely to matter unless they have a Sort Order change or something like that)

      3. Check that you're getting up-to-date content - check for the latest concept names, for example.

   2. This of course isn't ideal for long term management, but we're getting together plans for Cleaning the Collection (i.e. de-versioning references) and for Smartening the Collection (i.e. finding those opportunities to use a single cascaded reference to get concepts into a collection rather than using one-reference-per-concept/mapping).

9:52

2. If you have enough time to also improve your collection modeling during this process, then use the OpenMRS Cascade without Transform.

• Grace: Collection stuff

  • Pain: So many collections with versioned references 

    • https://app.openconceptlab.org/#/orgs/openmrs/collections/DiagnosesStarterKit/versions

    • https://app.openconceptlab.org/#/orgs/openmrs/collections/BasicDrugs/

    • https://app.openconceptlab.org/#/orgs/openmrs/collections/DrugDispense/

    • https://app.openconceptlab.org/#/orgs/openmrs/collections/CLF/

    • https://app.openconceptlab.org/#/orgs/openmrs/collections/CDU/

    • https://app.openconceptlab.org/#/orgs/openmrs/collections/CIELAllergySet/

    • https://app.openconceptlab.org/#/orgs/openmrs/collections/DeathCause/

    • https://app.openconceptlab.org/#/orgs/DRCEMR/collections/DRC-EMR-Drugs/

    • https://app.openconceptlab.org/#/orgs/DRCEMR/collections/DRC-EMR-Labs/

  • Potential opportunity: Python Notebook - un-versioning references

  • Improvement needed - OpenMRS Cascade and Transformation button - what's OpenMRS' proposed state for this option?

  • Risk: OpenMRS Validation Schema issue - needs a quick change for validation?

  • Approach:

    • More development approach: Change the validation schema behavior to allow same-concepts to have same name. Then, OpenMRS' collections get the OpenMRS-without-transform Cascade applied during the unversioning (more ideal for long term)

      • Potential issue - lots of redundant references e.g. old mapping references that are now covered by a cascaded concept reference

    • Less development: Simply unversion references and apply source_to_mappings cascade to each one, which will get new names and mappings

      • Issue: New answers to questions don't get added to collection if not already in there

    • Middle-ground: Turn off validation schema in OCL, apply unversioning plus OpenMRS-without-transform cascade, then re-apply validation schema

      • If there's an issue, just save a collection version and try importing the collection into OpenMRS to diagnose issues

  • Longer term wins:

    • 1 concept reference plus its 5 mappings references → 1 cascaded concept reference

• Ellen: Talk about OCL Mapper

• Collection Management Topics:

  • Grace's issue: BasicLabTest collection has lots of versioned references

  • Problem groups:

    • Unversioned references exist in my collection, and I need to un-version them

    • I can't navigate my collection references to find the versioned references and remove/update them

    • Validation of intensional/cascaded references - a cascaded reference can conflict just because one of its "child" concepts is already in the collection (due to the "same name" rule being broken)

    • Badly modeled collection using extensional references (i.e. 3 references to individual question + answer concepts) instead of intensional/cascaded references (1 reference that gets all of those question and answer concepts)

  • Reference cleanup script (in progress) - Simply gets the collection references that have a version number and provide OCL import files to delete "bad" references and recreate "good" references

    • Ticket: https://github.com/OpenConceptLab/ocl_issues/issues/2212

    • Temporary repo (ready to hand off?): 

  • Not in scope for that script:

    • "Smartening" of references e.g. selecting a "parent" concept to cascade from, using cascaded references instead one reference per concept/mapping (OCL MCP use case?)

    • Changing default behavior in OCL for OpenMRS Cascade

  • Potential dependencies or helpful things to have:

    • Repo/expansion comparison

  • Recommendations for OpenMRS

    • Uncheck the Transform option in the Cascade pop-up? Not until validation issues are resolved.

  • Quick wins:

    • Reference unversioner script to OCL GitHub, ready for someone to pick up 

    • Validation schema logic - fix the same-name conflict for the same concept?

    • Finish defining best practice for cascade heavior, version behavior, and reference-add default option

  • Long term wins:

    • OCL collections are more "version-fixed" - you lock the collection to a particular CIEL version, for example

    • Repo/expansion comparison

    • OpenMRS Cascade uses cascaded references by default

    • "Smartening" Collections are supported by proposing "parent" concepts that can be cascaded to clean up the collection modeling

• Collection Management Topics:

  • Add to Collection from HEAD (MSF) - https://docs.google.com/presentation/d/1YgFOVpYnpCxthSeCvvWzoNQeNuqL7N7DmIhIviIW3qg/edit

    • Chat:

      • Michael: how different are the behaviours (expansions, references, etc) within vs outside the same workspace/org? Is there differences?

      • Jon: today there is no difference. We’re discussing the approach where collection HEAD can point to source HEAD when they are in the same org.

      • Michael: In the MSF case, the MSF source belongs to the MSF org, then collections belongs to Operational centres orgs (MSFOCB Brussels, MSFOCG Geneva, MSFOCP Paris, etc.). Would that be an issue with HEAD <> HEAD pointer?

  • Maintaining resolved source versions for collections - https://docs.google.com/document/d/1dYIaEEKH2cMMaWliOBnMruHFNONhUVH7U7w5QHYhJso/edit?tab=t.0

• SAME-AS issue - PIH

  • How did OCL get the mis-cased map type?

  • Let's track this for the future - no idea what went wrong.

  • Make sure bulk import isn't the culprit, because OCL can accept mis-cased map types via API/Bulk import

• OCLv3 testing kickoff: https://docs.google.com/document/d/11BxQnuCfpi8It_7ilrImT6z4lz7tCNvQYM3-xM1r__s/edit

  • Consider - open this up to more users in the UI itself

  • Please raise your hand! Let's engage on this testing - low time commitment, high value for the OCL community!

• Chief Complaints: https://talk.openmrs.org/t/enhancing-chief-complaints-with-specialty-specific-supplementary-details/46459

• Allowing provider to create concepts dynamically (if it is not available), like diagnosis, Lab Investigation , etc to not stop the workflow and may be some staff could review and update it.

  • 
    https://docs.google.com/document/d/1LA-M4X2i7mqwqBhy8Qn3jHnfBRGOT2cD1_O5vUthMOg/edit?tab=t.0

  • Recommendation: give providers a method to communicate with a terminologist/dictionary manager about their needs, but don't let them add straight into the concept dictionary itself!

• OCL MCP

  • MCP = Model Context Protocol (I believe). Basically, it tells an AI (like Claude AI) how to interact with OCL.

  • Michael Bontyes used OCL's MCP to add translations to OCL concepts

  • Joe Amlung used OCL's MCP to research OCL's LOINC source and understand its model and what it's made of - what kinds of concepts are there? What kinds of mappings are there?

  • Abert Namaya - "This is very nice to have agent to analyze the concepts my question is on data security if it's pointing direct to openmrs database"

    • "Have you looked at other options like having a thirdpart with flattened tables which don't include data like patients "

  • If you have multiple concepts in a procedure set, what concepts might be missing?

  • Other use case ideas:

    • Advanced search/editing of concepts and mappings

    • Ai helps to make on-the-fly reports? (More for OpenMRS)

• Concept Management for Labs - how to facilitate this within OpenMRS?

  • https://docs.google.com/document/d/1LA-M4X2i7mqwqBhy8Qn3jHnfBRGOT2cD1_O5vUthMOg/edit?tab=t.0

  • Idea: Dedicated UI (which might interact with OCL's API) to manage concepts, rather than using the OCL UI or OpenMRS front-end. This team wants to integrate concept management directly into their workflow to avoid disrupting doctors' work

    • Workflow Dictionary Management vs. Backend Management: this use case differs from typical backend dictionary management where changes are made before they're needed in user workflow.

    • Risks: duplication of data, creation of bad data, and negative impacts on reporting, forms, and clinical decision support

  • Considered temporary concept creation within the workflow, flagging the data as temporary, and then having a separate process for proper management and update of these concepts retrospectively

  • Balance between Responsiveness and Content Management

  • Note that labs are complex

  • Potential approaches and existing tools to consider:

    • OCL MCP: Allows an AI to query OCL to find content that a user otherwise couldn't find.

    • OCL $match operation: Structured query to find a concept's potential matches in an OCL source

  • To dos:

    • Identify concrete examples 

    • Join future CIEL Office Hours or Squad call to define the problem better (invite experts e.g. OpenELIS?)

• Modeling Reference Range metadata - Should OCL do it?

Open

• Ontologies in terminology/OpenMRS:

  • Local copies of CIEL can fork and create their own concepts, but harder to tie back to CIEL.

  • Potential examples: Sets have concepts, and question concepts have answers. But OCL thinks of those as mappings.

  • Global ontology standards have really well established concepts that don't change over time

• Representing concepts as system/mnemonic (e.g. PIH:123) instead of using UUIDs.

  • Issue: How to resolve source names e.g. recognizing that CIEL points to the real CIEL.

    • Also, when PIH refers to AMPATH:1234, how does that system meaning get resolved correctly?

    • Want to avoid the need for a central, global registry that has to be managed

    • Canonical URLs may be the example on the OCL side

  • Previous discussion on OpenMRS talk about standardized concept delivery - do we use UUIDs or source code maps?

  • OCL has already started some canonical URL features e.g. the registry, but not yet fully launched due to v3.

    • Could test it more publicly with the OpenMRS use case as a driver.

    • Burke to put together test cases and ways we can throw rocks at the idea

• ICD-11 maps for Mapper LLM

• Collection Management with MSF

  • Goal - don't need to release a source version every time a new concept is created just to use it in a collection

    • Concept sets with mapping (e.g. Q&A) don't get added to collection like they were before - happened at the same time as the release issue

  • Ideas for addressing this:

    • Quick TB additions:

      • Simple warning when adding to a collection (if applicable): “You’re adding an unreleased concept or mapping to a collection and it probably won’t work”

      • Simpler troubleshooting from the Collection Reference list: Visually denote if a reference is pointing to a concept that’s only in HEAD and will not resolve until a source version is released

    • More natural workflow ideas- make OCL's API behavior smarter?

      • Allow user to get HEAD concepts if you own the concept or have allowed it from the repo? (maybe modify API behavior to look for the "exceptions" where getting HEAD concepts is allowed)

      • Allow HEAD collection versions to access HEAD source versions (under what conditions? Same ownership? (No, this would fail multi-org use cases like MSF) Something more manual like an allowed collection?)

    • Much more natural workflow - manage source and collection together as one dictionary

• Built-in ontology features in OCL?

  • https://qudt.org/ is     An ontology where as https://en.wikipedia.org/wiki/ISO/IEC_80000 is similar standards, but international, but not in RDF/OWL (semantic web) format

  • ICD-10-WHO source in OCL is an example of OCL's hierarchy features.

• Zimbabwe TS - Starting with CIEL - What are our recommendations on Source vs. Collection?

  • Collections might not be ready for a huge CIEL-based collection?

    • OCL can do a single gigantic reference to the CIEL dictionary

  • Challenge with sources: not everyone has PIH's terminology capabilities. Less management would be ideal.

• Herman - best practices for representing forms in a concept dictionary

• Squad Priorities continued

  • Burke: Using Mappings instead of UUIDs

• Squad priorities:

  • UAT for source-based dictionary management in TBv3 (as features are available in May/June timeframe)

  • In the meantime...

    • Identifying concepts by authoritative source and code (e.g. PIH:1234): Write the full scenario as it relates to OpenMRS and OCL

    • Requirements for CIEL source management in OCL (getting ready for when we have developer resources available)

      • List of queries that Andy runs when managing CIEL (e.g. query to clean up names in bulk)

      • UI/UX improvements

Recording:

• Continue the Shortlist with shared outputs for the next 3-6 months:

  • CIEL source management directly in OCL

    • Definition: A large source like CIEL that is being used as a reference by a large number of users has unique requirements to make management directly inside OCL possible. This is essentially source-based dictionary management, plus some advanced features like bulk querying and editing, review and proposal workflows, etc.

    • Output: Team to help write specific business-level requirements for source management in OCL

      • Examples: Performing bulk content operations, Content proposals, comments, discourse integration, etc.

      • Andy is primary source of biz level requirements

      • Filipe may be able to push this after ICD-11

  • Source-based Dictionary management in TBv3 (e.g. PIH) - managing your own concepts (with cloning)

    • Definition: A source is where you create novel concepts and mappings

    • Medium-term Output: UAT on TBv3 (starting when Ellen returns mid-June)

    • Scope is to support multi-site concept dictionary management

  • Collection-based Dictionary management in TBv3 - using curated concepts along with some of your own concepts (with referencing)

    • Definition: A collection is where you bring together concepts and mappings from other repositories using references

    • Example features:

      • Customizing concepts in OCL using collections

      • Managing a concept that is a reference to another source, and making the entire workflow more intuitive

    • This one we’ll wait for until we’ve made some progress on source-based dictionary management

  • How do we actually get folks using concept codes for mappings instead of UUIDs

    • Outputs:

      • Write the full scenario as it relates to OpenMRS and OCL (did Burke already do this in OpenMRS talk?)

      • Translate this to: Best practice guide AND requirements for OMRS and OCL

    • An example requirement: Easier concept Self-map management (avoid needing to manually create this on your own) — preference for a solution in OpenMRS long-term so that we don’t duplicate concept’s Identity, but can implement an OCL solution in the short-term if needed

  • Specific use cases, e.g. ICD-11

    • 2 ways big buckets that we may want to consider:

      • Terminology management use cases – what happens when I have ICD-11 showing up on the scene – how do I manage change once ICD-11 is in the mix, especially at the point of care – e.g. may need specialized tooling in OpenMRS to help a user select the right code

      • I need to migrate from ICD-10 to 11 or from SCT to ICD-11

    • No specific outputs defined yet

• Existing Resources that we need to dig up:

  • Original dictionary management workflows from several years ago

  • More recently, dictionary/source management workflows created for TBv3 requirements

• Short-term things that could improve quality of life:

  • Nuisance to fix for all OCL web applications -- ticket created here: https://github.com/OpenConceptLab/ocl_issues/issues/2132