Reports are accessed from the main navigation menu. Within the reporting tool, we have report templates and report instances:
- Report template: This defines the features of a report. This includes what fields are available to the report, options for grouping and filtering, display choices (tabular, bar/pie chart), and any other options available.
- Report instance: This selects and saves specific criteria and options you wish to view. For example, you may want to view a constituent summary report displaying all contacts in Group A. At a later time, you may create a second instance of the constituent summary report displaying all contacts in Group A and Group B.
A template will be reused many times as different criteria and display options are selected to meet specific needs. After generating a report, you may print it, export as .csv, or publish as .pdf. It is common to refer to a report instance as simply a report, but you should make sure that the distinction between the template and instance is clear.
CiviCRM is packaged with a number of report templates covering all the major data types and purposes you would expect. The construction of a template does require programming skill, though the structure, design, and method of registering them in the system are all designed for extensibility. If you create a report that may have value to a broader audience, or extend an existing one by programming in more features, consider contributing it back to the project for inclusion in core.
In contrast, the process of selecting criteria and options for a report instance are designed to be easily managed by non-technical staff.
While creating a new report or editing an existing one, you will be presented with Report criteria, Report settings, and a Preview of the report, each of which is contained in an expandable panel. In order to create a new report from a template, visit Reports | Create Report from Template and select your desired template. Select Reports | Report Listings to view all saved report instances.
Report Criteria will include options such as what fields may be included in the report, how they will be grouped, what filtering criteria may be applied, and how the results should be ordered. These settings are defined in the template code and will be specific to the nature and purpose of each template. For example, contribution reports will have contribution-related fields and options that the constituent report does not have. While creating and editing a report, most of your time will be spent adjusting these options to meet your needs.
For some of the more complicated reports, certain display fields and grouping options are dependent on each other, or are mutually exclusive of each other. For example, the donor report (summary) cannot be grouped by the received date if the contact name column is included. These limitations are generally due to the nature of the data being retrieved and grouped.
When adjusting the criteria for an existing report or setting criteria for a new report, you will often need to do some testing and tweaking before the report displays exactly as you desire. This is easily done by adjusting the criteria and clicking to preview the report, and then continuing to adjust and preview as needed.
The following screenshot displays the criteria options for the Constituent Report. Note that some reports support inclusion of custom data fields and filtering on them too, as seen with the Food Pantry fields in the following example:
Report Settings control the title of the report, the header and footer text (which will be displayed when the report is printed or exported as a PDF), e-mail settings, permissioning options, and navigation settings. Let's take a minute to understand each of the options in this panel, as they are common to all reports.
The title and description appears in the report listing page and should help users understand the criteria you configured for the specific report. When completing these fields, be specific about the purpose and criteria selected. For example, rather than using a generic title such as "Contribution Report", use a more descriptive title, such as "Donations Received, Year to Date".
The header and footer fields contain the HTML code that is inserted into reports when they are printed or published to PDF. The default content may be sufficient, but is very generic. You may wish, for example, to replace the<title> tag with the actual title of the report. You may also want to include images and CSS styles to customize the look of your report. You do need to have at least a basic understanding of HTML in order to work with these fields. Be sure that your footer closes any tags that were opened in the header (such as the<html> and<body> tags).
The report instances may be generated as a PDF file and e-mailed on a periodic basis. For example, you could have a report e-mailed to staff management every Monday that provides an overview of the recently received contributions. The membership services director could receive a report with upcoming lapsed memberships to make phone calls in order to solicit renewals of the same. Use the fields in this section to determine the recipients of the report (comma-separated lists) and the subject line of the report.
Note
Note that the e-mail reports functionality requires setup of a cron job to control the reports that should be e-mailed, and the delivery frequency. Simply completing the fields present within the report settings will not actually trigger the report delivery. The cron job should invoke a URL using the following format (using wget or curl), where the instanceID value for your report is replaced with the corresponding report ID in your system:
- Drupal:
<yourwebsite>/sites/all/modules/civicrm/bin/CiviReportMail.php?instanceId=3&reset=1&sendmail=1&<name>=username&<pass>=password&<key>=sitekey - Joomla!:
<yourwebsite>/administrator/components/com_civicrm/civicrm/bin/CiviReportMail.php?instanceId=3&reset=1&sendmail=1&<name>=username&<pass>=password&<key>=sitekey
For a full discussion of cron jobs in CiviCRM, refer to Chapter 3.
After creating a new report, you may view it on the Reports Listing page under the main Reports menu item. This page will always display the complete list of report instances active on your system. Additionally, you may choose to add a report instance to the navigation menu in a specified location. This ability is not restricted to the Reports menu item. For example, if you create a standard bookkeeping report that displays contributions received over the previous seven days, you can add that to the Contributions menu item.
Under the Other settings section of Report Settings, click on the checkbox and select the parent menu item your report should fall under. Leave the parent menu field empty (set to Select ) if you want the report added as a top-level menu item.
Drupal users may restrict a report to certain permission(s) using the next field in the display. For example, you may decide that your contribution-related reports should not be accessible to the data entry staff who would have no need to review potentially sensitive financial data.
The last option in this section provides the ability to enable the report to be included in the CiviCRM home page dashboard. Recall that when you first enter CiviCRM, you are presented with a dashboard page which displays a number of reports. The dashboard is fully configurable on a user-basis, meaning each user may choose different reports to include on that display. CiviCRM includes several special reports that are available as dashlets, and you may enable any other report created through the reports tool to be a dashlet. Very wide reports generally do not make good dashlets.
Note that enabling a report as a dashlet does not automatically include it in your dashboard—it simply makes it available as an option. It is up to each user to configure their dashboard as they desire.
The following screenshot is a sample Report Settings panel:
While working with reports, you will typically do one of the following:
- Review an existing report instance
- Review and modify an existing report instance on a temporary basis
- Review and modify an existing report instance, choosing to update the saved report with your new criteria and settings
- Create a new report from a template
As mentioned earlier, you may visit Reports | Reports Listing to see a list of all the existing saved report instances, or if available, select your report from the appropriate menu item. Note that not all reports will necessarily be found on the Reports menu, as menu assignment happens on an individual-report basis. If you are working with an existing report and alter any of the criteria or settings, a button entitled Update Report will be displayed.
Understand that clicking this button will save your settings to the report instance you are currently working with. Be sure you intend to do this, as it may alter the original intent of the report and affect other users. If you are only altering the criteria for temporary use, do not update the report; simply choose to preview the report, which allows you to view and take action on the report without saving it.
Tip
Depending on how you have configured CiviCRM, you may have already noticed that certain report types are not visible in your system. CiviCRM categorizes reports according to the component they work with, and will only display available reports for those components that you have enabled. For example, if you are not using the Membership component, you will not see any reports that display membership records.
You create a new report instance by going to Reports | Create Reports from Templates or Administer | CiviReport | Create Reports from Templates. From this tool, you select the report template that will generate the report, choose your criteria and options, and name the report. Once it is named and saved, it can be retrieved and your criteria and options will be preserved.
When creating a new report, you must first select your desired criteria and preview the report before you are given the additional report settings options. This is done to ensure you have valid criteria before saving the report.
As noted earlier, completed reports may be printed, published as a PDF, or exported as a CSV file. Some reports may be displayed in graphical format, such as a bar or pie chart. Constituent reports may have the option of adding the resulting contacts to a group.
Note
You may run into difficulties printing very long reports as a PDF file. The PDF generation engine is very resource-intensive. Depending on the quality of your hosting environment, you may experience server timeouts while creating large PDF files. If you find this happening, consider restricting your criteria to generate smaller subsets of your report for PDF generation, or consider upgrading your hosting environment to a more robust solution.
CiviCRM ships with over 25 report templates covering everything from constituent lists, bookkeeping reports, event participation, memberships, and case review. The following list, organized by CiviCRM component, provides a brief description of each template available at the time of writing this book.
Note
Note that new report templates are continuously added to the system; review the list on the Create Reports from Templates page for a description of reports available with your current version.
The contact report templates are as follows:
- Constituent Report (Summary): Provides a list of address and contact information for constituent records.
- Constituent Report (Detail): Provides contact-related information on contributions, memberships, events, and activities.
- Activity Report: Provides a list of constituent activity, including activity statistics for one or all contacts during a given date range (required).
- Walk/Phone List Report: A basic contact report with layout options designed for use in a phone bank or as a walk list. This report has additional use with the CiviEngage toolset. Originally designed as a Drupal module geared toward political campaign support, CiviCampaign and elements of CiviEngage will be included in core CiviCRM as part of v3.3.
- Current Employer Report: Provides a basic report detailing contacts in an employer/employee relationship. The report includes details about the relationships, such as the relationship start date (employed since).
- Relationship Report: Filters constituents by relationship type for either side of the relationship, and by groups, tags, and address fields.
- Database Log Report: A log of contact and activity records created or updated in a given date range (changelog data).
- Activity Report (Summary): Shows activity statistics by type/date, filtered by status or priority.
The contribution report templates are as follows:
- Donor Report (Summary): Shows contribution statistics by month/week/year, country/state, and type.
- Donor Report (Detail): Lists detailed contribution(s) for one/all contacts. Contribution summary report points to this report for specific details.
- Donation Summary Report (Repeat): Given two date ranges, shows contacts (and their contributions) who contributed in both the date ranges with percentage increase/decrease.
- Donation Summary Report (Organization): Displays a detailed contribution report for organization relationships with contributors. This includes the contribution record from an employee of some organization or from that organization itself.
- Donation Summary Report (Household): Provides a detailed report of contributions made by contributors (or the household itself) who have a relationship with the household. For example, a contributor is the head of household for some households, or is a member of the household.
- Top Donors Report: Provides a list of the top donors during a time period you define. You can include as many donors as you want (for example, top 100 of your donors).
- SYBUNT Report: "SYBUNT" stands for "Some year(s) but not this year". It provides a list of constituents who donated at some time in the history of your organization, but did not donate during the time period you specify.
- LYBUNT Report: "LYBUNT" stands for "Last year but not this year". It provides a list of constituents who donated last year, but did not donate during the time period you specify as the current year.
- Soft Credit Report: Provides soft credit details. Contacts may be manually marked for soft credit when the contribution record is created, or they may be automatically marked for the same, if the contribution originated through their personal campaign page.
- Bookkeeping Transactions Report: Provides contribution details geared toward regular reporting needs of bookkeepers.
The member report templates are as follows:
- Membership Report (Summary): Provides a summary of memberships by type and join date.
- Membership Report (Detail): Provides a list of members along with their membership status and membership details (join date, start date, and end date).
- Membership Report (Lapsed): Provides a list of memberships that have lapsed, or will lapse before the date you specify.
The event report templates are as follows:
- Event Participant Report (List): Provides lists of participants for an event.
- Event Income Report (Summary): Provides an overview of event income. You can include key information such as event ID, registration, attendance, and income generated to help you determine the success of an event.
- Event Income Report (Detail): Helps you analyze the income generated by an event. The report can include details by participant type, status, and payment method.
- Participant list Count Report: Shows the participant list with participant count.
- Income Count Summary Report: Shows the income summary of events with participant count.
The pledge report templates are as follows:
- Pledge Report: Displays pledge details filtered by date, amount, or status.
- Pledged But not Paid Report: Displays contacts who have pledged, but have outstanding or overdue payments.
The case report templates are as follows:
- Case Summary Report: Provides a summary of cases and their duration by date range, status, staff member and/or case role.
- Case Time Spent Report: Aggregates the time spent on case and/or non-case activities by activity type and contact.
- Contact Demographics Report: Displays demographic breakdown for case clients (and/or non-case contacts) in your database. It also includes custom contact fields.
The grant report templates are as follows:
- Grant Report: Generates report filterable by any of the grant data fields, including date range options.
Tip
A few report templates come in a disabled state. Visit Administer | CiviReport | Manage Templates to view and manage the status of report templates registered in your system.
Note
FPAGM staff members deal with several levels of leadership and key stakeholders who expect to receive reports on a regular basis. This includes the Executive Director, who is concerned with membership numbers and total donations, the Marketing Committee chair, who requires monthly membership status reports, and the Development Committee Chair, who wants to see total contributions of major donors over specified periods of time.
During system configuration, for each requested report, they review the list of templates and select and configure the one they believe will be most appropriate for their needs. Since the Executive Director has much on his/her plate, he/she look for reports that support bar and pie charts, as it provides a visual snapshot of the organization's activity that can be interpreted quickly.
The Marketing Committee chair wants to receive reports on a monthly basis. The staff members use the Membership Report (Summary) template to construct a report that breaks down membership by type, grouped by month, and displays data for the previous 12 months. The e-mail settings are configured and a cron job is set up to have this report e-mailed to the chairperson on the last day of the month, freeing staff from the responsibility of generating and sending the report.
Likewise, a "Top Donors" report is constructed, displaying the activity for the previous six months. Since this report is only provided as requested, staff members save it to the Contributions menu for easy access.
Though the reports that ship with CiviCRM seek to anticipate the bulk of your potential reporting needs, it is possible that you may have needs not addressed by existing report templates.
While it is beyond the scope of this book to delve into specific details regarding the development of new report templates, it is important to note that the report tools anticipate these needs. The code to build templates is very self-contained, modularized, and somewhat more accessible to beginner programmers than other areas of the software. You still need some familiarity with PHP and the MySQL database in order to build your own report template, but you may find it easier to work with than other areas of the CiviCRM codebase.
If you are interested in exploring this further, visit the following online documentation for guidance on customizing or creating a template: http://wiki.civicrm.org/confluence/display/CRMDOC/Custom+Reports+(How+to).