Knowledge Model - KPI
Key Performance Indicators (KPI) are a quantifiable measure of performance over time for a specific objective. KPIs can be displayed in Studio apps using components such as KPI List and charts, as well as being referenced from other KPIs. They can also take Knowledge Model (KM) variables, runtime Variables, or KPI parameters into account.
An example of KPIs being used in a Studio View:
 |
Creating KPIs in the Knowledge Model
Within the KM, the KPI assets contains all KPI definitions including a human-readable name, its PQL formula, and a description.
To create a KPI:
Click Studio and then open the package containing the KM you want to create the KPI in.
Open the KM you want to create the KPI for.
Select KPIs and then click Create KPI.
Configure your KPI value assignments and settings. For an overview of available value assignments and settings, see: KPI value assignments and settings.
Click Save.
The KPI is added to your KM and available to use in your related content.
Within your Knowledge Model, you can see where your KPIs are being used and referenced:
View usage: This displays the Studio Views where this KPI is being used, with a shortcut to open the View provided. This doesn't display where the KPI is used within an Analysis or if it's included as part of an extended Knowledge Base.
Entity references: This displays where the KPI is referenced in other business entities, such as calculated attributes, filters, and variables. This doesn't display where the KPI is referenced in extended Knowledge Models.
 |
When deleting KPIs, you'll also be warned if deleting the KPI impacts existing Views or entities:
 |
When configuring your KM KPIs, the following value assignments are available:
Display Name: A human-readable label used in the user interface.
Short Display Name: A human-readable label used in the user interface when the browser is minimized or below a certain resolution.
ID: A technical identifier used for unique referencing of this KPI.
Description: A human-readable description for the KPI.
Internal Note: A human-readable description used for documentation of PQL.
Allow other analysts to edit KPI from extension KM: Only available when editing a base KM, toggling this on allows other team members to edit this KPI when it is used in extension KM.
PQL Formula: Refers to the value you want this KPI to reflect. This can be either a hard-coded number, a KPI formula, or a parameter. For more information, see: Writing PQL formulas for KPIs.
Parameters: Using parameters enables part of the formula to be replaced by a value defined by the end-user. For more information, see: Referencing parameters in KPIs using PQL.
Format: Defines the format in which the KPI should be presented (rounded, percentage, decimal, date, etc.) This can be selected from a dropdown list or input manually as text input.
Unit: Symbol that will be attached to resulting KPI. Often used to represent add a currency symbol to the KPI.
KPI Desired Direction: Defines the desired direction of the KPI's trend (Up or Down Trend).
Default KPI Target: Sets a KPI target directly in the KM using a PQL statement.
Allow users to update the target from Views: Toggle button to allow overwriting the Default Target from Views.
Scope: Indicates where in the Package the KPI can be used. If a KPI's scope is disabled then the KPI cannot be accessed and used anywhere in a package.
You can manage existing Knowledge Model objects by clicking the Options icon:
 |
You then have the following options per object:
Disable scope: By disabling the scope of an object, the object then can't be used anywhere within the package. This is a good option if you want to disable an object but delete it from your KM.
Duplicate: This opens the create object window with the configuration of the object you are duplicating used as a template. When saving a duplicate object, the object ID must be unique.
Delete: This deletes the object from the KM and any references to that object in existing content. When deleting an object, there is no undo or recovery option.
When creating or editing your KM KPIs, you can define the PQL formula for it. This uses the PQL editor, enabling you to translate process-related business questions into queries. This includes using runtime and KM variables, parameters, and KPI targets.
Note
KPIs and records cannot have comments at the end of the PQL statement in the editor window. If the final line of code is a comment, you will not be able to save the KPI/record and a syntax error will display in the Preview section at the bottom of the tab.
Referencing variables in KPIs using PQL
To reference variables in KPIs, use the following formats:
Runtime variable:
'${{my_runtime_var}}'Knowledge Model variable:
'${my_km_var}'Referencing parameters in KPIs using PQL
Parameters are used to abstract a part of the KPI's PQL formula. This enables part of the formula to be replaced by a value defined by the end-user. Parameter definition has the following arguments:
Display Name: A human-readable label for the parameter.
ID: A technical identifier used for unique referencing of this KPI.
Default Value: Value which each of the parameters should have.
Parameters can be referenced in PQL using its parameter placeholder, for example:
{p1}
{p2}
{p3}Referencing KPI target values in KPIs using PQL
You can define KPI target values directly in the KM by using a PQL statement. When using PQL to set targets, you can take advantage of dynamic and filterable values in the View, unlocking new use cases. Furthermore, you have the option to determine whether the target is editable by end-users within the View or not.
 |
A KPI is specified within the KPIs segment in the KM and is defined by the following fields:
Field name | Description | Required? | Expected value |
|---|---|---|---|
id | A technical identifier that is used for unique referencing. | yes | Alphanumerical, no spaces |
displayName | A human-readable label that is used in the user interface. | yes | String |
description | A human-readable description. | String | |
pql | The PQL query statement. | yes | String: PQL statement |
desiredDirection | Specifies the normative judgment of KPI developments. Is the KPI desired to INCREASE or DECREASE? If neither applies, NONE can be used. | no, only if used inside the anomaly component | One of the following values: INCREASE, DECREASE, NONE |
defaultTarget | Sets a KPI target directly in the KM using a PQL statement. | no | String: PQL statement |
allowTargetUpdate | Option to allow overwriting the Default Target from Views | no | Boolean: true/false |
unit | Specifies the unit of the KPI. | no | See Formats and Units. |
format | Specifies the display format of the KPI. | no | See Formats and Units. |
parameters | Specifies the list of (optional) required KPI parameters. A parameter definition consists of an id, a displayName and a defaultValue. The parameter can be referenced in the pql field via single curly brackets and its id. For instance, parameter param1 can be referenced in the pql statement via {param1}. The following example shows a KPI definition that sets up a parameterized KPI called 'RATIO' which defines a generic ratio calculation that accepts a single parameter called param1. - id: RATIO
displayName: Ratio
pql: SUM(CASE WHEN {p1} THEN 1.0 ELSE 0.0 END)/COUNT(ISNULL(CASE WHEN {p1} THEN 1.0 ELSE 0.0 END))
parameters:
- id: p1
displayName: "First parameter"
defaultValue: "# the value the parameter should have as the default' | no | List of parameter definitions |
Referencing KPIs from KPIs using YAML
The following example shows how to use YAML to call a KPI inside another KPI. It also shows you how to create a parameterized KPI and call it inside another KPI:
kpis:
- id: TOTAL_INVOICE_VALUE
displayName: Total Invoice Value
description: ""
pql: SUM(CASE WHEN "BKPF"."BELNR" IN ('9330002454','9330001796','9330002109')
THEN "BSEG"."WRBTR_CONVERTED" * 0.3 WHEN MONTH("BKPF"."CPUDT") = 4 THEN
"BSEG"."WRBTR_CONVERTED" * 3.1 ELSE "BSEG"."WRBTR_CONVERTED" END)
unit: ""
format: ""
#kpi calling the previous one
- id: "TOTAL_INVOICE_VALUE_CALL"
displayName: "Total Invoice Value Call"
description: ""
pql: KPI(TOTAL_INVOICE_VALUE)Parameterized KPIs using YAML
The following example shows how to use YAML to call a KPI inside another KPI, or create a parameterized KPI and call it inside another KPI:
kpis:
- id: TOTAL_INVOICE_VALUE
displayName: Total Invoice Value
description: ""
pql: SUM(CASE WHEN "BKPF"."BELNR" IN ('9330002454','9330001796','9330002109')
THEN "BSEG"."WRBTR_CONVERTED" * 0.3 WHEN MONTH("BKPF"."CPUDT") = 4 THEN
"BSEG"."WRBTR_CONVERTED" * 3.1 ELSE "BSEG"."WRBTR_CONVERTED" END)
unit: ""
format: ""
#kpi calling the previous one
- id: "TOTAL_INVOICE_VALUE_CALL"
displayName: "Total Invoice Value Call"
description: ""
pql: KPI(TOTAL_INVOICE_VALUE)
# kpi defined with a parameter
- id: TOTAL_INVOICE_VALUE_Param
displayName: Total Invoice Value_Param
description: ""
pql: SUM("BSEG"."WRBTR_CONVERTED" * {p1} )
parameters:
- id: Factor
displayName: Factor Value
defaultValue: 10
# calling the KPI with parameter value
- id: TOTAL_INVOICE_VALUE_Param_Use
displayName: Total Invoice Value_Param
description: ""
pql: KPI(TOTAL_INVOICE_VALUE_Param, 50)kpis:
# kpi defined with a parameter
- id: TOTAL_INVOICE_VALUE_Param
displayName: Total Invoice Value_Param
description: ""
pql: SUM("BSEG"."WRBTR_CONVERTED" * {p1} )
parameters:
- id: Factor
displayName: Factor Value
defaultValue: 10
# calling the KPI with parameter value
- id: TOTAL_INVOICE_VALUE_Param_Use
displayName: Total Invoice Value_Param
description: ""
pql: KPI(TOTAL_INVOICE_VALUE_Param, 50)Setting KPI parameters from a View
The following example is based on a KPI list:
- show: true
kpi: TOTAL_INVOICE_VALUE_Param
order: 100
kpiParams:
- id: Factor # This ID must match KPI parameter ID defined in KM
value: "50"