Overview

The Reporting Module was designed to provide a feature-rich and user-friendly web interface for managing reports within OpenMRS. In addition, the Reporting Module provides a flexible and extensible API that module developers can develop against to build their own reports and tools. The core idea behind the Reporting Module is to provide a solid foundation so that other developers can use the framework to implement new features.

There are many different types of reports but these can be categorized into two main types.

Row-Per-Domain Object Reports

These reports export data in a multi-column format where each row represents the object and each column represents an attribute associated with the object. Currently, only Row-Per-Patient reports are natively supported but more objects (for example Row-Per-Encounter and Row-Per-Program) are in planning. For information on how to build Row-Per-Patient reports, see <UI> and <Code>.

<IMAGE>

Indicator Reports

Indicator reports aggregate groups of people for each question.

<IMAGE>

The answer to each question is itself a link to the underlying members of the group that fulfills the question. For information on how to build indicator reports, see <UI> and <Code>.

<IMAGE>

Limitations

Right now reporting compatibility is used to bridge the gap between the old and new e.g. cohort builder, data exports. This reporting module has a lot of the core features for evaluating parts of a report but doesn't have a good UI yet for designing a full report. Cohort builder is probably best for adhoc querying unless there's something in there that isn't supported then you'd have to use the cohort query editor in the reporting module. Data exports can only be designed/exported using reporting compatibility. There's a feature in this module that let's you define some simple dataset definitions like a SQL-based dataset but we ripped out a lot of the other ones we were working on. So this module and the reporting compatibility are complementary at the moment.

Release Notes

• See Release Notes 0.6.x
• See Release Notes 0.5.x
• See Release Notes 0.4.x

Getting Started

Downloads

We encourage all OpenMRS users and developers to download the module, use it frequently, create new tickets for bug fixes and feature requests, and provide feedback.

Javadocs: javadoc-reporting-0.4.2.zip

View source code: http://source.openmrs.org/browse/Modules/reporting/trunk

Download source code: http://svn.openmrs.org/openmrs-modules/reporting/trunk/

Installation

To install the Reporting Module download the Reporting Module .omod (above), along with its dependencies (see box above) and upload them into your system.

Upgrade

To upgrade from Reporting Module 0.3.x:

• Check to make sure that you have all of the Required Modules installed on your system.
• Double-check to make sure that you have all of the Required Modules installed on your system.
• Log into OpenMRS
• Navigate to Admin > Manage Modules.
• Click the trash icon next to Reporting 0.3.x to remove the module from your system.
• Navigate to the newer omod on your system using the browse button and click Upload.

Privileges

In order for users to be able to run most reports, you need to put them in a group with the privileges:
(this is accurate as of 0.4.1.2)

• View Reports
• Run Reports
• View Patient Cohorts
  • technically this is only required if you want to be able to run reports including cohorts of patients, which is basically all reports
• (up until 0.4.1.1) Manage Scheduler

To be able to edit and configure reports, you need:
(this is accurate as of 0.4.1.3)

• Manage Reports (this just enables you to see the menu items)
• Manage Report Definitions
• Manage Data Set Definitions
• Manage Indicator Definitions
• Manage Dimension Definitions
• Manage Cohort Definitions
• Manage Report Designs

You also need to grant View privileges related to the base objects your reporting definitions use. For example you need "View Programs" to create and use an "In Program" Cohort Query

Building Reports

Understanding the Basic Terminology

Report Definition

Report Definitions are the outermost layer of your report. They contain one or more DataSet Definitions which in turn will contain the data for your report.

DataSet Definition

A DataSet Definition maps out what information will be in your report. It will contain the data for your report or lower level components which themselves contain the data for your report. Row-Per-Patient reports are an example of the former whereas Cohort Indicator reports are an example of the latter. A Cohort Indicator DataSet Definition will have associated indicators which will require underlying cohorts.

Cohort

Cohorts are the building blocks of an indicator report. They must be created before questions can be added to an indicator report. A cohort is a group of people who meet a certain condition or conditions. When one creates a cohort definition, such as number of pediatric patients on ARVs, the result is a list of patients who meet those criteria (pediatric and on ARV).

Composition Cohorts combine multiple cohorts. For instance, you could have a cohort of people who weigh less than 30 KG and a cohort of people who have been enrolled in the program called HIV Program. You could create a composition cohort which returns people who are in the HIV Program and less than 30 KG. You could also return people who are in the HIV Program but not less than 30 KG. How you combine cohorts depends on which operators you select (using AND, OR, NOT).

Indicator

An indicator requires a Cohort Definition (so the cohort definition must be created before the indicator). The reason? An indicator aggregates the members of a cohort. You can't aggregate people in a group until the group has been created.

The most common form of aggregation is counting. An indicator might count the cohort "Males" and return 521. An indicator is not limited to counting, however. It is possible to apply other aggregate functions such as median, mean, and fractions as well as more complex logic expressions. For instance, you could create an indicator for the mean cost of transport for a cohort of tuberculosis patients (providing you had already created the numeric cohort which has a question representing the numeric concept for transportation cost and already had a cohort of tb patients).

Dimension

A dimension, like an indicator, is built from a Cohort Definition. A dimension is a filter that narrows the results of an indicator, removing the patients that don't meet the criteria of the dimension

For instance, the question "Number of male pediatric patients on a first line regimen" might be made up of an indicator that aggregates a cohort of patients on first line regimens which has the dimension of age and gender applied to it.

One could create a composition cohort definition that has everything in the indicator (pediatric, male, and on first line) but dimensions are helpful for reuse. For instance, in a report with a question about female adult ARV patients and female child ARV patients and male adult ARV patients and male child ARV patients, it is possible to create four complicated indicators or, one could just create one indicator, on ARVs and then create the appropriate dimensions once each.

Filter

A filter is also built from a Cohort Definition. A filter narrows the results of every question in the indicator report. For instance, applying a filter using the Cohort Definition "Not Exited from Care", makes sure that no patient ends up in a report that is no longer a patient of the clinic.

Types of Reports

Row-Per-Domain Object Reports

Simple Row Per Patient Report

 
Here is where the description will go.
 

Indicator Reports

Period Indicator Report

A period indicator report is a good report for monthly or quarterly indicator reports. That is, reports that have a list of questions with a count of people who meet each question's criteria. These reports have parameters of Start Date, End Date, and Location which are entered as the report is run to constrain the results to given time period and location. see Indicator Report Tutorial for step-by-step instructions in building this report.
 

Indicator with Dimensions Report

Here is where the description will go.
 

Crosstab Indicator Report

Here is where the description will go.
 
 

Cohort Query Types By Domain

1. Concept: Concepts are defined and used to support strongly coded data throughout the system
2. Encounter: Contains the meta-data regarding health care providers interventions with a patient.

   Domain Object	Table	Field	Cohort Queries
   Encounter	encounter	encounter_type	Encounter Query
   Encounter	encounter	form_id	Encounter Query
   Encounter	encounter	location_id	Encounter Query
   Encounter	encounter	encounter_provider	FUTURE RELEASE?
   Encounter	encounter	encounter_datetime	Encounter Query
   Encounter	encounter	creator	Encounter Query
   Encounter	encounter	date_created	Encounter Query

1. Form: Essentially, the user interface description for the various components.
2. Observation: This is where the actual health care information is stored. There are many observations per Encounter.

   Domain Object	Table	Field	Cohort Queries
   Observation	obs	question	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	obs_datetime	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	location_id	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	encounter_id	Coded Observation Query, Date Observation Query, Numeric Observation Query, Text Observation Query
   Observation	obs	value_coded	Coded Observation Query
   Observation	obs	value_datetime	Date Observation Query
   Observation	obs	value_numeric	Numeric Observation Query
   Observation	obs	value_text	Text Observation Query
   Observation	obs	value_boolean	Numeric Observation Query (using value EQUALS 0 or 1)

1. Order: Things/actions that have been requested to occur.

   Domain Object	Table	Field	Cohort Queries
   Drug Order	drug_order	drug_inventory_id	Drugs Active Query, Drugs Started Query, Drugs Completed Query
   Drug Order	order	start_date	Drugs Active Query, Drugs Started Query
   Drug Order	order	auto_expire_date	Drugs Active Query, Drugs Completed Query
   Drug Order	order	discontinued_date	Drugs Active Query, Drugs Completed Query

   **NOTE--Drug Order Queries have been removed from the core module. For now, create custom definitions and evaluators for drug orders.  See module rwandareports for an example of this.

1. Patient: Basic information about patients in this system.
2. User: Basic information about the people that use this system.
3. Person: Basic information about person in the system.

   Domain Object	Table	Field	Cohort Queries
   Person	person	birthdate	Age Query, Birth and Death Query
   Person	person	gender	Gender Query
   Person Attribute	person_attribute	person_attribute_type	Person Attribute Query
   Relationship	relationship	relationship	FUTURE RELEASE?

1. Business: Non medical data used to administrate openmrs
2. Groups/Workflow: Workflows and Cohort data

   Patient Program	patient_program	program_id	Program Enrollment Query, In Program Query
   Patient Program	patient_program	date_enrolled	Program Enrollment Query, In Program Query
   Patient Program	patient_program	date_completed	Program Enrollment Query, In Program Query
   Patient State	patient_state	state	Patient State Query, In State Query
   Patient State	patient_state	start_date	Patient State Query, In State Query
   Patient State	patient_state	end_date	Patient State Query, In State Query

Cohort Query Types Not Domain Related

Static Query
SQL Query
Inverse Query

For Implementers

Step-By-Step Tutorials

Reporting UI Tutorial

Screen Casts

To help get you started with the Reporting Module, we have put together a few screen casts.

• How to define a new Simple Report
• How to define a new Cohort Query with a parameter
• How to define a new Cohort Indicator (and map it to the underlying Cohort Query)
• How to break indicators down by dimensions like sex and age

For Developers

Developing a Report Module

Getting Started with the basicreportmodule

Understanding and Extending the basicreportmodule

Custom Extension of the Reporting Framework

This release is our first stable release of the Reporting API. We have designed what we consider to be the basis for all of the APIs needed for the reporting. We feel very confident that the classes and interfaces designed will allow you to use and extend the API to:

• Define new cohort queries to allow users to calculate a custom metric that is specific to your organization.
• Define new data set definitions to expose data sets that are important to your users.
• Define new custom data set definitions that can be used in any implementation.
• Define a custom report based on your own data set definition.
• Build new reporting tools and user interfaces (e.g. a custom Reporting Dashboard for clinicians or an interactive data quality tool for data managers).
• Render reports in a standard format (e.g. SDMX-HD).
• Render reports in a proprietary format (e.g. .docx).
• Define custom logic rules to be used in indicators and cohort queries.
• Define new data quality rules to allow data managers to identify problems areas within your form entry process.

Using Parameters in SQL Cohort Definitions

Pre-defined parameters:startDate, endDate, and location.

Self-defined parameters: you can include the parameters in sql queries by using the notation of :parameterName. For example, you can set up enrollment date by using :enrollmentDate in your sql statement. Remember to choose the correct data type. In this example, the data type should be date instead of string. If not, the program will treat it as a string instead of date. You won't get a date picker for this field as well. Also, those parameters *cannot* be part of the SELECT statement. Instead, they should be used in the WHERE clause.

Designing Reports

Report Renderers

Report Templates

Excel Templates

How to Render a Report Into a Custom Excel File

Support

We welcome and encourage user comments, new feature requests, and bug reports. In fact, we can't continue development without your feedback. So please play around with the module and let us know what you think. We're aware of that this release of the Reporting Module does not do everything you want, but we're hoping that your feedback will help us to develop a module that does meet your needs. Again, this is an alpha release, so you should expect to encounter a few bumps along the way in the form of bugs, usability issues, performance bottlenecks, and missing features. If you find a bug or want to suggest a new feature, create a bug report, or send feedback please choose one of the options below. If you have other suggestions or feedback, please send an email to dev@openmrs.org.