Skip to main content

Celonis Product Documentation

KM - KPIs

Introduction to KPIs
Why do they exist?

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

  • 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)

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

KPI1.png
Parameters

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

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

KPI3.png
Parametrised 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.

KPI4.png
KPI5.png
Parametrised KPIs with Array Parameter

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

KPI6.png
KPI7_1.png
YAML
Defining KPIs

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

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, or 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"

Using Parametrises KPIs

  1. The following example shows:

    • calling a KPI inside another KPI

    • Creating a parametrized KPI & 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)

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"
KPI7_1.png