KPI Type Definitions

[This topic is pre-release documentation and is subject to change.]

Key Performance Indicators (KPIs) represent quantifiable measures and key insights about business data or processes, or aspects thereof. A KPI type is defined over a Profile or Interaction for each step of a business workflow or as a cumulative measure of a business process. A KPI can also be defined over other KPIs, this type of KPI is referred to as a KPI on KPI. KPIs are defined with a set of basic built-in functions, and are recomputed every 15 minutes over a specified rolling time period, called a calculation window. KPIs have a number of other characteristics, which can be modified through the UI or programmatically, such as the associated metric unit, filters, threshold values, grouping values, and KPI aliases.

KPIs can also capture more complicated secondary relationships between Interactions and Profiles through the use of Links and Relationships.


Property names appended with asterisks* are required.

KpiDefinition properties

Property JSON type Description
kpiName string Name of the KPI (readonly)
entityType* string Type of the associated entity: ["None" (KPI on KPI) | "Profile" | "Interaction" | "Relationship" ]
entityTypeName* string Name of the type on which the KPI is defined. Empty in the case of a KPI on KPI
function* string KPI computation function: ["None (KPI on KPI)" | "Sum" | "Avg" | "Min" | "Max" | "Count" | "CountDistinct"
expression* string KPI computation expression. This is '*' in case the function is "Count". Otherwise, any mathematical expression composed of the properties in the profile/ interaction type/alias can be used here. The expression should evaluate to a number. In case of a KPI on KPI, this will be an expression composed of other KPI names
calculationWindow* string Time window over which the KPI computation will be done. : ["Lifetime" | "Hour" | "Day" | "Week" | "Month"]
calculationWindowFieldName string By default, for an interaction KPI, the KPI Time is based on the interactions' timestamp property. This calculationWindowFieldName field is used to explicitly declare the DateTimeOffset field name of the interaction that should be used instead for KPI Time
filter string This expression will be used to filter out data before computation is done.
groupBy string[ ] Specifies the dimensions for the KPI. Up to 14 dimensions are supported.
aliases KpiAlias[ ] Aliases for the current KPI (see below). Up to 50 aliases are supported.
extracts KpiExtract[ ] Extracts for the KPI (see below). Up to 50 extracts are supported.
unit string Measurement unit for the KPI
thresHolds KpiThresholds KPI threshold limits (see below)
displayName dictionary Localized display name(s) for the property
description dictionary Localized description of the KPI
provisioningState string KPI provisioning state: ["Provisioning" | "Succeeded" | "Expiring" | "Deleting" | "HumanIntervention" | "Failed" ] (readonly)
groupByMetadata KpiGroupByMetadata[ ] Specifies the metadata for the groupby properties (readonly, see below)
participantProfilesMetadata KpiParticipantProfilesMetadata[ ] Participant profiles (readonly, see below)
tenantId string Hub name (readonly)

KpiAlias properties

Property JSON type Description
aliasName* string KPI alias name
expression* string Alias expression; Aliases allow using complex operation expressions as fieldnames in KPI expression; Aliases support set operations (Union, Intersect, CrossApply), date functions and string functions.

Example1: ColumnName1*ColumnName2
Example2: Union(ColumnName1, ColumnName2, .. ColumnNameN)
Example3: Intersect(ColumnName1, ColumnName2, .. ColumnNameN)
Example4: CrossApply(ColumnName1, ColumnName2, .. ColumnNameN)
Example5: CountElements(ColumnName1, ColumnName2, .. ColumnNameN)
Example6: DateAdd(day, 4, date1)
Example7: DateDiff (month, date1, date2)
Example8: DateTimeUtcNow()
Example9: StartsWith(ColumnName1, ColumnName2)
Example10: Contains(ColumnName1, ColumnName2)

KpiExtract properties

Property JSON type Description
extractName* string KPI extract name. Extracts allow using complex operation expression as fieldnames to extract information from relationship graph
expression* string KPI extract expression.

For KPIs on profiles: TRAVERSE(RelationshipTypeName).FILTER(ProfileFieldName == ‘Field1’).SELECT(ProfileFieldName)
>For KPIs on interactions: TRAVERSE(LinkTypeName).TRAVERSE(RelationshipTypeName).FILTER(ProfileFieldname == ‘Field1’).SELECT(ProfileFieldName)

Example1: TRAVERSE(RelationshipTypeName).SELECT(profileFieldName)
Example2: TRAVERSE(RelationshipTypeName,DEPTH(5)).SELECT(profileFieldName)
Example3: TRAVERSE(RelationshipTypeName).FILTER(ProfileFieldname == ‘Field1’).SELECT(profileFieldName)
Example4: TRAVERSE(RelationshipTypeName,DEPTH(2)).FILTER(ProfileFielname == ‘Field1’).SELECT(profileFieldName)
Example5: TRAVERSE(LinkTypeName).TRAVERSE(RelationshipTypeName,DEPTH(2)).FILTER(ProfileFielname == ‘Field1’).SELECT(profileFieldName)

The output of an extract statement is an array which can be used as extractName.profileFieldName. For example, to count the number of elements returned by an extract, use alias expression: CountElements(extractName.profileFieldName)

KpiGroupByMetadata (readonly) properties

Property JSON type Description
displayName dictionary Localized display name(s) for the property
fieldName string Name of the field
fieldType string Type of the field

KpiParticipantProfilesMetadata (readonly) properties

Property JSON type Description
typeName string Name of the type

KpiThresholds properties

Property JSON type Description
lowerLimit decimal* Lower threshold limit
upperLimit decimal* Upper threshold limit
increasingKpi* boolean True if the increasing KPI values are desirable

JSON example

    "aliases": [{
        "aliasName": "customer",
        "expression": "CrossApply(Customers.customerName)"
    "calculationWindow": "Day",
    "entityType": "Profile",
    "entityTypeName": "BranchProfile",
    "expression": "SavingAccountBalanceField",
    "function": "Sum",
    "groupBy": "customer",
    "kpiName": "TotalSavingsKpi",
    "extracts": { "ExtractName": "Customers", "Expression": "TRAVERSE(branch_customer_relationship).SELECT(customerName)" }
    "thresHolds": {
        "increasingKpi": true,
        "lowerLimit": 5.0,
        "upperLimit": 50.0
    "unit": "USD"