KPIs

Defining a Machine Type KPI

Machine Type KPIs are designed to evaluate the performance of individual machines or compare performance across multiple machines of the same type. These indicators play a key role in tracking metrics such as machine efficiency, uptime, and output rates. Each KPI is uniquely designed for specific machine types, referencing only attributes pertinent to that machine.

Configuring a Machine Type KPI

• name (required): Raw field name for the KPI.

• display_name (required): Display name for the KPI shown in the UI.

• formula (required): Mathematical expression to calculate the KPI.

• dependencies (required): List of objects specifying aggregate functions for the variables in the formula, which must have the same name.

  • name: Variable name as it will be referenced in the formula

  • aggregate:  Aggregate function for the variable. It must be one of sum, min, max, avg.

• field_maps (required): List of objects mapping KPI dependencies to actual database column names.

  • alias_map (required): Object mapping each dependency, using the name defined for it, to the raw field name. Multiple mappings are only required if different machine types map to dependencies differently

    • name (required): Raw field name (you can user Field Explorer to find this string)

    • machine (optional): Specific machine used for this KPI field. Each machine will have the KPI available to them

    • row_formula (optional): Applies per-row, pre-aggregation transformations to the KPI's dependencies--uses the same syntax as runtime fields.

• unit (optional): Unit of measure for the KPI (e.g., %, pounds).

• rollups (optional): Object containing mappings for factory and line rollups. Rollups are used when computing aggregate KPIs for lines and factories on the homepage.

  • factory: Mapping of factory names to machine lists.

  • line: Mapping of line names to machine lists.

• directionality (optional): Indicates if higher values are better ("positive") or lower values are better ("negative").

• good_threshold (optional): Threshold above which the KPI is considered "good".

• bad_threshold (optional): Threshold below which the KPI is considered "bad".

Restrictions on a Machine Type KPI

1. Machine Type KPIs are available within the KPI and Lines models but can only reference attributes within a given machine type.

2. Within the field_maps, Machine Type KPIs do not require a single machine to be specified for each dependency because they automatically retrieve and aggregate data from all machines in the query.

Machine Type KPI Example

{
  "bad_threshold": 60,
  "dependencies": [
    {
      "aggregate": "sum",
      "name": "Record_Duration"
    },
    {
      "aggregate": "sum",
      "name": "Duration_Planned_Downtime"
    }
  ],
  "description": "",
  "directionality": "positive",
  "display_name": "% Planned Downtime",
  "field_maps": [
    {
      "alias_map": {
        "Duration_Planned_Downtime": {
          "name": "stats__Duration Planned Downtime__val"
        },
        "Record_Duration": {
          "name": "stats__Duration (min)__val"
        }
      },
      "machine_types": [
        "mt_filler"
      ]
    }
  ],
  "formula": "((Duration_Planned_Downtime/Record_Duration)*100) if (Record_Duration > 0) else 0",
  "good_threshold": 80,
  "name": "percentage_of_time_in_planned_downtime",
  "rollups": {
    "factory": {},
    "line": {}
  },
  "unit": "%"
}
}

Defining a Line KPI

A Line KPI evaluates the productivity of an entire production line rather than individual machines. These KPIs are associated with a specific machine but take into account data and attributes from multiple machines along the production line. An example of a Line KPI is yield measurement, which could calculate the total output efficiency of a production line by comparing the input at the start of the line (first machine) with the output at the end of the line (last machine). This approach provides a holistic view of the production line's effectiveness in converting inputs to outputs.  

Configuring a Machine Type KPI

• name (required): Raw field name for the KPI.

• display_name (required): Display name for the KPI shown in the UI.

• formula (required): Mathematical expression to calculate the KPI.

• dependencies (required): List of objects specifying aggregate functions for the variables in the formula, which must have the same name.

  • name: Variable name as it will be referenced in the formula

  • aggregate:  Aggregate function for the variable. It must be one of sum, min, max, avg.

• field_maps (required): List of objects mapping KPI dependencies to actual database column names.

  • alias_map (required): Object mapping each dependency, using the name defined for it, to the raw field name. Multiple mappings are only required if different machine types map to dependencies differently

    • name (required): Raw field name (you can user Field Explorer to find this string)

    • machine (required): Specific machine used for this KPI field. Each machine will have the KPI available to them

    • row_formula (optional): Applies per-row, pre-aggregation transformations to the KPI's dependencies--uses the same syntax as runtime fields.

  • machine_types (required): List of machine types used in the KPI calculation.

• unit (optional): Unit of measure for the KPI (e.g., %, pounds).

• directionality (optional): Indicates if higher values are better ("positive") or lower values are better ("negative").

• good_threshold (optional): Threshold above which the KPI is considered "good".

• bad_threshold (optional): Threshold below which the KPI is considered "bad".

Restrictions on a Line KPI

1. Line KPIs are only available within the Line model and are not currently supported on the Homepage or applications that do not support the Line model (such as the Single Value Widget).

2. Within the field_maps, Line KPIs require a single machine to be specified for each dependency. This is the machine from which that dependency's data will be retrieved.

3. Line KPIs are automatically available to all machines used to calculate it, and the value is the same independently of which machine is selected to display it.  

Line KPI Example

{
  "name": "KPI_internal_name",
  "display_name": "KPI display name",
  "formula": "100*kpi field name 1/(kpi field name 1 + kpi field name 2) if (kpi field name 1 + kpi field name 2) > 0 else 0",
  "dependencies": [
    {
      "aggregate": "sum",
      "name": "kpi field name 1" // First KPI field name
    },
    {
      "aggregate": "sum",
      "name": "kpi field name 2" // Second KPI field name
    }
  ],
  "field_maps": [
    {
      "alias_map": {
        "kpi field name 1": {
          "machine": "Machine 1", // Specific machine used for this kpi field
          "machine_type": "Machine Type 1", // Machine type of the machine used for this kpi field
          "name": "stats__field_for_kpi_field_1__val"
        },
        "kpi field name 2": {
          "machine": "Machine 2", // Specific machine used for this kpi field
          "machine_type": "Machine Type 2", // Machine type of the machine used for this kpi field
          "name": "stats__field_for_kpi_field_2__val"
        }
      },
      "machine_types": [ // List of all machine types used in the KPI calculation
        "Machine Type 2",
        "Machine Type 1"
      ]
    }
  ],
  "unit": "%", // Used for color-coding on homepage
  "directionality": "positive",     // 'positive' means higher is better. 'negative' means lower is better.
  "good_threshold": 80,             // Threshold at which the KPI is "good"
  "bad_threshold": 60               // Threshold at which the KPI is "bad"
}

Note: The comments, delineated by //, are not considered valid JSON and you should remove them when configuring your KPI.