KPI Configuration Example

Requirement Gathering

This example focuses on a KPI to capture shipments (from suppliers) that are expected to be delivered early. The following table captures more information about the logic needed by this KPI:

Requirement Mapping

With the business requirements collected in the table above, we can conduct the following mapping:

1. Specify the data model object to look at. The existing supply chain data model does support supply shipment entity, with object SupplyShipment. SupplyShipment object also has the required attributes for ETA (estimatedTimeOfArrival) and requested delivery time (requestedTimeOfArrival), thus no data model customization is needed. To learn more about data objects and attributes of each object in the supply chain data model, refer to data model API documentation. The result of this mapping gives us this part of the KPI definition:

   { 
       "baseObject": "SupplyShipment"
   }
   

   

2. Specify the cube to use for this KPI. Most of the KPI logic is implemented in cube design and cube mapping. For this step, InterSystems IRIS® provides powerful tools that support the following techniques, accessible to non-technical users:

   • Understanding the analytics cubes. KPI logic is based on the predefined analytics cubes; specifically, you use cube queries to identify sets of records and measures of interest. The prebuilt cubes provide easy access for information on common supply chain entities, such as sales orders, supply shipments, and inventory.

   • Cube mapping. In general, the cube whose primary base object matches the data objects for the KPI base entity should be used. In our example, we use the out-of-box cube SupplyShipmentCube, because its base object SupplyShipment matches the business entity shipments from suppliers. The result of this mapping gives us this part of the KPI definition:

   { 
       "deepseeKpiSpec":
       {
           "cube": "SupplyShipmentCube"
       }
   }
   

   

3. Specify the measure to use for this KPI. As mentioned above, a KPI measure must be a measure of the cube. The example KPI uses shipment count as the KPI measure. By default, all cubes have a measure for count. To find the exact name for the measure to use in a KPI definition, do the following:

   1. Open the cube in the Business Intelligence Analyzer.

   2. Drag and drop the measure from the left area (which shows the cube contents) to the Measures box on the right.

   3. Click the Display Query button on the toolbar. This displays the MDX Query window, which will then show a simple query like this example:

      SELECT [Measures].[%COUNT] ON 0 FROM [SUPPLYSHIPMENTCUBE]
      

      

      In this case, the name of the measure is %COUNT

   4. Use the measure name as the value of the kpiMeasure attribute within the KPI definition. The result is this part of the KPI definition:

      {
          "deepseeKpiSpec": 
          {
              "kpiMeasure": "%COUNT"
          }
      }
      

      

4. Describe the condition (possibly with multiple characteristics) that the KPI identifies. Ultimately the KPI condition is expressed as a set of MDX member expressions, which the system automatically combines via a logical AND. For common conditions, such as delivery status or order status and so on, the out-of-box cube design provides suitable dimensions. You can use the Analyzer to get these expressions:

   1. Clear any previous work in the Analyzer. (One option is to press the New button.)

   2. Expand the cube dimensions on the left, and drag and drop from there to the Filters box.

      For this example, the SupplyShipmentCube contains the dimension Actual Time of Arrival, which contains the members Delivered and InTransit. We drag InTransit and drop that into the Filters box. The same cube also contains the dimension Estimated vs Actual Time of Arrival, which has a status level that contains the members Early, OnTime, and Late. We drag Early and drop that into the Filters box.

      The Filters box then looks like this:

      

   3. Click the Display Query button on the toolbar. This displays the MDX Query window. In this case, it shows the following query, shown with an artificial line break:

      SELECT  FROM [SUPPLYSHIPMENTCUBE] %FILTER 
      NONEMPTYCROSSJOIN([estimatedVsRequestedDelivery].[H1].[status].&[Early],[actualTimeOfArrival].[H1].[value].&[<null>])
      

      

      In this case, the pivot table shows a crossjoin of the two MDX members we will use:

      • [estimatedVsRequestedDelivery].[H1].[status].&[Early]

      • [actualTimeOfArrival].[H1].[value].&[<null>]

      Notice that these are separated by a comma within the NONEMPTYCROSSJOIN function.

   4. Use these member expressions as items in the kpiConditions list, as in the following example:

      {
          "deepseeKpiSpec": {
              "kpiConditions": [
                  "[estimatedVsRequestedDelivery].[H1].[status].&[Early]",
                  "[actualTimeOfArrival].[H1].[value].&[<null>]"
              ]
          }
      }
      

      

5. If the KPI has the value type of percentage, also describe the base condition (for the denominator). The steps are the same as those in the previous step, except that now you specify the baseConditions property, as in the following example.

   {
       "deepseeKpiSpec": {
           "baseConditions": [
               "[actualTimeOfArrival].[H1].[value].&[<null>]"
           ]
       }
    }
   

   

6. Identify the KPI dimensions, which are the possible breakdowns of the KPI values. Each KPI dimension is expressed as an MDX level expression. You can use the Analyzer to get these expressions:

   1. Clear any previous work in the Analyzer. (One option is to press the New button.)

   2. Drag and drop the dimension or (level within a dimension) from the left area to the Rows box on the right. For example, drag and drop carrier.

   3. Click the Display Query button on the toolbar. This displays the MDX Query window. In this case, it shows the following query, shown with an artificial line break:

      SELECT NON EMPTY [carrier].[H1].[name].Members ON 1 FROM [SUPPLYSHIPMENTCUBE]
      
      

      

      In this case, the level expression is [carrier].[H1].[name]

      Members is the MDX function that displays the members, and you do not need that part of the syntax.

   4. Use this level expression within an object in the kpiDimensions array in your KPI definition as follows:

      {
          "deepseeKpiSpec": {
              "kpiDimensions": [
                  {
                      "name": "carrier",
                      "label": "Carrier",
                      "cubeDimension": "[carrier].[H1].[name]"
                  }
              ]
          }
      }
      

      

      In this object, the cubeDimension attribute must be the level expression you found, the name attribute is the local name of this KPI dimension for use in APIs, and the label attribute is only for display purposes.

   5. Repeat this step to get other KPI dimensions as needed.

7. Other KPI configuration data. This tutorial has covered the difficult part of the KPI configuration. The remaining should be fairly straightforward, as no additional mapping is required, and most information are collected in the business requirement section such as KPI name, description, and so on.

Final Result

The final KPI definition looks like the following:

{
    "name": "ExpectedEarlyDeliverySupplyShipment",
    "label": "Supply Shipment with Expected Early Delivery",
    "description": "Supply shipments which is expected to be delivered early",
    "baseObject": "SupplyShipment",
    "status": "Active",
    "watchingThreshold": 5,
    "warningThreshold": 10,
    "issueKpi": true,
    "defaultIssueSeverity": 2,
    "analysisService": "Early Arrival Process",
    "type": "DeepSee",
    "deepseeKpiSpec": {
        "namespace": "SC",
        "cube": "SupplyShipmentCube",
        "kpiMeasure": "%COUNT",
        "valueType": "percent",
        "kpiConditions": [
            "[actualTimeOfArrival].[H1].[value].&[<null>]",
            "[estimatedVsRequestedDelivery].[H1].[status].&[Early]"
        ],
        "baseConditions": [
            "[actualTimeOfArrival].[H1].[value].&[<null>]"
        ],
        "kpiDimensions": [
            {
                "name": "carrier",
                "label": "Carrier",
                "cubeDimension": "[carrier].[H1].[name]"
            },
            {
                "name": "supplier",
                "label": "Supplier",
                "cubeDimension": "[supplier].[H1].[name]"
            },
            {
                "name": "toCountry",
                "label": "Ship to country",
                "cubeDimension": "[shipToLocation].[H1].[country]"
            }
        ]
    }
}

You can use the following API to submit the JSON payload to create the KPI:

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

Once the KPI is defined, you can query the KPI value with API calls, such as:

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