Report Parameters Overview

This document describes the main uses of report parameters, report parameter properties, and parameter values. Report parameters allow you to control the report's content, connect related reports, or use them as arguments in functions.

To design a report that uses parameters effectively, you need to understand how parameters and Data Source components work together, how parameters and expressions work together, and how to manage parameters.

Main Usage of Report Parameters

Parameters may contain single or multiple values. In case they have pre-defined values (i.e. Available Values), the latter may be static or dynamic (e.g. query-based) collections. The parameters may be allowed to have BLANK and NULL values. Other usages of the report parameters are:

• in data binding - to vary report data retrieved from a Data Source component
• in expressions - to directly provide a value
• in data item filtering, sorting or grouping criteria

After a report parameter is created, you can modify the default values and other parameter properties, such as visibility.

For example, you might want to create a report with a hidden parameter that selects data specific to the user running the report. Or you can filter the displayed results in a table item, based on the selection of the report parameter.

Report Parameter Properties

Report parameters can have the following properties:

• Type

  Determines the type of the acceptable values. The allowed types are Boolean, DateTime, Integer (values are converted to System.Int64 i.e. long), Float(values are converted to System.Double i.e. double), and String. Acceptable values for each type are listed here: ReportParameterType The default parameter type is String.

  • DateTime

    The DateTime values in the report are evaluated based on the Reporting Engine time zone:

    When you use the HTML5-based web viewers, the DateTime parameter values that come from the Reporting REST Service/Report Server are considered UTC values and the Kendo widget transforms the DateTime to local time, i.e. the user sees it in local time. When the user selects another DateTime value for the corresponding Report Parameter, the latter gets converted back to UTC when sending it to the service. This ensures all users will see the correct local times, and send the correct times to the server.

    The desktop viewers may have an embedded Reporting Engine that will work with its local time. If you connect them to a REST Service or Report Server they will also show the reports rendered with the service time.

  • Integer

    In some scenarios you may need to convert the Integer Parameter Value to System.Int32 i.e. int, for example, to pass it to a User Function, DataSource parameter, etc. In these cases, apply the Conversion Function CInt to the parameter before passing the value to avoid the potential failure of the cast from System.Int64 to System.Int32.

• Name

  Specifies the parameter name. Use it to access the parameter. The name must be a valid identifier - may contain only digits (0-9), letters (a-z, A-Z), and underscore sign (_). Must begin with a letter or underscore.

• Value

  Used to specify a value for the parameter. It can be blank, a value of the allowed types, an Expression that evaluates to a value of the allowed types, or IEnumerable containing values of the allowed types.

  When a parameter accepts multiple values (MultiValue=True), you can set the value by programmatically assigning an IEnumerable of the allowed types.

• Text

  Specifies the text for the parameter to be displayed in the report viewer as a prompt to the end user. It can be blank, string, or Expression. May be accessed in Expressions with the Global Object =Parameters.[Parameter Name].Text. If not set, the Name of the parameter will be used instead.

  When you use an Expression to set the property, data fields should not be used and respectively they are not listed in the Edit Expression Dialog.

• Visible

  Specifies whether the editor will have UI in the parameters area. If you turn on the Visible property for at least one report parameter, the parameter area is shown when previewing the report in the report designer or in the report viewer.

• AllowNull

  Determines if null (Nothing in VB.NET) value is acceptable.

• AllowBlank

  Applied only when the parameter is of type String. Determines if an empty string is acceptable.

• MultiValue

  Determines if a collection of values (of the specified Type) is acceptable as a value of the parameter. Parameters with MultiValue turned on are mainly used with the IN logical operator.

• AvailableValues

  The available values, or valid values, are a set of predefined values which are acceptable as the value of the parameter. Each available value may have a label that will be displayed if the parameter is visible. To define available values for a parameter you need to set the following nested properties:

  • DataSource – a data source for the value/label pairs. The same data sources are supported as for the Data Items, including the Telerik Reporting Data Source Components.

    The optimization for reusing the raw data from the same DataSource component introduced with R3 2019 (13.2.19.918) is valid only for data items. It doesn't concern the Report Parameters with AvailableValues relying on DataSource components. Even if several parameters fetch their AvailableValues from the same DataSource, the latter will be called once for each parameter.

  • ValueMember – a column name, expression, or embedded expression based on the DataSource schema. It is used as Value in the value/label pair. May be accessed in Expressions with the Global Object =Parameters.[Parameter Name].Value.

  • DisplayMember – a column name, expression, or embedded expression based on the DataSource schema. It is used as Label in the value/label pair. May be accessed in Expressions with the Global Object =Parameters.[Parameter Name].Label. If omitted the ValueMember will be used as DisplayMember as well. Optional.

  At design time, you can use the Data Source Wizard to select an existing or to create a new data source.

• Mergeable

  Controls parameter merging in ReportBook. The default value of the Mergeable property is true. Set the Mergeable property to false if you want to prevent a parameter from being merged with its equivalent ones.

• AutoRefresh

  Determines whether to trigger the report preview after changing the value for a parameter. Applies only to visible parameters. The default value is False.

Report Parameter Validation

When a report enters the processing stage, its value is validated against its validation properties. If one or more parameters do not have valid values, processing is aborted. The following properties are used to validate the supplied parameter’s value:

• Type
• AllowNull
• AllowBlank
• MultiValue
• AvailableValues

Passing a value to a Report Parameter

A Parameter is populated by setting its Value property. You may set this property to a valid value or an expression that evaluates to a valid value. The expression evaluation and validation are performed while the report is processed. An expression used as a parameter value may not contain a reference to the built-in Fields collection, as fields are still not populated when the parameters are processed.

Report Parameters' value can be populated in one of the following ways:

• At design time through the ReportParameter Collection editor
• Using the automatic user interface that each Report Viewer provides.
• Programmatically by using the ReportParameters collection.
• Using a SubReports Parameters collection.

Cascading (dependent) parameters

Cascading parameters provide a way of creating dependencies between parameters to handle large amounts of input data. You can define a set of parameters where the list of available values for one parameter depends on the values chosen in other parameters.

For example, the first parameter could present a list of product categories. When the user selects a category, the second parameter is updated with a list of subcategories within the category. A third parameter could then display a list of products within the selected subcategory. The value for the product parameter is used to filter the report to a particular product. The parameters whose values depend on other parameter values are known as cascading, dependent, or hierarchical parameters. For more details on how to use cascading parameters, see the following documents:

• How to Cascade Parameters with applied filtering on Report level
• How to Cascade Parameters with applied filtering on data source level

The Report Parameter is processed as a whole entity. Its evaluation starts after all its dependencies, for example, other Report Parameter values have been evaluated. If, for example, the Text property is set with an Expression that can be evaluated and the Value property depends on another Report Parameter, whose value is unknown/invalid, neither the Text nor the Value property will be set.

Parameter area

When at least one report parameter has its Visible property turned on, a parameter area is shown as part of the report viewer. This helps the report developer to easily provide an input method for the end users. Based on the settings of the parameters, a suitable editor UI is created. The parameter's layout on the parameter area is formatted automatically. The order is determined by the order in which the parameters appear in the ReportParameters collection. The end user can enter or select values in the editors. When at least one visible report parameter has the AutoRefresh property turned off, a Preview button is available. In this case, to preview the report, the end user must click the Preview button. If all parameters have default values, the report runs automatically on the first view. You can show or hide the parameters area from the Parameters button in the report viewer’s toolbar.

See Also

• Adding Report Parameters
• Using Report Parameters in Expressions
• Using Report Parameters programmatically
• Using Multivalue Parameters