> 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/english-v14/apps/app-sdk.md).

# App SDK

Apps make it possible to extend Eliona individually with new functions and to control any other systems and integrate their metrics. There is already a wide range of ready-made apps that can be used as needed. With the Eliona App SDK, there is a tool for developing new and custom apps, thereby expanding the range of available integrations and functions.

<figure><img src="/files/7e5b13828db4a90ced5e77af5b7d4bff0570a604" alt=""><figcaption></figcaption></figure>

### Overview

When developing apps with the Eliona App SDK, certain requirements and framework conditions must be observed. On the one hand, defined interfaces must be used; on the other hand, defined interfaces must be offered. Only then can an app be used smoothly in an Eliona environment. In addition, technical requirements must be met. These primarily serve to ensure a consistent configuration of the app as well as compatibility across all apps.

The central point of contact for the Eliona App SDK and all necessary resources for app development can be found on GitHub.

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

### Interface

Access to the Eliona core system takes place exclusively via the Eliona API. For own data, for example for configuration, a database must be used for permanent persistence. External access to this data as well as to possible functions of the app is only possible via a separate API.

<figure><img src="/files/5f81fefa8aa79b710f5dc2d0bbdd2bae3930e7e8" alt=""><figcaption></figcaption></figure>

### REST API

To allow apps to access functions and data of the Eliona core system, Eliona provides an extensive REST API as well as WebSockets. The accessibility of this API must be configurable via the environment variables API\_ENDPOINT and API\_TOKEN.

<figure><img src="/files/03da31672fc54aed85d6225f7b07efb4e6842297" alt=""><figcaption></figcaption></figure>

Ready-made libraries can be used to access the REST API and WebSockets, which already take all necessary requirements into account.

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

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

For development, a mock can be used that enables access via the API without using a complete Eliona environment.

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

### Database

Apps usually need their own data. This includes, for example:

* Configuration data (general settings, timeouts, poll intervals, etc.)
* Data for access to external systems (passwords, API endpoints, etc.)
* Mapping between Eliona objects and external units (assets, devices, etc.)

This data must be permanently persisted by the app in a database. This database must be configurable via the CONNECTION\_STRING environment variable. Within the database, this data must be stored in an app-specific schema, typically named after the app. To ensure cross-app compatibility, all database access must work seamlessly and fully with a PostgreSQL DBMS.

<figure><img src="/files/55bc4601b62e08f033729ece100def4d5583c1aa" alt=""><figcaption></figcaption></figure>

Ready-made libraries can be used to access the database, which already take all necessary requirements into account.

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

For development, a mock can be used that enables access to a suitable database without using a complete Eliona environment.

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

### App API

If an app provides or requires separate functions or its own data, these must be callable or modifiable externally via a separate API. This makes it possible, among other things, for Eliona to provide its own configuration interfaces for the app.

The definition of this interface is to be specified via an OpenAPI description file named *openapi.yaml* This is intended to ensure a consistent and precise description of the interface. The reachability of the API must be configurable via the environment variable API\_SERVER\_PORT (default value 3000).

<figure><img src="/files/efb46a273fd4b7c0881eb9919d7839b306230b8b" alt=""><figcaption></figcaption></figure>

The API must be available together with the app's functionality. This means that when an app is started, the API must always be started at the same time.

### App lifecycle

An app created goes through a lifecycle within an Eliona environment.

1. Activation
2. Installation
3. Initialization
4. Further development
5. Uninstallation

For an app to be available in or used within an Eliona environment, it must be activated. To do this, the administrator must register the app under its name. This includes the app being versioned within Eliona and the token required for access being generated and communicated for the Eliona API.

Installation ensures that a runnable version of the app is available. Usually this is a Docker image that contains and starts the necessary components of the app.

The initialization of the app takes place during the first start of the app within an Eliona environment. During this process, this app start is registered in Eliona and the app itself can, if necessary, create its database schema as well as the required database objects and populate them with initial values.

After the first start of the app, several further developments can modify the app and require a migration of existing structures or data. For this purpose, patches can be registered in an Eliona environment and the necessary steps carried out.

If an app is no longer needed, it can be removed from an Eliona environment again. This means that the app is stopped and the runnable version is removed.

#### Installation

For the installation of an app, it must also be available as a Docker image so that it can ultimately be integrated and started modularly in an Eliona environment. Accordingly, each app needs a suitable Dockerfile, via which an image with a runnable version of the app can be created. The image must then start all necessary components of the app (functional, app API, etc.).

#### Initialization

The initialization of the app must be registered by it in Eliona. This tells the Eliona environment that the app has been set up and is available. The prerequisite is that the app has previously been activated in Eliona. The following tasks are typical during initialization:

* Registration via Eliona API
* Creation of database schema for app
* Creation of database objects
* Creation of default data

Ready-made libraries can be used for initialization, which already take all necessary requirements into account.

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

#### Further development and migration

Newer versions of an app must each be registered in Eliona. At the same time, this serves to detect which version is currently installed and thus whether and which migration steps may need to be carried out.

Ready-made libraries can be used for migration, which already take all necessary requirements into account.

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

### App best practices

#### Continuous Asset Creation (CAC)

Continuous Asset Creation (CAC) enables apps to automatically detect new devices and sensors and create assets in Eliona, including the mapping between them. Hierarchical relationships and existing designations can be taken into account, while the user decides how they use the automatically created assets in Eliona. CAC also supports deleting assets and enables the creation of dashboard templates that appropriately display the automatically generated assets.

### Summary of Eliona App SDK requirements

The technical and system requirements for an app with the Eliona App SDK can be summarized as follows:

* App development takes place in Go
* Use of the Git version control system
* App must be registered and an access token must have been created
* Use the Eliona API for access via access token
* Use of a separate database schema for persistence
* Database objects and access compatible with PostgreSQL
* Data access and functions from outside only via own API

The app must support at least the following environment variables:

* `API_ENDPOINT`: Endpoint of the Eliona API
* `API_TOKEN`: Access token for the Eliona API
* `CONNECTION_STRING`: Database for storing own data (PostgreSQL)
* `API_SERVER_PORT`: Reachability of the app's own API

The following files are expected:

* `Dockerfile`: Creation of a runnable image
* `openapi.yaml`: Definition and documentation of the app's own API

### Overview of App SDK resources

Numerous resources and libraries are available for developing Eliona apps. These are located in the Eliona profile on GitHub.

* Eliona on GitHub: <https://github.com/eliona-smart-building-assistant>

The following resources should be mentioned in particular:

* Eliona API: <https://github.com/eliona-smart-building-assistant/eliona-api>
* Eliona API documentation: <https://api.eliona.io>
* Eliona Mock: <https://github.com/eliona-smart-building-assistant/eliona-mock>
* Template for new apps: <https://github.com/eliona-smart-building-assistant/app-template>
* Go client for Eliona: <https://github.com/eliona-smart-building-assistant/go-eliona>
* Go client for API: <https://github.com/eliona-smart-building-assistant/go-eliona-api-client>
* Utilities for 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 dynamically by asking a question.

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

```
GET https://docs.buildings.ability.abb/collection/english-v14/apps/app-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.