Skip to main content

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 variables, runtime Variables, or KPI parameters into account.

An example of KPIs being used in a Studio view:

KPI_list_example_1.png
Creating KPIs in the Knowledge Model

Within the Knowledge Model, the KPI assets contains all KPI definitions including a human-readable name, its PQL formula, and a description.

To create a KPI:

  1. Click Studio and then open the package containing the Knowledge Model you want to create the KPI in.

  2. Select KPIs and then click Create KPI.

    Create_KPI.png
  3. Configure your KPI value assignments and settings. For an overview of available value assignments and settings, see: KPI value assignments and settings.

  4. Click Save.

    The KPI is added to your Knowledge Model and available to use in your related content.

When configuring your Knowledge Model 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 knowledge model, toggling this on allows other team members to edit this KPI when it is used in extension knowledge models.

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

When creating or editing your Knowledge Model 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 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.

kpitarget.png

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'

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"