Report Splitting

For a video explanation, please check out our Dr. Jaspersoft Report Splitting session

Report splitting allows you to split the output of a single report executed by the JasperReports Server scheduler into several parts, which can be delivered individually to different destinations.

A common scenario for report splitting is to design a report that contains data for several entities (such as accounts, departments or divisions) and then run the report in the JasperReports Server scheduler with a separate output file for each entity.

Report splitting is based on report parts, which are traditionally created by Book reports.  Running a book report produces a generated report that is split into multiple parts, each consisting of several consecutive pages.  The JasperReports Server report viewer displays report parts as tabs that can be clicked to navigate to the first page of the part.

Version 8.2.0 introduces properties that can be set at the report part level to control the way the parts behave in different scenarios.  The properties used in JasperReports Server are:

• net.sf.jasperreports.print.part.visible to toggle the part visibility as a tab in the report viewer

• net.sf.jasperreports.print.part.split to trigger an output split in the report scheduler

• Arbitrary net.sf.jasperreports.print.part.* properties to use dynamic report job output attributes in the scheduler.

Also starting from version 8.2.0, report parts can be generated from band-based (non book) reports as well by setting properties on a report element to trigger the report part creation.  The net.sf.jasperreports.print.part.name property set on an element triggers a part creation starting with the page on which the element is placed and also provides a name for the part.  Additional part properties mentioned above can be set on the same element that triggers the part creation.

Band-based reports meant for report splitting need to meet a certain conditions imposed by the splitting requirement.  First of all the reports need to be paginated, with page breaks in the places where splitting is meant to occur.  That can be achieved for instance by grouping the data according to the splitting value and setting the isStartNewPage flag for the group.  Then, if the report displays a "Page i of n" text, it would normally need to be created in such a way that the current and total page numbers are relative to the report part and not to the entire report.  The isResetPageNumber group flag and group evaluation time for the text can be used for that in most cases.

For book reports the conditions mentioned above can be met easier given that pagination can be configured per individual book part.

Designing reports meant for splitting is made easy by Jaspersoft Studio, which provides a Report Splitting configuration dialog for report elements and parts.

Once a report has been designed for report splitting, executing it via the JasperReports Server scheduler will produce separate outputs for each report part that has the net.sf.jasperreports.print.part.split flag set.  Note that the conditions listed above still need to hold, which means that splitting will not apply to unpaginated report outputs.

Arbitrary net.sf.jasperreports.print.part.* properties set at the part level can be used to provide dynamic values for report job output attributes.  To do that, property placeholders of the form ${net.sf.jasperreports.print.part.*} need to be set as report job attributes; that can be done only for attributes having text inputs and not for attributes that use radio or combo boxes.  Part properties can be used for attributes that apply to individual job outputs, that is output name and repository location, output destinations and email notifications.  Job schedule, report parameters and job status cannot use part properties.