This section explains how to set up CiviReports. It assumes a basic understanding of why you would want to use CiviReport, and describes the workflow for creating a report from a template through to making these reports available for users. It also assumes that the report you require can be achieved using the report templates supplied with CiviCRM.

If the report template you need does not exist you (or your developer) should refer to the Custom Reports chapter in the Extensions section of the Developer Guide for information about creating new templates.

Report templates

Report templates are general reports that can be further customised to create specific report instances. These report instances can then be made available to users.

The Create report from templates page lists all available report templates and is found in the Reports menu. The templates are grouped by component, and each has a brief description of its intended scenario. If there are already report instances for a given template, you'll see a link to view Existing Reports.


Clicking on the report template name will bring up a screen where the report can be configured.

There are two steps to configuring a report:

  1. Select your report criteria: decide what information will be displayed in the report.
  2. Define the report settings: choose a title, set permissions and add it to a menu. 

Select report criteria

There are three types of report criteria:

  • Display Columns
  • Group by Columns
  • Filters

The options available for these criteria change from report to report. General principles for the different types of report criteria are outlined  below. 

Display Columns

These check boxes allow you to select the data to be displayed for each record in your report. In most reports, at least one display column is required and cannot be unselected. For example, in the Top Donors report, showing the total amount donated is required. In the Constituent Detail report, showing the contact name is required.

Group by Columns

This is not available in all reports, but it is useful when creating a report which summarises data, rather than displaying each individual row, and for reports that compare different types of data.

The report shown below compares donations per quarter in 2009.


You can specify more than one grouping criteria. When you do this, groupings will be nested based on both groupings. Not all groupings or combinations of groupings will make sense for your data. You may need to spend time experimenting with Group By Columns to become familiar with this functionality.

Note that some Groups By Columns interact with Display Columns and can't be selected at the same time. The system will warn you if you try to make an invalid selection.


Set Filters

Filters are the main way to specify the records that you want to include in the report. For example, running the Membership Detail report without choosing any filters will show you all membership records. You could then filter the report to show all members of a specific membership type who joined last year.

The Date Range Filter

Most reports will have a date range filter. This can be configured in two ways:

  • by using an absolute date range, e.g. "1st Jan 2010" to "31 July 2010"
  • by using a relative date range, e.g. "Previous Year".


Relative date ranges are very useful for reports that you want to run on an ongoing basis.

  • This year gives all records from the start of the current year.
  • Previous year gives all records from the previous year.
  • Earlier year gives all records excluding this year.
  • Ending year gives all records between one year from today's date, and today (really useful!).

The Ending date ranges are particularly useful when used in combination with Group By Columns. Combining Ending Year with Group By Month gives a report that summarises data by month for the previous 12 months.

The report below shows the total amount of contributions received in the past 12 months, as well as each month's total.  past_12_months_income

Once you have selected your report criteria, click Preview Report. If the report displayed isn't exactly what you wanted, open the Report Criteria section at the top of the screen to modify your criteria. You may need to make several modifications before you achieve the report you want.

Report settings 

Once you are happy with the report criteria you have entered into the template, save it as a report instance so that it is available to use again.

  1. In the Create Report section of the template, give your report a title and description that will help other people understand its usage, for example, "Student members joined so far this year".
  2. You can optionally create a report header and footer in HTML. The header and footer will be displayed at the beginning and end of any PDF or downloaded versions of the report. This can be used to personalise your reports with your organisation's logo and to other useful information.
  3. If you wish to have the report emailed to yourself or someone else on a regular basis, fill in the Subject, To and CC fields in the Email Delivery Settings. You can enter one or more email addresses in the To and CC fields; multiple email addresses should be separated by commas. See the information below about email settings.
  4. If you want to make this report available to other users through a menu item, check Include Report in Navigation Menu? and specify the parent menu and permissions. For example, if you would like it to appear in the Reports menu, select Reports as the "Parent Menu". Alternatively, you might want to add an event report to the event menu.
  5. You can set up permissions to view reports on a report-by-report basis. This allows you to simplify the user interface for junior users and set sensitive reports to be accessible only to certain users. 

    Drupal installations only: the ability to edit report criteria is a separate permission that can be configured globally in Drupal. Users with this permission will be able to edit report criteria; users without this permission will be able to view reports but not edit the criteria. 

  6. Checking the box Available for Dashboard? to make the report available for users with appropriate permissions to add this report to their dashboard (this is done by clicking the Configure Your Dashboard button on the individual's dashboard).
  7. Click Create Report. It will now appear in the drop down list of reports under the Reports navigation menu. 

Email settings

As well as entering the email delivery settings described above, you will need to configure a cron job for each report that you want to send. The cron job runs a script in the civicrm/bin directory (CiviReportMail.php) which takes several parameters, including the ID of the report instance that you wish to send.

For example, if you want to send a Donor Report to your board members, you can configure a cron job with the ID of the particular report instance to email the report in HTML or PDF format. Refer to the sections on setting up email and Cron for more information.