How to: Define a Report Parameter
Important
This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.
Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012
Parameters are used to specify the data to use in a report, connect related reports together, and control report presentation. This topic contains a section that describes the different kinds of report parameters that can be used on Microsoft Dynamics AX reports.
Report parameters are used to enable interactive, client-side data filtering in a report. In this case, you must manually define a parameter, and then use it to define an expression for a report filter. Since filters are applied on the client, there is no round tripping required.
The following procedures explain how to manually define a report parameter and use it in a filter.
To manually define a report parameter
In Model Editor, expand the node for the report that you want to work with.
Right-click the Parameters node, point to Add, and then click Parameter. A node for the parameter displays.
Select the node for the parameter.
In the Properties window, specify property values for the parameter.
Property
Description
Allow Blank
Indicates whether the parameter is allowed to be blank.
Data Type
The data type of the parameter, such as DateTime.
Note
If a parameter is the DateTime Data Type, the Microsoft Dynamics AX client treats the parameter as coordinated universal time (UTC) and any default value from Reporting Services will be converted to the local user time zone. When you preview a report with a DateTime parameter, the time format displays as an Integer Data Type in Visual Studio preview. The report will render correctly as a DateTime Data Type in the Microsoft Dynamics AX client.
Default Value
A default value for the parameter.
Multi Value
Set the property to True in the following scenarios:
The parameter is allowed to have multiple values.
The parameter is static and represents a range on a query.
Note
The ‘;’ is not supported by the MSDAX client to mean Multi Value. If you set the Multi Value property to True and the end user of the report provides values like 1;2;3 then the client will only use 1 as the value.
Name
The name of the parameter in the model.
Nullable
Indicates whether the value of a parameter can be null. If the Nullable property is set to True, a null value indicator check box displays next to the control that is generated for the parameter.
Note
The Reporting Framework does not provide support for indicating that an Integer, Float, or String parameter is a NULL value.
Prompt String
The text that displays in the user interface when a user is prompted to enter a value for the parameter.
Values
Indicates how values are supplied for a parameter. Click the ellipsis button (...) to display a dialog box with the following options.
From Dataset - Use this option to display a set of values from a particular dataset. Select a dataset from the drop-down list for the Dataset property, and then select a Label Field and a Value Field from the corresponding drop-down lists. The Label Field value displays to the end user. The Value Field value is used in filters or passed back to a query parameter when this parameter is used by a dataset.
Non-queried - Use this option to display a set of unbound values that are not from a dataset. Provide a set of value/label pairs in the table for each item that you want to include as an available value. Unbound values must be a String type because they are entered and stored as text. You can leave the table blank and not specify any value/label pairs. However, if you do this, you will not be allowed to specify a default value for the parameter using the Default Value property since the default value must come from the set of available values. In this case, it is recommended that you use the Null option.
Null - Use this option if you want to allow unrestricted values for the parameter (restricted only by the data type). You can specify a default value for the parameter using the Default Value property.
Visibility
Indicates whether the parameter is displayed to the user.
The property values that you specify for a parameter in the Properties window determine what a user sees when the parameter displays in a report. For more information about the controls used to render parameters in a report, see Controls Used to Render Report Parameters.
To use a report parameter in a filter
In Model Editor, expand the Designs node for the report.
Expand the node for the design that you want to add a filter to.
Right-click the Filters node, and then click Add Filter. A node for the filter displays.
Select the node for the filter.
In the Properties window, specify the following properties.
Property
Description
Expression
An expression for the filter. From the drop-down list, choose a valid field for the filter to create a simple expression, or choose <Expression…> to open the Edit Expression dialog box to create a more complex expression.
Name
The name of the filter.
Operator
An operator for the filter expression.
Value
The parameter or an expression that contains the parameter. Choose <Expression…> from the drop-down list to create a complex expression. For information about creating expressions, see Expression Examples in Reporting Services.
To preview the layout of the report, right-click the node for the design, and then click Preview. The parameters display when you select the Parameters tab in the Preview window.
Note
If the report is bound to a query with a range and a default value is specified, the report could be filtered by a multivalued parameter. To avoid this, you have the following options:
-
Mark the query range parameter as internal in the report design to prevent duplicating the filter.
-
Override the single filter using a report data provider (RDP) class.
-
Avoid using queries that contain a predefined query range in reports.
There are many types of report parameters. Use the following table to decide which is best suited for your report. The following table describes how parameters are created, how that affects a report, and any special considerations:
Type of parameter |
Description |
|---|---|
SysQuery parameters |
SysQuery parameters are generated from a query that is created in the AOT. If you use a parameterized query in a dataset, a report parameter is generated for each parameter in the query. Applying user-selected parameter values require round-tripping the parameterized query to the server during the data retrieval process. Queries created in the AOT are defined by using the SysQuery class. Reports that are accessed from Enterprise Portal cannot use SysQuery parameters. A static range parameter is generated if a query has a range specified, and the Dynamic Filters property on the dataset is set to False. A static range parameter is based on the query range, and is generated for a report bound to the query. A dynamic range parameter is generated if a query has a range specified, and the Dynamic Filters property on the dataset is set to True. A dynamic range parameter is based on the query range generated for a report bound to the query. The generated parameter will be named with a suffix of _DynamicParameter. |
System parameters |
These parameters are generated based on metadata for the company name, user context, language, and report context. These parameters are prefixed with AX_, for example, AX_CompanyName. |
Filter parameters |
These parameters enable interactive, client-side data filtering in a report. In this case, you must manually define a parameter, and then use it to define an expression for a report filter. Since filters are applied on the client, there is no round-tripping required. For more information, see How to: Define a Report Filter. |
Static parameters |
These parameters are bound to a dataset and let the user select report data. |
Unbound parameters |
These parameters display a set of values that are not from a dataset. You provide a set of value/label pairs in the table for each item that you want to include as an available value. |
Business logic parameters |
These parameters are generated when the dataset is bound to a data method. For more information, see Using Business Logic in Report Data Methods to Access Report Data. |
Report data provider (RDP) parameters |
These parameters are generated for an RDP data contract as a static parameter. RDP parameters are defined in Controller classes. Enterprise Portal does not support the Controller class. For more information, see How to: Use a Report Data Provider Class in a Report. |
Enum parameters |
These parameters expose enum types on a report in a friendly drop-down list. You can create a range on a query to expose an enum parameter in the Microsoft Dynamics AX client. However, if you want the report to be run from Enterprise Portal, you must use an AX Enum Provider to define the parameter. For more information, see How to: Use an Enum as a Report Parameter. |
Online analytical processing (OLAP) parameters |
These parameters are used in OLAP reports where you provide the parameter selection into a Multidimensional Expression (MDX) query that generates an OLAP dataset. For more information, see Parameters Overview. |
Cascading parameters |
Cascading parameters provide a way of managing large amounts of report data. You can define a set of related parameters so that the list of values for one parameter depends on the value chosen in another parameter. For example, the first parameter is independent and might present a list of product categories. When the user selects a category, the second parameter depends on the value of the first parameter. Its values are updated with a list of subcategories in the chosen category. When the user views the report, the values for both the category and subcategory parameters are used to filter report data. |
See also
How to: Define a Report Filter