/
UI-Defined Reports

UI-Defined Reports

Note on UI-Defined Reports

UI-Defined Reports are deprecated and no longer actively supported.
They may continue to work in some environments, but they are not recommended for new development and are used at your own risk.
Future enhancements, bug fixes, and documentation focus will be on the programmatic and configuration-based approaches.

This guide provides complete, hands-on tutorials for building the most common types of reports in OpenMRS using the UI.

Learn report building through three practical tutorials that cover the essential report types you'll need: a simple row-per-patient report for detailed patient lists, a period indicator report for monthly statistics and performance monitoring, and a custom cohort indicator report for flexible data analysis. Each tutorial walks you through every step from initial planning to testing the final report, giving you real-world experience with the complete report building process.

Tutorial 1: Simple Row-Per-Patient Report

This tutorial creates a report listing patients with basic demographic information.

Goal

Create a report showing: Patient ID, Name, Age, Gender, and Last Visit Date for patients from a specific location.

Step 1: Create Data Set Definition

  1. Navigate: Report Administration → Data Set Definitions

  2. Add New: Click "+" next to "Simple Patient Data Set"

  3. Configure:

    • Name: Basic Patient Demographics

    • Description: Patient list with demographics and last visit

  4. Add Patient Properties:

    • Expand the dropdown next to “Person/Patient Properties”

    • Select “Fixed Value”

    • Add these properties one by one (Click "+" to add next):

      • patientId - Patient identifier

      • givenName - First name

      • familyName - Last name

      • gender - Gender

      • birthdate - Birth date

      • age - Current age

image-20250711-082841.png

  1. Save the data set definition

Step 2: Create Report Definition

  1. Navigate: Reports Administration → Report Definitions

  2. Add New: Click "Custom Report (Advanced)"

  3. Configure:

    • Name: Patient Demographics Report

    • Description: Basic patient information for specified location and date range

    • Click “Save” (You have to go back to the Report Administration page to see the created report)

Step 3: Add Parameters

  1. Go back to Report Administration and click on the edit icon

  2. Add Location Parameter:

    • Click "+" next to Parameters

    • Type: Single → Location

    • Name: location

    • Label: Facility Location

Step 4: Link Data Set to Report

  1. Add Data Set:

    • Click "+" next to Data Set Definitions

    • Key: demographics

    • Data Set Definition: Select Basic Patient Demographics

    • Parameters: Map location and date parameters as needed

  2. Save the report

Step 5: Test Your Report

  1. Navigate: Reporting → Run a Report

  2. Select: Your new Patient Demographics Report

  3. Set Parameters: Choose location

  4. Run: Select Excel output format

  5. Verify: Check that results match expectations

Tutorial 2: Period Indicator Report

This step-by-step tutorial will guide the user in making indicator reports, using a period indicator report as an example.

Goal

Create a report that only includes patients in the Heart Failure Program. The first question will be:

  • Percentage of men whose main job is farming

Step 1: Create Cohort Queries

Cohort 1: Male Patients

  1. Navigate: Report Administration → Cohort Queries

  2. Add: Click "+" next to "Gender Query"

  3. Configure:

    • Name: Male Cohort

    • Description: All male patients in the system

    • Properties:

      • Male = True (fixed value)

      • Female = False (fixed value)

      • Unknown = False (fixed value)

        image-20251216-114953.png

         

  4. Save the cohort

  5. Test: Click "Preview" and "Run" to verify patients exist

Cohort 2: Farmers

  1. Navigate: Back to Cohort Queries page

  2. Add: Click "+" next to "Coded Observation Query"

  3. Configure:

    • Name: Farmer Cohort

    • Description: Patients whose main occupation is farming

    • Properties:

      • Which Observation: Fixed value Last (to get latest occupation)

      • observations with this question: Fixed value : MAIN ACTIVITY (This is a fixed value, as you do not want to change the observation each time you run the report.)

    • Constraint:

      • Comparison: IN (fixed value)

      • Value: Farmer (fixed value)

  4. Save the cohort

  5. Note: Leave 'When' and 'Other' blank - dates and location will be set by report parameters

    image-20251216-115721.png


    This sets the observation of 'Main activity' to the value 'Farmer.' All of these fields are fixed values because we do not want the choice of changing what the cohort contains each time the report is run. We will leave the 'When' and 'Other' categories blank because the dates of observation and location will be set by the report parameters, which will be described in a later step.

Cohort 3: Heart Failure Program Patients

  1. Navigate: Back to Cohort Queries page

  2. Add: Click "+" next to "In Program Query"

  3. Configure:

    • Name: In Heart Failure Program

    • Description: Patients enrolled in Heart Failure Program

    • Properties:

      • Programs: Heart Failure Program (fixed value)

    • Or Specifically:

      • Property: Parameter

      • Label: effectiveDate

  4. Save the cohort

Step 2: Create Indicators

We will now build the 'Farmers Indicator', which will return the percent of farmers in the Heart Failure Program at the report 'End Date' and in a specific location.

Farmers Indicator

  1. Navigate: Administration → Indicator Definitions

  2. Add: Click "Create Cohort Indicator"

  3. Configure Basic Properties:

    • Name: Farmers Indicator

    • Description: Percent of farmers in Heart Failure Program

    • Type: Fraction (for percentage calculation)

    • Standard Parameters: Check all three:

      • ✓ startDate

      • ✓ endDate

      • ✓ location

  4. Configure Location Filter:

    • Click "Edit mappings" for Location Filter

    • Set to: Health Center Location

    • Type: Parameter

    • Parameter Type: Location

  5. Configure Numerator:

    • Click "Edit mappings" for Numerator

    • CohortDefinition: Farmer Cohort

  6. Configure Denominator:

    • Click "Edit mappings" for Denominator

    • CohortDefinition: In Heart Failure Program

    • effectiveDate: Parameter → End date

    • Note: The numerator is automatically constrained by the denominator

Step 3: Create Dimensions

We will now create a dimension to restrict the Farmers Indicators to only males.

Gender Dimension

  1. Navigate: Administration → Dimension Definitions

  2. Add: Click "+" next to "Dimension"

  3. Configure:

    • Name: Gender Dimension

    • Dimension Option:

      • Key: Males Cohort

      • CohortDefinition: Male Cohort

Step 4: Create Period Indicator Report

  1. Navigate: Report Administration

  2. Add: Click "Period Indicator Report"

  3. Configure:

    • Name: Heart Failure Report

    • Description: Heart Failure Program performance indicators

    • Click "Submit"

  4. Add Dimensions:

    • Click "Add Dimension"

    • Key: Gender

    • CohortDefinitionDimension: Gender Dimension

  5. Add Filter:

    • Click "Edit mappings" under Filter

    • CohortDefinition: In Heart Failure Program

    • effectiveDate: Parameter → End date

    • This ensures only Heart Failure Program patients appear in the report

  6. Add Indicators:

    • Click "Add" under Indicators

    • Indicator Number: 1

    • Label: Percent of Male Farmers in Heart Failure Program

    • Indicator: Farmers Indicator

    • Dimensions: Change Gender to Males Cohort

    • Click "Save"

Step 5: Test and Refine

  1. Run Report: Test with known data period

  2. Verify Numbers: Cross-check with manual counts

  3. Adjust: Modify cohort criteria if needed

  4. Document: Add clear descriptions for users

Your Period Indicator Report is now complete!

Tutorial 3: Custom Cohort Indicator Report

This step-by-step tutorial will guide the user in the creation of a custom Indicator Report, using a Cohort Indicator with Dimensions Report as an example. This example will highlight how parameters are used in reports.

Goal

The first question in this report will be:

  • Number of People in the HIV Program at the endDate

Step 1: Build Cohorts

InProgramOnDate Cohort

We will now make our cohort, InProgramOnDate, which will contain patients in a specific program by the end date of our report.

  1. Navigate: Administration → Cohort Queries (see Step 1 of Building a Period Indicator Report)

  2. Add: Click "+" next to "In Program Query"

  3. Configure:

    • Name: InProgramOnDate

    • Description: Patients in a specific program by end date

    • Properties:

      • Program: Parameter (allows choosing which program for each report run)

    • Or Specifically:

      • Label: effectiveDate

      • Type: Parameter (allows selecting the date each time the report is run)

  4. Save the cohort

You are now ready to create an Indicator.

Step 2: Build Indicators

In HIV Program Indicator

  1. Navigate: Administration → Indicator Definitions

  2. Add: Click "Create Cohort Indicator"

  3. Configure Basic Properties:

    • Name: In HIV Program Indicator

    • Description: Count of patients in HIV Program

    • Type: Count (aggregate function will count the number of patients)

    • Standard Parameters: Check endDate

    • Click "Submit"

  4. Add Parameters:

    • Under "Parameters", click "Add"

    • Add the parameter endDate so it can be passed in

  5. Configure Cohort Definition:

    • Under "Cohort Definition", click "Edit Mappings"

    • Cohort Definition: InProgramOnDate

    • Program: Adult HIV Program (passed to InProgramOnDate program parameter)

    • effectiveDate: Expression → endDate - 1m (one month before the endDate)

You are now ready to build your data set definition.

Step 3: Build Data Set Definitions

HIV Data Set Definition

  1. Navigate: Administration → Data Set Definitions

  2. Add: Click "+" next to "Cohort Indicator with Dimensions Data Set"

  3. Configure Basic Properties:

    • Name: HIV Data Set Definition

    • Description: Data set for HIV program indicators

  4. Add Parameters:

    • Under "Parameters", click "Add"

    • Click the "endDate" shortcut link to automatically add it

    • Click "Submit"

  5. Add Indicators:

    • Under "Indicators", click "Add"

    • Indicator Number: #1

    • Label: Patients in HIV Program

    • Indicator: In HIV Program Indicator

    • Parameter: End Date

    • Click "Submit"

Note: You can also add dimensions to the data set by clicking "Add" in the Dimensions box, but make sure you have built the necessary dimension before this step.

You are now ready to build your custom Indicator Report.

Step 4: Build Custom Indicator Report

HIV Report

  1. Navigate: Administration → Report Definitions

  2. Add: Click "Custom Report (Advanced)"

  3. Configure Basic Properties:

    • Name: HIV Report

    • Description: Custom HIV program indicator report

    • Click "Submit"

  4. Add Parameters: