Skip to main content

Introduction to the KPI API

InterSystems Supply Chain Orchestrator™ provides an analytics APIOpens in a new tab for the supply chain KPIs, including the initial configuration step. This page introduces the API calls that apply to KPIs.

KPI Definitions

To find all defined KPIs, use the following API (no parameter required)

GET {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/definitions

To define a new KPI, use the following API call:

POST {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/definitions

With the following JSON in the message body:

    "name": "KPI name",
    "description": "KPI description",
    "type": "DeepSee",
    "baseObject": "SC base object for the KPI, such as SalesOrder",
    "status": "Status value, such as Active/Inactive",
    "watchingThreshold": xx,
    "warningThreshold": yy,
    "deepseeKpiSpec": {
    "namespace": "IRISnamespace",
    "cube": "KpiCubeName",
    "kpiMeasure": "cubeMeasure",
    "valueType": "raw/percentage",
    "kpiConditions": [
        "MDX condition 1",
        "MDX condition 2"
    "kpiDimensions": [
                "name": "dim1",
                "cubeDimension": "MDX dimension expression"
                "name": "dim2",
                "cubeDimension": "MDX dimension expression"

Common KPI definition attributes are:

Attribute Required Description
name Yes KPI name, alphabetic string without any space or other characters. name must be unique within the same deployment.
description No KPI description
type No Type of KPI definition. Currently only one type is supported: DeepSee. More can be supported in the future.
baseObject Yes The supply chain object the KPI is based on, such as SalesOrder or SupplyShipment.
status Yes The status of the KPI definition, such as Active, Inactive, etc.
watchingThreshold No Threshold value for the watching level
warningThreshold No Threshold value for the warning level
resolutionService No Host name (within the supply chain production) of the business service that performs issue resolution for this KPI

Here are detailed descriptions of the KPI specification:

Attribute Required Description
cube Yes cube name
valueType No Value type, must be raw or percentage. Default value is raw, which means the same value as provided in the corresponding cube measure.
kpiMeasure No Cube measure in MDX format for the KPI. If not specified, the corresponding Count measure of the cube is used.
kpiConditions No List of MDX filter values, which is used to define KPI conditions. If no value is provided, the KPI gets the total measure, such as total number of orders, or total revenue.
baseConditions No This is used when the KPI value type is percentage. This set of MDX filter values determines the denominator of the KPI, while the KPI numerator is determined by combining this set of conditions together with the set of conditions defined in kpiConditions
kpiDimensions No This attribute is used to keep track of a set of dimensions that can be used in the scope of the KPI. The name of each dimension is used to do KPI filtering or breakdowns.

There are other API calls related to KPIs:

  • Get the definition of a specific KPI:

    GET {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/definitions/{KPI_NAME}
  • Update a KPI definition. Use this API call with body with same format as used for creating a new KPI.

    PUT {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/definitions/{KPI_NAME}
  • Delete a KPI definition

    DELETE {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/definitions/{KPI_NAME}

KPI Values

To get a KPI value without any dimension expansion, use the following API call:

GET  {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/values/{KPI_NAME}

The response may look like:

    "kpiName": "kpiName",
    "values": [
            "label": "kpi",
            "value": xxx

To get KPI values with breakdown by a dimension:

GET  {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/values/{KPI_NAME}?expandDimension={dimName}

and the response may look like:

    "kpiName": "kpiName",
    "expandDimension": "dimName",
    "values": [
            "label": "dim-value-label1",
            "value": x1
            "label": "dim-value-label2",
            "value": x2

This API call can be used for UI to show a chart to see the breakdown of the KPI, such as late shipment by region.

Detail Listings for KPIs

To get the source records related to a KPI, you can use the following API call:

GET {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/listings/{KPI_NAME}

The response is a list of the source records. For example, a late ship order KPI listing request returns a list of orders which were shipped late. This API call accepts typical pagination parameters as well as sorting parameters.

Filtering KPIs

For any KPI defined, one can apply additional filter to a API call to get KPI values or listings. An KPI filter is a REST parameter kpiFilter, with value in the form of (dimName1,value1),(dimName1,value2),.... You can have any number of filter name-value pairs as needed, but for a given dimension, there can be at most one name-value pair in a filter. Any dimension used in kpiFilter must be defined in the KPI definition, under kpiDimensions. Another limitation: if a dimension is used in expandDimension, the same dimension should not be used in the filter. Other than that, one can use expandDimension together with kpiFilter in the same API call to get KPI values.

The following is an example of a KPI request with a filter defined in the request:

GET  {{IRIS-SERVER-URL}}/api/scbi/v1/kpi/values/OrderLateShip?kpiFilter=(productFamily,iPhone),(region,EMEA)

which retrieves Late ship order KPI value for product family iPhone, in the region EMEA.

See Also

FeedbackOpens in a new tab