Simple metrics are used to receive and store RAW data published by products, machines, or sensors remotely connected to your application.

Simple metrics are used to store simple data, like measures and logical variables.

Creating a Simple metric

To add a new Simple Metric to a Thing Definition, you should:

Enter the RAW Data page.
Select the Thing Definitions tab.
Select the Thing Definition to edit.
Press the Add Metric button.
Select the Simple Metric type and provide the required information.
Press the Save button and edit the additional information, if needed.

Editing a Simple metric

Once a Simple Metric has been saved, you can configure more information on it.

A Simple Metric is described by:

General

Label: the metric label shown within the widget.
Name: the name of the metric, also used to reference it within the dashboards' templates.
Description: the text describing the metric. The description is displayed as a tooltip within the dashboard widgets.
Unit: the unit of measurement (e.g. Kg, °C, pieces, liters...etc.)
Value Type: the type of the value, one of Boolean, Double, Float, Integer, Long, String.
Pay attention to select the right type, if not, metric values may not be stored correctly.
Group: the group the metric belongs to (e.g. Temperatures, System).
Privatizable by customer: allow the customer to define whether the metric is private or not.
For more details, refer to this Privatizable date article.

Mapping

The mapping section of a metric you can configure:

Path: the path used to dispatch the incoming messages according to the underlying connection protocol, for instance in the case of MQTT this is the last part of the message topic.
Name: the name of the property to be extracted from the incoming message payload.
Value Encoding: the way the value is encoded within the payload (Literal, Binary HEX/INT).
For more details, see the article Encoding Values.
Value Transformer: the transformer to be applied to the decoded value before being saved in the data storage.
For more details, see the article Transforming Values.

Initial value

Into a Simple metric, you can configure the value to be assigned to the metric when the thing is created or activated the first time. The value is registered by using the creation/activation timestamp.

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.

Discarding invalid values

Suppose a thing produces data points with a frequency higher than the real need (e.g. ambient temperature sensor), unnecessary data points will be generated with the effect to consume DPH for Data Points Processing.

You can define whether to discard consecutive equal values received by the IoT Connector.

With this approach, the granularity of the data will be lowered, and therefore the current data (if missing) is to be considered equal to the previous data. In a time-series-chart widget, a STEP visualization is recommended in order to highlight changes in the series of data.

Out of range data points can be discarded, avoiding unexpected behaviors, like alerts and rules triggering or wrong widget visualization (e.g. spikes on time-series-chart widget).

Note that, only constant values are used to validate the incoming metric values. In case you are using a dynamic range, remember to specify a static range that at least contains the dynamic one.

Import/Export Metric Definitions

If you have many metrics to define, you can click on the Import button and select a CSV file containing all the information about the metrics you want to create.
In case a metric is already present (matching by name), it is updated with the new definition.
It is also possible to export all defined metrics; clicking the Export button will generate a CSV file.

The CSV file must have the following header:

Name,Label,Description,Group,Value Type,Unit,Initial Value,Mapping Path,Mapping Name,Encoding,Binary Position,Binary Length,Binary Byte Order,Value Transformer,Min,Max,Privatizable,Consecutive Equal Values Discarded,Countable Type,Dictionary,Ranges

Here are described the various columns to provide in the CSV:

Name: the name of the metric. It should contain only A-Z characters, numbers and ‘_’.
Label: the metric displayed label.
Description: the metric description
Group: the metric group.
Value Type: the type of the stored value.
Unit: the unit of measurement (e.g. kg).
Initial Value: the initial value to store under the metric when the thing is created (STRING, BOOLEAN, INTEGER, LONG, FLOAT, DOUBLE).
Mapping Path: the mapping path (default data).
Mapping Name: the mapping name (default is the name).
Encoding: how values are encoded in the incoming messages (LITERAL, BINARY_INT, BINARY_HEX).
Binary Position: the position of the first bit to read (BINARY encoding only).
Binary Length: the number of bits to read (BINARY encoding only).
Binary Byte Order: the byte orders (BIG_ENDIAN, LITTLE_ENDIAN) (BINARY encoding only).
Value Transformer: the name of the data transformer.
Min: the minimum value (numeric metrics only).
Max: the maximum value (numeric metrics only).
Privatizable: true if the metric can be privatized, else false.
Consecutive Equal Values Discarded: true to avoid duplicated value, else false.
Countable Type: how to handle numeric values (CONTINUOUS, DISCRETE).
Dictionary: the dictionary definition (DISCRETE countable type).
<THESHOLD_VALUE>:<LABEL>:<SEVERITY>:<ICON>|<THESHOLD_VALUE>…
The severity could be one of: NORMAL, WARNING, CRITICAL, NEUTRAL.
Ranges: the definition of the numeric thresholds (CONTINUOUS countable type).
<THESHOLD_VALUE>:<LABEL>:<SEVERITY>:<ICON>|<THESHOLD_VALUE>…
The severity could be one of: NORMAL, WARNING, CRITICAL, NEUTRAL.

Simple Metrics