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.

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

1. Jedes empfangene Datenpaket eines eingehenden Konnektors
2. Jede Änderung eines Datenpunktes von einem Virtuellen Gerät
3. Jede Änderung eines Datenpunktes von einem Digitalen Zwilling
4. 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 Datenformat gebracht werden (siehe Kapitel “Transformationen”). Am Ende eines Integrationsflows können ein oder mehrere ausgehende Konnektoren für die Weiterleitung der Daten ausgewählt werden.

Einen Integrationsflow anlegen

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

• Name: Vergebe hier einen eindeutigen Namen
• Auslöser: Hier ist auszuwählen, welche Art von Datenstream von dem Integrationsflow berücksichtigt werden soll. Es gibt folgende Optionen:
  • BEFORE STATE-HANDLING: Berücksichtigt den unveränderten Datenstream der Konnektoren im Konto. Diese Option sollte gewählt werden, wenn die unveränderten Rohdaten weitergeleitet werden sollen. Dabei ist zu beachten, dass diese in diesem Fall keine Metainformationen, wie beispielsweise dtwin_id zur Verfügung stehen.
  • AFTER STATE HANDLING: Hier werden alle Veränderungen an Datenpunkten eines Virtuellen Gerätes oder Digitalen Zwillings als Auslöser des Integrationsflows verwendet. Dabei stehen auch Metainformationen, wie beispielsweise die dtwin_id zur Verfügung.
  • ALARMLOG WAS CREATED/RESOLVED: Erzeugt einen Trigger sobald ein Alarmprotkolleintrag erstellt oder gelöst wurde. Wie dieser Trigger verwendet werden kann, um Nachrichten für Slack, Microsoft Teams oder Monitoring-Anwendungen zu erzeugen, ist in folgendem Artikel exemplarisch beschrieben: Best Pratice Beitrag - Alarmierungen in Slack & Microsoft Teams
• Integrationsflow Schritte: Über dieses Dropdown können Filter, Transformationen und Konnektoren zu einem Integrationsflow hinzugefügt werden.
• Reihenfolge: Definiert die Reihenfolge der Schritte eines Integrationsflows. Der letzte Schritt eines Integrationsflows muss ein Konnektor sein.

Erläuterung des “After state handling” - Objektes

Im AFTER STATE HANDLING - Objekt stehen die folgenden Informationen des zugehörigen Virtuellen Gerätes oder Digitalen Zwillings zur Verfügung:

{
  "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,
    "flowtemperatur": 55,
    "returntemperatur": 35,
    "battery": 2.75
  }
}

• meta: Enthält die Meta-Informationen zu dem Datenpunkt, der sich verändert hat.

  • timestamp: Zeitstempel, zu dem die Veränderung registriert wurde. Beispiel: 2024-07-12T13:09:45.901Z
  • state_id: ID des Datenpunktes. Beispiel: 1178539
  • dtwin_id: ID des Digitalen Zwillings oder Virtuellen Gerätes, zu dem dieser Datenpunkt gehört. Beispiel: 63797
  • dtwin_title: Titel des Digitalen Zwillings oder Virtuellen Gerätes, zu dem dieser Datenpunkt gehört. Beispiel: My device
  • twin_tags: Liste der Tags. Beispiel: ["tag1"]
  • twin_ancestor_ids: Liste der Digitalen Zwillinge, die in der Hierarchie über diesem Virtuellen Gerät oder Digitalen Zwilling stehen. Beispiel: [63796]
  • twin_category: Kategorie des Zwillings oder Gerätes. virtualDevice oder digitalTwin
  • vdevice_groups: Gruppen, denen das Virtuelle Gerät angehört. Beispiel: ["group1", "group2", "group42"]
  • device_type_id: ID des Gerätetyps. Beispiel: 1957
  • device_driver_id: ID des Gerätetreibers. Beispiel: 1957
  • operational_status: Betriebsstatus des Gerätes. 0 = nicht gesetzt; 1= “Unterwegs”; 2= “Betriebsbereit; 3= “in Betrieb”; 4= “Vorübergehend inaktiv; 5= “Stillgelegt”.
  • geolocation: Geografische Lage des Gerätes.
    • latitude: Breitengrad. Beispiel: 71.17092
    • longitude: Längengrad. Beispiel: 25.783081
    • address: Adresse des Gerätes. Beispiel: Storgata 78, 9008 Tromsø, Norway
  • unit: Einheit der Messung. Beispiel: number
  • state_identifier: Schlüssel des Datenpunktes. Beispiel: _parsed
  • state_type: Datentyp des Datenpunktes. Beispiel: json
  • account_id: ID des zugehörigen Kontos. Beispiel: 1250
  • config_id: ID des Konnektors. Beispiel: 557
  • config_type: Typ des Konnektors. Beispiel: bridge-incomingwebhook
  • source_type: Quelle des Datenpunktes. bridge = Konnektor; virtual-device= Virtuelles Gerät; virtual-device-aggregate= Virtuelles Gerät Aggregation; none= keine; timeseries-aggregate= Zeitlich aggregiert; aggregate= Aggregation; random= Zufall
  • source_identifier: Externer Id / Device Id. Beispiel: my-device-external-id
  • parser_variable: Parser-Variable. Beispiel: _parsed
  • twin_key_value: . Benutzedefinierte Eigenschaften des Virtuellen Gerätes/ Digitalen Zwillings. Beispiel: {"key": "value", "custom": "info", "additional": "properties"}

• value: Enthält Wert des Datenpunktes.
  

Alarmlog was created/resolved Objekt

Im ALARMLOG WAS CREATED/RESOLVED - Objekt stehen die folgenden Informationen zur Verfügung:

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

• meta: Enthält die Meta-Informationen zu dem erzeugten Alarmprotokoll-Eintrag.
  • account_id: Account für den der Alarmprotokoll-Eintrag erzeugt wurde.
  • account_name: Name des Accounts für den der Alarmprotkoll-Eintrag erzeugt wurden.
  • timestamp: Zeitstempel zu dem der Alarmprotkoll-Eintrag erzeugt wurde.
• value: Enthält die Informationen zu den Parametern des Alarmprotkoll-Eintrags.
  • alarm_log_id: Id des Alarmprotkoll-Eintrags.
  • alarm_log_parent_id: Wird ein Alarmprotkoll-Eintrag resolved, wird die Id des ursächlichen Alarmprotkoll-Eintrags hier ausgegeben.
  • alarm_origin_type: virtual-device , wenn die Quelle des Alarmprotkoll-Eintrags ein Virtuelles Gerät ist. smart-group , wenn die Quelle des Eintrags eine Smarte Gruppe ist.
  • alarm_message: Inhalt der konfigurierten Fehler-/Warnmeldung.
  • alarm_origin: Enhält Detailinformationen zur Quell-Eintät des Alarmprotkoll-Eintrags.
    • id: Id des Virtuellen Gerätes oder der Smarten Gruppe.
    • title: Titel des Virtuellen Gerätes oder der Smarten Fruppe.
    • tags: Tags stehen nur für Virtuelle Geräte zur Verfügung.
    • groups: Gruppen stehen nut für Virtuelle Geräte zur Verfügung.
    • link: Link über den das Virtuelle Gerät oder die Smarte Gruppe geöffnet werden kann.
    • address: Adresse steht nur für Virtuelle Geräte zur Verfügung.
  • alarm_level: error , wenn das Level “Fehler” in der Konfiguration definiert ist. warning , wenn das Level “Warnung” in der Konfigurationd efiniert ist.
  • log_category: null , wenn die Kategorie nicht gesetzt ist. Sonst eins von frequency, battery, device oder packet-threshold
  • is_resolved: false , wenn es sich um einen ungelösten Alarmprotokoll-Eintrag handelt.true , wenn der Eintrag gelöst wurde.

Übersicht der für Integrationsflows verfügbaren Konnektoren

Es können folgende ausgehende Konnektoren für Integrationsflows verwendet werden:

• MQTT Broker
• Websocket
• Webhook (Outgoing)
• MQTT (Outgoing)
• Kafka (Outgoing)