Integrationsflows

Überblick

Überblick

Integrationsflows erlauben es, Daten eventbasiert aus niotix an Drittsysteme zu übertragen. Zusätzlich können die zu übertragenden Daten vor der Übertragung gefiltert und transformiert werden. So können die relevanten Datenpakete in dem vom Drittsystem benötigten Datenformat übertragen werden.

%%{ 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 Integrationsflow direction TB A([ Auslöser]) --> |Liefert erzeugtes Datenobjekt| B([ Filter]) --> |Lässt nur Auslöser mit definierten Kriterien weiter| C([ Transformation])--> |Konvertiert erzeugtes Datenobjekt in gewünschtes Datenformat| D([ Konnektor]) end D --> |Leitet Daten im definierten Format weiter| E([ Externes System])

Grundsätzlich können in einem Integrationsflow die folgenden Daten verwendet werden:

Jedes empfangene Datenpaket eines eingehenden Konnektors
Jede Änderung eines Datenpunktes von einem Virtuellen Gerät
Jede Änderung eines Datenpunktes von einem Digitalen Zwilling
Jeder erzeugte Alarmprotokolleintrag

Hierbei werden für einen Integrationsflow zunächst alle erzeugten Daten für den jeweiligen Account berücksichtigt. Um nur die benötigten Datensätze weiter zu verarbeiten, können Filter definiert werden. Beispielsweise können so die Daten auf einen Digitalen Zwilling oder Konnektor eingeschränkt werden (siehe Kapitel “Filter”). Zusätzlich ist es möglich die Daten vor der Weiterleitung über einen Konnektor zu transformieren. Dabei können Daten in die gewünschte Struktur oder das gewünschte Datenformat gebracht werden (siehe Kapitel “Transformationen”). Am Ende eines Integrationsflows steht genau ein Konnektor-Schritt — dieser Schritt kann jedoch mehrere ausgehende Konnektoren enthalten, sodass Daten gleichzeitig an mehrere Zielsysteme weitergeleitet werden können.

Einen Integrationsflow anlegen

Im Navigationspunkt Integrationen > Integrationsflows den Anlegen-Button verwenden, um einen neuen Integrationsflow anzulegen. Es öffnet sich der folgende Dialog:

Das niotix-Backend liefert Daten standardmäßig im Format generic. Sollen die Daten an ein System weitergeleitet werden, das JSON erwartet, muss im Integrationsflow vor dem Konnektor-Schritt eine Transformation eingefügt werden — mit Eingabe-Typ generic und Ausgabe-Typ application/json.

Name: Eindeutiger Name für den Integrationsflow.
Konto: Das Konto, für das der Integrationsflow gelten soll. Kann nach dem Anlegen nicht mehr geändert werden.
Auslöser: Bestimmt, welche Art von Daten den Flow auslöst. Es stehen folgende Optionen zur Verfügung:
- BEFORE STATE-HANDLING: Datenstrom nach der Konnektortransformation, aber noch vor der Zuweisung an ein Virtuelles Gerät oder einen Digitalen Zwilling. Jedes eingehende Paket erzeugt eine Nachricht — einmal für _parsed (vollständiger Messwert-JSON) und je eine für jede einzelne Variable. Metainformationen wie dtwin_id oder twin_tags sind nicht verfügbar. Struktur des Datenobjekts: Before State-Handling Objekt.
- AFTER STATE HANDLING: Jede Änderung eines Datenpunktes eines Virtuellen Gerätes oder Digitalen Zwillings. Metainformationen wie dtwin_id, twin_tags, vdevice_groups und Custom Properties sind verfügbar. Struktur des Datenobjekts: After State Handling Objekt.
- ALARMLOG WAS CREATED/RESOLVED: Wird ausgelöst, sobald ein Alarmprotokolleintrag erstellt oder aufgelöst wird. Struktur des Datenobjekts: Alarmlog-Objekt. Anwendungsbeispiel: Best-Practice-Beitrag — Alarmierungen in Slack & Microsoft Teams
Integrationsflow Schritte: Über das Dropdown können Filter, Transformationen und der abschließende Konnektor zum Flow hinzugefügt werden. Die Reihenfolge lässt sich per Drag-and-drop anpassen.
Reihenfolge: Der letzte Schritt muss zwingend der Konnektor-Schritt sein. Innerhalb des Konnektor-Schritts können über das -Symbol mehrere ausgehende Konnektoren hinzugefügt werden — die Daten werden dann parallel an alle gewählten Zielsysteme gesendet.

Erläuterung des BEFORE STATE-HANDLING Objektes

Das BEFORE STATE-HANDLING-Objekt enthält die Daten, nachdem der Konnektor sie empfangen und der Gerätetreiber sie in benannte Messwerte aufgeteilt hat — aber bevor eine Zuweisung an ein Virtuelles Gerät oder einen Digitalen Zwilling stattfindet. Das Feld value enthält die vom Gerätetreiber geparsten Messwerte.

Für jedes eingehende Paket werden mehrere Nachrichten erzeugt: eine mit allen Messwerten gemeinsam (meta.parser_variable: "_parsed") und je eine pro einzelnem Messwert. Das Feld meta.parser_variable zeigt an, auf welchen Messwert sich die jeweilige Nachricht bezieht.

{
  "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
  }
}

Feldbeschreibungen:

Feld	Typ	Beschreibung
`meta.account_id`	`number`	Konto-ID
`meta.config_id`	`number`	ID des eingehenden Konnektors
`meta.source_identifier`	`string`	Externe ID des Geräts (Identifier aus dem eingehenden Paket)
`meta.parser_variable`	`string`	Variablenname, z.B. `_parsed` oder `flowtemperature`
`meta.timestamp`	`string`	Zeitstempel des Pakets (ISO 8601)
`value`	`any`	Datenwert: Objekt mit allen Messwerten (bei `_parsed`) oder Einzelwert (bei einzelner Variable)

Felder wie dtwin_id, twin_tags, vdevice_groups, state_id oder unit sind in diesem Kontext nicht verfügbar, da die Daten noch keinem Virtuellen Gerät oder Digitalen Zwilling zugeordnet sind.

Erläuterung des “After state handling” - Objektes

Das AFTER STATE HANDLING-Objekt ist das Standardformat der von niotix ausgehenden Pakete im Integrationsflow. Soll das Datenformat vor der Weiterleitung an ein Drittsystem angepasst werden, muss im Flow vor dem Konnektor-Schritt eine Transformation eingefügt werden.

Im Objekt stehen die folgenden Informationen des zugehörigen Virtuellen Gerätes oder Digitalen Zwillings zur Verfügung. Jede Änderung eines einzelnen Datenpunktes erzeugt dabei eine separate Nachricht im Integrationsflow.

Unterschiede zwischen Virtuellem Gerät und Digitalem Zwilling:
Das Feld twin_category zeigt, ob es sich um ein virtualDevice oder einen digitalTwin handelt. Die Felder vdevice_groups, device_type_id, device_driver_id, operational_status und config_type sind ausschließlich beim Virtuellen Gerät belegt. Beim Digitalen Zwilling sind diese Felder leer oder null. Das Feld twin_ancestor_ids enthält beim Virtuellen Gerät die IDs der übergeordneten Digitalen Zwillinge; beim Digitalen Zwilling auf oberster Hierarchieebene ist es leer. Der Wert source_type ist beim VG typischerweise bridge (Daten kommen von einem Konnektor), beim DT häufig virtual-device (Daten wurden von einem untergeordneten VG übertragen).

Gerät — JSON-Datenpunkt"> _parsed`, `state_type: json` — `value` enthält ein Objekt mit allen Messwerten des Gerätes: 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": "Dokumentation", "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 } }