Lektion 2.1 Die Rule Engine (Legacy)

Regeln lösen Actions aus – wie das Senden einer E-Mail –, wenn festgelegte Bedingungen erfüllt sind. Da sowohl Conditions als auch Actions angepasst werden können, eignet sich die Rule Engine ideal zur Überwachung von Schwellenwerten und Alarmen.

In dieser Lektion behandeln wir folgende Themen:

• Wie man einen Contact erstellt, um eine Alarm-E-Mail zu erhalten.
• Wie man Conditions erstellt, um eine Regel auszulösen oder einen Wert zu bewerten, sobald eine Regel ausgelöst wurde.
• Wie man verschiedene Arten von Actions erstellt und sich mit ihnen vertraut macht, die definieren, was passiert, wenn eine Regel ausgelöst wird.
• Wie man Conditions, Actions und Contacts kombiniert, um eine vollständige Regel zu erstellen.

Es ist ein unkomplizierter und einfacher Prozess, also fangen wir an!

Beginnen Sie mit der Erstellung einer einfachen Regel, die einen Alarm überwacht und eine E-Mail-Benachrichtigung sendet, wann immer ein Schwellenwert überschritten wird.

Hinweis: Regeln sind single-tenant, was bedeutet, dass sie nicht mit anderen Benutzern geteilt werden können.

Eine Regel erstellen

Beginnen Sie mit dem Hinzufügen eines Contacts

1. Gehen Sie zu Rule Engine in Apps.
2. Klicken Sie auf Contacts.
3. Drücken Sie Add contact.
4. Fügen Sie Ihrem Contact eine E-Mail-Adresse und optional eine Telefonnummer hinzu
5. Wenn Sie fertig sind, drücken Sie Add Contact und gehen Sie dann zurück zum oberen Menü.

Beginnen Sie mit dem Hinzufügen einer Condition

1. Klicken Sie auf Conditions.
2. Drücken Sie Add Condition.
3. Benennen Sie Ihre Condition. In diesem Beispiel stammt die Condition von einem Alarmübersetzer.
4. Geben Sie Ihre Condition ein. Sie sollte ungefähr so aussehen:
   
5. Wenn Sie fertig sind, drücken Sie Add Condition.

Häufige Operatoren: Häufige Operatoren in Conditions sind:

• == Gleichheitsoperator (=== strikte Gleichheit)
• != Ungleichheitsoperator (!== strikte Ungleichheit)
• > Größer als
• < Kleiner als
• <= Kleiner oder gleich
• >= Größer oder gleich
• || Bedingtes ODER
• && Bedingtes UND

Zulässige Datentypen: Number, Boolean und String

• Verwenden Sie für String-Vergleiche einfache Anführungszeichen um den String. Beispiele:
  • Astro-Clock-Conditions: sunState=='Night' oder sunState=='Day'
  • Condition für Missing expected report: message=='Missing expected report'
• Verwenden Sie für alle anderen Datentypen keine Anführungszeichen.

Es wird empfohlen, hauptsächlich ==-Gleichheitsprüfungen und einfache Boolean-Conditions zu verwenden. Beachten Sie, dass = Zuweisung bedeutet und kein gültiger Operator in einer Condition ist.

Die Verwaltung von Zuständen in der Rule Engine kann schnell komplex werden, da die Anzahl möglicher Zustände wächst und viele zusätzliche Regeln erfordert, um sie effektiv zu verwalten. Dies macht Regeln nicht nur schwerer wartbar, sondern schränkt auch die Skalierbarkeit ein. Für bessere Performance und überlegene Skalierung lassen Sie Übersetzer die Zustandslogik übernehmen, während Ihre Regeln sich auf einfache Vergleiche konzentrieren.

Eine Action erstellen

Nachdem Sie eine Condition erstellt haben, möchten Sie eine Action erstellen:

1. Gehen Sie zu "Actions" in der Rule Engine.

2. (Optional) Suchen Sie eine bereits vorhandene Action, die dem ähnelt, was Sie möchten. Sie können den Inhalt kopieren, da das Bearbeiten vordefinierter Actions dazu führt, dass sie in ihren Originalzustand zurückkehren.

3. Erstellen Sie eine neue Action.
   

4. Beim Erstellen einer Regel können Sie zwischen verschiedenen Arten von Actions wählen. Jeder Typ unterstützt unterschiedliche Fähigkeiten:

   a) E-Mail-, SMS- oder Log-Actions

   • Sie können dynamische Daten vom IoT-Node verwenden, der die Regel ausgelöst hat.
   • Beispiel: ${iotnode.co2} fügt den Wert co2 vom Node ein. Ersetzen Sie "co2" durch das Feld, das Sie einbeziehen möchten.
   • Bei E-Mail-Actions können Sie die Nachricht mit HTML-Formatierung verbessern – Logos hinzufügen, Schriftgrößen anpassen und Stile für professionell aussehende E-Mails anwenden.
   • Bei Log-Actions können Sie entweder:

     • Direkt den Log-Typ, die Priorität und die Kategorie auswählen, oder

     • Diese Werte dynamisch aus dem Log-Objekt eines Alarmübersetzers abrufen (falls verfügbar).

       Beispiel-Log-Objekt:

       "log": {
          "type": "info",
          "priority": "severe",
          "category": "status",
          "message": "Log text"
       }

     • Um den von einem Alarmübersetzer generierten Text zu verwenden, referenzieren Sie ihn mit: ${iotnode.log.message}.

   b) Command-Actions

   • Command-Actions unterstützen ebenfalls dynamische Daten, erfordern jedoch einen Generic MQTT Connector, um an einen Ziel-MQTT-Broker zu veröffentlichen.
   • Derzeit wird nur der Befehl sendDownlink zum Veröffentlichen von Daten unterstützt.
   • Die Payload muss im JSON-Format vorliegen und sowohl einen message-Teil als auch einen mqttTopic-Teil enthalten.
   • Wichtig: Escapen Sie doppelte Anführungszeichen (") innerhalb von JSON-Werten mit einem Backslash (\").
   • Da die Formatierung knifflig sein kann, validieren Sie Ihre Payload mit einem Online-JSON-Linter, bevor Sie sie verwenden.

   Beispiel für Befehl und Payload:

   sendDownlink

   {
   "message": "{\"temperature\":${iotnode.temperature}}",
   "mqttTopic": "${iotnode._id}"
   }

   c) LoRaWAN-Downlink-Actions

   • Geben Sie die hex-kodierte Payload, die Portnummer und an, ob der Downlink bestätigt werden soll.
   • Beachten Sie: Ein "bestätigter" Downlink meldet nur, ob die Nachricht erfolgreich zugestellt wurde oder fehlgeschlagen ist. Er garantiert nicht, dass das Gerät die Aktion wie beabsichtigt ausgeführt hat.
   • Um die Wirkung des Downlinks zu überprüfen:
     1. Erstellen Sie eine weitere Regel, die mit einer 60-Sekunden-Zeitverzögerung durch die erste Regel ausgelöst wird.
     2. Prüfen Sie in der 2. Regel im UND-Teil der Regel, ob das erwartete Ergebnis nicht eingetreten ist.
     3. Falls nicht, erreicht die Regel den Action-Schritt und ergreift Korrekturmaßnahmen – zum Beispiel das erneute Senden des Downlinks alle 2 Minuten, bis die Wirkung bestätigt ist.

   d) Rule

   • Dies ist eine vordefinierte Action, mit der Sie eine andere Regel direkt auslösen können, ohne deren Trigger-Condition zu bewerten. Sie ist essenziell für Anwendungsfälle, die Regelverkettung erfordern.

   e) Report

   • Dies ist eine flexible Action, die zwei Arten von E-Mail-Reports generieren kann:
     1. CSV-Report – Enthält Zeitstempel und einen einzelnen Messwert basierend auf angegebenen Suchkriterien.
     2. Geräteanzahl-/Abrechnungsreport – Zählt die Anzahl der Geräte pro Konto über alle verfügbaren Organisationen hinweg, exportiert als CSV.

5. Wenn Sie fertig sind, drücken Sie "Add Action".

Condition und Action kombinieren, um eine Regel zu erstellen

Nachdem Sie eine benutzerdefinierte Condition und Action erstellt haben, ist es Zeit, sie in einer Regel zu verwenden:

1. Navigieren Sie zu "Add Rule".

2. Geben Sie Ihrer Regel einen Namen.

3. Fügen Sie Trigger-Conditions hinzu.
   Es gibt eine hilfreiche Abkürzung, um schnell mehrere Geräte hinzuzufügen:

   • Drücken Sie "Select Node" und geben Sie einen Teil des Gerätenamens ein (z. B. device)

   • Wenn Ihre Geräte device-1, device-2 usw. heißen, erscheinen sie in der Liste

   • Klicken Sie dann so schnell wie möglich auf jedes Gerät, bis alle hinzugefügt sind. Es ist in Ordnung, mehrere Geräte in einer Zeile hinzuzufügen.

     

   • Hinweis: Verwenden Sie diese Abkürzung nicht, wenn die Geräte unterschiedliche Trigger-Conditions benötigen.

   • Sie können nach Select value suchen, was Ihre Condition sein kann.

4. Wählen Sie im Abschnitt "Actions" die Action aus, die Sie erstellt haben.
   Wenn es sich um eine E-Mail-Action handelt, stellen Sie sicher, dass Sie auch den Empfänger-Contact auswählen.

5. Klicken Sie nun auf "Add Rule" – herzlichen Glückwunsch, Sie haben eine Regel erstellt.

Versuchen Sie nun, fortgeschrittenere Regeln zu erstellen.

Beispiele sind:

1. Device Supervision Report
   Benachrichtigen Sie sich selbst, wenn ein Gerät nicht innerhalb des erwarteten Intervalls meldet.
   Hinweis:
   a) Gehen Sie zu Devices → Ihr Gerät und stellen Sie ein Expected Report Interval ein.
   b) Verwenden Sie die Standard-Condition "Missing expected report".
   c) Verwenden Sie die Standard-E-Mail-Action "Device did not report in time"

2. Ein Licht ein- und ausschalten und dabei das Ereignis protokollieren
   Aus der Perspektive einer Regel gibt es keinen Unterschied zwischen der Steuerung eines einzelnen Lichts oder einer ganzen Straßenbeleuchtungsgruppe mit Hunderten von Lichtern.
   Der einzige Unterschied besteht darin, dass Sie im letzteren Fall möglicherweise Redundanz für erhöhte Zuverlässigkeit hinzufügen möchten.

   Beispiel - Redundante Straßenbeleuchtungsregel

   Steuern Sie die Straßenbeleuchtung mit eingebauter Redundanz

   Aktivieren Sie die Straßenbeleuchtung, wenn die Astro-Clock-Condition auf Nacht wechselt

   Überprüfen Sie, ob die Straßenbeleuchtung aktiviert wurde; falls das LoRaWAN-Downlink-Paket verloren ging, warten Sie zwei Minuten und versuchen Sie erneut, sie einzuschalten.

3. Einen CSV-Report senden
   Verwenden Sie die Report-Action, um Ihren Report zu definieren. Probieren Sie zunächst folgende Definition aus:

   [
      {
         "query": "all",
         "csv-column": true,
         "measurement": "temperature",
         "duration": "1d",
         "distance": "0h",
         "fileName": "myReport.csv"
      }
   ]

   Wenn Sie weitere Details benötigen, siehe das Benutzerhandbuch Report Generator

Fragen und Antworten

Frage

Muss ich Geräte einzeln in separaten Zeilen im Trigger-Abschnitt einer Regel hinzufügen?

Antwort

Nein, Sie können alle Geräte, die dieselbe Trigger-Condition verwenden, in derselben Zeile hinzufügen.
Dies ist schneller und leichter zu warten. Verwenden Sie zusätzliche Zeilen nur, wenn Sie mehrere Trigger-Conditions benötigen.

Frage

Kann ich mehrere Actions hinzufügen, die ausgeführt werden, wenn eine Regel ausgelöst wird?

Antwort

Ja, Sie können mehrere Actions hinzufügen und sogar Zeitverzögerungen zwischen ihrer Ausführung einbauen.
Ein häufiges Beispiel ist: einen Aktuator auslösen, 30 Sekunden warten und dann eine weitere Regel auslösen, um zu bestätigen, dass der Aktuator wie erwartet aktiviert wurde. Falls nicht, geeignete Maßnahmen ergreifen, um den Aktuator zu aktivieren und das Ereignis zu protokollieren.

Frage

Meine Regel wurde nicht wie erwartet ausgeführt, als ein Uplink empfangen wurde. Was sollte ich prüfen?

Antwort

Wenn eine Regel nicht auslöst, liegt es oft daran, dass die Condition falsch ist – falscher Feldname, falscher Datentyp, falscher Vergleichswert oder falscher Operator. Gehen Sie zur Fehlerbehebung wie folgt vor:

1. Feldnamen prüfen
   Gehen Sie zu Devices → Ihr Gerät → Data und überprüfen Sie, dass der Feldname in Ihrer Condition genau mit der Schreibweise in den Gerätedaten übereinstimmt.

2. Datentyp prüfen

   • In der Plattform sind Feldwerte farblich codiert:
     • Blau = Zahl
     • Grün = Boolean
     • Rot = String
   • Stellen Sie sicher, dass Ihre Condition das richtige Format verwendet:
   • Verwenden Sie für Zahlen oder Booleans keine Anführungszeichen.
   • Verwenden Sie für Strings einfache Anführungszeichen um den Wert (z. B. 'Day').

3. Vergleichswert prüfen
   Wenn das Obige korrekt ist, die Regel aber immer noch nicht auslöst, überprüfen Sie, ob Ihr Trigger-Wert korrekt ist. Überprüfen Sie anhand der Zeitreihe, ob die eingehenden Daten den Schwellenwert tatsächlich überschreiten.

4. Action prüfen
   Um zu bestätigen, ob die Regel auslöst, aber die Action fehlschlägt, fügen Sie der Action ein Log hinzu.

   • Wenn das Log erscheint, löst die Regel korrekt aus und das Problem liegt in der Action.
   • Beheben Sie die Action entsprechend.

Frage

Ist es erlaubt, schleifende Regeln zu erstellen, bei denen eine Regel eine andere Regel auslöst, die schließlich die ursprüngliche Regel auslöst? Dies kann in Kombination mit Zeitverzögerungen nützlich sein, um zu bestätigen, dass eine erwartete Action tatsächlich eingetreten ist.

Antwort

Die IoT-Plattform verhindert die Erstellung direkt schleifender Regeln, wie Regel A, die Regel B auslöst, die dann Regel A auslöst.

Es gibt jedoch Umgehungslösungen:

• Verwenden Sie States, um Regeln indirekt auszulösen.
• Verwenden Sie MQTT, um Daten auf dem Plattform-Broker zu veröffentlichen und dann Regeln basierend auf normalen Conditions auszulösen, anstatt eine andere Regel direkt aufzurufen.

Selbst mit diesen Methoden drosselt die Plattform den Datenverkehr, um Überlastung zu vermeiden, aber Sie sollten dennoch Zeitverzögerungen zwischen Actions verwenden, um eine zuverlässige Ausführung sicherzustellen und unbeabsichtigte Schleifen zu vermeiden.