Using Report Parameters in Jaspersoft Studio

Parameters in Jaspersoft are an important aspect of how report templates are built and they can greatly improve the user experience when it comes to generating the right report for the right user and with the right information. It is a concept of the JasperReports Library so it sits right in the heart of the reporting engine within all of the Jaspersoft solutions powered by JasperReports.
Some Jaspersoft users know parameters as the object required to capture the input control values entered during the report execution so that it can be injected in the query and used as a filter accordingly.

Report parameters can indeed be used that way and be injected in datasource query but it can do much more than that.

They are a way to:

• personalize the information presented in the report output (i.e. add a custom value to be used as a title or to display the server logged-in user name in the report),
• customize how the information is presented in the report (i.e. a boolean parameter will allow a user to define whether a section of the report should be displayed or not),
• provide data to be used as a source of the report (it is possible for the JasperReports library to either use the result set generated by a query as well as a full JSON object passed through a parameter to the report as a data source),
• enforce data governance in the report by filtering the result set of the query specifically for the logged-in user at report execution (when deployed into JasperReports Server).

However you use parameters, they represent the best communication channel between the report engine and the execution environment (which is your application).

What is a parameter? 

A parameter is defined by a ‘name’ and a ‘class’, which is a Java class type like java.lang.String or java.lang.Integer. Any Java class is valid for the parameter ‘class’. For example a parameter of type java.sql.Connection may be used to define a subreport data connection, while a java.lang.Boolean parameter may be used to show or hide an element, a group of elements of the entire section of a report.

A parameter can have a default value which is defined by means of the default expression property. This expression is evaluated by JasperReports solely when a value for the parameter has not been provided by the user at run time. For example, the default value may be used during reports preview in Jaspersoft Studio.

How to create and manage parameters?

To create a new parameter, use the outline view.

• add a parameter by right-clicking on the item "Parameters" in the Outline panel,
• choose "Create Parameter".
• in the property panel, configure:
  • Its name;
  • Its class;
  • Whether it should be used for the prompt or not (which will require an input control at run time if true);
  • Optionally add a description, a default value;
  • Since version 7 it is also possible to set the parameter evaluation time to late or early which will define whether the parameter default value should respectively be calculated before or after running the report data query. 

To delete a parameter from the outline view right click on it and select "Delete". The parameters with a light gray name are created by the system and can not be deleted or edited.

Built-in Parameters

All reports contain a set of built-in parameters, parameters available by default that contains some key run time information. Some of the most important ones are:

• REPORT_CONNECTION, which holds the JDBC connection used to run the SQL query of the report (if the report is filled using a JDBC connection)
• REPORT_DATA_SOURCE which contains, if available, the data source used to fill the report
• REPORT_LOCALE which contains the Locale used to fill the report

Some built-in parameters are specific to a specific query language, for example when using the XML query language, the report will automatically include the parameter "XML_INPUT_STREAM" which defines the records to be used in filling the report. The built-in parameters can not be modified or deleted.

Using Parameters in an SQL Query

Parameters can be used in SQL queries to filter records in a where condition or to add/replace pieces of raw SQL or even to pass the entire SQL string to execute.
In the first case, the parameters are used as standard SQL parameters, in this example we refer to the parameter value with the syntax $P{...}:

SELECT * FROM ORDERS WHERE ORDER_ID = $P{my_order_id}

In this example, my_order_id is a parameter that contains the ID of the order to read. This parameter can be passed to the report from the application that is running it or by the user running the report to select a specific order. Please note that the parameter value here is directly used as a SQL parameter. This means that the query will be executed using a prepared statement like:

SELECT * FROM ORDERS WHERE ORDER_ID = ?

and the value of the parameter my_order_id will then be passed to the statement. 

Now let's consider this second case which refers to a parameter using the $!P{...} syntax (note the extra exclamation mark):

SELECT * FROM ORDERS ORDER BY $P!{my_order_field}

In this case, my_order_field is not directly used as a SQL parameter. JasperReports will consider this parameter like a kind of placeholder that will be replaced with the text value of the parameter (which may even be a portion of the SQL statement such as "ORDERDATE DESC").
With the same logic, a query can be fully passed using a parameter. The query string would then look like

$P!{my_query}

The number of parameters in a query is arbitrary. When passing a value using the $P!{} syntax, the value of the parameter is taken as is, and the user is responsible for the correctness of the passed value (SQL escaping is not performed by JasperReports in this case). 

When using a parameter in a query, Jaspersoft Studio requires that a default value would be set for the parameters used in the query to that it can retrieve the fields automatically.

Note: You should be extremely careful when using a parameter in a query through the $P!{} syntax. If the parameter is also used for prompt then that would allow the user to inject a query and thus potentially access some unauthorised data. It is then recommended to have one or more parameters requesting specific information through input controls and then use these values in the parameter default value which will generate the appropriate portion of SQL query that you’d like to inject in the query.

Parameters Prompt

If a parameter is set to be used as a prompt, then when executed the report will require to enter a value for these parameters. This is true with Jaspersoft Studio,  JasperReports Server, or any other solutions which use the JasperReports Library.

Here is a simple example.
> Create a simple report with the template "Blank A4", name it "ParameterExample"
> Use the data adapter "One Empty Record - Empty Rows".
> In this report, create a parameter, and using the Properties panel,

• name it MESSAGE,
• set its type to String,
• and set it to be used as a prompt (the property "Is For Prompting" must be checked).

> Drag the parameter from the outline view into the title band which will trigger Jaspersoft Studio to create a text field displaying the parameter value.
> You should have something like the following image:

Now, when executing the report, using the Preview button, for example, the parameter prompt dialog appears asking for a value for the MESSAGE parameter

Set a value for the parameter (i.e. Hello World!) and hit the "Play" button. The message will be printed in the title band

Jaspersoft Studio provides input dialogs for parameters of type String, Date, Time, Number, and Collection.