App SDK

Apps ermöglichen es Eliona individuell, um neue Funktionen zu erweitern und beliebige weitere Systeme zu steuern und deren Kennzahlen einzubinden. Dazu gibt es bereits eine Vielzahl vorgefertigter Apps, die bei Bedarf genutzt werden können. Mit dem Eliona App SDK existiert ein Werkzeug, mit dem neue und eigene Apps entwickelt werden können und so die Palette verfügbarer Integrationen und Funktionen ausgebaut wird.

Überblick

Für die Entwicklung von Apps mit dem Eliona App SDK sind gewisse Anforderungen und Rahmenbedingungen zu beachten. Zum einen gilt es definierte Schnittstellen zu nutzen und zum anderen definierten Schnittstellen anzubieten. Nur so kann eine App reibungslos in einer Eliona-Umgebung eingesetzt werden. Ausserdem sind technische Voraussetzungen zu erfüllen. Diese dienen primär einer einheitlichen Konfiguration der App sowie der Kompatibilität über alle Apps hinweg.

Zentrale Anlaufstelle für das Eliona App SDK und alle notwendigen Ressourcen für die Entwicklung von Apps sind bei GitHub zu finden.

Eliona bei GitHub

Schnittstelle

Zugriffe auf das Eliona-Kernsystem erfolgen ausschliesslich über die Eliona-API. Für eigene Daten, beispielsweise zur Konfiguration, ist eine Datenbank zur dauerhaften Persistierung zu verwenden. Auf diese Daten sowie auf mögliche Funktionen der App kann von extern nur über eine eigene API zugegriffen werden.

REST API

Damit Apps auf Funktionen und Daten des Eliona-Kernsystems zugreifen können, stellt Eliona eine umfangreiche REST-API sowie WebSockets zur Verfügung. Die Erreichbarkeit dieser API muss über die Umgebungsvariablen API_ENDPOINT und API_TOKEN konfiguriert werden können.

Für den Zugriff auf die REST API und die WebSockets können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.

Eliona-Client
Client

Für die Entwicklung kann ein Mock verwendet werden, der den Zugriff über die API ermöglicht, ohne eine vollständige Eliona-Umgebung zu nutzen.

Eliona Mock

Datenbank

Apps benötigen in der Regel eigene Daten. Das sind beispielsweise:

  • Konfigurationsdaten (allg. Einstellungen, Timeouts, Poll-Intervalle usw.)

  • Daten für den Zugriff auf externe Systeme (Passwörter, API-Endpunkte usw.)

  • Mapping zwischen Eliona-Objekten und externen Einheiten (Assets, Devices usw.)

Diese Daten sind durch die App dauerhaft in einer Datenbank zu persistieren. Diese Datenbank muss über die Umgebungsvariable CONNECTION_STRING konfiguriert werden können. Innerhalb der Datenbank sind diese Daten in einem App-eigenen Schema, typischerweise mit dem Namen der App, abzulegen. Zur Sicherstellung einer übergreifenden Kompatibilität aller Apps müssen die Datenbankzugriffe reibungslos und vollständig mit einem PostgreSQL DMBS funktionieren.

Für den Zugriff auf die Datenbank können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.

Für die Entwicklung kann ein Mock verwendet werden, der den Zugriff auf eine geeignete Datenbank ermöglicht, ohne eine vollständige Eliona-Umgebung zu nutzen.

Eliona Mock

App API

Sofern eine App separate Funktionen oder eigene Daten anbietet bzw. benötigt, müssen diese extern durch eine eigene API aufgerufen oder modifiziert werden können. Somit ist es unter anderem möglich, dass die Eliona für die App eigene Konfigurationsoberflächen anbietet.

Die Definition dieser Schnittstelle ist über eine OpenAPI-Beschreibungsdatei mit dem Namen openapi.yaml zu definieren. Dadurch soll eine einheitliche und exakte Beschreibung der Schnittstelle sichergestellt werden. Die Erreichbarkeit der API muss über die Umgebungsvariable API_SERVER_PORT (Standardwert 3000) einstellbar sein.

Die API muss zusammen mit der Funktion der App verfügbar sein. Das bedeutet, dass beim Start einer App auch immer gleichzeitig die API gestartet sein muss.

App Lebenszyklus

Eine erstellte App durchläuft einen Lebenszyklus innerhalb einer Eliona-Umgebung.

  1. Freischaltung

  2. Installation

  3. Initialisierung

  4. Weiterentwicklung

  5. Deinstallation

Damit eine App für einer Eliona-Umgebung zur Verfügung steht bzw. genutzt werden kann, muss die App freigeschaltet werden. Dazu muss der Administrator die App unter ihrem Namen registrieren. Dazu gehört, dass die App innerhalb Eliona versioniert werden kann und dass der für den Zugriff notwendige Token für die Eliona-API generiert und bekannt gegeben wird.

Die Installation stellt sicher, dass eine lauffähige Version der App zur Verfügung steht. In der Regel ist dies ein Docker-Image, das notwendigen Komponenten der App enthält und startet.

Die Initialisierung der App erfolgt im Rahmen des ersten Starts der App innerhalb einer Eliona-Umgebung. Dabei wird dieser Start der App in Eliona registriert und die App selbst kann, sofern erforderlich, ihr Datenbankschema sowie notwendige Datenbankobjekte anlegen und mit Initialwerten befüllen.

Nach dem ersten Start der App können mehrere Weiterentwicklungen die App modifizieren und eine Migration bestehende Strukturen oder Daten erfordern. Dazu können Patches in einer Eliona-Umgebung registriert und die notwendigen Schritte durchgeführt werden.

Wird eine App nicht weiter benötigt, kann sie wieder aus einer Eliona-Umgebung entfernt werden. Das bedeutet, dass die App gestoppt und die lauffähige Version entfernt wird.

Installation

Für die Installation einer App muss auch als Docker Image zur Verfügung stehen, um letztendlich modular in einer Eliona-Umgebung integriert und gestartet werden zu können. Demnach benötigt jede App ein passendes Dockerfile, über das ein Image mit einer lauffähigen Version der App erstellt werden kann. Das Image muss dann alle notwendigen Komponenten der App (funktional, App-API usw.) starten.

Initialisierung

Die Initialisierung der App muss von dieser in Eliona registriert werden. Damit wird der Eliona-Umgebung mitgeteilt, dass die App eingerichtet und verfügbar ist. Voraussetzung ist, dass die App vorher in Eliona freigeschaltet wurde. Folgende Aufgaben sind typisch im Rahmen einer Initialisierung:

  • Registrierung über Eliona-API

  • Anlage Datenbankschema für App

  • Erstellung Datenbankobjekte

  • Anlage Standarddaten

Für die Initialisierung können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.

Weiterentwicklung und Migration

Für neuere Version einer App müssen diese jeweils in Eliona registriert werden. Dies dient gleichzeitig der Erkennung, welche Version bisher installiert ist und somit ob und welche Migrationsschritte eventuell zu erledigen sind.

Für die Migration können vorgefertigte Bibliotheken verwendet werden, die bereits alle notwendigen Voraussetzungen berücksichtigen.

App Best Practices

Continuous Asset Creation (CAC)

Das Continuous Asset Creation (CAC) ermöglicht es Apps, automatisch neue Geräte und Sensoren zu erkennen und Assets in Eliona anzulegen, einschliesslich des Mappings zwischen ihnen. Hierarchische Beziehungen und vorhandene Bezeichnungen können berücksichtigt werden, während der Benutzer entscheidet, wie er die automatisch erstellten Assets in Eliona verwendet. Das CAC unterstützt auch das Löschen von Assets und ermöglicht die Erstellung von Vorlagen für Dashboards, die die automatisch generierten Assets angemessen darstellen.

App SDK Zusammenfassung der Anforderungen

Die technischen und systemischen Anforderungen für eine App mit dem Eliona App SDK können wie folgt zusammengefasst werden:

  • Die Entwicklung von Apps erfolgt in Go

  • Einsatz der Versionsverwaltung Git

  • App muss registriert und ein Zugriffstoken muss erstellt sein

  • Für Zugriffe Nutzung der Eliona-API über Zugriffstoken

  • Zur Persistierung Nutzung eines eigenen Datenbankschemas

  • Datenbankobjekte und Zugriffe kompatibel für PostgreSQL

  • Datenzugriff und Funktionen von extern nur über eigene API

Die App muss mindestens folgende Umgebungsvariablen unterstützen:

  • API_ENDPOINT: Endpunkt der Eliona-API

  • API_TOKEN: Zugriffstoken auf die Eliona-API

  • CONNECTION_STRING: Datenbank für die Ablage eigener Daten (PostgreSQL)

  • API_SERVER_PORT: Erreichbarkeit der App-eigenen API

Folgende Dateien werden erwartet:

  • Dockerfile: Erstellen eines lauffähigen Images

  • openapi.yaml: Definition und Dokumentation der App-eigenen API

App SDK Ressourcen Übersicht

Für die Entwicklung von Eliona Apps stehen etliche Ressourcen und Bibliotheken zur Verfügung. Diese befinden sich im Eliona Profil auf GitHub.

Im Einzelnen sind folgende Ressourcen zu nennen:

Last updated