Thing Definition Insight Metrics

  • 4 minute(s) read

Thing insights can be computed by defining Insight Metrics for a specific Thing Definition.
An Insight Metric is based on the execution of an Algorithm, which can be built-in or a custom one.

The value of an Insight Metric is automatically computed every day for each thing after the midnight considering the time-zone of the thing, and only one value per computation period is saved. For more details, refer to the Insights Computation article.

An Insight Metric is like any other metric, with a saved data point for each day, and the same ways to access and use historical data.

Creating an Insight Metric

To add a new Insight Metric on a Thing Definition, you should:

  1. Enter the Insights / Insight Metrics page.

  2. Select the Thing Definitions tab.

  3. Select the Thing Definition to edit.

  4. Press the Add Metric button.

  5. Select the Algorithm you want to use for computation.
    Only algorithms that have the usage equal to Thing Definition Insight Metric can be selected.

  6. Press the Save button and edit the additional information.

Editing an Insight Metric

The Insight metric is described by the following sections, some of which relate to the binding of the algorithm, while others are used to configure the standard properties of the metric.

Algorithm

Reports the algorithm that was chosen, with the option to jump to its documentation (built-in) or definition (custom).

Inputs

This section allows you to configure the inputs of the selected Algorithm.

Inputs can be static, where a value used for all calculations must be entered, or dynamic, where values come from, for example, a metric.

For each input, according to the type, you have to configure it:

  • STRING: a text string must be provided.

  • INTEGER: an integer number must be provided.

  • FLOAT: a float number must be provided.

  • BOOLEAN: true or false must be selected.

  • METRIC: a thing-definition metric must be selected.

  • LOCATION METRIC: a location metric must be selected.

  • EVENTS: no need to be configured.

  • WORK SESSIONS: no need to be configured.

In case there are inputs of type METRIC, LOCATION METRIC, EVENTS or WORK SESSIONS, in addition, you can specify the Date Range to be extracted and passed to the Algorithm (e.g. Last 24 hours). The end instant of the selected date range always refers to past midnight relative to the time at which the insight computation takes place.

Output

This is the Algorithm output to be read once executed and saved as the value of the metric.

By changing the output, also other metric properties may change, for instance, the Name, the Value Type, and relative Dictionary or Ranges.

General

This section allows defining the basic metric information.

  • Label: the label displayed in the DPS pages.

  • Name: the name of the metric, also used to reference it within the page templates.

  • Description: the text describing the metric, and displayed as a tooltip within the pages.

  • Unit: the unit of measurement (e.g. Kg, °C, pieces, liters...etc.)

  • Value Type: the type of the metric values, one of Boolean, Double, Float, Integer, Long, String.

    The type is automatically selected according to the chosen Algorithm output type.

  • Group: the group the metric belongs to (e.g. Temperatures, System).
    Used to organize and search metrics in the console, and used by widgets (e.g. Metrics Data) in the DPS.

  • Privatizable by customer: the flag allowing the customers to make the metric private.
    For more details refer to the Privatizable data article.

Computation Period

The period used to compute the insight metric and save samples, possible values are: 1 Day, 1 Month, 1 Year. For more details, refer to the Insights Computation article.

Data

In case of numeric metrics, the Data Type allows you to define whether the metric values are DISCRETE or CONTINUOUS, and then you can also define Dictionary and Thresholds.

Range

In case the metric is of type numeric, in this section, you can specify the minimum and maximum values the metric can assume. Minimum and maximum values can also be dynamically redefined by specifying a property or a metric for them. In case you are using a dynamic range, remember to specify a static range that at least contains the dynamic one.

These values are used to define thresholds (CONTINUOUS data type), and are used into widgets to display additional information:

Reset

  • Manual Reset: if checked, the metric can be manually reset from the Thing Details widget.

  • Reset Value: the value to be saved when a reset occurs.
    Note that, the reset value is also applied when a Factory Reset occurs.

  • Editable Reset Value: if checked, when the user reset the metric, the reset dialog allows providing the new value. The provided value is validated according to the configured range (Min and Max values).

Try Insight Computation

Once you have configured the algorithm you want to use for computing the Insight, you can test its execution by using the Try Insight Computation button.

By clicking on the button, a popup allows you to select the Customer, Location and Thing where to test the execution.

When the context has been provided, you can push the Try button to execute the algorithm, the next page will show you the Result and Logs.