In case the built-in algorithms are not enough, you can create your own.

According to the selected Usage, Algorithms can be bound to other elements in the Console, for instance, can be referenced by an Insight Metric or a Work Session Definition.

An Algorithm is described by:

Main Information: Name, Description, Group, and Usage.
Inputs: the algorithm input data definition, and used by the algorithm binding.
Script: the Python script executed when the algorithm is computed.
Outputs: the algorithm result used by algorithm binding, for instance, into Insight Metrics to select a specific output.

This feature is available for the following modules:
VALUE-ADDED DIGITAL SERVICES, CONNECTED FIELD SERVICES, SMART SPARE PARTS & CONSUMABLES

Creating a custom Algorithm

To add a new Algorithm, you should:

Enter the Insights / Insight Algorithms page.
Press the Add Algorithm button.
Enter the name and description of the algorithm, which will be visible when configuring, for instance, an Insight Metric.
Select the Usage, this will affect where the algorithm can be selected, for instance, into a Work Session Definition or an Insight Metric.
Press the Save button and complete the Algorithm configuration.

Editing a custom Algorithm

By entering the Insights / Insight Algorithms page, into the algorithm card, you can click on the Open icon.

Note that only custom algorithms can be modified.

An Algorithm is described by:

Name: the name of the algorithm, which is visible in algorithm selection dialogs.
Description: the description of the algorithm, which is visible in algorithm selection dialogs.
Group: the group, which can be used to organize and search algorithms.
Usage: identifies how this algorithm will be used.
Inputs: the set of inputs required by the execution of the algorithm, and which will be configured when the algorithm is referenced according to usage.
Python Script: the Python script to be executed during algorithm computation.
Outputs: the set of results computed by the algorithm, which will be read by the element referencing the algorithm based on usage.

Algorithm Usage

When you define an algorithm, you have to declare how it will be used; this has an impact on what elements will be able to reference the algorithm, and which data will be available as input.

Thing Definition Insight Metric

When configuring an Insight Metrics of a Thing Definition, you can select algorithms with this Usage.
The Algorithm is computed daily, and takes as input the static values and metrics data according to the selected Dataset Range (e.g. Last 24 Hours).
Inputs of type Metric can be configured by using any metric defined or inherited from the thing definition in which the Insight metric was defined.

Location Insight Metric

When configuring an Insight Metric of a Location, you can select algorithms with this usage.
The Algorithm is computed daily, and takes as input the static values and metrics data according to the selected Dataset Range (e.g. Last 24 Hours).
Inputs of type Metric can be configured by using a Location Metric or a Thing Definition Metric.
Comply with the Thing Definition Insight Metric usage, the algorithm will receive input data coming from multiple things under the same location.

Work Session Post Computation

When configuring a Work Session Definition, you can define Post Computations by selecting algorithms with this usage.
The Algorithm is computed each time a Work Session completes, and takes in input the Work Session object and other configured inputs.
Inputs of type Metric, can be configured by using any metric defined or inherited from the thing definition in which the Insight metric was defined. The input metric data will be automatically limited to the Work Session duration, so there is no need to define any Dataset Range.

Inputs

This section allows you to define the Algorithm inputs that must be configured within the element referencing the Algorithm.
To add a new Input, you can click the Add Input button. By clicking on the Input row, the Input editing dialog is opened.
Instead, clicking the 3-dots icon on the right of the row provides additional actions, like Delete.

An Input is described by:

Label: the label of the input displayed in the Algorithm binding form.
Name: the name of the input used in the script as a parameter.
Description: the description of the input displayed in the Algorithm binding form.
Type: the type of the input, see below for more details.
Default Value: the default value used to preload the Algorithm binding form.
Required: indicates whether this input cannot be left blank within the Algorithm binding form.

When referencing an algorithm, inputs must be configured in the binding form within the element editing page (e.g. Insight Metric).

An Input can be of one of the following types, and according to it, the binding form, and the way values are passed to the script may be different.

Metric

The binding form requires selecting a Thing Definition metric, and allows you to specify a Dataset Range among the supported ones (if available).
In case of Work Session Post Computation usage, the dataset range is locked to the duration of the completed work session, so this option is not available in the form.
In the inputs parameter of the script, under the thing node, you will find:

csvUrl: the URL where to retrieve a CSV with all metrics data related to the dataset range.
values: includes the last metric values before the end timestamp of the dataset range.
peviousValues: includes the last metric values before the start timestamp of the dataset range.

This is an example of the input parameter fragment passed to the script:

{
	"thing": {
		"name": "Oven 1",
		"properties": {},
		"thingDefinition": {},
		"csvUrl": "https://servitly-files......",
		"values": [
			{
				"value": 180,
				"timestamp": 1706095456745,
				"metric": "temperature"
			}
		],
		"previousValues": [
			{
				"value": 32,
				"timestamp": 1706095285843,
				"metric": "temperature"
			}
		]
	}
}

Note that when the CSV is generated, the system extracts all metric values for the specified data range, with a maximum limit of 100k values for each input metric.

Reading BLOB Metrics

If the metric is of type BLOB, the single metric value will be a string-encoded JSON, which can be parsed to get the file name, file size, and temporary URL from which to obtain the BLOB content.

"previousValues": [
	{
		"value": "{\"fileName\":\"log_2025-04-11.txt\",\"length\":220,\"url\":\"https://servitly.......\"}",
		"timestamp": 1744369596061,
		"metric": "metric_1"
	}
]

Location Metric

The binding form requires selecting a Location metric, and allows you to specify a Dataset Range among the supported ones (if available).
In case of Work Session Post Computation usage, the dataset range is blocked to the duration of the work session, so this option is not available in the form.
In the inputs parameter of the script, under the thing node, you will find:

csvUrl: the URL from which to retrieve a CSV with all metrics data related to the dataset range.
values: includes the last metric values before the end timestamp of the dataset range.
peviousValues: includes the last metric values before the start timestamp of the dataset range.

{
	"location": {
		"name": "Sweet Bread Milano",
		"properties": {},
		"csvUrl": "https://servitly-files......",
		"values": [
			{
				"value": 15,
				"timestamp": 1706095456745,
				"metric": "outdorTemperature"
			}
		],
		"previousValues": [
			{
				"value": 10,
				"timestamp": 1706095285843,
				"metric": "outdorTemperature"
			}
		]
	}
}

Note that when the CSV is generated, the system extracts all metric values for the specified data range, with a maximum limit of 100k values for each input metric.

Active Events

This input type does not require any other configuration in the binding form.
In the inputs parameter of the script, under the thing or location node, you will find:

eventsCsvUrl: the URL from which to retrieve a CSV with all events (FAILURE, ANOMALIES, OPERATION) that were active within the dataset range.

{
	"thing": {
		"name": "Oven 1",
		"properties": {},
		"thingDefinition": {},
		"eventsCsvUrl": "https://servitly-files......"
	}
}

Running Work Sessions

This input type does not require any other configuration in the binding form.
In the inputs parameter of the script, under the thing or location node, you will find:

workSessionsCsvUrl: the URL from which to retrieve a CSV with all work sessions that were active within the dataset range.

{
	"thing": {
		"name": "Oven 1",
		"properties": {},
		"thingDefinition": {},
		"workSessionsCsvUrl": "https://servitly-files......"
	}
}

String / Integer / Float / Boolean

You can define inputs that are static values passed to the script, for instance, to add some thresholds or execution options.
According to the type, the binding form requires entering a string, a number, or a Boolean value.
In the inputs parameter of the script, you will find the inputs node with all input static values.

{
	"inputs": {
		"stringType": "WORKING",
		"integerType": 123,
		"floatType": 1.23,
		"booleanType": true
	}
}

Script

This section allows you to edit the Python script and try it by selecting the context (location or specific thing) and configuring inputs.

Starting 28 February 2025, it will no longer be possible to create or update Algorithms using the Python 3.8 runtime.
If it has not already been done, after that date, to update an Algorithm it will be necessary to upgrade to Python version 3.11.

Libraries

By using the latest version (v 3.11), in the Python script, you can use the following libraries:

Library	Description	Version
Numpy	Provide multidimensional array object, various derived objects, and an assortment of routines for fast operations on arrays, including mathematical, logical, shape manipulation, sorting, selecting, I/O, discrete Fourier transforms, basic linear algebra, basic statistical operations, random simulation, and much more	1.26.2
Pandas	A powerful, flexible, and easy-to-use data analysis and manipulation tool.	2.1.3
SciPy	Provides algorithms for optimization, integration, interpolation, eigenvalue problems, algebraic equations, differential equations, statistics, and many other classes of problems.	1.11.3
Statsmodel	Provides classes and functions for the estimation of many different statistical models, as well as for conducting statistical tests and statistical data exploration.	0.14.0

Outputs

In this section, you can define the Outputs of the Algorithm, and at least one output must be defined. When you create a new Algorithm, a default output named value is created, but you can change it as desired or add new ones.
Multiple outputs can be defined, so in this way, the same algorithm can be reused in different places, by using different outputs. For example, you can have an algorithm that generates a synthetic indicator and also calculates some additional information that is complementary to the index.
To add a new Output, you can click the Add Output button. By clicking on the Output row, the Output editing dialog is opened.
Instead, clicking the 3-dots icon on the right of the row provides additional actions, like Delete.

An Output is described by:

Label: the label of the output displayed in the Algorithm binding form.
Name: the name of the output used to extract the value from the Algorithm result.
Description: the description of the output displayed in the Algorithm binding form.
Group: the group that is used as a preset when selecting the Output into an Insight Metric.
Unit: the unit that is used as a preset when selecting the Output into an Insight Metric.
Value Type: indicates the type of the output value. You can select among Integer, Float, Boolean, and String.
Data Type: in case of numeric Value Type, indicates whether the values are discrete (e.g. error code) or continuous (e.g. temperature).
Dictionay: in case of a non-numeric value type or a discrete data type, you can specify a dictionary that will be used as a preset when selecting the Output into an Insight Metric.
Range and Thresholds: in case of numeric value type (continuous), you can specify min/max values and thresholds, which will be used as a preset when selecting the Output into an Insight Metric.

When defining the script, you must return a map including the output names as keys and the values, which must be encoded according to the value type.

return {
 "stringOutput": "SUCCESS",
 "integerOutput": 123,
 "floatOutput": 1.23,
 "booleanOutput": true,
}

Try Algorithm

By pressing the Try Algorithm button, you can try your script execution on a real context.

In the first step, you can select the execution context according to the selected Usage, then there is a section where you can configure the inputs by selecting metrics or entering static values.
Context and Inputs are preserved between different testing sessions, even between different algorithms.
By pressing the DOWNLOAD INPUTS button, you can obtain the JSON passed as input parameters of the script you are configuring.

Instead, by pressing the TRY button, the dialog switches to the execution mode, which displays the Outputs and the Logs.