Report parameters allow you to change the results of the report by specifying values for the parameters. The report definition contains an array of zero or more report parameter definitions. The report parameter definitions define all of the parameters used by the report. The parameter definitions include the name, data type, operator (if required), and default value. The operator of a parameter indicates how the parameter is used, such as if it’s compared as equal to, or greater than/less than, as well as In and Not In list.
Some report parameters represent an enumerated type. In such cases, the ReportParameterDefinition includes an array of ListValue types. The ListValue defines an ID and Name. The ID value is the value that should be returned in a report parameter, the Name is for display purposes.
Set Report Parameters
Reports might contain many parameters, some required, some optional, and some with default values. You are only required to pass in parameter values for parameters that are required and don't have a default value. Optional parameters and required parameters with default values don't need to be passed in when executing a report.
Report parameters are provided on the request as an array of ReportParameter objects. The ReportParameter allows you to set a UniqueId and a Value. The UniqueId must match one of the parameters as defined in the ReportDefinition, and the Value is any string value that adheres to the datatype specified in the ReportDefinition.
Sample Code – Setting report parameters
The sample code above is prompting the user for values to use for required parameters. All parameter values are passed as string values regardless of the parameter data type. The value will be validated prior to executing the report to ensure it can be coerced into the proper type.
The data type of the parameter is defined as a .NET data type (for example, Int32, String, Date). When setting values, ensure that the values adhere to the rules of the .NET data type to prevent errors.
If the Operator indicates that multiple values are permitted, such as when it’s In or Not In, then the Value can be set to a comma delimited list of values.
The report won’t be executed and an error is returned if:
- A required parameter has no value.
- A parameter is passed in with a UniqueId that doesn't match a parameter on the report.
- A parameter value can’t be coerced into the correct data type.