Skip to main content

Celonis Product Documentation

KM - Advanced / YAML

Info

Currently, certain configurations of the KM can only be reached via YAML.

YAML

For advanced users, there is also the option to configure KMs with YAML files. YAML (“Yet Another Markup Language”) is a standardized, human-readable general-purpose markup language. YAML provides a way to represent (i.e. describe and annotate) data. YAML can be used within the Studio to specify KMs as well as Apps. For further information on YAML please refer to the official website here.

Please click the corresponding button in the top right corner of the screen to reach the YAML version of the KM.

57542450.png
KM Meta Information

A KM consists of different segments. The first segment in YAML contains the required meta-information about the KM. The modeling primitives of a Knowledge Model will be extended over time. As of now, the following modeling primitives are supported.

57542451.png

Kind (required)

This segment is a single field that indicates whether the current KM is an independent KM ("BASE") or an extension of an existing KM ("EXTENSION").

Example: Meta Information

kind: BASE

Metadata (required)

The metadata segment contains information that is required for the processing and handling of the KM by the Studio application such as a unique key to reference the KM and a human-readable display name.

Example: Meta Information

Metadata: 
  key: ACCOUNTS_PAYABLE_OPERATIONAL_APP_DEMO_EXTENSION 
  displayName: AP Operational App Demo Extension 
  version: 2.0.9

Data Model ID (required)

The Data Model ID is used to reference the data model which contains the underlying data. Inside the Data Model ID field, you can add the data model runtime variable using the ${{variable-key}} notation.

Example: Meta Information

dataModelId: ${{demo-ap-execution-app}}

For each KM there can be only one Data Model at the same time. To gain data from multiple Data Models, you can either switch between Data Models with runtime Variables or use multiple Knowledge Models within a single view (one per component).

YAML Cheatsheet
  • YAML relies on indentation for structure. Thus, correct indentation is very important.

  • Scalars are defined using a colon and a space.

    Examples:

    id: OTD_KPI 
    displayName: "On-Time Delivery KPI" 
    order: 100
  • The preferred way to define lists of values is by Block Format (separating the list items by hyphens).

    Example:

    kpis: 
      - id: OTD_KPI 
      # remaining fields of the KPI definition 
      - id: AUTOMATION_RATE_KPI 
      # remaining fields of the KPI definition 
      - id: REWORK_RATE_KPI 
      # remaining fields of the KPI definition
  • Strings such as PQL statements can be denoted in five ways:

    • Plain Scalar

      displayName: On-Time-Delivery

      Attention: Plain scalar without (double) quotes can conflict with YAML syntax. Thus, it is highly encouraged to not use plain scalars for strings such as PQL statements.

    • Single Quoted (' ')

    • Single quotes in the string itself need to be escaped by doubling it (' is escaped as '')

      displayName: 'On-Time-Delivery'
    • Double Quoted (" ")Double quotes in the string itself need to be escaped using a backslash (" is escaped as \"). Furthermore, only double-quoted strings may contain escape sequences like \n for a new line.

      displayName: "On-Time-Delivery"
    • Literal Block Scalar (|)

      The content of a literal block scalar starts after the pipe symbol in a new line and needs to be intended.

      description: | 
        This is 
        a 
        multiline text
    • Folded Block Scalar (>)

      The content of a folded block scalar starts after the > sign

      description: > 
        This is a long line 
        split into short lines
  • Since (double) quotes are both YAML primitives as well as PQL primitives, you might encounter situations where the YAML parser has difficulty disambiguating (double) quotes correctly.

  • Comments

    Inline comments with a leading # are not supported in YAML. However, every KM object has a field called 'internalNote' which can be used for documentation and comments.

    Example KPI configuration

    kpis: 
      - id: _open_invoices 
            displayName: "# Open Invoices" 
            description: Open Invoices 
            internalNote: This is my documentation for complicated things which is not visible to business users. 
            pql: COUNT(DISTINCT "RSEG"."_CASE_KEY")