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.
