InetSoft Reporting Software: Report Parameterization

It is often desirable to allow the user to customize certain aspects of report display. For example, the user might want to view only records that satisfy a specific filter condition (e.g., ‘State’ is one of NJ, MD, NY), or they may wish to hide certain report elements and display others.

To provide users with this kind of control, you can define report parameters. Parameters are variables whose values are specified when the report is generated. The following sections explain how to define parameters, and how to prompt the user for their values.

Parameter values can also by set by script, drill-down report, or JSP/HTTP request.

BI DemoRegister
Report Parameterization Example

Defining Report Parameters

To define report parameters within Report Designer, follow the steps below:

  1. Select Edit → Parameter from the Designer menu. This opens the ‘Parameter Definition’ dialog box with its Parameters tab displayed. This tab displays all existing report and data-binding parameters.
  2. Click ‘New’, and specify the name of the new parameter in the dialog box. Then click ‘OK’.
  3. Click the ‘Set Selection List’ button to open the ‘Selection List’ dialog box. (The button’s text is displayed in green if the selected parameter already has a list associated.)
  4. To enter a fixed set of labels/values for the parameter, follow these steps:
    1. Click the List tab.
    2. Click ‘Add’ to add a new label/value pair.
    3. Enter the desired ‘Label’ and ‘Value’. (The ‘Label’ text is displayed to the user in the interface element; the corresponding ‘Value’ is assigned to the parameter.)
  5. To acquire parameter labels/values from a query at runtime, follow these steps:
    1. Click the Query tab.
    2. Select the query that contains the label/value pairs. The results in the first column of the query will be used as the parameter values; the results in the second column of the query will be used as the labels. (Query conditions can reference other report parameters if those parameters possess default values.)
  6. (Optional) Select ‘Allow Multiple Selection’ to permit the user to select multiple values for the parameter.
  7. Click ‘OK’ to close the ‘Selection List’ dialog box.
  8. (Optional) In the ‘Parameter Definition’ dialog box, select ‘As customization parameter’ to expose the parameter as a customization parameter. Customization parameters are displayed when the user clicks the ‘Customize’ button on the report toolbar.
  9. (Optional) Select ‘Prompt User’ if the user should be automatically prompted to enter a value for this parameter. (Disable this option for parameters set by scripts and drill-down reports.)
  10. (Optional) Select ‘Sort Values’ if you want the list to be sorted alphabetically.
  11. Click ‘OK’ to close the ‘Selection List’ dialog box.
#1 Ranking: Read how InetSoft was rated #1 for user adoption in G2's user survey-based index Read More

Parameterized Query

Parameters specified for a query condition or data binding condition are italicized in the Parameters tab. You can modify a query parameter’s default value and type through the Parameters tab. Query parameters can be used in the query selection conditions. A parameter can be either based on a subquery, or get its value from the end user at runtime. If a user parameter is used in a query, the application that performs the query needs to collect the parameter values before the query can be executed.

Multiple queries may have parameters with the same name. In this case, you can specify whether parameters sharing a name should be treated as the same parameter. To treat them as the same parameter (and prompt the user only once) select ‘Preferences’ from the Tools menu, click the Misc tab, and enable the ‘Parameter Name Unique’ option (default).

Parameterized Query Charts
 
Parameterized Query Charts

Parameter Sheets

If query or report parameters are defined for a report (see Parameterization above), then a default parameter screen opens when the user first launches the report. This screen prompts the user for all of the parameters which have the ‘Prompt User’ option enabled. (The prompts are displayed as a dialog box when the report is previewed in Designer.) You can create custom parameter prompting by designing a form using Designer’s form elements. Unlike the default parameter prompting, the form you design will appear as a regular report in the report viewer, and will be replaced by the new report when the form is submitted.

Staged Parameters

When you prompt the user for a series of related parameters, it is often desirable to guide the user through these choices in a certain order. This is called parameter staging. This technique allows you to constrain the options presented to the user at each stage so that only compatible parameter combinations can be selected.

For example, consider a Parameter Sheet that has two menus, one for ‘State’ and one for ‘City’. Initially, you want only the ‘State’ menu to be enabled, so that the user is forced to select a state first. After the user selects a state, you want to then enable the ‘City’ menu, but restrict its values to those cities that fall within with the selected state.

There are therefore several aspects to parameter staging, as described in the following sections:

  • Creating a Parameter Sheet Layout Add controls, and set ‘Field’ values to map to corresponding parameters.
  • Defining a Parameter Flow Specify the order for parameter control activation.
  • Filtering Parameter Options Populate parameter controls with options that are consistent with previous selections.
Previous: Advanced Enterprise Reporting Topics