# App SDK

Apps allow Eliona to be extended individually with new functions and to control any additional systems and integrate their metrics. A variety of ready-made apps already exists and can be used if needed. With the Eliona App SDK, there is a tool with which new and custom apps can be developed, thereby expanding the range of available integrations and functions.

<figure><img src="https://content.gitbook.com/content/Nyvwhz1kEMXcHf4HLuZ8/blobs/HaRT8vg9tfh7GrsOdhNK/E41E3AC1-D7E4-40AE-B250-E2298376A5A0.png" 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 prerequisites must be met. These primarily serve to ensure uniform app configuration 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 your own data, for example for configuration, a database must be used for permanent persistence. These data, as well as any possible functions of the app, can only be accessed externally via a separate API.

<figure><img src="https://content.gitbook.com/content/Nyvwhz1kEMXcHf4HLuZ8/blobs/Q7WEdu0Gj4CeoqfywNtX/BD9EF003-C9FC-4EAC-B59E-F509CB53A454.png" 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 availability of this API must be configurable via the environment variables API\_ENDPOINT and API\_TOKEN.

<figure><img src="https://content.gitbook.com/content/Nyvwhz1kEMXcHf4HLuZ8/blobs/gR7Iv3hmpVx1BvR2wA4L/3774B0AD-B247-4887-A90F-D990D5FBEBCF.png" alt=""><figcaption></figcaption></figure>

For access to the REST API and the WebSockets, ready-made libraries can be used that 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 require their own data. These are, 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 entities (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 is to be stored in an app-specific schema, typically named after the app. To ensure cross-app compatibility, all database access must work smoothly and fully with a PostgreSQL DMBS.

<figure><img src="https://content.gitbook.com/content/Nyvwhz1kEMXcHf4HLuZ8/blobs/zU0se9rUALXYuO6btz6m/96066E61-EC7C-4D16-94AD-175933041617.png" alt=""><figcaption></figcaption></figure>

For access to the database, ready-made libraries can be used that 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 offers 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 with the name *openapi.yaml* This is intended to ensure a uniform and precise description of the interface. The availability of the API must be configurable via the environment variable API\_SERVER\_PORT (default value 3000).

<figure><img src="https://content.gitbook.com/content/Nyvwhz1kEMXcHf4HLuZ8/blobs/I0cgbDL3COJ3mOMXdG1n/image.png" alt=""><figcaption></figcaption></figure>

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

### App Lifecycle

An created app 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 ability for the app to be versioned within Eliona and for the token required to access the Eliona API to be generated and communicated.

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, the app start is registered in Eliona and the app itself can, if required, create its database schema and necessary database objects and populate them with initial values.

After the first start of the app, several further developments may modify the app and require 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 through 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 informs the Eliona environment that the app is set up and available. The prerequisite is that the app has previously been activated in Eliona. The following tasks are typical as part of an initialization:

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

For initialization, ready-made libraries can be used that 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. This also serves to determine which version is currently installed and thus whether and which migration steps may need to be carried out.

For migration, ready-made libraries can be used that 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 to 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.

### App SDK summary of requirements

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

* App development is done in Go
* Use of the Git version control system
* App must be registered and an access token must be created
* For access, use the Eliona API via access token
* Use your own 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`: Accessibility of the app's own API

The following files are expected:

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

### App SDK Resources Overview

For the development of Eliona apps, numerous resources and libraries are available. 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>