AX1725

Executing commands from KPI Panels in web reports

You can configure a KPI box in a KPI Panel component to execute one or more commands. For example, you may want to launch a file with supporting information about the KPI.

There are several different ways that you can configure commands for KPIs. The approach to use depends on whether you need to execute one command or multiple, and whether you need to use custom icons with the command.

  • Basic Single Command: If you only need to execute a single command, and you don't need a custom icon, then you can define the command in the Command column of the KPI table. The KPI box displays with a three-dots icon in the upper right corner. Users can click this icon to execute the command.

  • Custom Single Command: If you want to display a custom icon with a single command, then you can use a separate KPIMenu data source to define the command and its icon. The KPI box displays with the custom icon in the upper right corner. Users can click this icon to execute the command.

  • Custom Menu with Multiple Commands: If you need to present multiple command options to users, then you can use a separate KPIMenu data source to define these commands. The KPI box displays with a carat icon in the upper right corner. Users can click this icon to open a fly-out menu that displays all of the commands using their defined names and icons.

Example KPIs with commands

If you want to use a KPIMenu data source with the KPI table, this must be part of the save-to-database file that is being used to save data to the table. See Saving KPIMenu values when using a KPI table for more information.

Valid command strings for use in KPIs

Command strings for KPIs can be any of the following items:

Valid Commands Description
URL

Specify a URL (starting with HTTP/S) to open a web page, Axiom form, or web report.

For example, you can use GetFormDocumentURL or GetWebReportDocumentURL to generate a URL to another Axiom file and launch it from the KPI.
Document shortcut

Specify a document shortcut to a file in the Axiom Software file system. Document shortcuts use the syntax document://filepath. For example:

document://\Axiom\Reports Library\Reports\expense_analysis.xlsx

Commands from the Command Library cannot be used in web reports. If a command is used, no error displays and no action occurs when a user clicks on the menu item.

Creating a KPIMenu data source

Using the KPIMenu data source, you can define one or more commands to display with custom icons on a KPI box. When using the data source with a KPI table, the data source must be created in the save-to-database file that is being used to populate the table.

The tags for the data source are as follows:

Primary tag

[KPIMenu;DataSourceName]

The DataSourceName identifies this data source so that it can be assigned to a KPI in a KPI Panel. Data source names must be unique within a file and must start with a letter. Names can only contain letters, numbers, and underscores. Names are validated when the file is saved; an invalid name will prevent the save.

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

[MenuItem]

Each row flagged with this tag defines an item to display in the menu.

Column tags

[ID]

An ID that uniquely identifies each row in the data source. The ID can consist of numbers, text, or a combination of both, as long as it is unique for each row.

[Name]

The name of the menu item. This is the text that displays on the menu. The user clicks on the text to execute the menu item.

[Icon]

The name of an icon to display in the menu for this menu item. Enter any valid icon name, such as fa-bar-chart. The icon names are the same as the symbol names available for use in Axiom form components such as Formatted Grids.

To look up valid icon names, you can use the symbol choosers available for Formatted Grid, Label, and Button components. Currently, no helpers are available to populate the Icon column with icon names directly.

[Tooltip]

Optional. Defines text to display in a tooltip when a user hovers their cursor over the menu item.

[Command]

The command to execute when a user clicks the menu item. For more information, see Valid command strings for use in KPIs.

[Disabled]

Optional. Specifies whether the item is disabled on the menu (True/False). The default value is False if omitted or blank.

If True, then the item continues to display on the menu, but it is grayed out and cannot be selected. This option can be used to dynamically enable or disable a menu item based on a condition.

[Hidden]

Optional. Specifies whether the item displays on the menu (True/False). The default value is False if omitted or blank.

If True, then the item does not display on the menu. This option can be used to dynamically show or hide a menu item based on a condition.

NOTES:  

  • The primary tag must be placed in the first 500 rows of the sheet.
  • Formulas can be used to create the tags, as long as the initial bracket and identifying keyword are whole within the formula. For more information, see Using formulas with Axiom feature tags.

The following example data source defines a KPI menu with two items:

Example KPIMenu data source

To use the Data Source Wizard to add the tags, right-click a cell and select Create Axiom Form Data Source > KPI Menu. You can right-click a single empty cell to place the initial tags and then fill out the data, or you can have the data already in the spreadsheet and highlight the applicable data to add the tags. The cells in the row above the data and the column to the left of the data must be blank in order for Axiom to place the tags in sheet.

The resulting menu would display on the KPI as follows:

Example fly-out menu on KPI 

If the KPIMenu data source only contains one visible item, then that item displays directly in the top right corner of the KPI box, using the specified icon.

Saving KPIMenu values when using a KPI table

You can use a KPIMenu data source when saving KPI values to a KPI table. To do this, the save-to-database file that you use to save KPI data to the table must be set up as follows:

  • The file must contain a KPIMenu data source. This data source is set up as normal, on any sheet of the file.
  • When setting up Save Type 1 in the file, the contents of the MenuData column must contain the following special syntax to specify the KPIMenu data source to save: [Datasource=DataSourceName].

For example, imagine that you have a KPIMenu data source named Menu, and you want to associate that data source with a KPI titled Expense. In the data to be saved to the database, the MenuData column for that KPI must contain the text [Datasource=Menu].

Example save-to-database using special syntax to save KPI menu data

When the save-to-database is executed, Axiom Software finds the designated KPIMenu data source, and converts the contents of it into an XML string. That XML string is then saved to the MenuData column in the KPI table. When the KPI table is used with a KPI Panel component, the XML string is used to render the menu on the KPI box.

The MenuData column in KPI tables can only accept the special data source syntax when saving to the database using Save Type 1. If any other contents are present in the MenuData column within the sheet (even the resulting XML syntax), an error occurs when saving. If you want to modify and save the other columns in the table without modifying the MenuData column, then the MenuData column must be omitted from the save.