You are here:

AX1670

KPI Panel component for Axiom forms

Using the KPI Panel component, you can display key performance indicators (KPIs) in a series of easily readable, eye-catching panels. The design of the component is flexible to accommodate various numbers and display configurations.

The KPI Panel component displays each KPI using a primary value and several secondary supporting values. The panel can include an optional bullet chart that illustrates the primary value as compared to a target. The KPI can be flagged as trending up (positive) or trending down (negative), which is indicated using an arrow and a color (green for up, red for down). KPIs can also be configured to execute a command from an "action button" at the top right of the KPI box.

Defining a KPI panel is a two-part process that requires the following:

Creation of a KPISource data source in the spreadsheet to define the KPIs to display in the form. Each KPI displays as its own box within the overall KPI panel. Alternatively, you can use a KPI table to provide the KPI data to the component, instead of defining a data source.
Placement and configuration of a KPI Panel component on the Axiom form canvas.

NOTE: Your Axiom Software license determines whether you have access to this component. For more information, see Licensing requirements for Axiom forms.

Component overview

KPI Panel components must point to a defined set of KPI data. This data can be provided using either of the following options:

Use a KPISource data source in the spreadsheet. In this case, the component reads the KPI data from the spreadsheet. You can use any Axiom data query features to bring data into the spreadsheet and then perform calculations on that data as needed to arrive at the KPI data for the data source.

OR
Use a KPI table in the Reports Library. In this case, the component reads the KPI data directly from the table. The KPI data is never brought into the spreadsheet. This approach requires a KPI table to be present in the Reports Library, and that table must be populated with the desired KPI data using some other means. For example, you may have a separate report utility that runs periodically to calculate the KPI data and save it to the KPI table. For more information on KPI tables, see About KPI tables.

NOTE: This feature is only available to systems running Axiom Software version 2018.01.55 or higher.

The KPI Panel component depends on a predefined data structure so that it can automatically format and position the KPI data into a series of KPI boxes. KPI tables and the KPISource data source both use the same basic predefined structure to provide the KPI data. The following screenshot shows how this data structure maps to the presentation of KPI boxes in the component:

If the chart-related properties are not defined for a KPI, then the chart is omitted and the values, delta, and sign re-align as follows:

The KPI boxes are also impacted by the following properties:

Style: Determines the background color of the KPI box. In the previous examples, the style is blank.
Tooltip: Defines tooltip text for the command button.
Hidden: Specifies whether the KPI is hidden from components.
NumericType: Specifies the number format for the KPI values (Value 1, Value 2, Value 3). This only applies when using a KPI table. When using a data source, the number format is taken from the cell in the spreadsheet.
DeltaNumericType: Specifies the number format for the delta value. This only applies when using a KPI table. When using a data source, the number format is taken from the cell in the spreadsheet.
CalculatedDateTime: Specifies when the KPI was calculated. Displays on the title tooltip as Last Updated: CalculatedDateTime. This only applies when using a KPI table.

Sizing the KPI Panel on the canvas

The KPI Panel is a specialized panel component that is designed to show one or more KPI "boxes". The number of KPIs to display within the component depends on the KPI rows defined in the KPISource data source or in the KPI table.

The KPI Panel uses panel flow behavior to automatically position the KPI boxes within the component. You should size the KPI Panel component depending on how many KPIs are defined in the data source and how you want those KPIs to be arranged in the form.

For example, imagine that you have 3 KPIs and you want those KPIs to display in a horizontal bar. In that case, you should size your KPI Panel to be long and short, so that the KPIs all fit on the same "row" and flow horizontally:

If you want the KPIs to display as a vertical bar down the side of the form, you should size your KPI Panel to be tall and thin, so that each KPI flows down to a new "row":

If you want the KPIs to stack, size the KPI panel as wide as necessary to fit the number of KPI boxes that you want to display horizontally, and as tall as necessary to fit the number of KPI boxes that you want to display vertically.

The exact sizes necessary to fit the KPIs depend on the Child Padding X and Child Padding Y settings, which set the padding between each KPI box. Each KPI box is approximately 300px wide by 150px tall (plus the padding).

NOTE: The overflow behavior for the KPI Panel is set to Auto and cannot be changed. This means that if the number of KPI boxes exceeds the space allotted to the KPI Panel component, the component displays with a scroll bar to view the excess KPIs. The KPIs will not overflow the panel or be cut off as hidden.

Within the KPI Panel, the KPI boxes are ordered as follows:

When using a data source, the boxes are displayed in the order they are found in the data source.
When using a KPI table, you can specify a sort order for the boxes based on one or more columns in the table.

Data source tags

KPI Panel components can use a KPISource data source to define the KPIs to display in the component. The tags for the data source are as follows:

Primary tag

[KPISource;DataSourceName]

The DataSourceName identifies this data source so that it can be assigned to a KPI Panel component. 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

[KPI]: Each row flagged with this tag defines a KPI to display in the KPI Panel component. Each KPI row displays as a distinct KPI "box" in the form.

Column tags

[Title]

The title of the KPI, displayed at the top of the KPI box. The title typically indicates the type of KPI, such as Supplies Expense Variance or Customer Retention. Note that if the title is too long to fit on one line, it will not wrap to a second line. Instead, the text displays with an ellipses, and the user can read the full title text in the tooltip.

[TitleIcon]

Optional. The name of an icon to display in the KPI title. Enter any valid icon name, such as fa-dollar. The icon names are the same as the symbol names available for use in Axiom form components such as Formatted Grids. If specified, the symbol displays in the far left of the title, before the title text.

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 [TitleIcon] column with symbol names directly.

[Value1]

The primary value to highlight for the KPI. This value displays in large, bold font directly underneath the title. This is the value that you want to draw the most attention to. The value displays using the number format defined for the cell.

[Value2]

Optional. A secondary value to show for the KPI. Value 2 displays in smaller font to the left side of the KPI box, directly above the bullet chart. A label can be defined for this value, using the Value2Label column. The value displays using the number format defined for the cell.

The secondary values of Value 2 and Value 3 can be used to provide supporting information for the primary value or to provide additional information. For example, if the primary value is a variance, then Value 2 and Value 3 might display the actual and budget numbers used to calculate that variance. Or if the primary value is the actual number, then Value 2 and Value 3 might display the variance and the budget number to provide more context for the actual number. The values displayed are entirely user-definable.

[Value2Label]

Optional. The label for Value 2. The label precedes the value and displays with a colon, such as "Actuals: Value 2". The label should explain what Value 2 represents.

[Value3]

Optional. A secondary value to show for the KPI. Value 3 displays in smaller font to the right side of the KPI box, directly above the Delta value. A label can be defined for this value, using the Value3Label column. The value displays using the number format defined for the cell.

See the description of Value2 for more information.

[Value3Label]

Optional. The label for Value 3. The label precedes the value and displays with a colon, such as "Budget: Value 3". The label should explain what Value 3 represents.

[ChartTarget]

Optional. A value that defines the target line for the bullet chart. This value can be omitted if it is not needed on the chart, or if you are defining a KPI with no chart.

[ChartActual]

Optional. A value that defines the actual line for the bullet chart. This value is displayed using a red or green bar, where the color is determined by the Sign value. This value can be omitted if you are defining a KPI with no chart.

[ChartMax]

Optional. The maximum value of the bullet chart. The chart target and actual values are represented in relation to this maximum value. This value is required if you want to display a chart for the KPI. If you don't want to display a chart, omit this value.

For example, if the actual value is 100 and the maximum value is 1000, then the actual bar will only take up 1/10th of the bullet chart. But if the maximum value is 150, then the actual bar will take up 2/3rds of the bullet chart.

[Delta]

Optional. A value that illustrates the positive or negative measure of the KPI. This value can be omitted if not needed. If it is omitted and the KPI has a bullet chart, then the chart extends to fill the bottom area of the KPI box.

The value is displayed to the right of the bullet chart, in either red or green (as determined by the Sign value). The value displays using the number format defined for the cell.

The Delta value can be used to show a variance percent or a raw difference value. It can also be used to show the change in value since the last time the primary KPI value was measured.

[Sign]

Optional. Specifies whether the primary KPI value is trending up (positive) or down (negative). Enter either Up or Down. If omitted, Down is assumed.

If Up, then an up-arrow displays in front of the Delta value. The Delta value and the actual bar of the bullet chart display in green.
If Down, then a down-arrow displays in front of the Delta value. The Delta value and the actual bar of the bullet chart display in red.

[Command]

Optional. Specifies an action to execute when the user clicks the ... button in the top right corner of the KPI box. If a KPI does not have a defined command, no button displays on the box.

The action can be any of the following:

A URL (starting with HTTP/S) to open a web page, Axiom form, or web report.
A document shortcut (document://filepath) to a file in the Axiom Software file system.
A command from the Command Library. Multiple command strings can be used, separated by commas. You can use any command that is supported for use in Axiom forms, though some commands may not make sense to execute from a KPI Panel.

The command strings use the same syntax supported by the Button tag for Formatted Grid components. If the command string is invalid, no error displays and no action occurs when the button is clicked.

To create a valid command string, right-click the cell and select Axiom Wizards > Command Wizard. This opens the Shortcut Properties dialog. Click the [...] button to the right of the Shortcut Target box to open Axiom Explorer, then navigate to the Command Library to select a command. You can then configure the shortcut properties for the selected command. When you click OK, the command string is inserted into the cell.

[Style]

Optional. Specifies a color style to set the background color of the KPI box. The following Axiom color styles are supported (specify one per KPI): S1, S6, A11, A51, P5, P6, P7, P9, P10. When using darker background colors, the text in the KPI automatically adjusts to white.

[Hidden]

Specifies whether the KPI row is hidden from the KPI Panel (True/False). If omitted, False is assumed. You can use a formula in this property to dynamically show or hide the KPI based on some condition.

[Tooltip]

Optional. Defines a tooltip to display when a user hovers over the command button in the KPI box. The tooltip should tell the user what action will occur when the user clicks the button. If no command is defined, the button does not display and the tooltip is ignored.

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.

To use the Data Source Wizard to add the tags to a sheet, right-click in a cell and then select Create Axiom Form Data Source > KPI Panel. You can also highlight a range of data first and then use the wizard to add the tags around that data. The cells in the row above and the column to the left of the selected area must be blank in order for Axiom to place the tags in sheet.

The following example shows a sample KPISource data source tagged in a sheet:

Example KPISource data source

The resulting KPI Panel for the example data source shown above looks as follows:

As discussed in the previous section, the arrangement of multiple KPI boxes depends on the size of the KPI Panel component on the canvas. In this example, the KPI Panel has been sized long and short to display the three KPIs horizontally.

Once the KPISource data source has been added to the sheet, you can optionally use the Data Source Assistant to:

Add column and row tags to the data source. For general information on using the Data Source Assistant to add column and row tags, see Using the Data Source Assistant.
Review and complete column properties for each row in the data source. When your cursor is in a [KPI] row, all available column properties display in the Selection Editor. You can edit any property and that edit will be made in the corresponding cell of the data source.

Component properties

You can define the following properties for a KPI Panel component.

Component properties can be configured using the Form Assistant task pane or the Form Designer unless otherwise noted. All properties can also be defined on the Form Control Sheet directly if desired. For example, if you want a property to be dynamic depending on the result of a formula, you can define that formula in the control sheet. To access the control sheet settings for the component, double-click any property name to go to that property in the Form Control Sheet.

Component behavior properties

The following properties control the display and behavior of this particular component type.

Item	Description
Data Source	The data source to provide the KPI data for the component. You must have defined the KPISource data source within the file using the appropriate tags in order to select it for the grid. NOTE: In the Form Control Sheet, the selected data source is written as SheetName!DataSourceName. The sheet name is the sheet where the selected data source is located. If a data source is already specified and you want to locate it within the file, click the Show location button to the right of the drop-down list. This will move your cursor to the associated data source tag in the file. NOTE: KPI Panel components can use either a data source or a KPI Table. If you specify a data source, the table-related properties are hidden in the Form Assistant and Form Designer. If you later decide you want to switch from using a data source to a table, you must clear the data source name in order to show the table-related properties.
KPI Table	The KPI table to provide the KPI data for the component. Enter any KPI table name. Only KPI tables can be used in this context, because KPI tables contain the necessary columns that map to the properties used by the KPI Panel component. For more information on KPI tables, see About KPI tables. NOTE: KPI Panel components can use either a data source or a KPI Table. If you specify a KPI table, the Data Source property is hidden in the Form Assistant and Form Designer. If you later decide you want to switch from using a table to a data source, you must clear the table name in order to show the Data Source property.
Data Filter	Optional. A filter to limit the KPIs shown in the component. Enter any valid filter criteria statement based on the specified KPI table. Only applies when using a KPI table. If no filter is defined, then all KPIs in the table will display in the component (except for rows with the Hidden column set to True).
Sort Order	Optional. One or more table columns to determine the sort order of the KPIs shown in the component. Specify any columns on the KPI table or a lookup table. Only applies when using a KPI table. Use fully qualified Table.Column syntax to specify each column. Separate multiple columns with semicolons. If multiple columns are specified, the first column is the top-level sort. You can optionally indicate ascending (asc) or descending (desc) sort after the column name. Ascending order is used by default. For example: `Dept.Region desc; Dept.Dept`.
Child Padding X Child Padding Y	Defines the x-padding and y-padding between KPI boxes. Child Padding X defines the horizontal padding between KPI boxes. It is applied to the right side of each box. Child Padding Y defines the vertical padding between KPI boxes. It is applied to the bottom of each box. The padding can be set in pixels (default) or in percentages.
Component Dependencies	Optional. Specifies one or more components that the KPI Panel component is dependent on. Only applies when using a KPI table. If you want the KPI panel to dynamically update based on changes made to other components, list one or more component names in this field. Separate multiple component names with commas. If a component name is listed here, then the KPI panel is refreshed when a form update submits a change to the listed component. If no component names are listed here, or if the listed components are unchanged, then the KPI panel is not refreshed when a form update occurs. Components listed as component dependencies must be interactive components, such as Combo Box components, Check Box components, and so on. The purpose of this option is that you want to enable refreshing the KPI panel based on a change a user made to an interactive component. Non-interactive components, such as Label components, cannot submit values back to the source file and cannot trigger form updates. Therefore, non-interactive components cannot cause the KPI panel to refresh. NOTE: Although basic Button components do not submit changed values, they can still be used as component dependencies. If a button uses the default Command behavior, then whenever the listed button triggers a form update, the KPI panel will be refreshed. However, if the button uses a specialized button behavior, or if the button uses a command that alters the normal form update behavior, then the button may not cause the KPI panel to refresh. For more information, see Update behavior.

General properties

The following general properties are available for all components:

Item	Description
Component Name	The name of the component. This is for identification in the file; this name does not display on the Axiom form canvas. The name of the component identifies the corresponding settings for the component on the Form Control Sheet. The component names are also useful if you have multiple types of the same component within an Axiom form, so that you can tell which component you are currently editing. Component 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. NOTE: Spaces are not allowed in component names and will be automatically removed by Axiom Software. For example, if you enter "My Component" as the component name, it will be automatically adjusted to "MyComponent".
Visible	Specifies whether the component is visible on the Axiom form (On/Off). By default this is set to On. This setting can be used to dynamically show or hide the component using a formula. Keep in mind that if you have multiple components that you need to dynamically show or hide based on the same condition, then it is preferable to place those components on a dedicated layer and then show or hide the entire layer instead of the individual components. NOTE: This setting is only available on the Form Control Sheet; it cannot be set in the Form Assistant or in the Form Designer.
Layer	The layer that the component belongs to on the Axiom form canvas. In the Form Assistant and the Form Designer, this displays as the layer name (for example: Layer 1). In the Form Control Sheet, this is recorded as the layer ID (for example: 1). If the canvas only has one layer, then the component is automatically assigned to that layer and cannot be changed. If the canvas has multiple layers, you can assign the component to any layer using the drop-down list. By default, the component will be assigned to whichever layer is selected in the Layers box when you initially drag the component onto the canvas. For more information on layers, see Using multiple layers on the canvas. If desired, you can jump to the applicable layer settings on the Form Control Sheet by clicking the binoculars icon next to the drop-down list.
Parent	The parent component that this component is assigned to. If blank, then the component does not have an assigned parent. Currently, only Panel components can be designated as parents. If a component has an assigned parent, then that component is positioned within the parent instead of within the canvas at large. If the parent is hidden, all "child" components of that parent are also hidden. The parent assignment is automatically completed when a component is dragged into a panel in the Form Designer, and automatically cleared when a component is dragged out of a panel. In most cases, you should not need to manually assign a parent. For more information, see Using panels to group and position components.

Style and formatting properties

To define the component formatting, you can assign one or more styles to the component. Styles can impact formatting properties such as fonts, borders, and colors.

If you do not want to apply a style to this component, or if you want to override one or more formatting properties in an assigned style, click the Show Advanced Settings link underneath the Style box to display the individual formatting properties. For more information on defining individual formatting properties for a component, see Formatting overrides for Axiom form components.

Currently, the Axiom Software platform does not provide any styles specifically designed for KPI Panel components. Only the generic styles are available. Most styling is controlled by the skin.

Item	Description
Style	Optional. The styles used to determine the formatting of the component. You can assign one or more styles. Click the Select component styles button [...] to open the Choose Style dialog. Using this dialog, you can select one or more styles to apply to the component. The available styles depend on the component type and the skin assigned to the form. For more information, see Using component styles. Some components have several styles that are specifically designed for that component type, while other components may only have the "generic" styles that are available to all components. When using a generic style, keep in mind that they may not be useful for all components. You can view a description of each style and view the effective formatting applied by the selected styles within the Choose Style dialog.
Component Theme	(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme. This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary. This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override. NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Item

Description

Style

Optional. The styles used to determine the formatting of the component. You can assign one or more styles.

Click the Select component styles button [...] to open the Choose Style dialog. Using this dialog, you can select one or more styles to apply to the component. The available styles depend on the component type and the skin assigned to the form. For more information, see Using component styles.

Some components have several styles that are specifically designed for that component type, while other components may only have the "generic" styles that are available to all components. When using a generic style, keep in mind that they may not be useful for all components. You can view a description of each style and view the effective formatting applied by the selected styles within the Choose Style dialog.

Component Theme

(Deprecated.) The theme to use for the component instead of the form-level theme. If left blank, the component uses the form-level theme.

This setting should be left blank unless you need to override the form theme. Generally speaking, themes should be set at the form level and only overridden at the component level when necessary.

This setting is available in the advanced component properties (click Show Advanced Settings under the Style box). On the Form Control Sheet, the setting displays using the name Theme Override.

NOTE: This setting only applies if your form uses a legacy skin (any skin except the default Axiom2018). The Axiom2018 skin does not use themes.

Position and size properties

You can view the position and size properties for a component by clicking the Show Advanced Settings link under the Style box. If necessary, you can edit these properties directly (instead of automatically modifying them by adjusting the component's position and size on the canvas). For more information on using these settings, see Controlling component position and size.

Item	Description
Reference Location	The reference location determines how the x-position and y-position of a component are evaluated. By default the reference location is UpperLeft. NOTE: This setting is not exposed in the advanced component settings. It can be changed on the canvas by double-clicking the corner selection handles of a component, or you can edit the setting on the Form Control Sheet directly.
X Position Y Position	The x-position determines the component's position along the horizontal axis, and the y-position determines the component's position along the vertical axis. Both are evaluated relative to the reference location. Positions can be set in pixels (default) or percentages.
Width Height	The width and height determine the size of the component. The width and height can be set in pixels (default) or percentages. Size keywords are also available to support special behavior.
Rendering Order	The order in which the component is rendered in the layer. A component with a larger order number will display above a component with a smaller order number. For components that support tab navigation (tabbing to the next editable component), the rendering order also determines the tabbing order. NOTE: On the Form Control Sheet, this setting is labeled as Z-Index.
Lock Layout	If enabled, the component size and position are locked and cannot be changed by dragging and dropping on the canvas. This optional setting is intended to protect against accidentally moving or resizing a component while working on the canvas.

Update behavior

The KPI Panel component uses two different types of update behavior, depending on the source of data for the KPIs:

Data source: When using a data source, the update behavior is the standard form update behavior. Each time a form update is triggered, the KPI Panel component is refreshed to reflect the current component settings and show the latest data in the data source.
KPI table: When using a KPI table, the KPI Panel component queries data from the Axiom Software database when the Axiom form is initially rendered. This data remains the same until one of the following occurs:
- If the form uses refresh variables, applying changed refresh variables via the Filters panel will refresh the KPI panel. This means that the KPI panel can be set up to change its data based on the selected value of a refresh variable.
- If one or more components are listed in the Component Dependencies property for the KPI panel, the KPI panel is refreshed when a changed value is submitted for one of those components. Otherwise, if no components are listed, or if no changes are submitted for listed components, then form updates triggered by interactive components do not cause the KPI panel to refresh.

This means that when a KPI table is used, standard form updates do not cause the KPI panel to refresh. By default, when an update is triggered in the form, the KPI panel is preserved as is. The component settings are not re-read and the data query is not run again. This behavior is intended to improve performance by not executing the data query and not redrawing the panel every time a form update occurs.

For example, imagine that the form contains a Combo Box component that is set to auto-submit. When a user selects a value from the combo box, this value is submitted to the source file and a form update is triggered. Under normal circumstances, if another component is configured to dynamically change based on the currently selected value for the combo box, this change would be reflected in the form once the form update is complete. However, the KPI Panel component does not update in this circumstance. Even if the selected value for the combo box impacts a KPI Panel property—such as the KPI table or the data filter—by default the KPI panel will not change during this form update.

If you want the KPI panel to update based on the selected value of the combo box, then you must list the name of the Combo Box component in the Component Dependencies property for the KPI Panel component. For example, if the Combo Box component is named ComboDept because it is used to select a department, you would list ComboDept as a component dependency.

Now when a change is submitted for the Combo Box component named ComboDept, the KPI Panel component is refreshed. The data query is run based on the current component properties. This occurs at the end of the form update process, when the form display is updated in the browser.

When a form update is triggered, Axiom Software checks to see if any component names are listed in the Component Dependencies property of the KPI Panel component. You can list multiple component names, separated by commas. If any components are listed, Axiom Software then checks to see if any changes to those components are included in the current form submission. If the listed components are unchanged, the KPI Panel component is not refreshed during the form update. If one or more of the listed components are changed, then the KPI Panel component is refreshed.

NOTE: The components in Component Dependencies do not have be set to auto-submit in order to refresh the KPI Panel component. If an interactive component is changed but it is not configured to auto-submit, then its change will be submitted when the next form update is triggered (either by a Button component, or by a different component that is configured to auto-submit). The KPI Panel component will still recognize the component change, even though the change was submitted by a different component.