Create iReport Templates with Subreports

Creating Subreports

A Subreport is a report within a report; thus, providing a way to generate a report that includes data on the target IMSMA Item as well as data on other IMSMA Items that are associated to the target IMSMA Item. Generally a subreport is used in a situation where you have one or more sets of data relating to a single IMSMA item. A common use case would be a Location report with multiple details bands of different IMSMA items (Land, Activity, Accident, Victim, Education, and QM).

Regardless of what IMSMA data you’re including in your report and sub-reports, there are 5 basic steps to create a report with subreports:

Step 1 – Create the Main report

Step 2 – Add Sub-report to the Main report

Step 3 – Add Parameter to the Subreport

Step 4 – Define Report Query for the Subreport

Step 5 – Add Subreport Parameter to the Main report

Step 1 – Create the Main Report

Before creating the main report, you will need to determine what data to be included on your report. For example, if you are creating a report about Land with all the Progress Report data, then the target IMSMA item for your main report should be Land and the target data for your sub-report should be Activity assuming that Progress Reports are entered into the system as Activity. Below is a list of questions and things to be considered when designing a report.

What are all the data to be included on the report?
What is the target IMSMA Item for the Main report? This is the primary data of your report.
What is the target IMSMA Item for the sub-reports? This is the secondary data of your report.
Determine the relationship between the primary data and the secondary data. How did they get reconciled to one another? How are they linked?

The Main report should be created with the IMSMA item determined to be the primary data of your report. The Main report is just a basic report and can be created using the steps provided in the Create a Basic i-Report Template section.

Step 2 – Add Subreport to the Main report

Once the main report has been created you can add a subreport to the main report. The intent of the subreport is to bring data from a different but related datasource into the main report. For example, you could include Activity data on a report about Land. Below are the instructions to create a subreport:

On the main report, from the Palette pane, select Subreport and drag it to the desired band on the iReport template (normally this is the Detail band.
Subreport Palette
Release the button and the window below displays.
Click Next to define a new sub-report unless you have an existing report that you would like to use for sub-report.
Select the desired iReport Template to apply (Blank is recommended).
Select from the Connection/Data Source list. This should be the IMSMA item determined as the secondary data of your report. For example, if you are creating a report about Land with Progress Reports, then “Hazard Reduction” should be the data source for the sub-report. Click Next.
Select the attributes to be included in your sub-report. Click Next.
Select the fields to group by. This step is not required. Click Next.
Enter a name for the sub-report or use the default. Choose Next.
Select Use the same connection use to fill master report. Click Finish.
The sub-report displays.

Step 3 – Add Parameter to Subreport

To connect a subreport to the Main report, we next need to create a parameter for passing the identification (guid) of the primary IMSMA Item between the subreport and the main report. In the Report Inspector on the subreport, add a Parameter to hold the guid of the IMSMA Item on the main report. It is recommended to add a fairly generic parameter name such as ItemGUID so that the subreport can be more easily re-used.

From the Report Inspector, right click on the Parameter tree and choose Add Parameter.
In the Properties pane, enter a parameter name (e.g. ItemGUID} and edit any other properties. Normally it is not required to edit anything other than the name.
Once the parameter is added it will be available in the Report Inspector and can be referenced as $P{parametername}. For example:

$P{ItemGUID}

Step 4 – Define Report Query for Subreport

The next step is to create a report query for the subreport you just created in Step 3 to define how the IMSMA item on the Main report is related to the IMSMA item on the subreport. Typically the subreport Report Query will receive the guid from the main report via the parameter created in Step 4 and then use it to limit items in the subreport to those linked to the main report. Below is the instructions on how to define the Report Query:

Open the Report Query window.
From the Report query window, select ImsmaQuery from the Query language list.
Enter a Report Query filter using the parameter defined above to limit the objects according to the main report object. The most common Report Query filter would be to filter to only linked objects. For example links.toGuid="$P{ItemGUID}". In this step, the Report Query tells the subreport to return only rows that are linked to the guid of the the item in the main report via the link table. Other combinations of Report Query filters can be used on subreports beyond the link table. These are documented in the Possible Subreport Relationships section below.
Click OK. The Report query window closes.
Save the subreport.

Step 5 – Add Subreport Parameter to Main Report

We created a parameter on the sub-report to connect to the Main report in Step 3, now we need to create a parameter on the Main report as well. Below is the instructions to create the parameter you need for the Main report:

Make sure you are at the Main report by selecting the name of the Main report from the tabs at the top of the iReport Designer canvas pane.
Select the subreport box within the Main report.

Select the Subreport on the main report
On the Properties pane for the Subreport, select the Parameter selector.

Subreport properties
Add a parameter and give it a name (e.g. ItemGUID)

Add a parameter
For the value expression, select the appropriate field to include in the parameter. Normally this is $F{guid} but other choices are available.

Select the field to include in the parameter
Click OK and close Subreport Parameters window.

Kinds of Subreports

There are three main kinds of relationships in IMSMA on which subreports can be generated from IMSMA data. These are:

Location relationship
Link relationship
Geospatial relationship
Other relationship

Location relationship subreports

Because each of the main items in IMSMA^NG, Accident, Activity, Assistance, Education, Land, QM, and Victim, must be reconciled to a Location during the data entry phase, each of these objects has a relationship with Location and can thus be a subreport on a Location main report. Since all accidents, land, activities, educations, QMs, assistances, and victims are associated with a single location each record knows what location it is related to based on the location guid field. When creating a report where the main report is a Location and the subreport is one of the associated objects the Location's guid is passed to the subreport in a parameter and the subreport can use a special ImsmaQuery language syntax to limit the subreport data to those associated with the main report's location:

location.guid = "$P{parametername}"

The location guid field in the subreport item table contains the guid of the location to which the item record is associated. The figure below shows an example of a location and the accident and land that are associated to the location. Notice that the location_guid value (1234-1234) in the accident and land are identical to the location_guid of the location.

Figure 14. location_guid example

To create a subreport using the Location relationship:

From the main "Location" report, pass the location guid to the subreport in a parameter (e.g. in a parameter called ItemGUID).
Create a parameter on the subreport with the same name as in #1.
In the subreport for the related item (e.g. a Victim) use the parameter in the following ImsmaQuery language syntax

location.guid="$P{parametername}"

This has the effect of limiting the subreport records to only those records that are associated to the location from the main report.

Link relationship subreports

In addition to the Location relationship, the main items in IMSMA^NG can also be linked with one another during the reconciliation process. This is how, for example, Activities are linked with Land in the IMSMA^NG database. Accidents, land, activities, educations, assistances, QMs, and victims may be related to one another via links. For example, a victim may be associated to an accident in a particular land. If these relationships are known, IMSMA users may define these links while reconciling the Data Entry Form. This special relationship can also be modeled in iReport using a report and subreport

The process for creating a report on an item and its linked items is similar to the process for creating a report on items with a Location relationship. The item in the main report is the primary item for which you would like to find linked items. The sub-report would return the records for the particular item that is linked to the primary item. The key difference is the query used in the sub-report.

To create a subreport using the link relationship:

From the main report, pass the guid of the main report object to the subreport in a parameter (e.g. pass an accident's guid in a parameter called ItemGUID).
Create a parameter on the subreport with the same name as in #1.
In the subreport for the related item (e.g. a Victim) use the parameter in the following ImsmaQuery language syntax

links.toGuid="$P{parametername}"

This has the effect of limiting the subreport records to only those records that have a link to the guid or object passed from the main report.

Geospatial relationships

In addition to Location and Link relationships, many objects in IMSMA can store geospatial/geographic information (i.e. point/polygon information). This relationship with the geospatial data can be modeled in a report/subreport relationship for any item that has geospatial information associated with it. To include point/polygon information on an object's main report, follow 3 basic steps:

Step 1: Create a main report for an object with geospatial info
Step 2: Create a GeospatialInfo subreport on the main report
Step 3: Create a Geopoint subreport on the GeospatialInfo report

Step 1: Create a main report for an object with geospatial info

Create a main report with an object that has geospatial information (e.g. Land).
Ensure that the geospatialInfos field is added to the main report.

Step 2: Create a GeospatialInfo subreport on the main report

On the main report, add a subreport using the GeospatialInfo datasource
Pass the geospatialInfos field to the subreport in a parameter (e.g. GeospatialInfoList). Note: instead of passing the $F{guid} field to the parameter, the parameter value should be $F{geospatialInfos}
In the GeospatialInfo subreport use the parameter in the following ImsmaQuery language syntax

guid IN $P{parametername}

Step 3: Create a Geopoint subreport on the GeospatialInfo report

On the Geospatialinfo subreport, add a subreport using the Geopoint datasource
Pass the guid field to the subreport in a parameter (e.g. GeospatialGUID). Note: Pass the $F{guid} field NOT the $F{geospatialInfos} value.
In the Geopoint subreport use the parameter in the following ImsmaQuery language syntax

geospatialinfoguid IN $P{parametername}

This has the effect of limiting the Geospatial records to only those records whose guid is linked to the geospatialinfo of the main report.

Other subreport relationships

Certain items in IMSMA^NG have subsets of data that are contained within them. For example, an education may have education details such as the education type, total audience, and percentage of women and men. Examples of other subreport relationships include:

Other subreport relationships
Parent item	Child item(s)
Activity	Activity Device Impact survey Interviewee Question
Education	Education details
Victim	Received Education Needs Assessment Cause
Land	Land Device
Accident	Accident Device
Assistance	Assistance Given
Task	Work Item

The process for creating a report on a parent item and its children is the same as any other report/subreport relationship.

Example Subreport Relationships

Main Report	Subreport can be	Value to Pass to Subreport	Report Query
Location	Any Item with a Location	location guid	location.guid = "$P{ItemGUID}"
Any linked item	Any linked Item	Item guid (e.g. Land guid)	links.toGuid="$P{ItemGUID}"
Activity	Impact survey or Interviewee	Activity guid	hazreduc.guid = "$P{ItemGUID}"
Interviewee	Question	interviewee guid	interviewee.guid = “$P{ItemGUID}”
Task	Work Item	Task guid	task.guid = "$P{ItemGUID}"
Any Item with Geospatial information	GeospatialInfo	geoSpatialInfos	guid IN $P{GeospatialInfoList}
Geospatial Info	GeoPoint	GeospatialInfo guid	geospatialInfoGuid = "$P{ItemGUID}"
Any item with devices	Item Device (e.g. AccidentDevice)	Item guid (e.g. Accident guid)	accident.guid = "$P{ItemGUID}" hazard.guid = "$P{ItemGUID}"
MRE	MREDetail	MRE guid	mre.guid = "$P{ItemGUID}"
Victim	Needs Assessment	victim guid	victim.guid="$P{ItemGUID}"
Victim	Cause	victim guid	victim.guid="$P{ItemGUID}"
Assistance	Assistance Given	victimAssistance.guid	victimAssistance.guid="$P{ItemGUID}"
Task	Objective	SQL Field list of Objectives	guid IN ($P{SQLList})
Work Item	Linked Items (Activity, Education, QM, Assistance)	SQL Field list of Items	guid IN ($P{SQLList})