English

App SDK

Development Guide for Programming Apps with Eliona App SDK

Apps allow Eliona to be individually expanded with new functions and to control any other systems and integrate their key figures. For this purpose, there are already a large number of prefabricated apps that can be used as needed. With the Eliona App SDK, a tool exists with which new and own apps can be developed and thus the range of available integrations and functions is expanded.

Overview

For the development of apps with the Eliona App SDK, certain requirements and framework conditions must be observed. On the one hand, defined interfaces must be used and on the other hand, defined interfaces must be offered. Only in this way can an app be used smoothly in an Eliona environment. In addition, technical requirements must be met. These primarily serve a uniform 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 at GitHub.

Interface

Access to the Eliona core system is exclusively via the Eliona API. For own data, for example for configuration, a database is to be used for permanent persistence. This data as well as possible functions of the app can only be accessed externally via a separate API.

REST API

To enable 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.

For accessing the REST API and the WebSockets, prefabricated libraries can be used that already take into account all the necessary prerequisites.

A mock can be used for development that allows access via the API without using a full Eliona environment.

Database

Apps usually require their own data. These are for example:

  • Configuration data (general settings, timeouts, poll intervals, etc.)

  • Data for accessing external systems (passwords, API endpoints, etc.)

  • Mapping between Eliona objects and external entities (assets, devices, etc.)

This data must be persisted permanently in a database by the app. This database must be configurable via the environment variable CONNECTION_STRING. Within the database, this data must be stored in an app-specific schema, typically with the name of the app. To ensure cross-app compatibility, database accesses must work smoothly and completely with a PostgreSQL DMBS.

To access the database, prefabricated libraries can be used, which already take into account all the necessary requirements.

A mock can be used for development that allows access to a suitable database without using a full Eliona environment.

App API

If an app offers or requires separate functions or its own data, it must be possible to call or modify these externally via its own API. Thus, among other things, it is possible for Eliona to provide its own configuration interfaces for the app. The definition of this interface is to be defined via an OpenAPI description file with the name openapi.yaml. This is to ensure a consistent and accurate description of the interface. The accessibility of the API must be adjustable via the environment variable API_SERVER_PORT (default value 3000).

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

App Life Cycle

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

  1. Activation

  2. Installation

  3. Initialization

  4. Further development

  5. Uninstallation

In order for an app to be available or used in an Eliona environment, the app must be activated. To do this, the administrator must register the app under its name. This includes that the app can be versioned within Eliona and that the token required for access is generated and announced 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 necessary components of the app.

The initialization of the app takes place as part of the first launch of the app within an Eliona environment. This start of the app is registered in Eliona and the app itself can, if necessary, create its database schema and necessary database objects and fill them with initial values.

After the initial launch 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 can be taken.

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 executable version is removed.

Installation

For the installation of an app, it must also be available as a Docker image in order to ultimately be integrated and launched in a modular manner in an Eliona environment. Accordingly, each app requires 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 informs 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 as part of an initialization:

  • Registration via Eliona API

  • Creation of database schema for app

  • Creation of database objects

  • Creation of standard data

For initialization, prefabricated libraries can be used that already take into account all the necessary prerequisites.

Further development and migration

For newer versions of an app, these must be registered in Eliona. This also serves to identify which version has been installed so far and thus whether and which migration steps may need to be taken. For the migration, prefabricated libraries can be used that already take into account all the necessary requirements.

App Best Practices

Continuous Asset Creation (CAC)

Continuous Asset Creation (CAC) enables apps to automatically discover new devices and sensors and create assets in Eliona, including mapping between them. Hierarchical relationships and existing labels can be taken into account while the user decides how to use the automatically created assets in Eliona. The CAC also supports asset deletion and allows the creation of templates for dashboards that appropriately represent the automatically generated assets.

App SDK Summary of requirements

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

  • The development of apps is done in Go

  • Use of the version management Git

  • App must be registered and an access token must be created

  • For accesses use of the Eliona API via access token

  • For persistence use of own database schema

  • Database objects and accesses compatible for PostgreSQL

  • Data access and functions from external only via own API

The app must support at least the following environment variables:

  • API_ENDPOINT: Eliona-API endpoint

  • API_TOKEN: Access tokens to 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 an executable image

  • openapi.yaml: Definition and documentation of the app's own API

App SDK Resources Overview

A number of resources and libraries are available for the development of Eliona apps. These are located in the Eliona profile on GitHub.

Specifically, resources include the following:

PreviousKontakt.ioNextRest API

Last updated