I was asked to review a design document for a new OpenMRS module that aims to integrate the WHO ICD-11 Embedded Coding Tool (ECT) into the diagnosis workflow (targeting O3).
The proposed design suggests storing the selected diagnoses in a new custom table outside of the standard OpenMRS data model. While I understand the reasons behind this choice, I’m not entirely sure this is the best direction, as it seems to move away from using concepts.
From my current understanding and research, OpenMRS relies heavily on the Concept Dictionary for coded clinical data. Many core features — such as reporting, cohorts, indicators, dashboards, data quality rules, and interoperability — depend on diagnoses and observations being linked to concepts.
I’m wondering if there might be a better middle ground. One approach I’ve been considering is:
Creating concepts on demand only for the stem codes (to avoid having to import the full set of ~55k ICD-11 codes).
Storing the additional rich data coming from the ECT (search criteria, full post-coordinated expression, Foundation URI, etc.) inside an Obs Group.
This would allow the diagnosis to remain connected to a concept while still capturing all the detailed information from the ICD-11 tool.
I would really appreciate your thoughts on the following:
From your experience, is storing diagnoses in a custom table (instead of using concepts) generally seen as misaligned with how OpenMRS is designed?
Does on-demand concept creation for stem codes sound like a reasonable approach?
Has anyone worked on ICD-11 integration before and could share what worked well (or what challenges they faced)?
Thank you very much in advance for any guidance or feedback.
Sorry, didn’t see this. BIG TOPIC. First, the WHO encoder tool is non-clinical and not a great way for clinicians to capture clinical data in the EHR. Also, it does not integrate well with the data model as OpenMRS is currently configured as you mentioned. However, ICD-11 is required for reporting and needs to interoperate with the rest of the system and other coding systems such as SNOMED and previously coded ICD-10 data. There currently are licensing issues being worked out before a final integration can be done.
The current methodology is to use the ICD-11 maps that are provided via CIEL to the existing concept dictionary. However, since there usually is a post-clinical documentation step where ICD codes are added for reporting, I can imagine a module which takes the clinical documentation and provides an interface to assign ICD-11 codes to a separate administrative code table (for the visit). This would leverage the existing ICD-11 maps (if there are some from CIEL) and if not, then pass the clinical documentation to the API and allow a “coder” user to assign additional ICD-11 codes. This is worth a discussion with the community, particularly @burke who has been thinking about assigning “billing” codes for a loing time. Happy to jump on a call, or perhaps you could join either concept management office hours or one of the OCL squad calls?
A bit more context on the use case: this is specifically for the Medical Certificate of Cause of Death (MCCD). According to WHO guidelines, the ICD-11 code must be selected through the coding tool (ECT). The reason is to stop people relying on their usual “GoTo codes”. In practice the user first enters the human-readable cause of death and is then forced to search and select the most appropriate ICD-11 code via the ECT (the tool does not allow direct code lookup).
So the entry point is necessarily the ICD-11 code (or post-coordinated expression) coming from the ECT, not a normal clinical concept search.
Given that constraint, does the following approach make more sense?
Clinician/coder uses the ECT from the module → forced to search properly → selects a cause → ECT returns the ICD-11 code (stem or post-coordinated), full expression, Foundation URI, and any other rich metadata.
Module receives the ICD-11 code/expression as the entry point.
Look for an existing map in the concept dictionary (CIEL maps or others). Prefer CIEL concepts when they exist.
Decision:
Map found → use that existing concept for the diagnosis (obs / encounter_diagnosis). Store the full ECT payload (expression, URI, etc.) in an Obs group or linked table.
No map found → create a concept on-demand for the ICD-11 stem (or a suitable representation), create the map, then use the new concept. Again keep the full ECT data in an Obs group.
Result:
The cause of death stays inside the normal OpenMRS concept model → reporting, cohorts, indicators, interoperability continue to work.
Concepts are only created when no suitable map already exists.
We fully respect the WHO “must use the ECT” rule.
Two quick questions on this:
In the MCCD context, can we still consider this “clinical data”, or is it more purely administrative/mortality coding?
If we stored everything in a custom table without linking to concepts, how useful would that data actually be inside OpenMRS (for mortality statistics, dashboards, data quality, etc.)?
Looking at the ECT tool page it refers to the ICD browser or API which was what I thought they were referring to. It doesn’t look iike this is specific to the cause of death workflow (which requires determining primary underlying cause, secondary cause, etc. which is different from simply getting an ICD-11 code for a diagnosis. If we do want to be able to put the resulting data back into the cause of death concepts inside the OpenMRS data model (CIEL has these), then I still think you would want to be able to start from a clinical term through ICD-11 to store the SAME-AS ICD-11 concept (post-coordinated if required) back to the obs table.
There are multiple challenges with this. Simply running from the CIEL term to post-coordinated ICD-11 will give you the most accurate ICD-11 code, but this does not necessarily mean it is the correct concept to go in the cause of death form.
The CIEL concept with its post-coordinated ICD-11 can be used to popiulate the API and allow for further specificity or changing (and that might be worth exploring). The next is what to do after you have a NEW ICD-11 code expression… which might not exist in the concept dictionary. That would require creating a new concept on the fly which is problematic. Just using stem codes would reduce that likelihood, but then what’s the point of forcing people to use the tool to increase accuracy and then not use what they produce? The CIEL maps would be way more accurate.
The idea of keeping the separate table for the ICD-11 codes is a potential solution which would solve the reporting problem but not the integration problem. I do think the idea that we need a separate administrative OBS table specifically for these sorts of billing/reporting use cases might still be OK. FYI, I am exploring ways that we can keep full admin code sets in the dictionary but suppress them for clinical workflows… but that’s not going to really work for post-coordinated systems like ICD-11 and SNOMED which have too many codes (combinatorial explosion)
I’d really love to hear @burke’s thoughts on this. It does seem like the “right” thing to do would be something like the ability to tie a specific post-coordinated code to a specific obs? The precise codes, properly used, are definitely of value and that would keep the scope more confined.
Well, first off, I would strongly advise against dynamically adding concepts to OpenMRS. If anything we are trying to move in the opposite direction, making deployment decisions at the time of build/deployment so they are more explicit & predictable. While adding some concepts on the fly to a single instance of OpenMRS may not be disastrous, trying to oversee hundreds of OpenMRS instances with unpredictable dictionaries is untenable.
The “if I had it to do over again” answer would be to have adopted Regenstrief’s approach of point all concept references to a higher level concept registry of source & code, making the OpenMRS concept dictionary the “local” source. In other words, concept 123 might map to OpenMRS:456 while concept 124 maps to LOINC:789. This would allow coded references to use any terminology and those requiring interface terms (like traditional OpenMRS concepts) to constrain themselves to concepts within the local (OpenMRS) source. Unless we come up with a creative migration path, it may be too late to untie this Gordian knot.
If the ultimate goal is to grow the concept dictionary to include concepts with mappings to the most useful ICD11 terms, then I’d suggest borrowing from our old concept proposal approach: when a needed code doesn’t exist, store a placeholder concept like Free text comment and store the ICD11 elsewhere with a link to original entry. This would allow the ICD-11 to be stored and provide a queue of ICD-11 codes for which an existing concept isn’t already mapped. The local dictionary maintainer could routinely scan for these entries, add the missing concepts to the deployment (in an explicit & predictable way that scales to multi-server implementations) and then retrospectively update the uncoded entries to the correct concepts after they’re deployed. The next time someone looks for that same concept, they’d find it and wouldn’t need to use the free text option.
If this is specific to the cause of death use case, then an alternative could be to add a link to a reference term for cause of death (e.g., person.cause_of_death_term linking to concept_reference_term); however, since you want to collect multiple entries, I’m assuming you’d need to create a separate table anyway (e.g., person_cause_of_death that could contain 1-to-n reference terms). Adding reference terms on the fly might be more tolerable, but it may still be preferable to take the proposal-based approach. That is, only store reference terms that are already loaded in concept_reference_term, using a placeholder for those that don’t exist and capturing the free text and/or ICD-11 specifics elsewhere to serve as temporary “uncoded” entries that provide admins with a list of codes to be loaded into their deployments and that can later be converted to codes once the references terms have been added to the system.
I’ve double-checked the design document. Even though the primary use case is MCCD, the proposed module also registers a new diagnosis picker that uses the selectedEntity callback. That suggests it could have a broader impact beyond cause-of-death coding.
A couple of clarifying questions (forgive me if these are basic — terminology work is not my usual area):
@akanter — The ICD-11 browser is different from the coding tool / ECT. The WHO ICD team designed the coding tool specifically to improve coding accuracy when used by non-terminology experts. Is there anything that would argue against using ICD-11 as the primary list of diagnoses (rather than only as mapped administrative codes)?
@burke — You strongly advised against on-demand concept creation because of the management burden across many instances. In this design the diagnosis picker would be restricted to ICD-11 codes only (no other concepts could be selected for diagnosis). What if the codes therefore stayed strictly inside the ICD-11 namespace (i.e. a deterministic, official list) and we only created lightweight local concepts with mappings (e.g. a local code 1234 mapped to the ICD-11 stem)? Would that still create the same long-term dictionary-management problems, or would the constrained scope make it more manageable?
I’m also exploring whether I can arrange a short call with the requesting team and the WHO ICD team. If that happens, would either of you be interested in joining?
There is significant discussion about the use of ICD-11 in clinical information systems and connection to FHIR. I will state my biased view of this after participating in these discussions and having three decades of terminology in HIS expertise. Most people would clearly understand that ICD-10 is incompatible with good clinical information design (both from a core data coding perspective and a user experience perspective). This skepticism has not been translated to ICD-11, despite many of the same concerns. When given a technological solution, the hope is that this will solve the issues previously outlined. Unfortunately, this is not the case and new concerns are raised. There is an effort to compile all of the feedback into a comprehensive document that can guide decision making (and WHO). I will strongly state my case that for clinical information systems that require good user experience, good (and detailed) clinical specificity, longitudinal continuity, and cross-mapping to other coding systems for other use cases, the restricted use of an ICD-11 selection tool to constrain primary documentation to ICD-11 diagnoses is doomed to fail. This is not just about the stem codes, but capturing the full clinical intent. I do not rule out a hybrid solution which combines interface terminology with an ICD-11 tool, but for right now, that is not only not available, it is prevented by the license.