# App SDK

## App SDK

Apps ermöglichen es, BuildingPro Suites individuell mit neuen Funktionen zu erweitern sowie andere Systeme anzusteuern und deren Kennzahlen zu integrieren. Zu diesem Zweck steht bereits eine große Anzahl vorgefertigter Apps zur Verfügung, die je nach Bedarf genutzt werden können. Mit dem BuildingPro Suites App SDK gibt es ein Werkzeug, mit dem neue und kundenspezifische Apps entwickelt werden können, wodurch das Angebot verfügbarer Integrationen und Funktionen erweitert wird.

<figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2FiZEeH9lfOf3JVVDCTSqu%2FE41E3AC1-D7E4-40AE-B250-E2298376A5A0.png?alt=media&#x26;token=958f25c0-222d-4aa0-addd-445e5e153a9e" alt=""><figcaption></figcaption></figure>

### Übersicht

Für die Entwicklung von Apps mit dem BuildingPro Suites App SDK müssen bestimmte Anforderungen und Rahmenbedingungen beachtet werden. Einerseits ist die Verwendung definierter Schnittstellen erforderlich, andererseits das Bereitstellen definierter Schnittstellen. Nur so kann eine App in einer BuildingPro Suites-Umgebung reibungslos genutzt werden. Darüber hinaus müssen technische Voraussetzungen erfüllt sein. Diese dienen vor allem dazu, eine einheitliche Konfiguration der App und die Kompatibilität über alle Apps hinweg sicherzustellen.

Die zentrale Anlaufstelle für das BuildingPro Suites App SDK und alle notwendigen Ressourcen für die App-Entwicklung ist auf GitHub zu finden.

{% embed url="<https://github.com/eliona-smart-building-assistant>" %}
BuildingPro Suites auf GitHub
{% endembed %}

### Schnittstelle

Der Zugriff auf das BuildingPro Suites-Kernsystem erfolgt ausschließlich über die BuildingPro Suites API. Für benutzerdefinierte Daten, beispielsweise zur Konfiguration, muss eine Datenbank für die dauerhafte Persistenz verwendet werden. Auf diese Daten sowie auf mögliche Funktionen der App kann extern nur über eine benutzerdefinierte API zugegriffen werden.

<figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2FLSCoY3RxvzdWqqvWfMUm%2FBD9EF003-C9FC-4EAC-B59E-F509CB53A454.png?alt=media&#x26;token=3f81e5dc-43c3-4764-b6da-7d476dfee37e" alt=""><figcaption></figcaption></figure>

### REST-API

Damit Apps auf Funktionen und Daten des BuildingPro Suites-Kernsystems zugreifen können, stellt BuildingPro Suites eine umfangreiche REST API und WebSockets bereit. Die Erreichbarkeit dieser API muss über die Umgebungsvariablen API\_ENDPOINT und API\_TOKEN konfigurierbar sein.

<figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2F3nltvFVKPlYwxGRsGJJ9%2F3774B0AD-B247-4887-A90F-D990D5FBEBCF.png?alt=media&#x26;token=ff627e96-c4b4-490e-b1c0-b7dfd5c7839c" alt=""><figcaption></figcaption></figure>

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

{% embed url="<https://github.com/eliona-smart-building-assistant/go-eliona>" %}
BuildingPro Suites-Client
{% endembed %}

{% embed url="<https://github.com/eliona-smart-building-assistant/go-eliona-api-client>" %}
Client
{% endembed %}

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

{% embed url="<https://github.com/eliona-smart-building-assistant/eliona-mock>" %}
BuildingPro Suites Mock
{% endembed %}

### Datenbank

Apps benötigen in der Regel eigene Daten. Dazu gehören beispielsweise:

* Konfigurationsdaten (allgemeine Einstellungen, Timeouts, Polling-Intervalle usw.)
* Daten für den Zugriff auf externe Systeme (Passwörter, API-Endpunkte usw.)
* Zuordnung zwischen BuildingPro Suites-Objekten und externen Einheiten (Assets, Geräte usw.)

Diese Daten müssen von der App dauerhaft in einer Datenbank gespeichert werden. Diese Datenbank muss über die Umgebungsvariable CONNECTION\_STRING konfigurierbar sein. Innerhalb der Datenbank müssen diese Daten in einem app-spezifischen Schema gespeichert werden, typischerweise mit dem Namen der App. Um die übergreifende Kompatibilität aller Apps sicherzustellen, muss der Datenbankzugriff problemlos und vollständig mit einem PostgreSQL-DMBS funktionieren.

<figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2Fe8NULEk6zoVwKalKNfIP%2F96066E61-EC7C-4D16-94AD-175933041617.png?alt=media&#x26;token=147cac35-db34-4663-b423-af1c8638271c" alt=""><figcaption></figcaption></figure>

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

{% embed url="<https://github.com/eliona-smart-building-assistant/go-utils>" %}

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

{% embed url="<https://github.com/eliona-smart-building-assistant/eliona-mock>" %}
BuildingPro Suites Mock
{% endembed %}

### App-API

Wenn eine App eigene Funktionen oder eigene Daten anbietet oder benötigt, müssen diese extern über eine benutzerdefinierte API aufgerufen oder geändert werden können. Dies ermöglicht unter anderem, dass BuildingPro Suites eigene Konfigurationsoberflächen für die App bereitstellen kann.

Die Definition dieser Schnittstelle muss über eine OpenAPI-Beschreibungsdatei mit dem Namen *openapi.yaml*erfolgen. Dies soll eine einheitliche und präzise Beschreibung der Schnittstelle sicherstellen. Die Erreichbarkeit der API muss über die Umgebungsvariable API\_SERVER\_PORT (Standardwert 3000) einstellbar sein.

<figure><img src="https://3489494878-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9GvUpaatBiReR43XFSMg%2Fuploads%2FPoz5uSwEhzthcOhMMO6V%2Fimage.png?alt=media&#x26;token=2ee5e676-301b-4409-bee9-6cfd03e5f563" alt=""><figcaption></figcaption></figure>

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

### App-Lifecycle

Eine erstellte App durchläuft innerhalb einer BuildingPro Suites-Umgebung einen Lifecycle.

1. Aktivierung
2. Installation
3. Initialisierung
4. Weiterentwicklung
5. Deinstallation

Damit eine App in einer BuildingPro Suites-Umgebung verfügbar oder nutzbar ist, muss die App aktiviert werden. Dazu muss der Administrator die App unter ihrem Namen registrieren. Dazu gehört die Möglichkeit, die App innerhalb von BuildingPro Suites zu versionieren sowie den für den Zugriff auf die BuildingPro Suites API notwendigen Token zu erzeugen und bekanntzugeben.

Die Installation stellt sicher, dass eine lauffähige Version der App verfügbar ist. Dies ist in der Regel ein Docker-Image, das die notwendigen Komponenten der App enthält und startet.

Die Initialisierung der App erfolgt beim ersten Start der App innerhalb einer BuildingPro Suites-Umgebung. Dabei wird der Start der App in BuildingPro Suites registriert, und die App selbst kann bei Bedarf ihr Datenbankschema und notwendige Datenbankobjekte anlegen und mit Anfangswerten befüllen.

Nach dem ersten Start der App können mehrere Weiterentwicklungen die App verändern und eine Migration bestehender Strukturen oder Daten erforderlich machen. Dafür können Patches in einer BuildingPro Suites-Umgebung registriert und die notwendigen Schritte durchgeführt werden.

Wenn eine App nicht mehr benötigt wird, kann sie aus einer BuildingPro Suites-Umgebung entfernt werden. Das bedeutet, dass die App gestoppt und die lauffähige Version entfernt wird.

#### Installation

Damit eine App installiert werden kann, muss sie als Docker-Image verfügbar sein, um letztlich modular in einer BuildingPro Suites-Umgebung integriert und gestartet werden zu können. Dementsprechend benötigt jede App ein geeignetes Dockerfile, über das ein Image mit einer lauffähigen Version der App erstellt werden kann. Das Image muss anschließend alle notwendigen Komponenten der App starten (Funktion, App-API usw.).

#### Initialisierung

Die Initialisierung der App muss von der App in BuildingPro Suites registriert werden. Dadurch wird der BuildingPro Suites-Umgebung mitgeteilt, dass die App eingerichtet und verfügbar ist. Voraussetzung ist, dass die App zuvor in BuildingPro Suites aktiviert wurde. Bei der Initialisierung sind typischerweise folgende Aufgaben zu erledigen:

* Registrierung über die BuildingPro Suites API
* Erstellung eines Datenbankschemas für die App
* Erstellung von Datenbankobjekten
* Erstellung von Standarddaten

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

{% embed url="<https://github.com/eliona-smart-building-assistant/go-eliona>" %}
App-Handling
{% endembed %}

#### Weiterentwicklung und Migration

Für neuere Versionen einer App müssen diese in BuildingPro Suites registriert werden. Dies dient auch dazu, zu erkennen, welche Version bisher installiert wurde und somit, ob und welche Migrationsschritte gegebenenfalls durchgeführt werden müssen.

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

{% embed url="<https://github.com/eliona-smart-building-assistant/go-eliona>" %}
App-Handling
{% endembed %}

### Best Practices für Apps

#### Kontinuierliche Asset-Erstellung (CAC)

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

### Zusammenfassung der Anforderungen des App SDK

Die technischen und systemischen Anforderungen an eine App mit dem BuildingPro Suites App SDK lassen sich wie folgt zusammenfassen:

* Die Entwicklung von Apps erfolgt in Go
* Verwendung der Versionsverwaltung Git
* App muss registriert werden und ein Zugriffstoken muss erstellt werden
* Für den Zugriff die BuildingPro Suites API über ein Zugriffstoken verwenden
* Für die Persistenz ein benutzerdefiniertes Datenbankschema verwenden
* Datenbankobjekte und Zugriff müssen mit PostgreSQL kompatibel sein
* Datenzugriff und Funktionen aus externen Quellen nur über eine benutzerdefinierte API

Die App muss mindestens die folgenden Umgebungsvariablen unterstützen:

* `API_ENDPOINT`: Endpunkt der BuildingPro Suites API
* `API_TOKEN`: Zugriffstoken für die BuildingPro Suites API
* `CONNECTION_STRING`: Datenbank zur Speicherung benutzerdefinierter Daten (PostgreSQL)
* `API_SERVER_PORT`: Erreichbarkeit der benutzerdefinierten API der App

Folgende Dateien werden erwartet:

* `Dockerfile`: Erstellt ein lauffähiges Image
* `openapi.yaml`: Definition und Dokumentation der benutzerdefinierten API der App

### Übersicht über Ressourcen des App SDK

Für die Entwicklung von BuildingPro Suites-Apps stehen mehrere Ressourcen und Bibliotheken zur Verfügung. Diese befinden sich im BuildingPro Suites-Profil auf GitHub.

* BuildingPro Suites auf GitHub: <https://github.com/eliona-smart-building-assistant>

Folgende Ressourcen sind besonders zu nennen:

* BuildingPro Suites-API: <https://github.com/eliona-smart-building-assistant/eliona-api>
* BuildingPro Suites-API-Dokumentation: <https://api.eliona.io>
* BuildingPro Suites Mock: <https://github.com/eliona-smart-building-assistant/eliona-mock>
* Vorlage für neue Apps: <https://github.com/eliona-smart-building-assistant/app-template>
* Go-Client für BuildingPro Suites: <https://github.com/eliona-smart-building-assistant/go-eliona>
* Go-Client für die API: <https://github.com/eliona-smart-building-assistant/go-eliona-api-client>
* Utilities für Go: <https://github.com/eliona-smart-building-assistant/go-utils>