/
Working with Building Blocks

Working with Building Blocks

This guide provides detailed techniques for creating and configuring the core components that make up OpenMRS reports.

Reports are built from fundamental building blocks—cohort queries that define patient groups, indicators that perform calculations, dimensions that categorize results, and parameters that make reports flexible. This guide goes beyond basic creation to show you how to build robust, reusable components including effective cohort query patterns, reliable indicator calculations, strategic use of dimensions for data breakdown, and advanced parameter techniques that make your reports more powerful and user-friendly.

Table of contents

Creating Effective Cohort Queries

Common Cohort Types

  1. Gender-based Cohorts

  • Use: Gender Query

  • Parameters: Male = True/False, Female = True/False, Unknown = True/False

  • Tip: Set one as fixed value, other as parameter for flexibility

  1. Age-based Cohorts

  • Use: Age Range Cohort Query

  • Parameters: Min age, Max age

  • Example: Pediatric patients (0-14 years)

  1. Program Enrollment Cohorts

  • Use: In Program Query

  • Parameters: Program, Enrollment date range, Effective date

  • Tip: Use expressions like endDate-1m for relative dates

  1. Observation-based Cohorts

  • Use: Coded Observation Query

  • Parameters: Concept, Values, Date range

  • Example: Patients with TB diagnosis

  1. SQL-based Cohorts

  • Use: SQL Cohort Query

  • Format: Must return patient_id column

  • Parameters: Use :parameterName syntax

  • Example:

SELECT DISTINCT p.patient_id FROM patient p JOIN encounter e ON p.patient_id = e.patient_id WHERE e.encounter_datetime >= :startDate AND e.encounter_datetime <= :endDate AND e.location_id = :location

Cohort Query Best Practices

✅ Do:

  • Use descriptive names that explain the criteria

  • Test with preview function before saving

  • Document complex logic in description

  • Use parameters for reusability

  • Consider performance with large datasets

❌ Avoid:

  • Overly complex single queries (break into smaller ones)

  • Hardcoded values when parameters would be better

  • Missing null/void checks in SQL queries

  • Duplicate logic across multiple cohorts

Building Robust Indicators

Indicator Types Explained

  1. Count Indicators

  • Purpose: Simple counting of cohort members

  • Result: Whole numbers (e.g., 45 patients)

  • Use for: Total enrollments, active patients, new cases

  1. Fraction Indicators

  • Purpose: Calculate percentages and ratios

  • Components: Numerator cohort ÷ Denominator cohort

  • Result: Decimal (displayed as percentage)

  • Use for: Completion rates, coverage percentages

  1. Logic Indicators

  • Purpose: Complex calculations using multiple inputs

  • Components: Multiple cohorts with mathematical operations

  • Result: Calculated values

  • Use for: Rates per population, complex ratios

Creating Fraction Indicators

Example: TB Treatment Success Rate

  1. Numerator Cohort: Patients who completed TB treatment

  2. Denominator Cohort: All patients who started TB treatment

  3. Result: Completion rate as percentage

Configuration Steps:

  1. Create numerator cohort (completed treatment)

  2. Create denominator cohort (started treatment)

  3. Create fraction indicator

  4. Map both cohorts with appropriate parameters

  5. Test with known data

Parameter Mapping in Indicators

Standard Parameters:

  • startDate - Beginning of reporting period

  • endDate - End of reporting period

  • location - Geographic/facility filter

Parameter Expressions:

  • endDate-1m - One month before end date

  • startDate+2w - Two weeks after start date

  • endDate-1y - One year before end date

Mapping Examples:

Indicator Parameter → Cohort Parameter endDate → effectiveDate startDate → enrollmentStartDate endDate-6m → treatmentStartDate

Working with Dimensions

A dimension is a way to break down or group an indicator. It does not produce a number on its own; instead, it adds context to an indicator.

Indicator: What number do you want?
Dimension: How do you want to slice that number?

When to Use Dimensions

Use Dimensions When:

  • You want to break down indicators by categories

  • The same indicator applies to different groups

  • You need cross-tabulation (age × gender breakdowns)

Don't Use Dimensions When:

  • Categories are mutually exclusive and need separate indicators

  • Logic differs significantly between groups

  • Performance would be impacted by complex breakdowns

Creating Dimension Categories

Age Group Dimension Example:

  1. Create cohorts for each age group:

    • Age 0-4 cohort

    • Age 5-14 cohort

    • Age 15+ cohort

  2. Create dimension definition

  3. Add each cohort as dimension option

  4. Apply to relevant indicators

Location Dimension Example:

  1. Create cohorts for each location

  2. Or use location parameter directly

  3. Apply to multi-site reports

Advanced Parameter Techniques

Parameter Types and Uses

Collection Parameters:

  • List: Multiple values of same type

  • Set: Unique values only

  • Use for: Multiple locations, multiple programs

Advanced Configuration:

  • Coded Options: Predefined choices for string parameters

  • Option Headers: Custom dropdown labels

  • Question Concepts: Limit concept choices to specific answers

Expression Examples

Date Calculations:

${now} - Current date/time ${start_of_today} - Midnight today ${end_of_last_month} - Last day of previous month ${start_of_today-30d} - 30 days ago ${end_of_today-1y+6m} - 6 months ago last year

Parameter References:

endDate-3m - Three months before end parameter startDate+1w - One week after start parameter