Parameters

External parameters are passed from the outside when running a report and can be used as conditions in datasets. All external parameters become fields for each report band, so you can use them directly in the template as dataset fields. If any dataset contains field with the same name, it overrides the external parameter in the corresponding band and the report uses the dataset field value.

External parameters can be passed by the invoking code when running a report through API. Also, the report generator can show a dialog to enter parameters when a user runs the report. In the latter case you should describe the external parameters in the Parameters tab of the report detail view.

parameters

After you click on the Create button the Report parameter dialog is displayed.

report parameter

Properties

In the Properties tab, you can define parameter properties:

  • Name - parameter name, as it will appear in the parameter input form when running the report.

  • Alias - parameter alias used to access it in datasets.

  • Type - parameter type.

  • Hidden - flag that defines whether the request for parameter should be hidden from users.

  • Required? - flag determining if the parameter is mandatory.

  • Default value - defines the parameter value that will be used by default if no other value is selected by the user.

The parameter type can be primitive types of String, Number, Boolean or temporal types, besides, you can choose Enumeration, Entity or List of entities as a parameter type. Based on different type selected, additional fields are required:

If the Entity or List of entities parameter type is selected:

  • Entity - entity to use as parameter.

  • Entity selection view - optional view identifier, which will be used to select entity instances. If the view is not specified, selection will be made from a special view generic for all entities.

If the Enumeration parameter type is selected:

  • Enumeration - enumeration to use as parameter.

If the temporal parameter type is selected (Date, Time or Date and time):

  • Default date(time) is current - flag defines whether the current timestamp will be used as the default parameter value.

Localization

In the Localization tab, you can define the parameter name for different locales. In order to do this, you should enter the locale_name = parameter_name pairs, for example:

de = das Buch

Transformation

In the Transformation tab, you can apply a Groovy script to the parameter before using it in the report.

A Groovy script should return a new parameter value. The following variables are passed into the script:

  • params - parameters map is available by alias params.

  • paramValue - current parameter value is available in the script by the paramValue.

  • dataManager - an object of the DataManager type that provides CRUD functionality.

  • metadata - an object of the Metadata type that provides access to the application metadata.

  • applicationContext - an object of the org.springframework.context.ApplicationContext type that provides access to managed beans.

For example:

return "%" + paramValue + "%"

You can also use predefined transformations that add wildcards for text (String) parameters:

  • Starts with,

  • Ends with,

  • Contains.

transformation

In the Validation tab, you can define a Groovy script with some conditions for the parameter validation, see the details below.

Validation

You can validate an input parameter and/or define the cross-parameter validation.

  1. You can enable validation of each parameter in the Validation tab by checking the Validate checkbox. The validation logic is specified by a Groovy script. The script should check the parameter value and call the invalid() method if the value is not valid. This method will show the user an alert with the given message about the report validation errors.

    The following variables are passed into the script:

    • value - the parameter value entered by the user.

    • applicationContext - an object of the org.springframework.context.ApplicationContext type that provides access to managed beans.

    • currentAuthentication - an object of the io.jmix.core.security.CurrentAuthentication type associated with the currently authenticated user.

    • dataManager - an object of the DataManager type that provides CRUD functionality.

    • metadata - an object of the Metadata type that provides access to the application metadata.

    • invalid - groovy closure which effectively fails validation if called from inside the script.

      validation

  2. Cross-parameter validation can be enabled by checking the Validate checkbox in the Cross parameters validation section of the Parameters tab. The validation logic is specified by a Groovy script. The script should check whether or not parameter values make sense in relation to each other and call the invalid() method if they do not. This method will show the user an alert with the given message about the report validation errors.

    In addition to the variables listed above, the params variable is passed into the script to access the external report parameters map.

    cross parameter validation