• 11 Nov 2026

How to Create Jaspersoft Subreports: A Step-by-Step Guide

Quick Summary

Jaspersoft subreports let you include one report inside another, making it easier to present related information from multiple datasets in a single report. For example, a customer report can display customer details in the main report and corresponding order information in a subreport.

Creating effective Jaspersoft subreports involves more than inserting a report element. You need to configure the subreport design, data source, parameters, report expression, and layout properties correctly.

This guide explains how to create Jaspersoft subreports in Jaspersoft Studio, with practical examples, parameter-mapping instructions, configuration tips, and troubleshooting solutions.

What Are Jaspersoft Subreports?

A Jaspersoft subreport is an independent report template embedded within another report, commonly called the main report or master report.

The main report controls when the subreport runs, supplies the required data source or database connection, and passes parameters to it. The subreport generates its content, which the main report incorporates into the final output.

For example, imagine an organization generating a customer activity report:

• Main report: Displays customer ID, name, and contact information.
• Subreport: Displays the orders associated with each customer.
• Parameter: Passes the customer ID from the main report to the subreport.

This creates a master-detail report in which each customer's details appear alongside their corresponding order records.

When Should You Use Jaspersoft Subreports?

Subreports are useful when a single report needs to combine different datasets or reusable report components.

Common use cases include:

Subreports can also be nested, allowing one subreport to contain another. However, design deeply nested or frequently executed subreports carefully because they can increase report-processing overhead.

How to Create Jaspersoft Subreports: Step-by-Step

Follow these steps to create a main report and embed a subreport using Jaspersoft Studio.

Step 1: Create the Main Report

Start by creating the parent report that will contain the subreport.

1. Open Jaspersoft Studio.
2. Select File → New → Jasper Report.
3. Choose a report template or a blank report.
4. Enter a report name and select the project location.
5. Configure the required data adapter or database connection.
6. Create the main report query and retrieve the fields needed for the report.

For this example, assume the main report retrieves customer information from a database.

SELECT customer_id, customer_name, email
FROM customers;

The main report should include the customer fields that you want to display.

Important: Identify the field that will connect the main report to the subreport. In this example, that field is customer_id.

Step 2: Create the Subreport

Create the subreport as a separate report template.

1. Select File → New → Jasper Report.
2. Choose the appropriate report template.
3. Enter a name, such as CustomerOrders.
4. Select the required data adapter.
5. Configure the report layout and required fields.

The subreport will retrieve order information associated with each customer.

For example, use the following SQL query:

SELECT order_id, order_date, total_amount
FROM orders
WHERE customer_id = $P{ParentCustomerID};

Here, ParentCustomerID is a parameter that will receive the customer ID from the main report.

Configure the subreport layout:

• Set the margins to zero if the design requires the subreport to fit closely within the parent report.
• Adjust the report width to fit the available space in the main report.
• Remove unused bands only when they are not needed for the intended output.
• Retain the Detail band if it contains the records that need to be displayed.
• Add column headers where necessary.

The subreport's dimensions should be planned around the parent report's available width and expected content.

Step 3: Configure Subreport Parameters

Parameters allow the main report to pass values to the subreport.

In this example, the main report passes the customer ID so that the subreport retrieves only that customer's orders.

In the subreport:

1. Open the Outline panel.
2. Right-click Parameters.
3. Select Create Parameter.
4. Enter the parameter name as ParentCustomerID.
5. Set its Java class to match the data type of the customer_id field.

Example parameter declaration:

<parameter name="ParentCustomerID"
           class="java.lang.String"/>

The example assumes customer_id is stored as a string. If the database field is an integer, use the corresponding Java type, such as java.lang.Integer.

Important: The parameter name and data type must match the value being passed from the main report. Parameter names are case-sensitive.

Step 4: Compile the Subreport

After designing the subreport, compile it to generate the .jasper file.

1. Save the subreport.
2. Right-click the subreport file in the Project Explorer.
3. Select the compilation option available in your Jaspersoft Studio version.
4. Verify that the compiled .jasper file is generated.

The two file types serve different purposes:

The parent report must be able to locate the compiled subreport at runtime. Keep the compiled file in the appropriate project or deployment location.

Step 5: Add the Subreport to the Main Report

Now embed the compiled subreport in the parent report.

1. Open the main report in Jaspersoft Studio.
2. Locate the Palette panel.
3. Find the Subreport element.
4. Drag and drop it into the appropriate band of the main report.
5. Use the subreport wizard to select the existing subreport, if available.
6. Configure the subreport expression to point to the compiled report.

For example, the expression may reference the compiled report by name:

"CustomerOrders.jasper"

The exact expression depends on where the compiled report is stored and how your application loads report resources.

Tip: A relative path can be useful when the parent and subreport are deployed together. Confirm that the path resolves correctly in the actual runtime environment, not just in the Studio workspace.

Step 6: Configure the Connection and Map Parameters

This is one of the most important steps in creating a working subreport.

The subreport needs access to the appropriate data source and must receive the parameter values from the main report.

A. Configure the connection or data source

If the main report uses a JDBC connection and the subreport should use the same connection, configure the subreport's Connection Expression:

$P{REPORT_CONNECTION}

This passes the JDBC connection used by the main report to the subreport.

Alternatively, use a Data Source Expression when the subreport should receive a JRDataSource object.

These are alternative approaches. Do not configure both expressions for the same subreport element.

B. Map the subreport parameter

In the subreport properties:

1. Open Parameters or Edit Parameters.
2. Add the parameter ParentCustomerID.
3. Set its expression to the corresponding customer ID field in the main report.

Example:

$F{customer_id}

The mapping should look like this:

When the main report processes a customer record, the subreport receives that record's customer ID and uses it in its SQL query.

Step 7: Configure Subreport Layout Properties

Correct layout configuration helps prevent blank spaces, overlapping elements, and incomplete content.

Review these important properties:

Recommended configuration checks:

• Set the subreport width to fit within the parent report.
• Allow sufficient height for the expected content.
• Use Float positioning when preceding elements can expand.
• Enable blank-space removal when an empty subreport should not leave a gap.
• Review overflow behavior when the subreport can contain multiple records or long content.

The available property names and options can vary between Jaspersoft Studio and JasperReports versions.

Step 8: Preview and Run the Main Report

Once the subreport is configured, preview the main report to validate the complete output.

1. Save the main report and subreport.
2. Compile the main report.
3. Open the Preview tab.
4. Execute the report using the required data adapter or connection.
5. Check whether the customer details and corresponding order records appear correctly.
6. Test multiple customer records, including customers with no matching orders.
7. Export the report to the required format, such as PDF or Excel, and inspect the output.

Check the following before deployment:

• Does the subreport load successfully?
• Are the correct customer IDs passed?
• Does the subreport return the expected order records?
• Is the layout consistent across pages?
• Are empty subreports handled correctly?
• Does the compiled subreport path work in the deployment environment?

Jaspersoft Subreport Example: Main Report and Subreport

Consider a customer reporting application that needs to display customer information and related order details.

Main report: Customer Details

SELECT customer_id, customer_name, email
FROM customers;

Subreport: Customer Orders

SELECT order_id, order_date, total_amount
FROM orders
WHERE customer_id = $P{ParentCustomerID};

Subreport parameter:

<parameter name="ParentCustomerID"
           class="java.lang.String"/>

Main report parameter mapping:

$F{customer_id}

Connection expression:

$P{REPORT_CONNECTION}

The report execution follows this sequence:

1. The main report retrieves customer records.
2. For each customer record, the subreport receives the corresponding customer_id.
3. The subreport executes its query using the received parameter.
4. The matching order records are retrieved.
5. The subreport output is displayed within the main report.

This approach produces a consolidated customer report with related order information.

Common Jaspersoft Subreport Problems and How to Fix Them

Even when the subreport is correctly designed, configuration issues can affect the final output.

Troubleshooting tip: Test the subreport independently before embedding it in the main report. This helps determine whether the problem is in the subreport's query and design or in the parent report's configuration.

Advanced Features of Jaspersoft Subreports

Beyond displaying related records, JasperReports supports additional subreport functionality.

1. Returning Values to the Main Report

A subreport can return calculated values to the parent report through return-value configuration.

For example, a subreport can calculate the total order amount for a customer and pass that value to a variable in the main report.

The return-value configuration identifies:

• The variable in the subreport.
• The variable in the parent report.
• The calculation to apply, such as Sum or Count.

2. Nested Subreports

A subreport can contain another subreport. This is useful when a report requires multiple levels of related information.

For example:

• Main report: Customer information.
• First subreport: Customer orders.
• Nested subreport: Products associated with each order.

Use nested structures selectively because they can increase processing complexity.

3. Reusing Subreports

A separately designed subreport can be reused in multiple parent reports. This helps maintain consistent layouts and reduces the need to recreate the same report section.

Best Practices for Creating Jaspersoft Subreports

Follow these practices to make subreports easier to maintain and troubleshoot.

• Use meaningful names: Choose clear names for report files, parameters, and variables.
• Validate parameter types: Ensure the parameter's Java class matches the value passed from the parent report.
• Test queries independently: Verify that the subreport query returns the expected records before embedding it.
• Manage report paths carefully: Ensure compiled subreports are available in the development and deployment environments.
• Avoid unnecessary nesting: Use nested subreports only when the reporting requirement justifies them.
• Optimize queries: Avoid retrieving unnecessary columns or records, especially when a subreport runs for every parent record.
• Validate empty results: Decide how the report should behave when no matching records are available.
• Test exported formats: Check PDF, Excel, and other required outputs for layout differences.

Key Takeaways

• Subreports support complex layouts: Display related datasets within one report.
• Parameters connect reports: Pass values from the parent report to filter subreport records.
• Compilation matters: Compile the subreport and ensure the parent report can locate the compiled file.
• Data-source configuration is essential: Use either a JDBC connection expression or a data-source expression, depending on how the report is designed.
• Layout properties affect presentation: Configure positioning, overflow, and blank-line handling to avoid unwanted spacing or overlapping content.
• Preview before deployment: Validate the report output, parameter values, and data retrieval.

Conclusion

Creating Jaspersoft subreports involves designing separate report templates, configuring data sources, passing parameters, compiling the subreport, and embedding it within the main report.

By following these steps and validating the report output, you can build structured reports that combine related information while keeping individual report components reusable and manageable.

For organizations managing large reporting environments, maintaining and modernizing complex report assets can also become an important consideration.

Explore DataTerrain's BI Reports Conversion Services to learn about approaches to transitioning reporting assets between BI platforms.

Need help assessing your BI reporting environment? Contact DataTerrain to discuss your reporting and migration requirements.

Frequently Asked Questions

Related Resources

Explore these DataTerrain resources for more information about Jaspersoft, BI reporting, and report migration:

• Jaspersoft Report Migration: The Complete Guide – Understand different Jaspersoft migration scenarios and approaches.
• Jaspersoft Cloud Migration – Explore considerations for migrating Jaspersoft reporting environments to cloud infrastructure.
• Jaspersoft Customer Stories – Explore Jaspersoft-related customer experiences and solutions.
• Jaspersoft BI: A Comprehensive Guide – Learn more about Jaspersoft reporting and business intelligence.
• Migration Solutions – Learn about DataTerrain's migration capabilities and solutions.

For additional guidance, refer to the official JasperReports Subreport Sample and Jaspersoft Studio Subreports Documentation.