Knowledge Model

Celonis Product Documentation

Knowledge Model - KPIs

Key Performance Indicators (KPI) are one of the most important tools to measure the status quo as well as the development of key organizational characteristics. KPIs summarise crucial performance information into one (typically numerical) value. The calculation is performed against a particular data set.

What do they do?

The KPI segment contains all KPI definitions including a human-readable name, its PQL formula, and a description. KPIs can be referenced from other KPIs and can also take Knowledge Model variables, runtime Variables, or KPI parameters into account.

How are they used?

KPIs are frequently used by components such as KPI List, KPI Bowler, and Chart.

KPI Visual Editor

The screenshot on the right shows the creation tab for a new KPI.

The Create KPI tab contains Knowledge Model KPI definitions and associated value assignments. These associated value assignments are the following:

Display Name: A human-readable label used in the user interface.
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.
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.
Parameters: See the parameters section on this page for more information.
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 Knowledge Model 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.

After defining Display Name, ID, and description the PQL statement has to be defined. In this section you are able to reference variables in the following way:

Runtime Variable:
- ${{my_runtime_var}}

Knowledge Model Variable:
- ${my_km_var}

Parameter:
- {p1}

Please notice the preview section in the bottom which gives you a preview of the currently defined KPI.

Parameters - Knowledge Model KPIs

      - show: true
        kpi: TOTAL_INVOICE_VALUE_Param
        order: 100
        kpiParams: 
            - id: Factor # This ID must match KPI parameter ID defined in KM
              value: "50"

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.

Note

Remember that for a parameter to be referenced in the PQL formula field, it must be identified not by its ID or Display Name, but instead by its parameter placeholder ({p1}, {p2}, etc.)

Referencing KPIs from KPIs

The following example shows calling a KPI inside another KPI. The same example can be found for YAML at the bottom of this page.

Parametrized KPIs

The following example shows creating a parametrized KPI & calling it inside another KPI. The same example can be found for YAML at the bottom of this page.

The following example shows creating a parametrized KPI & calling it inside another KPI while giving an array as input.

KPI Targets

You can define KPI target values directly in the Knowledge Model 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 Knowledge Model 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' Learn how to call parametrized KPIs inside other KPIs and how to set the parameters dynamically from the Views.	no	List of parameter definitions
filterIds	DEPRECATED: Currently they have no functionality and will be fully deactivated soon.

Referencing KPIs from KPIs (YAML)

The following example shows how to use YAML to call a KPI inside another KPI and create a parametrized 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)

Parametrised KPIs (YAML)

The following example shows how to use YAML to call a KPI inside another KPI, or create a parametrized KPI and call it inside another KPI:

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 Views. The following example depicts a snippet of 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"

The following example shows:

calling a KPI inside another KPI
Creating a parametrized KPI and calling 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)

Was this helpful?

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