Creating a Simple KPI - Developer Documentation
Skip to content

Creating a Simple KPI

Simple KPIs use time series data and can display up to one month of data. Here are some additional characteristics of simple KPIs:

  • Mathematical calculations are written in JavaScript and display the Formula window. At the end of this topic are two example KPIs-one demonstrates using math in a KPI, the other using JavaScript.
  • The name you give to a simple KPI must be unique within your organization.
  • You can select up to one month of data to display, and this selection is made in the "Select a variable" pop-up window.
  • Calculation cycles of 1 to 59 seconds and 1 to 90 minutes are supported.
  • Advanced calculation settings can specify time ranges, time zone, and which days to run.

Simple KPIs Limitations

The following limitations apply to simple KPIs:

  • Simple KPIs are for time series data only.
  • A KPI must include at least one input variable and no more than five.
  • The output variable must be created beforehand as part of the asset model configuration in Asset Manager.

Illustration of the Create a Simple KPI Page

Simple KPI

① Toggle to activate the KPI immediately
② Advanced calculation cycle settings

How to Configure the General settings for a Simple KPI

Follow these steps to configure the general settings for a simple KPI:

  1. Click the "Create a simple KPI" link at the top of the KPI page. The Create a Simple KPI page displays.
  2. If you do not want the KPI to be immediately available, slide the "Enabled" toggle to the left. The Enabled toggle turns gray and displays, "Disabled".
  3. Enter a value and select "seconds" or "minutes" for the calculation cycle.
  4. Select the "Use advanced settings" check box to set more specific settings. Additional configuration settings display.
  5. Select the time range, time zone, and days of the week to run the KPI.

Configuring the Input and Output Variables

When you select the input asset, its aspects display; when you select an aspect, its variables display. This is an example of the pop-up window in which you select time series data for your KPI input and output variables:

Select a variable

How to Configure the Input Variables

Follow these steps:

  1. If you plan to use an aspect with static variables, slide the "Use Static Variables" toggle to the right. The slider turns blue.
  2. Click the "Add Input" link. The Select a variable pop-up window opens.
  3. Select an asset. The asset's aspects display in the next column.
  4. Select an aspect. The aspect's variables display in the next column.
  5. Select the input variable you want to use in the KPI.
  6. Repeat step 4 to add additional input variables, up to five.
  7. Click "Select". The pop-up window closes and your input selection displays in the Inputs area of the KPI.

Note

If the application doesn't display the variables you expect, try selecting a longer time range from the Displayed Range drop-down list at the bottom of the Variables display.

How to Configure the Output Variables and Save the KPI

Follow these steps:

  1. Click the "Add Output" link. The Select a variable pop-up window opens.
  2. Select an asset. When aspects display, select an aspect.
  3. When variables display, select the output variable you want to use in the KPI.
  4. Click "Select". The pop-up window closes and your output selection displays in the Output area of the KPI.
  5. Using JavaScript, enter additional formula details in the formula section.
  6. Click "Save". The KPI is saved and the system displays a Success message.

An Example of a Simple KPI that uses Math

This example demonstrates a KPI that uses a math script to calculate the length of a vector from origin to point, using using a math script.

How to Create a KPI that Uses Math

Here is an image of the KPI settings:

Add KPI

Follow these steps to create a KPI that uses math:

  1. Click “Create a Simple KPI”.
  2. Enter "Milling-vector" in the Name field.
  3. Enter "Length of Vector" in the Description field.
  4. Enter "10 minutes" as the Calculation cycle.
  5. Select "T_L_A_Equipping > Machine_KPIs > Quality" for "in1".
  6. Select "T_L_A_Equipping > Machine_KPIs > Quality" for "in2".
  7. Select "T_L_A_Milling_CNC > KPI_Quality > Quality" for "out". Your formula will look like this:
    $const X = in1;const Y = in2;out = Math.sqrt(X * X + Y * Y)$
  8. Click Save.

Milling Vector KPI Output Results

The KPI output is listed on the KPIs page. You can add your KPI to a dashboard using the KPI widget. See Dashboards Actions for more information.

This illustrates the Milling Vector KPI on the KPIs page:

Dashboard actions

An Example of a Simple KPI that Uses JavaScript

This example demonstrates using JavaScript to calculate the speed of a CNC milling machine spindle.

How to Create a KPI that Uses JavaScript

Follow these steps to create a KPI that uses JavaScript:

  1. Click “Create a Simple KPI”.
  2. Enter "Speed" in the Name field.
  3. Enter "Spindle speed" in the Description field.
  4. Enter "10 minutes" as the Calculation cycle.
  5. Select "T_L_A_Equipping > Machine_KPIs > Quality" for "in1".
  6. Select "T_L_A_Equipping > Machine_KPIs > Quality" for "in2".
  7. Select "T_L_A_Milling_CNC > KPI_Quality > Quality" for "out". Your formula will look like this:
    const last = flow.get('lastSpeed'); if (last !== null && last !== undefined) { out = in1 - last;} if (in1 !== null && in1 !== undefined) { flow.set('lastSpeed', in1);}
  8. Click Save.

CNC Milling Machine Spindle Speed KPI Output

The KPI output displays on the KPIs page. You can add your KPI to a dashboard using the KPI widget. See Dashboards Actions for more information.

Dashboard


Last update: January 22, 2024