Defining Algorithms

In case the built-in algorithms are not sufficient, 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 definition, and used by the algorithm binding to select a specific output.

Creating a custom Algorithm

To add a new Algorithm, you should:

1. Enter the Insights / Insight Algorithms page.

2. Press the Add Algorithm button.

3. Enter the name and description of the algorithm, which will be visible when configuring, for instance, an Insight Metric.

4. Select the Usage, this will affect where the algorithm can be selected, for instance, into a Work Session Definition or am Insight Metric.

5. 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 and which will be read by the element referencing the algorithm based on usage.

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 in 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 in 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 in 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 Inputrow, the Input editing dialog is opened, instead the 3-dots icon on the right of the row, provides additional actions, like the 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 into the script as 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: indicated 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 only for Insight Metrics, 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 metrics values before the end timestamp of the dataset range.

• peviousValues: includes the last metrics values before the start timestamp of the dataset range.

This is an example of the inputs 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.

Location Metric

The binding form requires selecting a Location metric, 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 where to retrieve a CSV with all metrics data related to the dataset range.

• values: includes the last metrics values before the end timestamp of the dataset range.

• peviousValues: includes the last metrics 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 where 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 where 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 script, for instance, to add some thresholds or execution options.

According to the type, the binding form requires entering a string, number of 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.

You can select the Python version to use, the default and latest version is 3.11, but if you have a script not supporting it, you can select the version 3.8, and then migrate to 3.11.

Libraries

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

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 are 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 the 3-dots icon on the right of the row, provides additional actions, like the Delete action.

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 Algorithm result.

• Description: the description of the output displayed in the Algorithm binding form.

• Group: the group which is used as pre-set when selecting the Output into an Insight Metric.

• Unit: the unit which is used as pre-set when selecting the Output into an Insight Metric.

• Value Type: indicated the type of the output value. You can select among Integer, Float, Boolean and String.

• Data Type: in case of numeric Value Type, indicates whther the values are discrete (e.g. error code) or continuous (e.g. temperature).

• Dictionay: in case of non numeric value type or discrete data type, you can specify a dictionary which will be used as pre-set 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 pre-set when selecting the Output into an Insight Metric.

When defining the script, you must return a map including the output names as key, 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 inputs parameters of the script you are configuring.

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