KPI Method Overview

addKpi

The addKpi method is mandatory for creating a new KPI, as it initializes the widget in the associated report.

Syntax:

$olap.addKpi(
    "kpi_id",
    "title_label",
    "time_column",
    "time_interval",
    "target_value",
    "real_value",
    "yellow_budget_rate",
    "green_budget_rate",
    "trend_icon_mode",
    "data_filter"
)

Example:

$olap.addKpi(
    "OR_YTDM",
    "Operating Revenue (Year-To-Day-Month)",
    "[time_month_no]",
    "YTDM",
    "SUM(CASE WHEN [time_year] = ?period.getYear(-1) AND [dim_1] BETWEEN '3000' AND '3999' THEN [accounted_amount_dcur] * -1 ELSE 0 END) * (1 + 0.1)",
    "SUM(CASE WHEN [time_year] = ?period.getYear() AND [dim_1] BETWEEN '3000' AND '3999' THEN [accounted_amount_dcur] * -1 ELSE 0 END",
    "0.8",
    "1.0",
    "1",
    "[dim_1_profit_or_loss_account] = 1"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	A user-defined unique identifier for this KPI. The kpi_id specified here must be passed as an argument to subsequent methods
title_label	Yes	The text label displayed as the title of this KPI
time_column	Conditional	Specifies the column containing time-related data. Must match the period format specified in time_interval. Set to NULL if not required
time_interval	Conditional	Delimits the time interval for the data used in the method. Valid arguments: YTD (default), NULL, TP, TPM, YTDM, 12M. Set to NULL if not required
target_value	Yes	Defines the target or benchmark for the KPI. Typically used for comparison with the actual value. Set to 0 if no target is required
real_value	Yes	Defines the actual (realized) value of the KPI to be compared against the target. Typically contains the expression for the current performance metric
yellow_budget_rate	Yes	Defines the percentage of the budget at which the KPI color-status changes from red to yellow. Must be lower than green_budget_rate. Set to NULL if not required
green_budget_rate	Yes	Defines the percentage of the budget at which the KPI color-status changes from yellow to green. Must be higher than yellow_budget_rate. Set to NULL if not required
trend_icon_mode	Yes	Controls how trend indicators and icons are displayed for the KPI. Set to NULL if not required. Valid arguments: 0 = Icon only, 1 = Icon and trend line, 2 = Trend line only, 3 = No icon or trend line
data_filter	Yes	General filter expression to limit which data is included for the KPI. Set to NULL if not required

Mutual Dependency

The column value used in time_column must match the period format specified in time_interval. For example, when comparing different years between target_value and real_value, you need to select TPM or YTDM.

setKpiSource

Overrides the default data source for a KPI, allowing it to retrieve data from an alternative table or view. This is useful when KPI data is stored in a different dataset than the report’s main data source. Using filter and drill functionality works if the dimensions are equally named (same column names).

Syntax:

$olap.setKpiSource(
    "kpi_id",
    "alias_key",
    "matrix_name"
)

Examples:

// Same database
$olap.setKpiSource(
    "Operating Revenue (Year-To-Day-Month)",
    "fact_general_ledger"
)

// External database
$olap.setKpiSource(
    "Operating Revenue (Year-To-Day-Month)",
    "mssql",
    "fact_general_ledger"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
matrix_name	Yes	The name of the alternative data source table or view
alias_key	No	The connection key for an external database if the data source is in a different database

setKpiSize

Defines the width of the KPI widget for different screen sizes, using Bootstrap grid classes. This enables responsive layouts so KPIs look good on mobile, tablet, and desktop devices.

Syntax:

$olap.setKpiSize(
    "kpi_id",
    "xs_size",
    "sm_size",
    "md_size",
    "lg_size"
)

Example:

$olap.setKpiSize(
    "Operating Revenue (Year-To-Day-Month)",
    "XS12",
    "SM3",
    "MD3",
    "LG3"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
xs_size	Yes	Width of the KPI on extra small screens (mobile). Valid arguments: XS1, XS2, …, XS12
sm_size	Yes	Width of the KPI on small screens (tablets). Valid arguments: SM1, SM2, …, SM12
md_size	Yes	Width of the KPI on medium screens (desktops). Valid arguments: MD1, MD2, …, MD12
lg_size	Yes	Width of the KPI on large screens (large desktops). Valid arguments: LG1, LG2, …, LG12

setKpiFormat

Defines the display format for a KPI value (e.g., number of decimals, thousand separators, percentage signs).

Syntax:

$olap.setKpiFormat(
    'kpi_id',
    'value_format'
)

Example:

$olap.setKpiFormat(
    'Operating Revenue (Year-To-Day-Month)',
    '###,##0.00'
)

Single Quotes Required

For this method, you must use single quotes (”) around arguments instead of double quotes ("") due to syntax requirements.

When applying a percentage format, do not scale ratios by multiplying by 100. The value should always remain in the range 0–1. The formatting logic will handle the conversion automatically.

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
value_format	Yes	The display format for the column value, using standard formatting syntax (e.g., number of decimals, thousand separators, percentage signs)

setKpiColors

Sets custom colors for a KPI based on its status thresholds (e.g., red = poor, green = good).

Syntax:

$olap.setKpiColors(
    "kpi_id",
    "blue_color",
    "green_color",
    "orange_color",
    "red_color"
)

Example:

$olap.setKpiColors(
    "Operating Revenue (Year-To-Day-Month)",
    "blue",
    "green",
    "orange",
    "red"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
green_color	Yes	The color for KPI values above green_budget_rate (good performance)
yellow_color	Yes	The color for KPI values between yellow_budget_rate and green_budget_rate (warning)
red_color	Yes	The color for KPI values below yellow_budget_rate (poor performance)

setKpiIcons

Sets the image for a KPI widget, changing dynamically based on whether the KPI is in red, yellow, or green color-status. Available images: FontAwesome

Syntax:

$olap.setKpiIcons(
    "kpi_id",
    "red_image",
    "yellow_image",
    "green_image"
)

Example:

$olap.setKpiIcons(
    "Operating Revenue (Year-To-Day-Month)",
    "frown_o",
    "meh_o",
    "smile_o"
)

Icon Names

Images with hyphens (-) in the name must be written with underscores (_). Example: user-circle-o becomes user_circle_o.

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
red_image	Yes	Image to display when KPI value is below yellow_budget_rate
yellow_image	Yes	Image to display when KPI value is between yellow_budget_rate and green_budget_rate
green_image	Yes	Image to display when KPI value is above green_budget_rate

setKpiTargetRealName

Changes the default display names for the target and actual (real) values in a KPI widget. Useful for giving the KPI more user-friendly labels.

Syntax:

$olap.setKpiTargetRealName(
    "kpi_id",
    "target_label",
    "real_label"
)

Example:

$olap.setKpiTargetRealName(
    "Operating Revenue (Year-To-Day-Month)",
    "Budget",
    "Actual"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
target_label	Yes	The custom label to display for the target value
real_label	Yes	The custom label to display for the actual value

setKpiTargetRealDisplayField

Replaces the KPI’s numeric target and actual values with custom text labels. This is useful when the KPI should display a status message instead of numerical values.

Syntax:

$olap.setKpiTargetRealDisplayField(
    "kpi_id",
    "target_value",
    "real_value"
)

Example:

$olap.setKpiTargetRealDisplayField(
    "Operating Revenue (Year-To-Day-Month)",
    "50 000 000",
    "~ 43 000 000"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
target_value	Yes	Text to show instead of the real target value
real_value	Yes	Text to show instead of the real actual value

setKpiStyleSize

Sets the text style size for a KPI widget, adjusting how large the value appears.

Syntax:

$olap.setKpiStyleSize(
    "kpi_id",
    "style_size"
)

Example:

$olap.setKpiStyleSize(
    "Operating Revenue (Year-To-Day-Month)",
    "tiny"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
style_size	Yes	Defines the text size. Valid arguments: huge (default), large, normal, small, tiny

setKpiNegativePositiveLine

Enables a trend line in the KPI widget that uses dynamic colors: red for negative values and green for positive values, regardless of KPI thresholds.

Syntax:

$olap.setKpiNegativePositiveLine(
    "kpi_id"
)

Example:

$olap.setKpiNegativePositiveLine(
    "Operating Revenue (Year-To-Day-Month)"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update

setKpiPlotLine

Adds a horizontal plot line at value = 0 in the KPI’s trend line chart to highlight the neutral threshold. This method depends on the trend-line being activated.

Syntax:

$olap.setKpiPlotLine(
    "kpi_id"
)

Example:

$olap.setKpiPlotLine(
    "Operating Revenue (Year-To-Day-Month)"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update

hideKpiTargetInfo

Hides the target value information from the KPI widget, showing only the actual (realized) value.

Syntax:

$olap.hideKpiTargetInfo(
    "kpi_id"
)

Example:

$olap.hideKpiTargetInfo(
    "Operating Revenue (Year-To-Day-Month)"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update

setKpiUrlLink

Adds a clickable link to the KPI widget that navigates to a report or another internal URL when the link is clicked.

Syntax:

$olap.setKpiUrlLink(
    "kpi_id",
    "internal_url"
)

Example:

$olap.setKpiUrlLink(
    "Operating Revenue (Year-To-Day-Month)",
    "x35_109"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
internal_url	Yes	The clickable link. Part of or the full internal URL (e.g., report reference). The full internal URL in the example: http://localhost:18080/demo/ui#!x35_109

setKpiExternalUrlLink

Adds a clickable external URL to a KPI widget. When the user clicks the link, they are redirected to the specified web address.

Syntax:

$olap.setKpiExternalUrlLink(
    "kpi_id",
    "external_url"
)

Example:

$olap.setKpiExternalUrlLink(
    "Operating Revenue (Year-To-Day-Month)",
    "https://www.deem.no/en/"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
external_url	Yes	The clickable link. The full external URL

setKpiFilterCollection

Controls how filters and OLAP-actions (slice, dice, drill and pivot) affect a KPI. You can choose whether the KPI responds to all filter scope, only header filters, or remains static.

Syntax:

$olap.setKpiFilterCollection(
    "kpi_id",
    "olap_scope"
)

Example:

$olap.setKpiFilterCollection(
    "Operating Revenue (Year-To-Day-Month)",
    "header"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update
olap_scope	Yes	Defines which OLAP-actions affect the KPI. Valid arguments: all = Respond to all actions, header = Respond only to header actions, report = Respond only to report-level actions

setKpiHideIfNull

Hides the KPI widget from the dashboard if its value is NULL (empty or not calculated).

Syntax:

$olap.setKpiHideIfNull(
    "kpi_id"
)

Example:

$olap.setKpiHideIfNull(
    "Operating Revenue (Year-To-Day-Month)"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update

setKpiHideIfZero

Hides the KPI widget from the dashboard if its calculated value is zero (0).

Syntax:

$olap.setKpiHideIfZero(
    "kpi_id"
)

Example:

$olap.setKpiHideIfZero(
    "Operating Revenue (Year-To-Day-Month)"
)

Parameters:

Parameter	Required	Description
kpi_id	Yes	The unique identifier of the KPI to update

Related

• Intro KPIs - Overview of KPI documentation
• KPI Wizard - Using the KPI wizard
• KPI Examples - Practical examples
• Graphs, Tables and KPIs - Overview of all widgets