Creating KPI rules

Edit online

Use the Rule builder to create a KPI rule from the user interface. The rule creates KPIs that provide insights into trends across events or business objects.

About this task

To define the rule, you specify the JSON payload for the KPI through the Rule builder by using the following JSON format:

{
	"instructions": {
		"filter": {
			"EQUALS": [{
					"SELECT": [
						"",
						""
					]
				},
				{
					"VALUE": [
						"",
						""
					]
				}
			]
		},
		"reduce": {
			"output": {
				"resultAlias": "",
				"resultType": ""
			},
			"expression": {
				"fieldPath": "",
				"type": "",
				"operator": ""
			}
		},
		"window": {
			"timeWindows": [
				""
			],
			"fieldPath": ""
		},
		"dimension": [{
			"fieldPath": "",
			"type": ""
		}]
	}
}

The JSON payload includes the following objects and arrays:

Filter: Filters data with a given expression.
Reduce: The mathematical operation that calculates the KPI. In the example, the mathematical operation is a sum. The final value is calculated when the time window elapses.
Window: The time window of the calculation. In the example, the calculation runs at minute intervals.
Dimension: If a dimension is specified, a separate KPI is calculated for each value of the dimension. In the example, a separate KPI is calculated for EDI documents of type 850 and 856.

For information about the complete set of nodes in the JSON payload, see the KPI rule language topic.

Procedure

In the rule library, click New rule.
Create a definition for the rule. From the Define rule page:
1. Enter a name for the rule, which is visible to general users in your organization. You can edit the name later.
  For example, Daily document volume.
2. Review the logical name for reference.
  The logical name of the rule uniquely identifies it in the system. This value is automatically generated based on the text that you enter in the name field, but you can change the logical name until you save the rule for the first time. The logical name must be a unique name.
3. Enter a description of the rule.
  This text displays next to the rule name in the rule library.
4. Select KPI as the rule type.
5. Optional: Activate the rule by setting the toggle to Active.
  Activating a rule makes it visible and available to others in your organization after you create it. Incomplete rules are not visible to general users even if they are activated. Rules must be both complete and activated to display for others. If you deactivate a rule that is active, it is no longer available for others to use.
Define the rule from the Configure page.
Add a JSON payload by using the format in payload. In the example, the total document volume for each document type is calculated at the end of each day from the document size.
Click Save.

Results

When the rule is met, a businessRuleEvent is sent to record the KPI.

Example

The following rule calculates the total document volume in KB every day. The result is stored as dailyDocumentVolume. The object model has two types of EDI documents, 850 and 856. The rule calculates the total document volume for each EDI document type.

{
    "instructions": {
        "filter": {
            "EQUALS": [
                {
                    "SELECT": [
                        "eventCode",
                        "String"
                    ]
                },
                {
                    "VALUE": [
                        "objectUpsertEvent",
                        "String"
                    ]
                }
            ]
        },
        "reduce": {
            "output": {
                "resultAlias": "dailyDocumentVolume",
                "resultType": "long"
            },
            "expression": {
                "fieldPath": "eventDetails.eventSource.EDI.size",
                "type": "LONG",
                "operator": "sum"
            }
        },
        "window": {
            "timeWindows": [
                "day"
            ],
            "fieldPath": "timestampEventOccurred"
        },
        "dimension": [
            {
                "fieldPath": "eventDetails.eventSource.EDI.transactionType",
                "type": "STRING"
            }
        ]
    }
}

What to do next

You can query your data to verify that the KPI is created. Create a GraphQL query for businessRuleEvents by using the rule ID. Use the following query as a guide and replace the rule ID.

{
  businessRuleEvents(
    simpleFilter: {rule: {id: "8bd65191-782e-4360-b82a-d7f31d51bf29"}}
    cursorParams: {first: 1}
  ) {
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      cursor
      object {
        eventCode
        timestampEventOccurred
        timestampEventReceived
        eventDetails {
          rule {
            id
            name
          }
          dimensionValues {
            name
            value
          }
          values {
            name
            value
          }
        }
      }
    }
  }
}

Verify that KPI is available in the values array under eventDetails in the query result For example:

{
	"data": {
		"businessRuleEvents": {
			"pageInfo": {
				"hasNextPage": false
			},
			"edges": [{
				"cursor": "Yjg2MHM4ZDQtZDc3Ny0zZjg4LWFiNzEtYMQwYzU22TUzzjJj",
				"object": {
					"eventCode": "businessEvent",
					"timestampEventOccurred": "2023-01-20T23:20:00Z",
					"timestampEventReceived": "2023-01-20T07:54:00",
					"eventDetails": {
						"rule": {
							"id": "8bd65191-782e-4360-b82a-d7f31d51bf29",
							"name": "dailyDocumentVolume"
						},
						"dimensionValues": [{
								"name": "day",
								"value": "2023-01-20T23"
							},
							{
								"name": "eventDetails.transactionType",
								"value": "850"
							}
						],
						"values": [{
							"name": "dailyDocumentVolume",
							"value": "100"
						}]
					}
				}
			}]
		}
	}
}

You can also add the query definition to a dashboard card to display the KPI.