Report Parameters

It can be useful to add parameters to the report. For example if you want to issue a report for a single customer, employee, product, or project but not for all customers, employees, etc. In order to do so you have to define a workflow variable and select it in the node you want to parameterize.

The report parameters are automatically added when you subsequently switch to the report. During runtime (when the report is generated) the user is prompted to enter a value for this variable. The value is inserted into the related node, in which the variable is used. This concept is explained below in more detail:

When building the workflow, right-click the opened workflow in the window Workflow Projects and select the context menu entry Workflow Variables…

If you cannot find this entry in the context menu, make sure you are in the expert mode: in order to enable workflow variables for your Report Designer edit the knime.ini file, which is located in your installation directory. Add the following line at the end of this file:
-Dknime.expert.mode=true

 

how to open the workflow variable dialog from the context menu in the workflow projects view

A dialog opens that allows you to add, edit or remove workflow variables:

 

The workflow variable dialog

When adding a workflow variable you have to enter

  • a unique name for the variable
  • a type (either string, double, or integer)
  • and a default value

Once the workflow variable has been added, the source nodes of the workflow have to be reset in order to propagate the variable throughout the workflow.

 

In order to apply changes of workflow variables to the workflow it has to be reset which has to be confirmed

Now the variable can be used in order to parameterize the nodes. Open the dialog of the node you want to parameterize and select the “Flow Variables” tab, where you can select the workflow variable:

 

use the workflow variable within your node's dialog

This replaces the actual value of this setting with the value of the variable at runtime (when the workflow is executed).
When you switch to the report, the workflow variable is automatically added as a report parameter:

 

the automatically added report parameter shows up in the data set view

In order to edit this parameter, right-click it and choose Edit. A dialog opens in which you can set, amongst others, the following properties of the report parameter:

  • the prompt text, displayed at runtime to the user
  • the display type which can be
    • a text field
    • a combo box
    • a list box
    • or a radio button
  • a help text
  • and a default value
  •  

 

dialog to edit the report parameter

When generating or previewing the report the user is subsequently prompted to enter a value for this report parameter in a dialog similar to the one below:

 

Dialog to enter a new value for a report parameter

If you do not want the user to enter free text but to choose from a provided set of values, select the combo box as display type and define which values should appear in the combo box.

 

Available display types: text box, combo box, list box, radio button

You can define the selectable values statically and enter each of the values by clicking the New… button:

 

How to enter a parameter value for later selection manually

However, it makes more sense to import the values once, i.e. select the Static radio button and then click Import Values… which opens a wizard that enables data to be selected from an existing data set:

 

Values can be imported once into a static list

Please note that there is a known issue related to the static import of values for report parameters of type string. If your report uses report parameters of type string, in turn each data set also has data set parameters, which makes it impossible for values to be imported.

The solution is to prepare the data you want to import within your workflow and to remove the data set parameters of type string from this data set once it has been imported. This is accomplished by double-clicking it in the Data Set View, or by selecting Edit in the context menu when the data set is selected in Data Set View. This opens the data set edit dialog:

 

In the edit data set dialog the data set parameters can be removed in the referring tab

Remove every parameter, click OK and try to import the data again. Ignore the error dialog: once you have selected the data set without data set parameters you will be able to import the values. Once imported you can remove the related node in the workflow and update the report – the values are retained.

Another option is to import the values dynamically, i.e. each time the report is generated or previewed the values are retrieved from a data set.

 

alues for the selection box can also be imported dynamically

If a combo box is selected as the display type, a report parameter prompt dialog is generated similar to the one below:

 

The resulting report parameter selectino dialog with a combo box

Once the user enters a value for the report parameter this value is inserted as a workflow variable in the underlying workflow and the workflow is re-executed again with this new value.