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.
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.
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.
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.
For access to the REST API and the WebSockets, ready-made libraries can be used that already take all necessary requirements into account.
For development, a mock can be used that enables access via the API without using a complete Eliona environment.
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.
For access to the database, ready-made libraries can be used that already take all necessary requirements into account.
For development, a mock can be used that enables access to a suitable database without using a complete Eliona environment.
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).
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.
Activation
Installation
Initialization
Further development
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.
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.
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 APIAPI_TOKEN: Access token for the Eliona APICONNECTION_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 imageopenapi.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 documentation: https://api.eliona.io
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
Was this helpful?