> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/german/fur-entwickler/app-sdk.md).

# App-SDK

## App-SDK

Apps ermöglichen es, BuildingPro Suites individuell um neue Funktionen zu erweitern, andere Systeme zu steuern und deren Kennzahlen zu integrieren. Dafür 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 maßgeschneiderte Apps entwickelt werden können, um das Angebot an verfügbaren Integrationen und Funktionen zu erweitern.

<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

Bei der Entwicklung von Apps mit dem BuildingPro Suites App-SDK müssen bestimmte Anforderungen und Rahmenbedingungen beachtet werden. Zum einen müssen definierte Schnittstellen verwendet und zum anderen definierte Schnittstellen bereitgestellt werden. Nur so kann eine App reibungslos in einer BuildingPro Suites-Umgebung eingesetzt werden. Außerdem müssen technische Voraussetzungen erfüllt sein. Diese dienen in erster Linie dazu, eine einheitliche Konfiguration der App und die Kompatibilität zwischen allen Apps sicherzustellen.

Die zentrale Anlaufstelle für das BuildingPro Suites App-SDK und alle für die App-Entwicklung erforderlichen Ressourcen 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, beispielsweise zur Konfiguration, muss eine Datenbank zur dauerhaften Speicherung verwendet werden. Auf diese Daten sowie auf mögliche Funktionen der App kann extern 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>

Für den Zugriff auf die REST API und WebSockets können vorgefertigte Bibliotheken verwendet werden, die bereits alle erforderlichen 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, Zeitüberschreitungen, Abfrageintervalle 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 muss die App dauerhaft in einer Datenbank speichern. Diese Datenbank muss über die Umgebungsvariable CONNECTION\_STRING konfigurierbar sein. In der Datenbank müssen die Daten in einem app-spezifischen Schema gespeichert werden, das in der Regel den Namen der App trägt. Um die übergreifende Kompatibilität aller Apps sicherzustellen, muss der Datenbankzugriff mit einem PostgreSQL-DBMS reibungslos und vollständig 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 erforderlichen 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 Daten anbietet oder benötigt, müssen diese extern über eine eigene API aufgerufen oder geändert werden können. Dadurch kann BuildingPro Suites unter anderem eigene Konfigurationsschnittstellen für die App bereitstellen.

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

<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 und nutzbar ist, muss sie aktiviert werden. Dazu muss der Administrator die App unter ihrem Namen registrieren. Dazu gehören die Möglichkeit, die App innerhalb von BuildingPro Suites zu versionieren, sowie die Generierung und Bekanntgabe des für den Zugriff auf die BuildingPro Suites API erforderlichen Tokens.

Durch die Installation wird sichergestellt, dass eine ausführbare Version der App verfügbar ist. Dabei handelt es sich in der Regel um ein Docker-Image, das die erforderlichen Komponenten der App enthält und startet.

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

Nach dem ersten Start der App können spätere Weiterentwicklungen Änderungen an der App vornehmen und eine Migration bestehender Strukturen oder Daten erfordern. Dazu können Patches in einer BuildingPro Suites-Umgebung registriert und die erforderlichen Schritte ausgeführt werden.

Wird eine App nicht mehr benötigt, kann sie aus einer BuildingPro Suites-Umgebung entfernt werden. Das bedeutet, dass die App gestoppt und ihre ausführbare Version entfernt wird.

#### Installation

Damit eine App installiert werden kann, muss sie als Docker-Image verfügbar sein, sodass sie schließlich modular in eine BuildingPro Suites-Umgebung integriert und gestartet werden kann. Daher benötigt jede App eine geeignete Dockerfile, mit der ein Image erstellt werden kann, das eine ausführbare Version der App enthält. Das Image muss anschließend alle erforderlichen Komponenten der App starten (Funktionalität, App-API usw.).

#### Initialisierung

Die App muss ihre Initialisierung in BuildingPro Suites registrieren. Dadurch wird der BuildingPro Suites-Umgebung mitgeteilt, dass die App eingerichtet und verfügbar ist. Voraussetzung dafür 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 Stammdaten

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

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

#### Weiterentwicklung und Migration

Neuere Versionen einer App müssen in BuildingPro Suites registriert werden. So lässt sich auch erkennen, welche Version bisher installiert wurde und ob beziehungsweise welche Migrationsschritte gegebenenfalls erforderlich sind.

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

{% embed url="<https://github.com/eliona-smart-building-assistant/go-eliona>" %}
App-Verwaltung
{% 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 ihrer Zuordnung. Hierarchische Beziehungen und vorhandene Bezeichnungen können berücksichtigt werden. 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, auf denen die automatisch generierten Assets passend dargestellt werden.

### Zusammenfassung der Anforderungen an das App SDK

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

* Die Apps werden in Go entwickelt
* Verwendung der Versionsverwaltung Git
* Die App muss registriert und ein Zugriffstoken erstellt werden
* Für den Zugriff wird die BuildingPro Suites API über ein Zugriffstoken verwendet
* Für die Persistenz wird ein benutzerdefiniertes Datenbankschema verwendet
* Datenbankobjekte und Zugriffe müssen mit PostgreSQL kompatibel sein
* Datenzugriff und Funktionen externer Quellen sind nur über eine benutzerdefinierte API möglich

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 zum Speichern benutzerdefinierter Daten (PostgreSQL)
* `API_SERVER_PORT`: Erreichbarkeit der benutzerdefinierten API der App

Die folgenden Dateien werden vorausgesetzt:

* `Dockerfile`: Erstellt ein ausführbares Image
* `openapi.yaml`: Definition und Dokumentation der benutzerdefinierten API der App

### Übersicht über die Ressourcen des App SDK

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

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

Besonders hervorzuheben sind die folgenden Ressourcen:

* BuildingPro Suites-API: <https://github.com/eliona-smart-building-assistant/eliona-api>
* Dokumentation der BuildingPro Suites-API: <https://dev.api-doc.buildings.ability.abb/>
* 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.buildings.ability.abb/collection/german/fur-entwickler/app-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
