/
Better Reporting Guidance: Docs and Tutorials

Better Reporting Guidance: Docs and Tutorials

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:

  • Currently (May 2025), there is no single guidance-hub for Implementers to use to understand Reporting in OpenMRS:

    • What is possible?

    • What option(s) should I use?

    • How do I configure those approaches?

    • What examples can I learn from?

  • There is no academy content on reporting. The last video explainer on OpenMRS Reports was in 2013.

  • We would like a one-stop-place in our Docs for clear reporting guidance, along with some video tutorials.

image-20250527-184709.png
Examples of just 2 main places where Line List reports and Data Viz can happen. (Source)

 

1. Problem

Reporting is one of the most important use cases for decision-makers choosing an EMR, because their funding is often tied to strict reporting metrics.

  • For Governments and Leaders choosing systems, an EMR that can quickly, easily output the metrics they need is a must-have.

  • For Implementers, Businesses, and NGOs, reports that show their impact is a must-have, especially for fundraising purposes.

  • For Clinical Staff, visuals that show their work and impact is important for morale and clinical insights, e.g. recent increases in cases of cholera would indicate an outbreak requiring escalation; or seeing correlations between a Youth Program vs Youth HIV viral load results.

The importance of rapid, easy reporting outputs is demonstrated in this story from an experienced Implementer: “At one time 10+ years ago in Kenya, building reports with OpenMRS was slow. We had a MoH delegation visit a site, and they asked the site to use the system to answer some questions for them. When the site staff said “That will take 2-3 days to run”, the MoH representatives wanted to cancel the use of OpenMRS entirely. Building a fast-performing ETL pipeline was critical to the sustainment of OpenMRS in Kenya.”

2. User Stories to Solve

  • What is possible in OpenMRS regarding reporting, exports, and data vizualization?

  • What option(s) should I use?

  • How do I configure those approaches?

  • What examples can I learn from?

3. Market Analysis

Market Analysis: How Other Groups Handle Explaining Reports:

Existing Approaches/Solutions for OpenMRS Reporting:

  • OpenMRS Reporting Framework

  • Line-lists

  • Configuring Reports/line-lists in Initializer

  • Cohort Module

  • DHIS2 integration

  • Superset integration (and similar, eg PowerBI; but Superset seems to be growing in popularity)

  • MambaETL Module

  • New Reporting UI from METS in O3 (2024)

  • New Reports generation UI from SolDevelo in O3 (2025)

  • FHIR Analytics Pipeline

  • Case Based Reporting (CBR) module

  • Automated Indicator Reporting (AIR) from Palladium

  • OMOP workflow to export OpenMRS data into Achilles and ATLAS via OMOP CDM

  • Bahmnimart (Bahmni’s report set-up tool)

  • Data Exports + SQL: If you're used to writing SQL, this way's easier. This is how PIH writes their reports - Data Export definition in yaml file + SQL for each. https://github.com/PIH/openmrs-config-pihsl/tree/master/configuration/reports/reportdescriptors/dataexports%E2%80%8B%E2%80%8B They like that they can use this exact same SQL for an ETL as well.

  • …and more…

Scope Note

I suspect our first step may be to narrow this list down by saying, “What do we want to support / focus on?” E.g. IMHO, I think we will want to focus on marketing & training materials for:
1.⁠ ⁠Reporting Framework (how to set up basic reports)
2.⁠ ⁠⁠Simple Data Viz with the new O3 Reports Generation UI SolDevelo recently contributed
3.⁠ ⁠⁠⁠Data Viz with Superset (so groups get the fancier data viz UI/UX they expect)

-Grace

Existing OpenMRS Docs and Guides about Reporting:

Existing Videos:

 

 

4. Technical Considerations & Dependencies

 

 

 

5. Sketches