KPI Editor

Overview

Sight Machine's KPI Editor allows for the dynamic calculation of Key Performance Indicators (KPIs) within the Sight Machine semantic layer, all at run-time. Perform dynamic calculations across different bins and attributes, ensuring flexibility and adaptability in monitoring performance metrics.

Accessing KPI Editor

To access KPI editor, navigate to the /dev page, available at https://<environment-name>.sightmachine.io/dev and then click KPI Editor.

Create your first KPI

1. Select Workspace: Choose any workspace in your environment.

2. Create KPI: Click the “Create New KPI” button on the top left corner.

3. Configure Parameters: Follow the editor's instructions and use the preloaded example to create your KPI.

4. Validation: A green validation indicates a “Valid KPI.” If there's an error, a message will appear below with details.

Configuring KPIs

Sight Machine supports two types of KPIs: Machine Type KPIs and Line KPIs.

What are Machine Type KPIs?

Machine Type KPIs are designed to evaluate the performance of individual machines or compare performance across multiple machines of the same type. These KPIs are ideal for monitoring metrics like machine efficiency, uptime, or output rates. Each KPI is specific to a machine type and can only reference attributes within that machine type.

Machine Type KPI Fields

• 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_conditions (optional): Conditional logic for row-by-row values (optional), containing:

      • cases: List of sorted cases, each with:

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

        • op: Comparison operator. It must be one of lt, lte, gt, gte, eq, ne, in, nin, startswith, not, exists, contains, like, notlike, overlaps

        • value: Value if condition is met, and can either be literal, raw field name, or an expression.

        • then: If the result is a raw field name with whitespaces then use the format column['<raw field name>'] to represent it. For example _column['stats__Name with space__val']

      • else: Result if no conditions are met. and can either be literal, raw field name, or an expression. If the result is a raw field name with whitespaces then use the format column['<raw field name>'] to represent it. For example _column['stats__Name with space__val']

• 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".

Machine Type KPI Restrictions

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

{
  "name": "yield",                  // The unique name of the KPI.
  "display_name": "Yield",          // The display name of the KPI. Should be unique.
  "formula": "cans_out/cans_in",    // The KPI formula. Variables here are generic--they are assigned aggregate functions in `dependencies`, and mapped to columns in `field_maps`.
  "dependencies": [                 // Specifies aggregate functions for the variables in the formula.
    {
      "name": "cans_out",           // Variable name as referenced in the formula 
      "aggregate": "sum"            // Aggregate function for the variable. Aggregate functions include: sum, min, max, avg.
    },
    {
      "name": "cans_in",
      "aggregate": "sum"
    }
  ],
  "field_maps": [
    {
      "alias_map": {                // Maps the KPI dependencies to actual database column names
        "cans_out": {               // "cans_out" is the name of a dependency
          "name": "stats__COUT__val", //stats__COUT__val is a column name in the machine_type tables listed in `machine_types`
          "row_conditions": {       // (optional) key for when value of column varies according to row-by-row conditional logic
            "cases": [              // Array of case objects. Cases are checked in the same order as the array.
              {
                "name": "net_cycle_time", // Must be a column name
                "op": "eq",               // Comparison operator. can be any of: lt, lte, gt, gte, eq, ne, in, nin, startswith, not, exists, contains, like, notlike, overlaps
                "value": 0,               // Literal, not column name
                "then": 0                 // Value if condition is met. Can either be literal, column name, or an expression. If the value is a column name with whitespaces then use the format _column['<column name with spaces>'] to represent the column name. eg: _column['stats__Name with space__val']
              }
            ],
            "else": "stats__COUT__val"    // Value of the column when no conditions are met. Can either be a literal, column name, or an expression. If the value is a column name with whitespace then use the format _column['<column name with spaces>'] to represent the column name. eg: _column['stats__Name with space__val']
          }
        }
      }
    },
  ],

  // Rollups are used when computing aggregate KPIs for lines and factories on the homepage
  "rollups": {
    "factory": {
      "ETL3_Atlanta": ["Packer1", "Packer2"]   // To compute the yield for the factory ETL3_Atlanta, aggregate the yield of the machines "Packer1" and "Packer2"
    },
    "line": {
      "Processing_line1": ["Packer1"],         // To compute the yield for Processing_line1, use the yield of the "Packer1" machine
      "Processing_line2": ["Packer2"]          // To compute the yield for Processing_line2, use the yield of the "Packer2" machine
    }
  },
  "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.

What Are Line KPIs?

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.  

Line KPI Fields

• 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_conditions (optional): Conditional logic for row-by-row values (optional), containing:

      • cases: List of sorted cases, each with:

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

        • op: Comparison operator. It must be one of lt, lte, gt, gte, eq, ne, in, nin, startswith, not, exists, contains, like, notlike, overlaps

        • value: Value if condition is met, and can either be literal, raw field name, or an expression.

        • then: If the result is a raw field name with whitespaces then use the format column['<raw field name>'] to represent it. For example _column['stats__Name with space__val']

      • else: Result if no conditions are met. and can either be literal, raw field name, or an expression. If the result is a raw field name with whitespaces then use the format column['<raw field name>'] to represent it. For example _column['stats__Name with space__val']

  • 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".

Line KPI Restrictions

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.

Troubleshooting

• All configuration must be valid JSON. Follow these rules:

  • Use double quotes instead of single quotes.

  • Do not use trailing commas.

  • Do not add comments.

• Units of Measure:

  • Be aware that the units of duration fields displayed in the Data Table are configurable, and may not reflect the actual units of the column. For example, the Data Table might say 1000 ms, but the value might actually be 1.

  • record_time and total are stored in milliseconds.

• If the value in the row_conditions else path or cases.then path is a column name with whitespaces, use the format column['<column name with spaces>'] to represent the column name.

  • For example: "column['stats__Downtime Type__val']"

• As a sanity-check, the actual value of your KPIs can be seen using the API GET /v1/selector/assets.

• Make sure all of your dependencies are mapped to db columns in a field_map.

• If your KPI queries are returning the wrong value, do the following:

  • Double-check the units of your KPI dependencies. Apply unit conversion in the formula as needed.

Debugging: