Knowledge Model

Celonis Product Documentation

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.
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.

KPI value assignments and settings

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.

Writing PQL formulas for KPIs

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.

Defining KPIs with YAML

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"

Was this helpful?

Would you like to provide feedback? Just click here to suggest edits.