4 Must-Do’s

1. Problem Description: Have you clearly defined the user problem(s) you intend to solve, and what value this creates? Write down a story, user insight, or quote about this problem (this is important because (1) this will motivate your team, and (2) without this your problem might not actually be a big problem for the users themselves).

2. User Stories: Have you clearly written at least 3 user stories and use cases?

3. Market Analysis: Have you surveyed what the market is doing here (e.g. comparison to other EMRs, or paper approaches; and don’t forget about learning from historic/existing OMRS instances)? Have you written down any possible gaps in your understanding of your users or their workflows? Have you reviewed the topic in FHIR to see what requirements or fields the global community references? (Eg if working on insurance, should look here)

4. Technical Considerations & Dependencies: Have you outlined what you need from cross-functional areas for success of the feature? E.g. do you need the platform to support a new API call? Have you explained how you’ve addressed dev concerns, such as designs that may not be feasible, or will be extra time-intensive to implement?

Optional/Encouraged

Sketches: Have you added a drawing or description of how the feature could work to solve the problem at hand? (Pictures of sketches are ok!)

Project Management: Have you created the Epic and JIRA tasks so you can share work clearly? Roll-out plan: Do you have an idea whether this will be an experiment, gradual roll out, and when? Have you added this to the timeline view? Have you planned how you will promote and/or work with communications folks in order to help this feature reach the widest audience and have the biggest impact it can?

Later but should do

QA Plan: Have you mentioned the plan for QA, such as how you will discover and address edge cases? Does your team/squad have a plan for automated tests to be added to new components (unit tests) or workflows (e2e tests)?

Safety & Tech Risks: Is there any reason you could regret rolling out this feature? (e.g. possible patient harm, heavy tech debt like introducing an unsupported library) Have you thought through the risks for this particular solution? And, how to reduce/address those?

This checklist was inspired by this article. Additional Business Analyst Resources here.

Summary:

OpenMRS needs a solution for:
- (1) a CDS Engine,
- (2) Authoring that's Clinician-friendly,
- (3) a way to test rules, and;
- (4) sources of content that are trustworthy, free, and actively maintained.

Key Links

Discussion in Talk Thread: https://talk.openmrs.org/t/o3-cds-a-way-forward-for-clinical-decision-support-must-haves/43089/6?u=grace
CDS Engine Repo: https://github.com/openmrs/openmrs-module-drools

Contents:

1 1. Problem Components: A Recipe for CDS
2 2. User Stories
3 ROADMAP for Low-Hanging Fruit Iterations:
4 3. Market Analysis
5 4. Technical Considerations & Dependencies
6 5. QA Plan:
7 6. Safety & Tech Risks

CDS is about more than pop-up alerts! You wouldn’t put a bunch of alerts in front of an F1 driver - so why would you put them in front of a busy clinician making health decisions?

1. Problem Components: A Recipe for CDS

CDS is a massive topical field. It helps to think about it as a “Recipe” with some key “Ingredients” (components). We need a solution for each of these.

A Recipe for CDS

A Recipe for CDS
Ingredient	Notes	How we plan to solve this
🧠 Brain / CDS Engine	A brain/engine the software uses to calculate rules Examples include: CQL Engine/cql-framework	Drools
Rules	The “knowledge base” here is the rules engine’s view of all “facts” the system contains.	In our case, these “facts” might be things like Obs, Encounters, Visits, Appointments, etc.
📝 Authoring that’s Clinician- and BA-Friendly	BA-friendly way to represent and write rules, content Way to safely QA / review rules that is Clinician- or BA-friendly.	DMN (graph/chart), BPMN (), decision tables (DMN = “Decision Model and Notation") This is a standard for representing “business decisions”, which are basically what we’ve been referring to as “rules”. More here: https://www.omg.org/dmn/ To learn: https://learn-dmn-in-15-minutes.com/ for DRD (Decision Requirements Diagrams). Demo environment hosted by BPMN: https://demo.bpmn.io/dmn/new Drools Docs: Defining spreadsheet decision tables https://docs.drools.org/8.44.0.Final/drools-docs/drools/language-reference/index.html#decision-tables-defining-proc The advantage of this is that we can use existing tooling to design rules in spreadsheets or decision table like formats. More details here: https://docs.redhat.com/en/documentation/red_hat_decision_manager/7.8/html-single/designing_a_decision_service_using_spreadsheet_decision_tables/index#idm140711560952544
✅ Way to test rules	This is usually overlooked. Having a way to write tests as you go, automated, is absolutely critical. E.g.: Something that will alarm when a rule stops working.	Drools' DMN offers a way to specify and run sample test cases before your eyes: https://docs.drools.org/8.44.0.Final/drools-docs/drools/getting-started/index.html#test-scenarios-intro-con_getting-started-decision-services
Way to quality control Rules	Prevent inappropriate use of stale/out-of-date healthcare information in rule generation; aka “Expiry dates” on rules or their components. E.g. “don’t use X value if data is > 6 months old”	Yes Drools supports this, with the caveat that it assumes that the rules are written in such a way that takes advantage of this information. We’ll need to have some common practices documented to fully handle these kinds of cases. (e.g. defining “Latest BP means…”). We’ll need to have (for some rules at any rate) some sort of notion of “scope”. E.g., for decision rules based on BP, the latest BP is probably only relevant if it was measured during the current visit.
Performance	Rules must execute very fast, so there’s no delay in rendering them, since delays can cause flags to be missed by clinicians.	The Phreak algorithm: https://docs.redhat.com/en/documentation/red_hat_decision_manager/7.4/html/decision_engine_in_red_hat_decision_manager/phreak-algorithm-con_decision-engine#phreak-rule-evaluation-con_decision-engine It’s intended to be substantially faster than just looping through the set of all rules and evaluating their trigger conditions (then “when this happens”)
📖 Content	Examples include: RxNorm SNOMED CT - paid license. E.g. $50k/yr for country license? UpToDate & Lexidrug(Lexicomp) - paid, expensive service used in HICs WHO’s ATC/DDD: Drug ranges for appropriate drug use	GAP. Need to find: Are there public datasets out there?
Metadata (Medical coding / Terminology)	Attached to content, but separated here because not all terminology sets include CDS connections.
🧑‍⚕️ Data Capture: Way of collecting required data	E.g. Forms, Orders, other data collection points where system obtains info about patients and groups.
⚠️ UI: A way to inform end-users of: 1) the result 2) how/why that result was calculated 3) what the end-user / clinician thinks of it	Examples include: Flags, Tasks, Modals (limit popups as much as possible though) As you’re developing the alerts: Sometimes it’s correct, but not useful. Eg OB-Gyn getting alerts saying “did you know your patient is pregnant?” Think about: Triggers, Data source (and quality of that data), and intended effect on who is the end user.	CDS-related UI Design Patterns: Flags : https://zeroheight.com/23a080e38/p/851fea-patient-flags Tasks (vision is that some tasks are generated automatically based on certain criteria): https://zeroheight.com/23a080e38/p/6226bc-task-management Orders (specifically, showing allergies at the point of ordering): https://zeroheight.com/23a080e38/p/71ad91-order-basket Clinical Views (showing just what you think a clinician would want to know is technically a form of CDS, even if it’s static / manual-config-driven): https://zeroheight.com/23a080e38/p/77d3d3-clinical-views
“Escape Clause” / Override Mechanism	Way for users to say “This was wrong”. Change rule, turn off rule. Override or cancel for that patient/population.
Audit Logging	Need a way to understand how an answer was derived at that point in time.	Drools has some tooling around this.
Feedback Loop	Need a way for clinicians to, at minimum, cancel a rule/flag for a given patient, since rule authors will often never be able to capture all exception logic. E.g. ability to say “This alert/rule doesn’t apply to this patient (any more).”	We’ll need a UI for this.

2. User Stories

Backlog of CDS-related Roadmap Items / use cases for OpenMRS: https://openmrs.atlassian.net/jira/polaris/projects/OMRS/ideas/view/6314977

Static Image:

As of Feb 20, 2025

Dynamic Widget:

https://openmrs.atlassian.net/jira/polaris/projects/OMRS/ideas/view/6314977

How to think about a CDS MVP:

The goal is not to go from nothing to an all-powerful CDS engine - because that can’t help us in the meantime, or for simpler, lower-hanging use cases that will still make a difference in Clinical Decisions.

Instead, we will focus on use cases that we can grow from: Starting with some value, some more value, and then lots of value!

ROADMAP for Low-Hanging Fruit Iterations:

Green = things Grace thinks are most promising right now

Favor Simple Alerts: Simple alerts are typically better than complex alerts. If your data quality is dubious, if you have complex alerts dependent on too many pieces of data, then odds are good that one of those pieces of data are bad. E.g.: geriatrics: “>70, opiates >3 days → get a laxative” (well what if the pt has diarrhea? what if…? List of exceptions was long. So in rule text we mention some of the more common reasons you should not do this. Decided not to write in all the exceptions to the rule itself, because then it would seem like the rule randomly appears.

Company A and Company B: A has very few; B has loads. But what they advise on are very similar, b/c there’s a set of rules made by the dutch gov’t. How these are handled in the different systems is different. In A, a lot of the rules go to the Pharmacy; in B a lot go straight to the prescriber.

Standards to look at: CDS-Hooks (effort to be a standard), OpenCDS project; paper: requirements for knowledge authoring tools (coming soon - includes interview with Teich)

Area	Real “MVP”	v1	v2

Area	Real “MVP”	v1	v2
Patient Flags		Use Case as Educational Resource e.g. Sepsis; GBV; or something with existing rule set
Forms: Recommended Forms	Custom Form buttons on focused widgets (e.g. “ANC Form” button on an ANC widget, like OHRI did) (Already done.)	https://openmrs.atlassian.net/jira/polaris/projects/OMRS/ideas/view/6025374?selectedIssue=OMRS-90&issueViewLayout=sidebar&issueViewSection=overview&atlOrigin=eyJpIjoiMGUyODEzZWFiY2RhNDQ0ZGE5ZDIwODMxM2ZkODdiMGUiLCJwIjoiaiJ9 "If patient is [obs] = X and [visit type] = Y, then recommend these forms". Needed: Example concrete rules. /drools?rule=<RULE ID>&patient=<UUID>&visit=<UUID>. How would the engine structure the response? Is that something that can be explicitly determined in the rules definitions? (A more systematic approach) Requires Rule Engine.
Cohorts: Catch Patients who will fall through “Gaps”	Add phone # to Patient Lists. Makes it easier for manual LTFU follow up.	Dynamic Patient Lists: Automatically add patients to a general System List E.g. Contact Tracing workflow: Show me patients I need to call, eg who missed their appointments (LTFU) so I can work with that list and go through and call them; and if they were successfully contacted I can click on something which will move them out of this list (action has to take place; avoiding needing big SQL queries that move pts across tables) E.g. Show me patients I have seen recently in the last 2 weeks so I can do remote follow up and ____ (confirm: what’s the workflow?) Ideally: Rules could be expressed in Content Package (e.g. LTFU List definition in HIV Package) Likely powerful extension of the work on patient flags	Detailed Cohorts: “Build me a list of all patients who X and Y etc” → then Dynamically up-to-date list of those patients. E.g. if selected “Refer to Psych” → Add to a Psychiatrist List
Allergies	Show Allergies in Drug Order UI	Alert when Allergy is chosen as exact Drug Order https://openmrs.atlassian.net/browse/OMRS-333 Requires Rule Engine.	Alert when an Allergy related Drug is chosen https://openmrs.atlassian.net/jira/polaris/projects/OMRS/ideas/view/6025374?selectedIssue=OMRS-34&issueViewLayout=sidebar&issueViewSection=overview&atlOrigin=eyJpIjoiMTcwODA0ZjljMTUzNDJhM2I4YWQ4MWIzOGI2MDNlZTUiLCJwIjoiaiJ9 Requires Rule Engine + Content.
Pediatrics: Weight-based dosing	Show patient weight in Drug Order UI "The Pediatric Pharmacy Association recommends that patient weight, recorded in kilograms, be required on all medication prescriptions in both the inpatient and outpatient settings." https://pmc.ncbi.nlm.nih.gov/articles/PMC10547047/	Show warning in Dosage section of Order Form: “patient is <18; consider Weight-based dose”. Requires Rule Engine.
Tasks: Recommended Tasks		eg HIV+ + Female >XXyrs old → Cervical CA Screening needed Requires Rule Engine.
Recommended Orders, Order Templates & Order Sets	Order Templates (Already have, partially.)	Stars / favoriting	Order Sets: “Based on Dx/CC etc, consider: …”
Forms: Templates for free text notes	Show “last data entered” in Forms UI; enables user to see and re-use past data in discrete questions. (Already done.)	Manually select a form template from a UI shown within long-form Text boxes (e.g. “SOAP”, “PQRST”, etc.)	Suggest a form template based on words typed

3. Market Analysis

SMART Guidelines & CQL “101”

https://www.youtube.com/watch?v=w_wuUoFAp7I&ab_channel=OpenMRS

Explaining our approach to SMART Guidelines & CQL Engine in 2023.

L1 (Level 1): Book-style, PDF-based guidelines released periodically by WHO with latest evidence base around a topic, like pregnancy or HIV

L2 (Level 2): Spreadsheets

L3 (Level 3): Executable code (WHO prefers FHIR planDefinitions because they’re a standard; and more specifically, CQL)

SMART Guidelines & CQL (Clinical Quality Language):
- Analysis of Categories of ANC WHO CDS Rules https://docs.google.com/spreadsheets/d/14sTL6D7ZcuYPMJ3IkBRgpWFTDk2x6EU9LhcKosOynn4/edit?gid=0#gid=0
- Docs about what we set up: https://openmrs.atlassian.net/wiki/spaces/projects/pages/26938745
- Sample ANC Maternity CDS rules in spreadsheet format: https://docs.google.com/spreadsheets/d/1lRXhJg7JQboYl9sGif8Tslc3HYK17jG2/edit?gid=206805698#gid=206805698
- Sample HIV CDS rules in spreadsheet format: https://docs.google.com/spreadsheets/d/117bKXdJ1GnAuQgR5JdftFOlPY7EOpTZT/edit?gid=1103435742#gid=1103435742
UW-DIGI and several OpenMRS Community Members (eg Mozzy, Ian, Piotr, Patric) worked on a way using CQL to implement PlanDefinitions / CarePlans in OpenMRS: https://talk.openmrs.org/t/o3-cds-a-way-forward-for-implementing-plandefinitions-activitydefinitions-and-careplans-in-openmrs-with-fhir/43665

Learning from Bahmni

Learning from Bahmni’s CDS efforts & SNOMED CT project:
- CDS in Bahmni 2023: Screenshots and video demo
- CDSS alert notification in Bahmni for drug-diagnosis interaction using SNOMED CT https://www.youtube.com/watch?v=P7BRsMra6_M&ab_channel=BahmniCommunity
- Bahmni CDSS Demo and E2E automation testing https://www.youtube.com/watch?v=PAkgaq6Qjuk&ab_channel=BahmniCommunity
Licensing Constraints: SNOMED-CT → comprehensive → $$$ license; vs. SNOMED-GPS → global, free license, but far less comprehensive
Technical approach: Global prop → fhir terminology server. Running a CDS server that supports FHIR CDS Hooks; more enterprise approach.

Learning from USA

https://www.youtube.com/watch?v=adIDR2r8VNc at the 54 min mark, see how this gets implemented in a large USA EHR...
There are a lot of resources on the AHRQ website too https://cds.ahrq.gov
Often USA rule examples, at the repository-level, have very site-specific rules.

Learning from Publications

Arden/CQL History article: _______

4. Technical Considerations & Dependencies

5. QA Plan:

SAFER Guide for CDS: Safety checklist

The US HealthIT program’s “SAFER Guides” offer a checklist to review to ensure you minimize CDS risks in your EMR. It’s designed for hospital administrators to double-check their implementation, but we can use some of the Recommended Practices to guide us.

We will rely heavily on this guideline: (link/source)

Additional SAFER Guides to review for CDS-relevant Safety insights

High Priority Practices: https://www.healthit.gov/sites/default/files/safer/guides/safer_high_priority_practices.pdf
System Interfaces: https://www.healthit.gov/sites/default/files/safer/guides/safer_system_interfaces.pdf
System Configuration: https://www.healthit.gov/sites/default/files/safer/guides/safer_system_configuration.pdf

TBC: The plan for QA, such as how we will discover and address edge cases

TBC: Plan for automated tests to be added to new components (unit tests) or workflows (e2e tests)

6. Safety & Tech Risks

TBC: Is there any reason you could regret rolling out this feature? (e.g. possible patient harm, heavy tech debt like introducing an unsupported library)

TBC: Have you thought through the risks for this particular solution? And, how to reduce/address those?

Hierarchy/Subsumption: Bahmni’s Lesson: You need subsumpsion: Say “not just this concept, but anything that might be subsumed under that conept” so you don’t have to consider every possible code. (SNOMED GPS doesnt offer hierarchy.) May need to specify what sub-components are relevant.
- BUT: Mappings can be wrong → means CDS calculation can end up being very wrong. How is this handled?
  - One approach: “Rule isn’t doing anything, just notifying” → Need workflow to signal “I’ve seen and will review/make a decision”.
  - Justification: Show exactly how or why that result was obtained. (REQUIRED.) May include Level of Evidence.
- BUT: Need to handle smaller than/greater than. Is SAME-AS always appropriate?
Expiry Dates / Acceptable Time Frame: Of input data; Of rule. E.g. if chest pain was reported 2 years ago, shouldn’t be part of a rule today. If Pre-ecclampsia risk in previous pregnancy, shouldn’t show today.
“The Curly Brace Problem” from Arden Syntax
How to Handle Missing Data, Sparse Data: If there’s no data for something (e.g. a missing VS), or you don’t have a lot of data points for a patient or population, how will you handle that?

CDS Support in O3: Engine & more