Monday, July 6, 2009 - 15:36
Written by
Version 2.2.7 was released today with CiviReport ("the return") phase 1. This version includes fourteen report templates with coverage for contact data, activities, contributions, events and memberships. Folks in the community who have had a chance to preview the functionality have been quite excited - and we think this is a significant step forward for CiviCRM. First, a few concepts... CiviReport is delivered with a set of report templates. Each template covers a general reporting area - for example: Donor Report (Summary), LYBUNT (Last Year but not this Year), etc. Administrators can then create one or more report instances from a template - with specific display columns, filters and grouping rules. Users go to the CiviReport menu to see a list of report instances, and run the reports.   For example, your organization might need a report which summarizes donations year-to-date grouped by Country. You create this instance from the Donor Report (Summary) template. In the template, you set the Group by Column to be State / Province, and the Filter to be Receive Date = This Year. You can assign a specific title and description for this report - "Donations by State - Year to Date". Then click "Create Report" to save your report instance. (For Drupal and Standalone installs, you can also set a specific permission to access each report instance - for example I might require "access CiviContribute" permission for this report). To give folks a head start, we've included both the template and a sample report instance for each template in the release. You can start exploring on the demo by logging in (user = demo, password = demo), and running some of the report instances.


There's a lot of functionality included in this release. Here's some highlights:
  • Relative date ranges - You can configure a report instance with relative ranges, including This Year, Previous Year, This Month, This Quarter, etc.
  • Bar and Pie Charts - Most reports allow you to view the data in a table OR as a Bar chart or Pie chart.
  • Print (from HTML) and PDF formats - Reports to be viewed and printed in a print-friendly HTML format, or downloaded as a PDF file. You can customize report headers and footers (including adding organization logos, importing a customized CSS file, etc.).
  • CSV Export - Most reports allow you to export data as a CSV file for further manipulation in a spreadsheet application.
  • Add report results (contacts) to a group - Many reports include a button to "Add these Contacts to Group". This enables users to take various actions on the results (e.g. send email, create mailing labels) by navigating to that group. (I suspect we will extend this to include direct support for these other actions from the reports in phase 2).
  • Automated report delivery - You can configure reports to be delivered to one or more recipients via email (in the report "Settings" section). Your site admin will need to create and schedule a cron task to invoke the new CiviReportMail.php script. The Donor Report (Summary) on the demo is a good place to try most of these features. Here's an example of a Quarterly Contribution pie chart to whet your appetite: pie chart example


    Some tips on permissioning ... If you're running Drupal or Standalone, you'll see three new permissions for reporting:
    • administer Reports - Allows users to access report templates and create report instances from templates
    • access CiviReport - Gives access to the listing of report instances via the "CiviReport" menu. Listings are filtered by each users permissions. For example, users who have "access CiviReport" but do NOT have "access CiviContribute" will not see the sample Contribution reports in the listing (since they all require "access CiviContribute" in their settings).
    • access Report Criteria - Allows users to modify the display columns, filters and grouping criteria when running a report. You can provide a simple "run as configured" report interface for some users by NOT giving them this permission.

    Use It and Help Improve It

    Ok - so now for the "fine print" (caveats). First, we're calling this phase 1 because we wanted to get something out there that was useful - and then get feedback AND code contributions to flush out features and add / refine report templates. If the included report templates don't cover your organization's needs - they should provide decent examples to build additional templates from (and / or extend existing templates). Second, support for custom fields is very limited "out of the box". You can only report on contribution custom fields - and you need to enable this with by adding a setting to your civicrm.settings.php file:
    Finally, there's a lot of new code in the reporting component - and it has not been cycled through our normal alpha -> beta -> stable release sequence. This means there are almost certainly some bugs, and we'll be looking to folks out there who have lots of live and interesting data to help us find and squash them over the coming months.


    A big round of applause goes out to a number of people who helped make this release a reality:
    • The team at Web Access India for persistance in pushing to get reporting back on the roadmap
    • Tomasz Finc and the folks at Wikimedia Foundation who collaborated with us in the design and development process.
    • ...and Deepak Srivastava and Sunil Pawar on the core team who worked super hard on making this first implementation both useful and powerful!


Looks exciting! Can't wait to take it for a spin.


Why isn't it on by default ? is there a performance impact of using it?


Custom field support is in a "prototype" stage at this point. There are a number of issues with the implementation such that we ultimately decided it was best to hold off exposing to folks unless they were ok with / aware of these issues. The ones I'm aware of are:

a. Radio Buttons and Select fields result appear as value (not labels) in report results.
b. Multiselect field results include separator character and values (not labels).
c. If field labels are the same for multiple fields, then first field is hidden.
d. Group by with custom data fields gives duplicate entries in report results (summary reports).
e. Searchable custom fields are not available as filters.

The last 2 items are the most significant - but the others are "messy" as well. I don't have a timeframe on getting custom field support up to speed - might depend on sponsorship and / or contributed work from folks outside the core team who need this.

Custom field support is a huge "must-have" for us. I would be interested in discussing sponsoring some work around this. David, please contact me to discuss.

Nice work. Lots of features. Is there a "getting started" document somewhere?

So far the only documentation is this blog. It would be great it someone(s) would step up and take this material and flesh it out as a section in the documentation wiki :-)

The limitations around reporting have been my biggest gripe with CiviCRM for a while now. What good is information if you don't have flexible and easily usable ways of accessing, displaying and analyzing it.

This is a first step in the right direction.



when will 2.3 be ready for general use? i know it's dangerous to say - but ballpark? i have a client now who is needing the CiviReport functionality. I assume that the 2.3 version of CiviCRM would not require the use of BIRT, and would have certain reports or customized displays (that can be cut/pasted in spreadsheet) available?

Very exciting.

we released an early version of CiviReport with 13 reports or so with CiviCRM v2.2.7 approx 3-4 weeks ago