AX1687

Configuring refresh variables for web reports

You can define refresh variables for web reports, to allow users to filter the data in the report on demand. For example, you may want users to be able to dynamically filter the report by entity. You can set up a refresh variable that allows users to select an entity name. When the variable value is applied to the report, the relevant data queries are filtered by the selected entity.

IMPORTANT: The legacy web report feature has been deprecated. For information on our new web report and Report Builder features, see Web Reports and Using the Report Builder.

The basic setup process for refresh variables in web reports is as follows:

• You define the refresh variables that you want to make available to users. Refresh variables have different types that control what users can select and how they select it.

• You create "dependencies" between refresh variables and data sources in the web report. The dependency tells the web report that the specified data source should be filtered by the variable value. All components that use the data source will then be updated to show the filtered data. This step is required for all refresh variables except the Year variable type.

To continue the previous example, imagine that your web report contains a Data Grid component that uses the GL2021 data source. In order for that data grid to be filtered by the user's selected entity, you must create a dependency between the Entity refresh variable and the GL2021 data source. When the user selects a value for entity and applies that value to the report, the GL2021 data source is automatically filtered by that entity, which in turn impacts the data shown in the data grid.

If a web report has defined refresh variables, those refresh variables display to web report users in the Filters panel. The user can open the Filters panel, define values for the variables, and then apply the selected values to impact the data shown in the report. For more information on how end users interact with the Filters panel, see Filtering data in web reports.

Differences when using refresh variables in web reports

The refresh variables available in web reports are essentially the same as the refresh variables available to spreadsheet Axiom files and Axiom forms. However, only a few variable types are currently supported for use in web reports, and there are some functionality limitations. For example:

• Web reports can only use the following refresh variable types: Combo Box, Grid (multi-select), Hierarchy Filter, and Year. The Year refresh variable is unique to web reports.
• Combo Box variables must use a table column as the data source. Other data options such as the ComboBox data source or an Axiom query are not supported in this context.
• The variables cannot be dependent on other refresh variables.

For these reasons, the web report refresh variables are documented separately, so that it is clear what is supported in web reports and what is not.

When you use refresh variables in spreadsheet Axiom files or Axiom forms, the variable setup is very manual but also very flexible. When a user selects a value for the refresh variable, that value is written back to the [RefreshVariables] data source. It is the responsibility of the file designer to configure the file to do something based on that selected value, but the value can be used for almost any purpose. For example, the value could be used to filter an Axiom query, or change the visible columns in a grid, or determine the visibility of a component.

When you use refresh variables in web reports, the variable set up is much simpler, but the variable can only be used to impact data queries in report components. The advantage to this setup is that once a dependency is created between the variable and a data source, there is nothing more that the file designer needs to do to make it work. The data source will automatically be filtered by the variable. The disadvantage to this setup is that refresh variables cannot currently be used for other purposes, such as to hide components or change the visible columns in a grid.

Defining refresh variables for a web report

Refresh variables for web reports are defined on the Refresh Variables panel of the Report Designer. If the report already has defined variables, they are listed here.

• To add a new variable, click Create New Refresh Variable. A new variable is added to the bottom of the list. You can define the name of the variable and other variable settings using the Configure Refresh Variable panel.

• To delete a variable, select the variable to display the action icons to the right of the variable name. Click the Delete icon to delete the variable. (These icons are also visible when you hover your cursor over the variable.)

  NOTE: Variables cannot be deleted if they are used in a refresh variable dependency for a data source. You must delete the dependency first, and then you can delete the variable.

• To edit the properties of an existing variable, select the variable to display the Configure Refresh Variable fly-out panel. You can then edit the variable settings as needed.

• To change the variable order, select the variable to display the action icons to the right of the variable name. Click the up arrow or down arrow to move the variable up or down in the list. The variable order determines the order that variables display to users in the Filters panel. (The up / down icons are also visible when you hover your cursor over the variable.)

Example refresh variable configuration for a web report

The behavior and configuration properties of a refresh variable depend on the variable type. For more information on how end users interact with each variable type and how each type is configured, see the following topics:

• Combo Box
• Grid
• Hierarchy Filter
• Year

IMPORTANT: Generally speaking, a refresh variable only impacts a web report if you define a dependency for the variable. If you do not define a dependency, then the variable still displays in the Filters panel, but applying a value for the variable has no effect. The exception to this rule is the Year variable, which automatically impacts all year-based tables in the report and does not require any dependency.

Refresh variable dependencies

Once you define a refresh variable for a web report, you must also define a dependency for the variable. The dependency creates an association between the refresh variable and components in the report, so that the components are automatically filtered by the selected variable value.

IMPORTANT: The exception to this rule is the Year variable, which automatically impacts all year-based tables in the report and does not require any dependency. For more information, see Configuring a web report to dynamically change years of data.

Refresh variable dependencies are based on the value column for the variable. For Combo Box and Grid variables, you specify a column directly, such as Dept.Dept. For Hierarchy Filter variables, the value column is determined based on the source table and the columns in the hierarchy. In order to create a dependency between the variable and a data source or component, the primary table of the data source or component must contain the value column, or contain a lookup path to the value column.

For example, imagine that the primary table of a data source is GL2021, and that table contains a column GL2018.Dept with a lookup to Dept.Dept. This means the data source can be associated with any refresh variable that uses columns from the Dept table. When a user selects a value for the variable and applies it to the report, Axiom Financial Institutions Suite automatically applies a filter to the data source such as Dept.Dept=40000 (where Dept 40000 is the user's selected value for the variable). This impacts all components that use the data source.

Note the following considerations:

• Although you can configure a refresh variable to use GL2021.Dept as the value column instead of Dept.Dept, the variable is then only valid against the GL2021 table. If the data grid that uses the data source contains columns from other tables, such as BGT2021, then you must use the lookup column of Dept.Dept so that the filter can apply to all data tables in the query. Generally speaking, it is a best practice to use a lookup column for refresh variables, to accommodate the broadest range of query configurations.

• If the data source primary table contains multiple paths to the value column for the refresh variable, then you must explicitly specify which path you want to use when you configure the dependency. For example, you may have a primary table with two different columns that validate against the same lookup column—such as where Encounter.PrimaryPhysician and Encounter.SecondaryPhysician both look up to Physician.Physician. If the value column for the variable is Physician.Physician (or another column on the Physician table), then you must indicate whether you want the filter to go through PrimaryPhysician or SecondaryPhysician.

Currently, you can create refresh variable dependencies as follows:

• Data Grids: To use a refresh variable to filter a data grid, set the dependency on the data source used by the grid. The refresh variable will filter all Data Grid components that use the data source. See Defining refresh variable dependencies for data sources.

• KPI Panels: To use a refresh variable to filter KPIs, set the dependency on the KPI Panel component directly. The refresh variable will filter that KPI Panel component. See Defining refresh variable dependencies for KPI Panel components

A refresh variable can be used to filter just one data source or component, or multiple. If you want the refresh variable to filter multiple components, a dependency must be created on each data source or component that you want the refresh variable to filter.

If the primary table contains multiple paths to the variable, then you can create multiple dependencies for the variable on a particular data source or component, using a different path for each dependency. If multiple dependencies for the same variable are defined on a data source or component, then the filters resulting from the variable are combined using AND. For example, if you create two dependencies for the Physician variable on a particular data source—one for the PrimaryPhysician path and one for the SecondaryPhysician path —then when a user selects a physician name for the variable the resulting filter would be constructed as follows: Encounter.PrimaryPhysician='Doe' and Encounter.SecondaryPhysician='Doe'. This means that the selected physician would have to be present in both columns in order to meet the filter.

Displaying refresh variables on open

If refresh variable selections are crucial to the report, you may want to configure the report so that it opens with the Filters panel active. This is intended as a clear indication to the user that they need to make filter selections and apply them to the report.

To enable this behavior, select Show Refresh Variables on Open at the top of the Refresh Variables panel. This option is disabled by default. If enabled, the Filters panel is active when the report is opened.

If instead the refresh variables are optional, then you can leave this option disabled. This means that when the report is opened, the Filters panel is not active. The user must click the Filters icon in the Web Client toolbar in order to see and apply the refresh variables.

NOTE: Enabling this setting does not require the user to make variable selections before the report is refreshed. It simply opens the report with the Filters panel active, so that it is clear to the user that filtering options are available.

Referencing the current value of a variable

You can reference the current value of a refresh variable in Label components. This can be useful to create title text that updates dynamically based on the currently selected value.

To reference the current value of a refresh variable, use the following syntax:

For example, if the variable name is Region, the label could look as follows:

When the label is rendered, the {rv} syntax is replaced with the currently selected value for the variable. For example:

When the file is first opened, if the refresh variable has a defined default value, this is used as the currently selected value.