Report Builder

Report Builder Overview

The report builder is a tool for CommCareHQ users to build basic web-based reports based on the data collected in their project's applications. Unlike CommCare's Pre-Configured Reports, the reports built with this tool are specifically tailored to data collected in your project and can be configured by anyone with access to the reports section of CommCareHQ.

There are three types:

Report Type


Report Type



This is a table with a basic list of data (either a list of forms or cases)


This is a report that contains summarized data based on a chosen case property or form question (i.e. data aggregated by mobile worker or by region).

You can add a bar or pie chart to this report.


This will allow you to display a list of cases or forms and plot their location on a map.

General Steps to Building a Report

Select a Data Source

Go to the Reports tab in CommCareHQ and choose + Create new report (if you do not see this option, make sure that your subscription is active in Project Settings).

Screenshot 2024-03-05 at 7.36.23 AM.png

Choose your report's name and data source.  The name can be anything you want - but should be descriptive since this is the name that will show up on CommCareHQ on the list of reports. Each report is based on either a case or a form data source. Select the general type of data you want to use (form or case) and then drill down to the exact case type or specific form that you want to use as the basis for your report. 

Configure the report

You can now configure your report and get a live preview of your report! The relevant configurations areas are highlighted below:

Report Name and Description:

Set a name and description for the report by clicking the Edit pencil next to each text field.

Report Type

Choose the type of report you'd like (a list of records, a summary or a map). 


Add indicators to your report by choosing a case property or form question and then clicking on the blue + button.   Drag and drop properties to re-order them. 

If you have a summary report, you will also see a "Format" column.  The options here are:

  • Group By: This will summarize that particular property (creating one row for each unique value of that property). 

  • Count Per Choice: This will create one column for each unique value of the property.  For example, if you have a Yes / No question, this will create two columns, a Yes column and a No column.  Each column will contain the number of forms / cases that had that particular answer.

  • Sum: This will sum up the answers for that column

  • Average: This will average the answers for that column

User Filters

This section will let you add filters that can be used when viewing the report. Choose "+ Add User Filter" and then choose the column you want to filter on.  The format column will control how the filter appears - Choice filters will let you choose one of the possible values of the property, Date filters will let you choose a date range. 

Default Filters

Default filters are always applied to the report (so that users don't need to manually apply the filters). For example, you may add a default filter so that only open cases are shown in the report.  The Date format will let you automatically filter the report to default date ranges (i.e. the previous month or the last 7 days). 

Adding Charts

If you are building a Summary report, you can also add a chart.  The chart types are "Bar" and "Pie".  Bar charts will show one bar per each column that is summed or averaged.  Pie charts will show the breakdown of the first column that is summed or averaged.


If you are building a Map report, you also need to choose a location field.  This is the field that contains the GPS location that you want to plot (the GPS location can be captured manually in a form or through Automatic GPS Capture.)

4 Test out the report

Click "View Report" to actually view and use the report. 

You can always edit the report by clicking on the blue edit button on the top right of the report.

Notes and Limitations

  • Most Report Builder reports can be saved and emailed like regular reports

    • Chart type reports will not send the pie chart or bar chart in the email

  • It is not currently possible to directly export reports; however if you save and set them to be emailed reports then you can include a Excel version in the emailed reports

  • Multiple languages are not currently supported in report builder reports

  • Multiple choice lookup table question types are not supported in report builder reports

  • Organizations/Location Hierarchy based search is not supported. 

  • Location restricted web users cannot access report builder reports.

  • When saving reports, the URL (which includes filters) must be less than 8000 characters. If not, a request to view the report will result in a 414 error "URI too large" response.

  • Report builder maximum column limit is 40.

The property of type Case Owner(Location) in the report builder dropdown allows us to mark data as owned by a location which we can then use to filter by location.

Report builder reports that are location safe

To create a report that is location safe, you must add this column as a filter to the report.

Known limitations

  1. Cases will need to be owned by locations for this to work (e.g. if it they owned by users or groups functionality will not apply)

  2. Form-based reports are not supported.