Package: @openmrs/esm-report-builder (currently being prepared for @openmrs/esm-report-builder packaging)
Platform: OpenMRS 3 (O3) Microfrontend
Status: Active Development
| Document | Description | Audience |
|---|---|---|
| User Manual | Complete guide for end users on using the application | Implementers, Report Developers |
| Technical Documentation | Architecture, API, and integration details | Developers, Technical Staff |
| Quick Reference | Quick lookup for routes, endpoints, and common patterns | All Users |
| Backend Support | Backend API dependencies and requirements | Developers |
| Endpoint Migration | API migration details and status | Developers |
The OpenMRS ESM Report Builder is an OpenMRS 3 frontend microfrontend (ESM) for designing, managing, and structuring health reports used in national and facility-level reporting.
It provides a unified environment where implementers, analysts, and developers can:
- Create and manage reports
- Design report layouts and sections
- Define reusable indicator logic
- Build structured, disaggregation-aware report templates
- Manage shared reporting metadata and catalogues
- Preview and export machine-consumable report definitions
The Report Builder intentionally separates report design, indicator logic, and template mapping, enabling reuse, governance, and long-term maintainability of reporting artifacts.
This project focuses on report design and management, not report execution. It helps teams create a clear source of truth for reporting structures that can later be evaluated by backend services, data pipelines, or reporting engines.
The goal of this project is to provide a modern, modular, and maintainable report-authoring experience for OpenMRS implementations such as UgandaEMR, while aligning the work for broader reuse in the OpenMRS ecosystem. The module is intended to make report definitions easier to create, review, reuse, govern, and eventually share across implementations.
- A report design and configuration tool
- A template and indicator authoring environment
- A source of truth for report definitions
- A bridge between reporting logic and downstream evaluators/renderers
- A reusable reporting workspace for structured health reporting metadata
- Not a report executor
- Not a data visualization runtime by itself
- Not responsible for evaluating indicators or querying data directly
- Not a data warehouse or backend reporting engine
Execution is delegated to backend services and reporting pipelines.
The application includes a landing page that introduces the report builder workspace and acts as the entry point for users navigating the module inside OpenMRS 3.
- Create new reports
- List existing reports
- Open and edit reports
- Duplicate and export reports (planned/partial workflow support)
- Manage report metadata such as name, description, and status
Each report is intended to encapsulate:
- A report design
- A report template
- References to reusable indicator definitions
Design the human-readable structure of a report.
Current and planned report design capabilities include:
- Pages and sections
- Narrative text
- Indicator tables
- Section configuration and previews
- Future chart and visual elements
The indicators module is one of the most developed parts of the project and is centered around reusable reporting logic.
Current work includes:
- Base indicator creation
- Composite indicator creation
- Final indicator creation
- Indicator status display
- Disaggregation-aware configuration
- SQL preview support
- Diagnosis filter support
- Preview table support
- Reusable indicator definitions across reports
This design helps separate indicator logic from final report layout so that indicators can be reused across multiple reports.
The report sections area supports building the structural layout of reports independently from indicator logic.
Current work includes:
- Section creation
- Section preview
- Section utilities
- Section type handling
The admin area supports shared configuration and reusable catalogues needed by the report builder.
Current work includes:
- Report library page
- Data themes management
- Report categories page
- Age categories page
- Age groups page
These shared resources help improve consistency and reduce repeated setup across reports.
A run reports page is included as part of the product structure and can support future integrations for execution, preview, orchestration, or report delivery workflows.
The codebase already includes AI support components and service definitions, creating a foundation for guided authoring, assisted SQL generation, and smarter report-building workflows.
The current application structure includes the following main routes:
/— landing page/reports— reports dashboard/new— create report/edit/:reportId— edit report/indicators— indicators workspace/sections— report sections workspace/run— run reports page/admin— admin home/admin/report-categories— report categories/admin/age-categories— age categories/admin/age-groups— age groups/admin/report-library— report library/admin/themes— data themes
This frontend is built with:
- OpenMRS 3 Microfrontend architecture
- React
- TypeScript
- Carbon Design System
- Sass
- Jest for testing
- ESLint for linting
- Yarn for package management
The project is currently packaged as an OpenMRS ESM and produces a browser bundle under dist/openmrs-esm-report-builder.js.
Available scripts include:
yarn start— start local developmentyarn build— production buildyarn analyze— build analysisyarn lint— lint source codeyarn test— run testsyarn coverage— run test coverageyarn typescript— run TypeScript checksyarn verify— run lint, tests, and type checks together
A simplified view of the project organization:
src/
├── components/
│ ├── admin/
│ ├── ai-support/
│ ├── app-shell/
│ ├── data-themes/
│ ├── indicators/
│ ├── landing/
│ ├── report/
│ ├── report-sections/
│ └── run-reports/
├── resources/
├── routes/
├── types/
├── utils/
├── config-schema.ts
├── index.ts
├── root.component.tsx
├── sample-template.ts
└── template-utils.ts
- Node.js 18+
- Yarn 1.x or Corepack-enabled Yarn
- OpenMRS 3 backend
yarn installyarn start --backend=http://localhost:9098http://localhost:8080/openmrs/spa/report-builder
yarn buildyarn verifyThis application is structured as an OpenMRS ESM and is intended to plug into an OpenMRS 3 shell. It defines a root lifecycle and extension entry points so it can integrate cleanly into the broader frontend platform.
- Report authoring and configuration
- Reusable indicator design
- Structural report composition
- Shared reporting catalogues and metadata
- A foundation for future AI-assisted authoring
- Indicator evaluation
- Data retrieval and backend execution
- Report scheduling and orchestration engines
- Advanced chart rendering and analytics runtime
This work began under the UgandaEMR scope and is being prepared for broader OpenMRS-aligned packaging. The current direction is to align the package and module pathing for publication under the @openmrs scope.
The project is being prepared with a GitHub Actions workflow to support:
- Build validation on push and pull request
- Verification using lint, tests, and TypeScript checks
- Prerelease publishing
- Release publishing to npm-compatible package scopes
Planned and likely next steps include:
- Completing more report editor workflows
- Strengthening report library and migration flows
- Expanding data theme configuration
- Improving execution handoff to backend/reporting services
- Adding richer preview capabilities
- Strengthening AI-assisted authoring experiences
- Finalizing package publication under
@openmrs - Adding documentation for extension slots and backend API expectations
When contributing:
- Keep report structure, indicator logic, and shared catalogues cleanly separated.
- Prefer reusable components and configuration-driven approaches.
- Run
yarn verifybefore submitting changes. - Keep alignment with OpenMRS 3 frontend conventions.
- Document any new routes, admin pages, or API contracts.
- Hexam Creation Consult
Mozilla Public License 2.0 (MPL-2.0)
For detailed documentation, see:
- User Manual - How to use the Report Builder
- Technical Documentation - Architecture and implementation details
- Quick Reference - Quick lookup for common tasks
This work builds on the OpenMRS 3 microfrontend platform and reflects implementation needs around structured health reporting, indicator management, and reporting governance within UgandaEMR and the wider OpenMRS ecosystem.