Subreport basics

A Subreport is a report that is executed inside of a another report. Subreports are always attached to bands and are executed and printed whenever the band will be printed.

Subreports can only be added as direct or indirect child to any the following root-level band types:

• "report-header"
• "report-footer"
• "group-header"
• "group-footer"
• "itemband"
• "nodata-band"

Pentaho-Reporting has two types of subreports. A banded subreport is attached to the root-level band itself and is always printed below the band to where it is attached. A inline subreport can be added to any band on any position and is printed at the given location.

Subreports added to the report-header, report-footer or nodata band will be executed once per lifetime of the parent report. If added to the group-header or group-footer, subreports will be executed for every instance of the group. Subreports added to the itemband will be executed as often as there are rows in the parent report's datasource.

Data-Processing

Whenever reports are executed, the reporting engine calls the data-factory of the report to retrieve the report's data-set. The data-factory receives the query-name and the current values of all declared parameters to allow the parametrization of the data-retrieval. If a subreport is attached to a band that is printed multiple times, the subreport will query the data-factory multiple times, each time with the current values of the master-report.

Master-Reports (= reports without a parent report) receive the values for the parameters that are passed into the data-factory from the declared set of report-parameters and report-properties.

Subreports read the parameter-values from the current data-row of the master-report. Subreport only import values for the columns declared as import parameters. Import parameters can be optionally aliased to avoid column-naming conflicts.

Parametrization strategies

Whenever multiple instances of a subreport are printed on a single parent report, the
data-factory needs additional information to return the correct dataset for the given instance of the subreport. This additional information must be passed to the subreport via parameters.

Usually a parent report's datasource contains a column with one or many foreign keys. Common cases for such keys are customer-numbers or invoice-numbers. Any information that allows the data-factory to identify a subreport instance during the report-processing can be used as key.

With SQL, MQL or MDX queries, the key almost always is used as a filter-argument in the query.

SELECT * FROM INVOICES WHERE INVOICE_NUMBER = ${INVOICE_NUMBER_PARAMETER}