This article applies to the Admin Console >  Data >  Parameters settings.

Parameters are used throughout the Exago application to store values. Although parameters can be created and given a default value in the Administration Console, parameters are designed to be set at runtime through the API.

Parameters can be used to:

• Pass values to Web Services, .NET Assemblies, or custom SQL Data Objects.

Important

Parameter values are passed in the order in which they are listed in a data object. It is critical to ensure that the order is correct. For more information please see the Data Objects article.

• Set tenant values to assure security in a multi-tenant environment. For more information see Data Objects.
• Pass values into cells and formulas of a report. To display a non-hidden parameter in a cell type "=@ParameterName@".

• Pass values into custom functions. For more information see Custom Functions.
• Create a custom dropdown list of values for user selection on a report prompt.

Create, Edit, Delete Parameters

All existing parameters are listed in the Admin Console Main Menu under Data. All the parameters that are added or edited will be displayed in a tab entitled Parameters.

• To add a new parameter click Parameters in the Main Menu and either:
  • click the Add icon at the top of the main menu
  • right-click and select Add from the context menu
• To edit a parameter either:
  • double click it
  • select it and click the Edit  icon at the top of the main menu
  • right-click it and select Edit from the context menu
• To delete a parameter either:
  • select it and click the Delete  icon at the top of the main menu
  • right-click it and select Delete from the context menu
• To save changes and new parameters click the Apply or Okay buttons.

Note

Currently, the prompt window will not appear when drilling down into a child report that contains prompting parameters. However, this can be partially bypassed by adding the prompting parameter in a hidden cell on the parent report so that the user will be prompted at execution for the parameter value.

Parameter Properties

Each Parameter has the following properties:

Name

A name for the parameter. Prompting parameters are sorted alphabetically by name unless otherwise specified or unless there are dropdown parameters with dependencies.

The following characters are not allowed: @ , . { } [ ]

The following names are reserved by the application: filter, email, userId, companyId, reportName, reportFullName, pageNumber, data_label, data_value, series_label, bubble_size, bubble_value, batch_x (where x can be any string of characters).

Important

Parameter names are case sensitive.

Type

The parameter data type. The following types are available:

• string
• date
• integer
• decimal
• boolean (v2019.1+)

Note

Select date for DateTimes and string for functions.

Value

The default value of a parameter. This is intended to be overwritten at runtime through the API.

Date values should be entered in yyyy-MM-dd format.

Null values may also be passed to parameters. In order to do so, the default value of the parameter needs to be set to {null}. This will allow parameters to process any null values that are passed through the API or application at runtime.

Formulas as Default Parameter Values

Formulas that return strings, integers, dates or decimals may also be passed as parameter default values. Just as entering a function into a cell in the Report Designer, include an equals sign as a prefix (e.g. =QuarterNumber(Today())).

Formulas may include multiple functions. As with other functions, these may also include other parameters.

Caution

The Admin Console will only allow String, Decimal or Integer Type parameters to have a formula as their default Value. If you need the Date type, select String in the Admin Console, enter the formula into the Value field and then manually edit the XML configuration file to choose the desired data type.

Examples

1. This parameter as defined in the XML configuration file is date type and by default will return the value of the Today() function, which is today's date.

<parameter>
    <id>DateChoose</id>
    <data_type>date</data_type>
    <value>=Today()</value>
    <hidden>False</hidden>
    <prompt_text>Choose a date</prompt_text>
</parameter>

2. This parameter defined in the Admin Console returns a string with an employee's name. The employee's name is decided based on the year of the current date.

3. This parameter defined in the Admin Console returns a decimal with the future value of an asset multiplied by 2.

Hidden

Set hidden to True to disable this parameter from being used by users in cells and formulas.

Prompt Text

Give non-hidden parameters a prompt text to query the user for a value at the time of report execution. Leave blank to use the default value.

Parameter Dropdown Object

Optional data object for populating the parameter as a drop-down selection list. Only applicable with prompting parameters. Commonly used in conjunction with programmable data objects (such as stored procedures).

For more information, see Paramter Dropdown at the end of this article.

Stored Procedure Parameters

A list of preexisting Exago parameters to be used as variables for a selected stored procedure.

Value Field

A column from the data object or custom SQL that sets that actual value of the parameter at runtime. This represents a set of values that are not displayed to the end user but are instead used when parameter values are required in custom SQL or stored procedures, or other server side processing.

Display Value Field

A column from the data object or custom SQL that sets the display value of the parameter for the dropdown selector. This represents the set of values that should be presented to the end user when they are executing or scheduling a report.

The Display Value is also displayed in reports and used in formulas (except in formula filters).

Note

These distinct values can be accessed in formulas with @ParameterName.Value@ and @ParameterName.DisplayValue@ respectively.

Display Type

The display value data type.

ReportObject report = (ReportObject)api.ReportObjectFactory.LoadFromRepository(@"Reports\Sales Reports");
report.Parameters.Find(x => x.Id == "SalesQuota").Value = "1500";
api.ReportObjectFactory.SaveToApi(report);

Parameter Dropdown

Drop-down lists can be added to parameters based on a data object, stored procedure, or custom SQL object.

For example, consider a filter on one value (the employee ID) but displaying another (the employee last name) to the end user:

The Parameter Dropdown Object field, if set, uses an object or procedure to populate a custom list of parameter values for the user when prompted. The fields below it are hidden until Parameter Dropdown Object contains a value.

The first drop-down list contains the list of Data Sources in the current configuration (see "Northwind" in Figure 1). Use this to select the name of a Data Source that exists in the configuration. Set to blank or click the Delete icon to disable the parameter dropdown.

The second field, when clicked, displays the Data Objects contained in the selected data source. (see Figure 2). Select one and click Okay to use that data object for the dropdown.

If the desired object isn't already available in the Data Source, a Custom SQL Object can populate the dropdown. Click on the Custom SQL Object icon. (see Figure 3).

Other parameters can be used as variables by typing them in @MyParameter@ form, or by selecting it from the parameter list and clicking the '+ Add' button. Verify the syntax of the SQL by clicking on the Test icon.

The Value field is a column from the data object or custom SQL that sets the actual value of the parameter at runtime. This represents a set of values that are not displayed to the end user but are instead used when parameter values are required in custom SQL or stored procedures, or other server side processing.

The Display Value field is a column from the data object or custom SQL that sets the display value of the parameter for the dropdown selector.  This represents the set of values that should be presented to the end user when they are executing or scheduling a report.

These distinct values can be accessed with @ParameterName.Value@ and @Parameter.DisplayValue@ respectively in the Report Designers.

Note

Parameter Dropdowns do not support default values.