Integration Flows

Overview

Overview

Integration flows allow data to be transferred from niotix to third-party systems based on events. The data to be transferred can be filtered and transformed before transmission, so that only the relevant data packets are forwarded in the format required by the target system.

%%{ init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#FFFFFF', 'primaryTextColor': '#031403', 'primaryBorderColor': '#606060', 'lineColor': '#606060', 'secondaryColor': '#2fcbff', 'tertiaryColor': '#E7E6E6', 'primary_font' : 'Poppins:wght@300;400;500;600;700;800', 'primary_font_type' : 'sans-serif' } } }%% flowchart TB subgraph Integration Flow direction TB A([ Trigger]) --> |Delivers created data object| B([ Filter]) --> |Only passes triggers matching defined criteria| C([ Transformation])--> |Converts data object into desired format| D([ Connector]) end D --> |Forwards data in the defined format| E([ External System])

In principle, the following data can be used in an integration flow:

Every data packet received from an incoming connector
Every change to a data point of a Virtual Device
Every change to a data point of a Digital Twin
Every alarm log entry created

For an integration flow, all data generated for the respective account is initially taken into account. Filters can be defined to process only the required records — for example to restrict data to a specific Digital Twin or connector (see “Filters” section). Data can also be transformed before forwarding via a connector to convert it into the desired structure or format (see “Transformations” section). At the end of an integration flow there is exactly one connector step — this step can however contain multiple outgoing connectors, allowing data to be forwarded simultaneously to several target systems.

Create an integration flow

In the Integrations > Integration Flows navigation item, use the Create button to create a new integration flow. The following dialog opens:

The niotix backend delivers data in generic format by default. If the data is to be forwarded to a system that expects JSON, a transformation must be added before the connector step in the integration flow — with input type generic and output type application/json.

Name: A unique name for the integration flow.
Account: The account for which the integration flow applies. Cannot be changed after creation.
Trigger: Determines which type of data triggers the flow. The following options are available:
- BEFORE STATE-HANDLING: Data stream after the connector transformation, but before assignment to a Virtual Device or Digital Twin. Each incoming packet generates a message — once for _parsed (full measurement JSON) and once for each individual variable. Meta information such as dtwin_id or twin_tags is not available. Data object structure: Before State-Handling object.
- AFTER STATE HANDLING: Every change to a data point of a Virtual Device or Digital Twin. Meta information such as dtwin_id, twin_tags, vdevice_groups and custom properties is available. Data object structure: After State Handling object.
- ALARMLOG WAS CREATED/RESOLVED: Triggered as soon as an alarm log entry is created or resolved. Data object structure: Alarm log object. Usage example: Best practice — Alerts in Slack & Microsoft Teams
Integration flow steps: Filters, transformations and the final connector can be added to the flow via the dropdown. The order can be adjusted using drag-and-drop.
Order: The last step must be the connector step. The flow cannot be saved if no connector step is present or if it is not in the last position. Within the connector step, multiple outgoing connectors can be added using the icon — data is then sent in parallel to all selected target systems.

Explanation of the BEFORE STATE-HANDLING object

The BEFORE STATE-HANDLING object contains the data after the connector has received it and the device driver has parsed it into named measurement values — but before any assignment to a Virtual Device or Digital Twin takes place. The field value holds the measurement values as parsed by the device driver.

Each incoming packet generates multiple messages: one containing all measurements together (meta.parser_variable: "_parsed") and one per individual measurement value. The field meta.parser_variable indicates which measurement value the respective message refers to.

{
  "meta": {
    "account_id": 1250,
    "config_id": 557,
    "source_identifier": "my-device-external-id",
    "parser_variable": "_parsed",
    "timestamp": "2024-07-12T13:09:45.901Z"
  },
  "value": {
    "flowtemperature": 72.4,
    "returntemperature": 55.1,
    "volume": 900
  }
}

Field descriptions:

Field	Type	Description
`meta.account_id`	`number`	Account ID
`meta.config_id`	`number`	ID of the incoming connector
`meta.source_identifier`	`string`	External device ID (identifier from the incoming packet)
`meta.parser_variable`	`string`	Variable name, e.g. `_parsed` or `flowtemperature`
`meta.timestamp`	`string`	Packet timestamp (ISO 8601)
`value`	`any`	Data value: object with all measurements (for `_parsed`) or individual value (for a single variable)

Fields such as dtwin_id, twin_tags, vdevice_groups, state_id or unit are not available in this context, as the data has not yet been assigned to a Virtual Device or Digital Twin.

Explanation of the “After state handling” object

The AFTER STATE HANDLING object is the default format of the packets sent out from niotix in the integration flow. If the data format needs to be adapted before forwarding to a third-party system, a Transformation step must be added to the flow before the connector step.

The following information about the associated Virtual Device or Digital Twin is available in the object. Each change to a single data point generates a separate message in the integration flow.

Differences between Virtual Device and Digital Twin:
The twin_category field indicates whether the source is a virtualDevice or a digitalTwin. The fields vdevice_groups, device_type_id, device_driver_id, operational_status, and config_type are only set for Virtual Devices and are empty or null for Digital Twins. The twin_ancestor_ids field contains the IDs of parent Digital Twins for a Virtual Device; for a Digital Twin at the top of the hierarchy it is empty. The source_type is typically bridge for Virtual Devices (data received from a connector) and virtual-device for Digital Twins (data forwarded from a child Virtual Device).

— JSON data point"> _parsed`, `state_type: json` — `value` contains an object with all measurement values of the device: style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;">

{ "meta": { "timestamp": "2024-07-12T13:09:45.901Z", "state_id": 1178539, "dtwin_id": 63797, "dtwin_title": "My device", "twin_tags": ["tag1"], "twin_ancestor_ids": [ 63796 ], "twin_category": "virtualDevice", "vdevice_groups": [ "group1", "group2", "group42" ], "device_type_id": 1957, "device_driver_id": 1957, "operational_status": 3, "geolocation": { "latitude": 71.17092, "longitude": 25.783081, "address": "Storgata 78, 9008 Tromsø, Norway" }, "unit": null, "state_identifier": "_parsed", "state_type": "json", "account_id": 1250, "config_id": 557, "config_type": "bridge-incomingwebhook", "source_type": "bridge", "source_identifier": "my-device-external-id", "parser_variable": "_parsed", "twin_key_value": { "key": "value", "custom": "info", "additional": "properties" } }, "value": { "persons": 23, "flowtemperature": 55, "returntemperature": 35, "battery": 2.75 } }

{ "meta": { "timestamp": "2024-07-12T13:09:45.901Z", "state_id": 1178540, "dtwin_id": 63797, "dtwin_title": "My device", "twin_tags": ["tag1"], "twin_ancestor_ids": [ 63796 ], "twin_category": "virtualDevice", "vdevice_groups": [ "group1", "group2", "group42" ], "device_type_id": 1957, "device_driver_id": 1957, "operational_status": 3, "geolocation": { "latitude": 71.17092, "longitude": 25.783081, "address": "Storgata 78, 9008 Tromsø, Norway" }, "unit": "°C", "state_identifier": "flowtemperature", "state_type": "number", "account_id": 1250, "config_id": 557, "config_type": "bridge-incomingwebhook", "source_type": "bridge", "source_identifier": "my-device-external-id", "parser_variable": "flowtemperature", "twin_key_value": { "key": "value", "custom": "info", "additional": "properties" } }, "value": 55 }

{ "meta": { "account_id": 1239, "account_name": "Documentation", "timestamp": "2024-07-12T11:09:11.152Z" }, "value": { "alarm_log_id": 7674, "alarm_log_parent_id": null, "alarm_origin_type": "virtual-device", "alarm_message": "Battery below 3000 mV", "alarm_origin": { "id": 63770, "title": "my-device", "tags": [], "groups": [], "link": "https://niotix.io/#/virtual-devices/63770" }, "alarm_level": "error", "log_category": "battery", "is_resolved": false } }