Applying parameters

A parameter is a variable whose value is input at runtime. If a report contains a parameter, you need to specify a value for the parameter when running the report. The runtime parameter dynamically controls your report result.

The topic shows how to create and use local parameters in a web report and specify values for the parameters used in a web report.

Using local parameters

When working with a web report, sometimes you may find that the predefined parameters in the catalog cannot meet your requirements, in which case, you can create some local parameters and use them in the report to get the desired data. Then when you save the web report, the local parameters will be saved along with it as its resources.

Local parameters are report level resources, which means they are only available to the report for which they are created.

To create a local parameter:

1. Do one of the following:
   • In the report wizard, click the Filter button next to the Data Source text box, then in the Query Filter dialog, select the field to be filtered from the Field drop-down list, click the button in the Value text field and select <Add Parameter…> from the Local Parameters node of the drop-down list.
   • Click Menu > Edit > Filter, or the Filter button on the Standard toolbar to display the Filter dialog, select the component in the web report to which you want to apply the filter from the Apply to drop-down list, select the field to be filtered from the Field drop-down list, then click the button in the Value text field and selecting <Add Parameter…> from the Local Parameters node of the drop-down list.

   The Add Parameter dialog appears.

2. In the Name field, input a name for the parameter.
3. Select a parameter type from the Value Setting drop-down list. For parameters in XML connection, it can only be Type-in Parameter.
4. In the values section, specify the parameter values as required. The section varies with the type you select from the Value Setting drop-down list.
   • For Type-in Parameter:
     1. Specify the data type of the parameter value from the Value Type drop-down list.
     2. Click to add a value line, double-click in it and then type in a value of the specified data type.

        If the parameter is of Date, DateTime, or Time type, you can also click the calendar button to set a date and time value using either calendar or expression functions in the Calendar dialog. If you use an expression to specify the value, when you hover the mouse pointer over this value, a tip will appear showing its expression. Click on the value, the expression will be displayed in the value text box and you can edit the expression in the text box directly if you want. After editing, when you click elsewhere outside of the value text box:

        • If the edited expression is correct, a new value calculated by the expression will be displayed in the parameter value text box.
        • If the edited expression is wrong, no value will be created and the expression itself will be displayed and highlighted in red in the value text box. Correct the expression, or click the calendar button to specify a value.
     3. Repeat the second step to add more values.

        To adjust the order of the values, click or ; to remove any unwanted value, select it in the list and then click .

     4. Specify the value which will be set as the default selected value in the Enter Parameter Value dialog by selecting it from the list.
   • For Bind with Single Column:
     1. From the Source drop-down list, select the required business view in the current data source. Then, all fields in the specified business view will be available for value selection.
     2. Select a field from the Bind Column drop-down list. This field is used to filter the query when running a report with the parameter.
     3. If you want the values of another field to be displayed in the Enter Parameter Values dialog, which makes more sense to report end users than the values of the Bind Column field, select that field from the Display Column drop-down list.
   • For Bind with Cascading Columns:
     1. From the Data Source drop-down list, select the required business view in the current data source from which to get the columns.
     2. Click to add a parameter row.
     3. Click in the Bind Column cell and select a field from the drop-down list.
     4. If you want the values of another field to be displayed in the Enter Parameter Values dialog, which makes more sense to report end users than the values of the Bind Column field, click in the Display Column cell and then select that field from the drop-down list.
     5. Click in the Parameter cell to create the parameter. A name for the parameter will then be automatically added by JReport.
     6. Repeat steps b to e to create more parameters. Make sure that the selected Bind Column fields are of cascading relationship one level by one level down. In this way, a group of cascading parameters are created.

        To adjust the order of the parameters, click or ; to remove any unwanted parameter from the cascading group, select it and then click .

5. In the Options box, set options for the parameter according to your requirements.
6. When done, click OK to create the parameter.

   To further edit the parameter, right-click it and select Edit from the shortcut menu. Then in the Edit Parameter dialog, edit the parameter as required.

   To remove the parameter, right-click it and click Delete on the shortcut menu.

Once a local parameter is created, you can then use it to dynamically filter data of the web report, add it to a parameter control or parameter form control in the web report, or reference it in a dynamic formula used in the web report.

Specifying parameter values

When running a web report with parameters, a dialog is displayed for you to specify parameter values. After the report is opened in Web Report Studio, you can change the parameter values using the following ways.

Using the Parameters panel

The Parameters panel is available when the current web report uses parameters. It lists all the parameters used by the report with your last-time saved default values, which could be the values saved in this panel last time, or in the Enter Parameter Values dialog, Parameter Settings dialog, or when advanced running or scheduling the report. If you have not yet set the default values on the server, or if you did but your last-time saved default values cannot fully match the current parameters, all the parameters will use their default values specified in the parameters' definition as the initial values.

Edit the values according to your requirement and then click Apply to make the report run with the specified parameter values. You may specify parameter values in these ways.

If you want to save the current specified parameter values as the default values for the report, select Save as default in the panel (to make this option available, you need to make sure the Enable Setting Default Parameter Values For Web Report is selected in the Profile > Customize Server Preferences > Advanced tab).

If you would like the report to run on the console with the saved default values directly next time, without popping the Enter Parameter Values dialog, unselect Re-enable Parameter Screen, which is available when the option Enable Hiding Initial Parameter Dialog For Web Report is checked in the Profile > Customize Server Preferences > Advanced tab. Note that if later the last-time saved default values cannot completely match the report parameters, the parameter dialog will still be displayed. You can check this option to show the Enter Parameter Values dialog again after it has been hidden.

The above two options are user-report level settings, that is to say, they take effect when both the same user and report are matched. This also applies to admin users, and therefore admin cannot customize the settings for all users.

If you want to reset the parameter values, use the Reset button, which varies on different situations:

• When Save as default is available in the panel, the Reset button contains a text part and a triangle icon. You can choose to reset the values to either of the following by clicking the triangle. If you click the text part of the button directly, the values will be reset to the original default values.
  • Original Default Values
    The default values defined in the parameters' definition.
  • User Defined Default Values
    Your last-time saved default values.
• When Save as default is unavailable in the panel, the Reset button contains only the text part. Clicking it will reset the values to the original default values.

Using parameter controls

You can insert a parameter control and bind it with a parameter used by the current report. By specifying values to the parameter in the parameter control, you can pass the parameter values to JReport and run the report with the specified values. For details, see Using parameter control to specify a parameter to a report.

Using parameter form controls

You can insert a parameter form control, make it run the current report, bind it with one or more parameters used by the report. By specifying values to the parameters in the parameter form control, you can make the report run with the specified parameter values. For details, see Using parameter form control to run reports.