Create iReport Templates with Subreports
| How To |
|---|
Contents
Sub-Reports
Sub-report is reports 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 sub-report 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 6 basic steps to create a report with sub-reports:
- Step 1 – Create the Main report
- Step 2 – Add Sub-report to the Main report
- Step 3 – Add Parameter to the Sub-report
- Step 4 – Define Report Query for the Sub-report
- Step 5 – Add Sub-report Parameter to the Main report
- Step 6 – Repeat Step 2-5 for additional Sub-reports
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?
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 Sub-report to the Main report
A Sub-report is a report within a report. As mentioned earlier, a sub-report should be created with the IMSMA Item determined as the secondary data of the report. Below is the instructions to create a sub-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 “Activity” should be the data source for the sub-report. Click Next.
- Select the attributes to be included in your sub-report. 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 Sub-report
To connect a sub-report to the Main report, we need to create a parameter for passing the identification (guid) of the primary IMSMA Item between the sub-report and the main report. Below is the instructions to create the parameter you need for the sub-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.
- 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 Sub-report
The next step is to create a report query for the sub-report 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. 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 limited objects. For example links.toGuid="$P{ItemGUID}". See the table below for other combinations of Report Query filters to use on subreports.
- Click OK. :The Report query window closes.
- Save the the subreport.
| Main Report | Subreport can be | Value to Pass to Subreport | Report Query | Header text |
|---|---|---|---|---|
| Location | Any Item with a Location | location guid | location.guid = "$P{ItemGUID}" | Example |
| Land, Activity, Accident, Victim, Assistance, Education, QM, Location | Any linked Item | Item guid (e.g. Land guid) | links.toGuid="$P{ItemGUID}" | Example |
| Activity | Impact survey, Interviewee, or Vegetation removal | Activity guid | hazreduc.guid = "$P{ItemGUID}" | Relationship is defined as “New” to an activity during the reconciliation. |
| Interviewee | Question | interviewee guid | interviewee.guid = “$P{ItemGUID}” | Relationship persisted automatically when Questions are entered for each Interviewee at Data Entry Form. |
| Task | Work Item | Task guid | task.guid = "$P{ItemGUID}" | Relationship is defined when adding a new Work Item to a Task at the Task Editor Window. |
| Example | Example | Example | Example | Example |
Step 5 – Add Subreport Parameter to Main Report
We created a parameter on the sub-report to connect to the Main report in Step 4, 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}.
-
Select the field to include in the parameter
-
- Click OK and close Subreport properties windows.
Step 6 – Repeat Step 2-5 for additional sub-reports.
You can have multiple sub-reports in one Main report. To add more sub-reports to the Main report, just repeat Step 2 to Step 5.
Once you have all the sub-reports created for your Main report, you can compile and run your Main report.
Various Kinds of Subreports
This section discusses relationships between Items in IMSMA and also provides instructions on how to create a specific report/sub-reports. The reports discussed so far in this training module have been based on a single data source. In this part of the training module, you will learn to create more complex reports that reference multiple data sources. Some items are dependent on the existence of another item. This type of relationship is referred to as a direct relationship. For example, an accident, land, activity, education, QM, or victim has a direct relationship to the location to which it is associated. The accident, land, activity, education, QM, or victim cannot exist unless it is associated with a location. This direct relationship is enforced in IMSMA via the reconciliation process.</p>
Figure 11. Location and item records directly associated with it
Direct relationships also exist when subsets of data are contained within an item. For example, an education may have education details such as the education type, total audience, and percentage of women and men. The education details data requires the education to exist.
The following sections will describe the process for creating reports on items that have a direct relationship between them.
Location and Associated Items
A report of locations and associated items requires you to create an iReport sub-report. A sub-report is a report that is contained within another report. A report on locations and its associated item records will require you to create a report and a sub-report. The main report will contain the data for the location. For each associated item that you would like to include, you will need to create a sub-report.
Figure 12. Location and associated item records
All records in IMSMA have a guid. A guid is a unique value that identifies the record in the IMSMA database. Because the guid is lengthy and comprised of alphanumeric characters, it is typically not a useful value to display in a report. However, the guid is necessary in determining which item records have a direct relationship.
All accidents, land, activities, educations, QMs, and victims are associated with a single location. The information about the location to which an item record is associated is stored in the location_guid field of the item table and corresponds to the location_guid of the location to which it is associated (Figure 13).
Figure 13. location_guid
The location_guid field in the item table contains the guid of the location to which the item record is associated. Figure 14 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
Items with Data Subsets
Certain items 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. The education details data requires the education to exist. Table 3. Parent/child relationships lists the items and the data subsets that depend on them.
| Table 3. Parent/child relationships | |
| Parent item | Child item(s) which require the parent item |
| Activity | Impact survey
Interviewee Organisation Question Vegetation removal |
| Location | Accident
Land Activity Education QM Victim |
| Education | Education details |
| Victim | Received Education |
The process for creating a report on a parent item and its children is similar to the process for creating a report on locations and their associated items. The key difference is that the main report will contain the attributes of the parent item. The sub-report will contain the attributes for the child item. For example, if you were trying to create a report of educations and their associated education details, the main report would contain the attributes for education and the sub-report would contain the attributes for education details.
Reports on Linked Items
Part 4 of this training module discussed direct relationships—relationships where the parent item must exist in order for the child item to exist. In this part of the training, you will learn about linked relationships. Linked relationships are optional relationships which may exist between items. Unlike direct relationships that are enforced during the IMSMA reconciliation process, links are optional. Accidents, land, activities, educations, and QMs 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.
Figure 21. Direct relationships vs. Links
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 direct 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.
If you would like to report on different items that linked to the item in the main report, you may create a new sub-report for each linked item. For example, to create a report of land and the accidents and activities that are linked to those land, you would create the main report on land. This report would then contain a sub-report to list linked accidents, and another sub-report to list linked activities.