AX1395

Defining refresh variables

Refresh variables are defined by using a RefreshVariables data source. This data source is a series of tags that define the refresh variable properties.

Each Axiom file can have a single RefreshVariables data source that is placed on any non-control sheet in the file. In practice, this data source is typically placed on a designated sheet named something like Variables. If the file is a standard Axiom spreadsheet file that users will access in the Excel Client or Windows Client, then this sheet is typically hidden from end users (though it does not have to be).

To create a RefreshVariables data source:

  • Right-click the cell in which you want to start the data source, then select Axiom Wizards > Insert Refresh Variable Data Source.

The wizard adds the primary tag, all column tags, and one row tag to define a single variable. To create variables, you can manually populate the data source, or you can use the Data Source Assistant. For more information, see Using the Data Source Assistant to add or edit refresh variables.

NOTE: The primary RefreshVariables tag must be located in the first 500 rows of the sheet.

The following screenshot shows an example RefreshVariables data source with two variables:

The RefreshVariables data source uses the following syntax:

Primary tag

[RefreshVariables]

The placement of this primary tag defines the control column and the control row for the data source.

  • All column tags must be placed in this row, to the right of the tag.
  • All row tags must be placed in this column, below the tag.

Row tags

[Variable]

Each row flagged with this tag defines a unique refresh variable. Generally speaking, each variable represents a value that you want the user to input or select.

Column tags

Each column in the data source defines a variable property, such as the variable name and type, and whether the variable is enabled. All variables share a set of general properties. Additionally, certain variables have additional properties that only apply to that particular variable type.

[VariableType]

This column defines the variable type, which determines what users can enter for the variable. The variable type also determines the valid property columns for the variable.

For more information on completing the property columns for a variable type, see the individual topics on each type (listed below).

  • AdvancedFilter: The user can create a filter criteria statement using the Advanced Filter view, or create a limit query statement.

  • Calendar: The user can select a date from a calendar.

  • CheckBox: The user can select or clear a check box.

  • ComboBox: The user can select a value from a drop-down list. The list can be generated based on a specified table column, or an Axiom query, or a ComboBox data source. The user can type into the box to filter the items in the list.

  • Decimal: The user can enter any numeric value, including decimals.

  • Grid: The user can select a value from a specified table column (for example, ACCT.ACCT to select from a list of accounts). The column values are presented in a searchable grid dialog.

  • HierarchyFilter: The user can select one or more values from a defined hierarchy to result in a filter criteria statement.

  • Integer: The user can enter any whole number.

  • RadioButton: The user can select a single value from among two or more radio buttons. The list of radio buttons can be generated based on a specified table column, or an Axiom query, or a ComboBox data source.

  • RangeSlider: The user can select the top and bottom values within a defined range, using slider buttons.

  • RelatedColumnValue: This is a special variable type that is not presented to the user. Instead, it is used to return a related column value for a parent variable, so that the value can be referenced in report titles or other settings.

  • Slider: The user can select a single value within a defined range, using a slider button.

  • String: The user can enter any string value.

  • StringList: The user can select any item in a manually defined list.

Note the following about placement of the data source tags:

  • Column tags can be in any order. Optional column tags can be omitted from the data source if they are not being used. For example, if none of your variables are StringList type, you can omit the [ListChoices] tag.

  • Column and row tags do not have to be continuous. Axiom Software will continue searching the control row and control column for valid tags until it reaches another tag of any type.

Testing refresh variables

To validate the refresh variable properties, perform a refresh in the Desktop ClientGeneral term for using either the Excel Client or the Windows Client, both of which are installed to the user's desktop.. If any invalid settings are present, an error message will display. You should do this even if the intended use of the file is the Web Client, to catch any invalid settings.

Once you have set up the file as desired and corrected any invalid settings, you should test the refresh variables in their intended environment (Desktop Client refresh dialog or Web Client filter panel). Make sure that:

  • The variable name and selections make sense from a user perspective. If it does not seem clear what you are asking the user to do, you may want to edit the variable name or use a different variable type.

  • If the variable is not required, test a blank entry to make sure that the report still makes sense if no value is specified. If not, you may want to edit the report design or make the variable required.

  • If you are using dependent variables, make sure that any dynamic settings are working as expected. Try entering different values for the parent variable to make sure you have accounted for all possibilities.

  • Lastly, test to make sure the data refresh is affected by the refresh variables as you intended. Remember that it is up to the file designer to reference the user's selected values as necessary to impact the data refresh.

Once you have finished testing the file, remember to clear the contents of the [SelectedValue] column before saving the file (or restore these values to your intended "default" values). You can also use the [ClearSelectedValueOnSave] column or the [ClearSelectedValueOnOpen] column to automatically clear values for you.