/
Getting Started with OpenMRS Reporting Module

Getting Started with OpenMRS Reporting Module

Table of contents

What is the OpenMRS Reporting Module?

The OpenMRS Reporting Module is a powerful, flexible framework that enables you to create, manage, and run reports within OpenMRS. It provides both a user-friendly web interface for building reports and a comprehensive API for developers to create custom reporting solutions.

Key Features

  • Flexible Report Building - Create reports using a web interface or programmatically

  • Multiple Output Formats - Export to Excel, CSV, HTML, PDF, and custom templates

  • Automated Scheduling - Run reports automatically and email results

  • Extensible Framework - Add custom report types and renderers

  • Performance Optimized - Handles large datasets efficiently

Understanding Report Types

The Reporting Module supports two main categories of reports:

📊 Row-Per-Domain Reports

These reports display data in a tabular format where each row represents an object (like a patient) and columns show different attributes.

Example: Patient List Report

Patient ID

Name

Age

Gender

Last Visit

Patient ID

Name

Age

Gender

Last Visit

12345

John Doe

45

M

2024-01-15

12346

Jane Smith

32

F

2024-01-10

Common Use Cases:

  • Patient demographic reports

  • Encounter lists

  • Program enrollment summaries

  • Data exports for external analysis

📈 Indicator Reports

These reports aggregate data to answer specific questions with numerical results. Each row represents a question and the answer is typically a count, percentage, or other calculated value.

Example: Monthly Health Indicators

Indicator

Value

Details

Indicator

Value

Details

New TB patients this month

25

[View patient list]

TB treatment completion rate

85%

[View details]

Patients on ART

450

[View patient list]

Common Use Cases:

  • Monthly/quarterly health indicator reports

  • Program performance monitoring

  • Government reporting requirements

  • Quality improvement metrics

Installation & Setup

System Requirements

  • OpenMRS Platform: Version 1.5.2 or higher

  • Java: Version 8 or higher

  • Database: MySQL 5.6+ (recommended)

Required Modules

Before installing the Reporting Module, ensure these dependencies are installed:

  1. HTML Widgets Module (version 1.5.5+)

    • Provides user interface components for parameters

  2. Serialization XStream Module (version 0.1.8.1+)

    • Handles data serialization for reports

Installation Steps

  1. Download the Module

  2. Install Dependencies

    • Install HTML Widgets and Serialization XStream modules first

    • Restart OpenMRS after each installation

  3. Install Reporting Module

    • Navigate to Administration → Manage Modules

    • Click "Add or Upgrade Module"

    • Browse and select the reporting .omod file

    • Click "Upload"

  4. Verify Installation

    • Look for "Reporting" in the main navigation menu

    • Check that no error messages appear in the server logs

Recommended Additional Modules

  • Reporting Compatibility Module (version 1.5.0.3+)

    • Provides backward compatibility with older reporting tools

    • Useful if migrating from Data Export or Cohort Builder

User Permissions & Security

Required Privileges

To use the Reporting Module effectively, users need appropriate privileges:

For Running Reports (End Users)

  • View Reports - See available reports

  • Run Reports - Execute reports

  • View Patient Cohorts - View patient lists in results

For Building Reports (Implementers)

  • All end user privileges, plus:

  • Manage Reports - Access report building interface

  • Manage Report Definitions - Create and edit reports

  • Manage Data Set Definitions - Build data sets

  • Manage Cohort Definitions - Create patient groups

  • Manage Indicator Definitions - Build indicators

  • Manage Dimension Definitions - Create filters

  • Manage Report Designs - Configure output formats

For System Administration

  • View Administration Functions - Access admin tools

  • Manage Scheduled Report Tasks - Set up automated reports

Setting Up User Roles

  1. Navigate to Administration → Users

  2. Create or edit user roles

  3. Assign appropriate privileges based on user needs

  4. Test access with different user accounts

Basic Terminology

Understanding these key concepts will help you work effectively with the Reporting Module:

Core Components

Report Definition 📋

  • The top-level container for your report

  • Contains one or more Data Set Definitions

  • Defines parameters and filters that apply to the entire report

Data Set Definition 📊

  • Defines what data will be included in your report

  • Can directly contain data (like patient demographics) or reference other components (like indicators)

Cohort Query 👥

  • Defines a group of patients who meet specific criteria

  • Examples: "Patients on ART", "Pediatric patients", "Patients in TB program"

  • Building blocks for indicators and filters

Indicator 📈

  • Performs calculations on cohorts (count, percentage, average, etc.)

  • Answers questions like "How many patients..." or "What percentage of..."

Dimension 🔍

  • Filters that break down indicators by categories

  • Examples: Age groups, gender, location

  • Allows one indicator to be split multiple ways

Parameter Types

Parameters ⚙️

  • Values entered when running the report

  • Examples: date ranges, locations, programs

  • Allow reports to be reused with different inputs

Fixed Values 🔒

  • Values built into the report definition

  • Cannot be changed when running the report

  • Used for report-specific settings

Expressions 🧮

  • Dynamic values calculated relative to parameters

  • Examples: "endDate-1m" (one month before end date)

  • Useful for relative date calculations

Quick Start: Your First Report

Let's create a simple patient list report to get you started:

Step 1: Access the Reporting Interface

  1. Log into OpenMRS

  2. Click "Reporting" in the main menu

  3. Select "Report Administration" from the toolbar

Step 2: Choose Report Type

  1. Click "Custom Report (Advanced)"

  2. Enter a name: "My First Patient Report"

  3. Add a description

  4. Click "Submit"

    image-20250930-061315.png

Step 3: Create a Data Set

  1. Go to the “Data Set Definitions ” page.

  2. Click the "+" next to "Simple Patient Dataset"

    image-20250930-062318.png

  3. Provide a name ex: “Patient Demographics Data Set”

  4. Under “Person/Patient Properties”, select “Fixed Value”

  5. Add patient properties like:

    1. patientId - Patient identifier

    2. givenName - First name

    3. familyName - Last name

    4. gender - Gender

    5. birthdate - Birth date

  6. Click "Save"

    image-20250930-062809.png

Step 3: Add a Data Set

  1. Go back to the “Report Administration” page and click the edit icon in front of the created report.

    image-20250930-063107.png

  2. Click the "[+] New Dataset Definition" next to "Data Set Definitions"

  3. Enter a key: "patients"

  4. Choose the previously created dataset definition from the dropdown

  5. Click "Submit"

    image-20250930-063331.png

Step 5: Run Your Report

  1. Go to "Report Administration"

  2. Click the Run icon next to your report

    image-20250930-064008.png

  3. Click "Request Report"

    image-20250930-064020.png

  4. On the next screen, click “View Report”

    image-20250930-064148.png

     

    image-20250930-064219.png

Congratulations! You've created your first OpenMRS report. 🎉

What's Next?

Now that you have the basics down, explore these areas:

For End Users

For Report Builders

Getting Help

Documentation

Community Support

  • OpenMRS Talk - Community forum for questions and discussions

  • Slack - Real-time chat with the community

Reporting Issues

  • JIRA - Official bug tracking and feature requests

  • GitHub - Source code

Ready to build your first real report? Choose your path:

 

Existing Videos: