# 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 bei Bedarf verwendet werden können. Mit dem BuildingPro Suites App SDK gibt es ein Werkzeug, mit dem neue und maßgeschneiderte Apps entwickelt werden können, wodurch sich das Angebot verfügbarer Integrationen und Funktionen erweitert.

<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 es erforderlich, definierte Schnittstellen zu nutzen, andererseits definierte Schnittstellen bereitzustellen. Nur so kann eine App in einer BuildingPro-Suites-Umgebung reibungslos verwendet 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 zwischen allen Apps sicherzustellen.

Der zentrale Ansprechpartner 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 eigene Daten, etwa für die Konfiguration, muss eine Datenbank zur dauerhaften Speicherung verwendet werden. Auf diese Daten sowie auf mögliche Funktionen der App kann von außen nur über eine eigene 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>

Zur Nutzung der REST-API und der 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 typischerweise 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 einer 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>

Zur Nutzung der 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 separate Funktionen oder eigene Daten anbietet oder benötigt, müssen diese von außen über eine eigene API aufgerufen oder verändert werden können. Dadurch ist es unter anderem möglich, dass BuildingPro Suites eigene Konfigurationsoberflächen für die App bereitstellt.

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-Lebenszyklus

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

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. Dies umfasst die Möglichkeit, die App innerhalb von BuildingPro Suites zu versionieren und das für den Zugriff auf die BuildingPro Suites API notwendige Token zu erzeugen und bekannt zu geben.

Die Installation stellt sicher, dass eine lauffähige Version der App verfügbar ist. Dabei handelt es sich üblicherweise um 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 sowie 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. Dazu können in einer BuildingPro-Suites-Umgebung Patches registriert und die notwendigen Schritte ausgefü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 schließlich 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 (funktional, 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. Typische Aufgaben während der Initialisierung sind:

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

Zur 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 eventuell durchgeführt werden müssen.

Zur 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 zu erstellen, 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 Git-Versionsverwaltung
* Die App muss registriert sein und ein Zugriffstoken muss erstellt werden
* Für den Zugriff die BuildingPro Suites API über Zugriffstoken verwenden
* Für die Persistenz ein eigenes Datenbankschema verwenden
* Datenbankobjekte und Zugriff müssen mit PostgreSQL kompatibel sein
* Datenzugriff und Funktionen aus externen Quellen nur über eine eigene 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 eigener Daten (PostgreSQL)
* `API_SERVER_PORT`: Erreichbarkeit der eigenen API der App

Die folgenden Dateien werden erwartet:

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

### Übersicht über App-SDK-Ressourcen

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>
* Dienstprogramme für Go: <https://github.com/eliona-smart-building-assistant/go-utils>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.buildings.ability.abb/collection/german/for-developers/app-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.