Überblick

Im niotix-Betrieb bildet die Firefly-Organisation den technischen Zielkontext für API-Schlüssel, Subscriptions, Geräte und Gateways. Der Firefly-Konnektor in niotix liest die Organisation über den verwendeten API-Schlüssel aus und legt die Datenintegration genau für diese Organisation an.

Organisationen und Unterorganisationen anlegen

Alle Schritte erfolgen in der Firefly-Weboberfläche. Die hierarchische Struktur besteht aus Organisationen und Unterorganisationen (Kinder unter einer übergeordneten Organisation).

Neue Organisation auf oberster Ebene

• In der Übersicht der Organisationen die Aktion zum Anlegen einer neuen Organisation wählen (Menü-/Buttonbezeichnung je nach Spracheinstellung).
• Einen Namen eintragen und das Formular absenden; die neue Organisation erscheint in der Liste und kann wie jede andere Organisation geöffnet werden.

Unterorganisationen

• Zur übergeordneten Organisation navigieren (Settings → Suborganizations).
• Dieser Bereich ist nur verfügbar, solange unter dieser Organisation noch weitere Verschachtelungsebenen zulässig sind. Die maximal mögliche Baumtiefe ist konfigurierbar (in Standardkonfigurationen liegt das Limit typischerweise im zweistelligen Ebenenbereich); ist das Limit erreicht, wird der Unterbereich nicht angeboten bzw. meldet die Oberfläche einen entsprechenden Hinweis.
• Im Baumeditor:
  • Namen der Unterorganisationen direkt in den Feldern eintragen oder ändern.
  • Über die Schaltfläche zum Hinzufügen einer Unterorganisation (oberhalb des Baums und am Knoten, sobald dieser gespeichert ist) neue Einträge auf gleicher Ebene oder tiefer ergänzen.
  • Knoten nur mit dem Papierkorbsymbol entfernen, wenn sie keine weiteren Kinder haben.
  • Die Reihenfolge per Ziehen am Griff-Symbol anpassen.
• Änderungen mit Speichern übernehmen; damit werden neue Unterorganisationen angelegt, bestehende aktualisiert oder zum Löschen vorgemerkte Einträge entfernt.

Damit lassen sich Mandanten oder Standorte als getrennte Organisationseinheiten abbilden, ohne die Verwaltung in niotix zu verdoppeln: niotix arbeitet jeweils im Kontext der Organisation, die der verwendete API-Schlüssel repräsentiert.

Hierarchieansicht Organisationen

Zugriff & Navigation

Die wichtigsten Bereiche sind:

• in niotix: Integrationen → Konnektoren — Details zum Konnektor firefly
• in Firefly: Organisation öffnen und dort Settings, Users, API Keys sowie optional Sinks

Konnektor und API-Schlüssel

Der Firefly-Konnektor in niotix verwendet mindestens:

• Firefly URL
• API Key
• optional MQTT URL

Der API-Schlüssel dient nicht nur zur Authentifizierung. niotix leitet daraus auch ab, zu welcher Firefly-Organisation der Konnektor gehört. Auf dieser Grundlage wird die organisationbezogene MQTT-Subscription angelegt.

Konto in niotix vs. Organisation in Firefly

Beide Systeme verwenden unterschiedliche Verwaltungsobjekte:

• niotix-Konto: Mandanten- und Verwaltungsgrenze in niotix
• Firefly-Organisation: Verwaltungsgrenze für Geräte, Gateways, Benutzer, API-Schlüssel und Sinks in Firefly

Für den Betrieb ist daher wichtig:

• ein niotix-Konto kann mit genau dem Firefly-Kontext arbeiten, der über den verwendeten API-Schlüssel erreichbar ist
• Unterorganisationen werden in Firefly verwaltet, nicht in niotix
• das Entfernen einer Organisationsmitgliedschaft in Firefly löscht nicht automatisch das zugrunde liegende Firefly-Konto

Benutzerverwaltung und Rollen

Firefly trennt zwischen Konto und Organisationsmitgliedschaft:

• ein Firefly-Konto ist die eigentliche Benutzeridentität
• die Rolle wird je Organisation vergeben

Firefly bietet drei sichtbare Organisationsrollen:

• Read-Only
  Lesezugriff ohne schreibende Verwaltungsaktionen
• Device Admin
  Schreibzugriff auf gerätebezogene Bereiche wie Geräte, Gateways, Multicast-Gruppen oder Anwendungsansichten
• Organization Admin
  Vollständige Organisationsverwaltung, einschließlich Einstellungen, Benutzer, API-Schlüssel und organisationsbezogener Änderungen

Typische Benutzeraktionen:

• Benutzer per E-Mail einladen
• Rollen einer vorhandenen Mitgliedschaft ändern
• Mitgliedschaft aus einer Organisation entfernen

API-Schlüssel in Firefly

Organisation: Einstellungen und API Keys

API-Schlüssel in Firefly werden organisationsbezogen verwaltet. Unter API Keys der Organisation lässt sich ein neuer Schlüssel über die dortige Anlegeaktion erzeugen. Pro Schlüssel sind u. a. Name, Gültigkeit (Ende der Gültigkeit, Valid Until), Rate Limit (Begrenzung der API-Zugriffe) und Besitzerkontext relevant. Der Schlüsselwert wird nach der Erstellung in der Regel nur einmal vollständig angezeigt und sollte sicher dokumentiert werden, bevor er in niotix im Konnektor firefly hinterlegt wird.

Im niotix-Kontext werden diese Schlüssel vor allem für:

• REST-Aufrufe des Firefly-Konnektors
• Ermittlung der Firefly-Organisation
• Subscription-Verwaltung
• Gateway- und Geräteoperationen

verwendet.

Gültigkeit und Ablauf von API-Schlüsseln

Jeder Schlüssel besitzt ein Ende der Gültigkeit (Valid Until). Neu erzeugte Schlüssel erhalten eine Standardlaufzeit (häufig etwa 90 Tage ab Erstellung, abhängig von Version und Konfiguration); das Datum kann in den Organisationseinstellungen unter API Keys angepasst oder verlängert werden.

Vor dem Ablaufdatum

• Für Organisation-Admins auf der betroffenen Organisation und ggf. auf übergeordneten Organisationen können E-Mail-Erinnerungen versendet werden, wenn die Gültigkeit in wenigen Wochen bzw. wenigen Tagen endet (mehrstufig; genaue Intervalle und ggf. weitere Kanäle hängen von der Betriebskonfiguration ab).
• Die Nachricht nennt Namen des Schlüssels, Organisation und das Datum Valid Until und verweist auf die Bearbeitungsseite der API-Schlüssel der Organisation.

Nach dem Ablaufdatum

• REST-Anfragen an die Firefly-API mit diesem Schlüssel werden mit HTTP 401 abgewiesen; die Antwort enthält eine klare Meldung, dass der API-Schlüssel abgelaufen ist.
• Der Firefly-Konnektor in niotix kann dann nicht mehr authentifiziert auf Firefly zugreifen; Synchronisation, Subscription-Pflege und verwandte Vorgänge bleiben ausgesetzt, bis ein gültiger Schlüssel hinterlegt wird (neuer Schlüssel oder Verlängerung in Firefly und Aktualisierung der Konnektorkonfiguration in niotix).
• Ein abgelaufener Schlüssel wird dadurch nicht automatisch aus der Datenbank entfernt; er muss explizit erneuert, ersetzt oder gelöscht werden.

Sinks und Webhooks

Firefly bietet mit Sinks eine organisationsbezogene Webhook-Funktion. Damit können Ereignisse wie Uplink- oder Downlink-Ereignisse an externe Ziele per HTTP weitergegeben werden.

Für niotix-basierte Firefly-Integrationen gilt jedoch:

• Sinks/Webhooks sind nicht der primäre Integrationspfad
• niotix verwendet stattdessen REST + MQTT-Subscriptions
• Sinks sind vor allem dann relevant, wenn Firefly ohne niotix an weitere Systeme angebunden wird

Typische Sink-Eigenschaften in Firefly sind:

• Ziel-URL
• Content-Type
• Ereignisauswahl pro Event
• organisationsbezogene Gültigkeit

Root-Admin-Funktionen

Bestimmte Verwaltungsfunktionen stehen nur Benutzern zur Verfügung, die in der Root-Organisation mit Administrationsrechten arbeiten. Dazu gehören insbesondere:

• übergreifende Administrationsmenüs
• organisationsweite Verwaltungsfunktionen
• Benutzer- oder Gerätezugriffe mit Root-Kontext

Zusätzlich gilt für Organisationen:

• neue Organisationen auf Wurzelebene können angelegt werden (siehe Organisationen und Unterorganisationen anlegen)
• Organisationen können nur gelöscht werden, wenn abhängige Geräte und Benutzerbeziehungen vorher bereinigt wurden
• das Verschieben oder Neuordnen von Geräten muss im Organisationskontext sauber vorbereitet werden

Fehlerbehebung

Wenn ein Firefly-Konnektor keine Daten liefert, wird empfohlen, Folgendes zu überprüfen:

• API-Schlüssel gehört zur erwarteten Organisation
• API-Schlüssel ist noch gültig (Datum Valid Until)
• Konnektor verwendet die richtige Firefly-URL
• MQTT URL im Konnektor firefly in niotix ist korrekt, wenn Uplinks erwartet werden

Wenn UI-Funktionen in Firefly fehlschlagen, wird empfohlen, Folgendes zu überprüfen:

• Rolle innerhalb der richtigen Organisation
• Root-Admin-Kontext erforderlich oder nicht
• Verwechslung von Firefly-Konto und Organisationsmitgliedschaft

Häufige Fragen

Warum sieht niotix nicht alle Firefly-Organisationen?

Der Firefly-Konnektor arbeitet mit dem Organisationskontext des verwendeten API-Schlüssels. Sichtbarkeit und technische Verarbeitung hängen daher direkt von diesem Schlüssel ab.

Wann sollten Sinks statt niotix verwendet werden?

Sinks sind sinnvoll, wenn Firefly Ereignisse direkt an ein anderes Zielsystem senden soll. Für die Anbindung an niotix ist jedoch der Firefly-Konnektor der Standardpfad.

Welche Rolle wird für API-Schlüssel und Benutzerverwaltung benötigt?

API-Schlüssel sind keine Organisationsmitglieder und haben keine Firefly-Rolle; sie sind organisationsgebundene Zugangsdaten für die API. Zum Anlegen, Verlängern und Entfernen von API-Schlüsseln in der Firefly-Oberfläche sind in der Regel Rechte auf Organisationsebene erforderlich — typischerweise die Rolle Organization Admin. Für die Benutzerverwaltung (Einladungen, Mitgliedschaften, Benutzerrollen) ist Organization Admin üblicherweise erforderlich; rein gerätebezogene Änderungen können je nach Bereich bereits mit Device Admin möglich sein.

Warum verarbeitet der Konnektor keine Daten, obwohl Firefly erreichbar ist?

In vielen Fällen gehört der verwendete API-Schlüssel nicht zur erwarteten Organisation, ist abgelaufen oder wurde im Konnektor mit der falschen Firefly-URL kombiniert. Zusätzlich die MQTT URL im Konnektor prüfen, wenn Uplinks erwartet werden. Siehe auch Fehlerbehebung.

Warum fehlen nach einem API-Key-Wechsel plötzlich Daten?

Ein API-Key-Wechsel ändert den Organisationskontext des Konnektors. Ab niotix 3.8.2 wird die Firefly-Subscription beim Speichern der Konnektoreinstellungen in der Regel automatisch auf die neue Organisation umgestellt; der Konnektor setzt die MQTT-Anbindung danach neu auf. Bleibt dennoch kein Datenfluss, sind MQTT URL, Netzwerk/Firewall und die Zielorganisation in Firefly zu prüfen.