/
Smart Notification Feature

Smart Notification Feature

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.

Status: READY FOR WORK

Technical Complexity: HARD / COMPLEX

Summary:

  • Clinicians who order lab tests have no automated way to know when results come back, and thus they must keep reopening the patient chart to check.

  • This feature surfaces new results through a notification feature so providers stop polling manually.

    • V1 covers the lab-based use case:

      • STAT Orders

      • Opt-In notifications

      • Notification when the lab result is rejected

      • Location-scoped routing.

    • V2 covers the prescription-based workflow and use case:

      • Notifying the clinician when safety concerns like drug interactions are discovered during medication dispensing.

image-20260703-150809.png

1. Problem

When a clinician orders laboratory tests during a consultation, the burden of tracking those orders falls on the clinician rather than the system. Without this feature, they must:

  • Manually track which patients have pending lab orders.

  • Periodically reopen the chart to check for new results.

  • Interrupt the current consultation to check a previous patient's results.

  • Risk missing follow-up on ordered tests during busy sessions.

Patients feel the same gap: they don't know when results are ready, may not know whether to wait or leave, and face delayed diagnosis when results are time-sensitive.

The core tension: clinicians want to focus on care, not on chasing status updates — yet notifying on every result creates the opposite problem, alert fatigue, where important findings are buried, and critical alerts are ignored. The design has to notify enough to be useful without becoming noise - hence defeating the entire purpose of the notification system.

Solution Overview

  • V1 — Notification inbox with STAT/urgent gating (what's prototyped)
    A header bell with an unread count. Clicking it opens a list of new results; selecting one opens a detail view where the provider marks it reviewed or clicks through to the patient's Results (resulting panel highlighted). "Mark as reviewed" clears the item from the active list, records who reviewed it and when, and archives it — a mailbox. Gating is by order priority: STAT/urgent orders raise a notification on the bell; routine orders post silently to the Results viewer with no alert. This uses the STAT flag already on the order, so no critical-value thresholds are needed.

  • V2 — Opt-in notification for any order, regardless of priority
    Lets a provider explicitly request to be notified when a result comes back for an order regardless of its criticality — including routine/non-urgent orders — for example to confirm a value is normal. In V1, the ordering provider is only notified for STAT/urgent orders; there is no way to say "tell me when this routine result is back" or to follow an order someone else placed. That capability is anticipated for a future version, and when it lands, non-urgent notification should be opt-in rather than default, so the feature doesn't reintroduce the alert-fatigue problem it's meant to solve.

What clinicians actually need is an intelligent "push" model that automatically notifies them when priority results become available, while keeping routine results accessible without causing interruption.

Smart Notification Filtering Based on Clinical Priority:

✅ DO Notify (Requires Attention)

  • STAT/URGENT Orders → Always notify

    • Reason: Clinician is actively waiting for the result/s to make treatment decisions

  • Critical/Dangerous Values → Immediate notification

    • Reason: Life-threatening findings require immediate action

❌ DON’T Notify (Can Wait)

  • Routine Normal Results → No interruption needed

  • Slightly Abnormal Results → No interruption needed

  • Expected Abnormal Results → → No interruption needed. For example, a patient with kidney disease always has elevated creatinine.

2. User Stories

USE CASE 1: STAT Lab Order → Results Notification

Scenario: A clinician is notified when a result comes back for an order they marked STAT/urgent; routine results post to the chart without an alert.

  1. Dr. Smith orders a lab test for John Doe and marks the order STAT/urgent (routine orders will not notify).

  2. The EMR sends the order to the laboratory queue.

  3. The lab technician processes the sample and enters the final result in the EMR.

  4. On result entry, the system checks the order priority:

    • STAT/urgent: a notification is posted to the ordering provider's bell (unread count increments).

    • Routine: the result posts silently to the Results viewer; no notification is raised.

  5. Dr. Smith opens the bell, reviews the item, and either clicks through to the patient's Results (resulting panel highlighted) or marks it reviewed — which clears it from her list and records who reviewed it and when. Routine results she views during her normal rounding or admin time.

User Story: STAT Lab Order

  • As a clinician, when I mark a lab order STAT/urgent, I want a notification on the bell as soon as the result is entered, so I can act without repeatedly reopening the chart.

  • As a clinician, I want routine results to post to the chart with no alert, so I can review them during rounding without being interrupted.

  • As a lab technician, I want the ordering provider notified automatically when I finalise the result of a STAT/urgent order, so my work leads to the fastest clinical response.

  • As a patient, I want urgent findings brought to my clinician's attention quickly, so I'm treated promptly, and nothing is missed.

USE CASE 2: Prescription Changes

Scenario: Patient arrives at pharmacy with prescription that requires modification.

  1. The patient presents a prescription to the pharmacy.

  2. The pharmacist identifies an issue with Jane Doe’s prescription (Metformin 1000mg) and requests a modification through the system. (e.g., dosage concern, drug interaction, or out-of-stock)

    1. IF Reason = "Drug Interaction Detected" or "Allergy Conflict" or Dosage concern, THEN the system Trigger Immediate Push Notification.

      • Alert: "⚠️ SAFETY ALERT: Jane Doe - Metformin interaction with [New Med]. Action required."

  3. The system immediately sends a notification alert to the prescribing clinician. Dr. Smith sees the pop-up immediately, reviews the interaction, and sends a safe alternative to the pharmacy in real-time.

    1. Message: Prescription modification requested by Pharmacy for Jane Doe - Metformin 1000mg. Reason: Drug interaction detected.

    2. Approves modification → System notifies pharmacy immediately

    3. Rejects/modifies differently → System sends alternative prescription to pharmacy

User Story:

  • As a Pharmacist, I want the system to automatically escalate (notify the clinician immediately) high-priority safety concerns (like drug interactions or allergies) to the prescribing clinician so that I can resolve medication safety issues quickly and reduce patient wait time at the pharmacy.

  • As a Clinician, I want the EMR to interrupt me for clinical safety risks or urgent medication changes, so that I can prevent medical errors, ensuring my patient receives safe and appropriate medication without delay.

  • As a Patient, I want the most urgent issues with my medication to be prioritized for my doctor's immediate attention, so that I am protected from dangerous drug conflicts.

  • As a Pharmacist, I want to be notified when a clinician has resolved a pending modification, so that I can finalize the dispensing process as soon as the clinical 'block' is removed.

3. Market Analysis

System

Features

Remarks

System

Features

Remarks

PIH

image-20260513-134246.png

 

image-20260513-134339.png
O3 header with notifications icon

 

image-20260513-134312.png
Notifications list

When lab results are entered, add a results banner (similar to the existing Lab Order banner)

image-20260715-152250.png

The Review link would open the patient’s workspace and show lab results

The “x” icon would dismiss the alert. Clicking “x” should warn users the alert will be dismissed for everyone.

image-20260715-152406.png

 

Requestor: Sierra Leone and Haiti

Problem: Clinicians don’t have easy way to know when a patient’s lab test results are entered in to the EMR and available to view. They currently need to navigate to the patient chart and continuously check the Lab Results page.

Proposal: When lab results are entered, notify the ordering clinician in the EMR.

Details:

  • Notification icon in the header ✅

  • If there are unread notifications, an alert should appear with the number of unread notifications ✅

  • Clicking on the notification icon should open the list of unread notifications ✅

  • Clicking on a notification should take you to that patient’s lab results page ✅

  • Once a notification is clicked on and you are directed to the patient’s lab results page, you should then have an option to click “Reviewed” this will then mark the notification as Read. We should capture who reviewed the lab result. ✅

  • Read notifications should not appear in the notification list ✅

  • The notification should include the date/time, patient name, and that there is a new lab result. Should this be one notification per patient? Or one per test if a patient has more than one result?✅ added in the mock-up

  • Notify when the sample is rejected ✅ added in the mock-up

  • The notification should only appear where they are ordered. MCOE should be considered one location. If an order is made from an MCOE location it should appear at all MCOE locations. ✅ added in the mock-up

  • Also include notifications on the Ward View patient card. The behavior should remain the same, they need to click review in order to clear the notification. ❌ Need clarity

Prognosis: https://youtu.be/0d4QXIU07uc

image-20260205-092526.png
image-20260205-092618.png

  • Message details

    • Message sender

    • Patient name

    • Message type

    • Date message received

    • Message subject/details

    • Action

  • Pagination ~ with configurable page size

OpenEMR: https://demo.openemr.io/openemr/interface/login/login.php?site=default (admin/pass)

image-20260216-082134.png
image-20260216-082217.png
image-20260216-082336.png
image-20260216-082442.png
image-20260216-082505.png
image-20260216-082533.png
image-20260216-082553.png

  • Message details

    • Message type (Referral, Lab results, Pharmacy, etc))

    • Message recipient

    • Message content (Typing space)

    • Message actions (Add new, Delete)

    • Date message last updated

    • Message status (new)

    • Patient name

  • Patient context: Where messaging appears in the patient chart

  • Message centre → envelope icon in the top-right corner

DrChrono: https://youtu.be/3PT1ViGDnss

https://youtu.be/wv5g1_HGCzQ

 

image-20260216-123123.png
image-20260216-124837.png

 

  1. https://www.charmhealth.com/resources/addons/lab-result-notifier.html

 

image-20260216-131045.png

 

  • Once the results get added to the system, this feature evaluates the result values against the configured notification criteria. The configured Members will receive notification(s) if the values uploaded in the system match the criteria.

    • The system automatically evaluates lab result values against pre-configured notification criteria

    • Notifications are only triggered when values match the criteria (not for every result)

    • Timestamp shown (date + time)

    • Patient identifier included

 

 

 

4. Technical Considerations & Dependencies

@tendo kiiza Martyn @tendo kiiza Martyn @Samuel Lubwama @Wikum Weerakutti @Dennis Kigen @Daniel Kayiwa. Please validate if this is accurate - I used Claude Code to check out the technical considerations and current gaps that would need to be bridged for the feature to work as expected.

Spec step

Reality in the codebase

Gap/work

Spec step

Reality in the codebase

Gap/work

Dr marks order STAT/urgent

✅ OrderUrgency = 'ROUTINE' | 'STAT' | 'ON_SCHEDULED_DATE' (order.ts); used in test-order & general-order forms; rendered as priority tag via getPriorityTagType().

None — done today.

Lab tech enters final result

✅ Result-entry workspace exists (testResultsFormWorkspace, esm-patient-orders-app).

None.

On result entry, system checks priority & notifies

❌ fhir2 has zero eventing — no org.openmrs.event/Interceptor/@EventListener/AtomFeed (0 hits). Nothing fires when an Obs is saved.

Build the backend trigger — a new module (or openmrs-module-event subscriber / Hibernate interceptor) that reacts to result save. This is the central dependency.

↳ check STAT flag

⚠️ Order.getUrgency() exists at the Java API, but ServiceRequestTranslatorImpl never sets ServiceRequest.priority — STAT is invisible over FHIR.

If the trigger works at the Java/API layer, no change needed. If any consumer reads STAT over FHIR, add urgency→priority mapping to ServiceRequestTranslatorImpl (mirror the existing MedicationRequestPriorityTranslatorImpl).

↳ correlate result → order

✅ ObservationTranslatorImpl sets obs.addBasedOn(...observation.getOrder()); linkage is real.

None — the result→order association already exists.

↳ identify recipient

✅ Order.getOrderer() is available (ServiceRequestTranslatorImpl maps it to requester).

Small — resolve orderer → Provider/User in the trigger.

↳ post to bell / increment unread count

❌ No persistent notification store, no unread concept (unreadCount/notification-inbox/notifications-menu = 0 hits).

Net-new: notification data model + REST endpoint (paginated) + recipient wiring.

5a. Dr opens bell (cross-patient inbox)

⚠️ Bell UI buildable, but the sticky-note template lives in patient-info-slot (a per-patient chart slot); the global top-nav is not in this repo — it's in esm-core's esm-primary-navigation-app.

Placement decision first, then build: global bell → work in esm-core (a 3rd repo); patient-scoped bell → fits these repos but weaker UX. Badge must derive from real unread state (template's count is a hard-coded stub).

5b. Mark reviewed → clears, records who + when, archives

❌ No review-state concept on orders or results.

Net-new: status, reviewedBy, reviewedDatetime fields + mark-reviewed endpoint (doubles as the audit trail).

5c. Routine posts silently to Results

✅ With no notification path, a routine result simply appears in the Results viewer.

None.

Real-time delivery ("push")

❌ No websocket/EventSource/refreshInterval anywhere (0 hits); everything is openmrsFetch + SWR with manual mutate().

MVP = SWR polling of the notifications endpoint (refreshInterval, currently unused). True push is a later, separate effort.

 

 

 

5. O3 Sketches/Mockups

V1 Scenarios:

  1. Lab Order Priority = STAT

  2. Opt-In by the Clinician Ordering the Lab/s

  3. Notification when the Lab rejects the Lab test

image-20260703-141532.png
Notify when resulted, order = stat/urgent
image-20260703-142830.png
Notification Panel
image-20260703-142929.png
Review Actions

 

image-20260703-141626.png
Opt-In: Notify even if the value isn't critical
image-20260703-142839.png
Notification Modal
image-20260703-143002.png
Results Viewer

 

 

Comments