# Eliona modules for Niagara
Functionality
The module enables data transmission from Niagara components to Eliona assets. It sends the value of a configurable slot (default: `out`) and, if available, its status to Eliona. Alarms can also be forwarded directly to Eliona. Optionally, the module can automatically create and link assets in Eliona and assign the corresponding asset types to them.
Conversely, the module can receive data from Eliona and write it to a configurable slot (default: `set`) of a Niagara component. Alarm acknowledgements from Eliona are supported, so status updates can be synchronized within the Niagara alarm console.
#### Communication
Communication between Niagara and Eliona uses the Eliona REST API and WebSockets provided by Eliona, with data transmitted in JSON format. All communication is encrypted via HTTPS.
***
### Quick Start Guide
#### Requirements
* Access to an Eliona instance (username and password)
* Credentials for the Eliona API (URL and token with read/write permissions)
* Access to a Niagara station (see compatibility)
#### Installation
To install the Eliona module, copy `eliona-rt.jar` and `eliona-wb.jar` in the `modules`to the folder of your local Niagara installation or use the **Software Manager** under Platform to install the module. Complete the installation by restarting the Workplace. You can now use components in the Eliona palette.
#### Configuration
* Open the **Niagara Workbench** and select the **Eliona Palette** out.
* Create an **Eliona Network** with an **Eliona Device**by dragging them from the palette and dropping them under **Configuration > Drivers** in the station.
* Open the **Eliona Device** and configure the Eliona API with URL and token. Specify the Eliona project ID you want to connect to.
* After configuration, the device status should be `OK` If so, save the station.
#### Display status information in Eliona
* After configuration, the module creates a **Niagara Station Asset**that automatically retrieves technical information every 5 minutes by default.
* This asset also monitors the station status as a live signal: `Active`when the station is operating normally, and `Inactive`when no activity is detected for 10 minutes. This status can be alerted through **Validity Monitoring** .
#### Send data to Eliona
* Select the Niagara datapoint you want to synchronize with Eliona and add an **Eliona Extension** (e.g. `ElionaCovExtension`) by dragging it from the **Eliona Palette** and dropping it. Open the extension and enable it.
* Once the extension is enabled, it automatically creates an asset in Niagara and in Eliona. Open the **Asset Mapping** in the extension and click the **asset**-link. This navigates to the asset created in Niagara.
* In the Niagara asset, you will find all information about the asset and the **Asset ID** of the created Eliona asset. You can use the **Asset Hyperlink** to open the asset in Eliona.
* When you open the Eliona asset, the current value of the datapoint is assigned to the **Value**attribute in Eliona. From that point on, every change to the datapoint is sent to this attribute. You can monitor this by checking the **Last Synchronized**timestamp in the Niagara asset view.
#### Receive data from Eliona
* After creating and mapping the assets in Niagara and Eliona, you can send values from Eliona to the Niagara datapoint. To do this, add a new value to the **Setpoint**attribute.
* By default, the value is sent to the **Set**action to the `fallback`slot in Niagara.
#### Send alarms to Eliona
* To synchronize alarms, first route the desired alarm classes. To do this, add the **Eliona Recipient** to the **Alarm Service** by dragging it from the **Eliona Palette** and dropping it.
* Now link the alarm class to the **Route Alarm**slot.
* Once the link is established, all alarms for the specified alarm class are sent to Eliona. You can test this by dragging a **Niagara Alarm Extension** (e.g. `OutOfRangeAlarmExtension`) from the alarm palette and placing it under the Niagara datapoint you want to monitor.
* Configure the extension, and when the first alarm is triggered, the **Eliona Recipient** a **Asset Mapping** similar to the one mentioned above under the alarm extension. If the asset does not exist, it is automatically created in both Niagara and Eliona.
* The alarm can now also be found in Eliona. The alarm can be acknowledged either in Eliona or Niagara, and the status is synchronized between them.
#### Asset Overview
* All assets assigned to Eliona can be found in the **Assets**component of the **Eliona Device**.
* Here you can monitor all asset information, remap assets, and if necessary resynchronize all assets or individual assets with Eliona.
#### Customizing n:1 mapping
You can set up more complex relationships between Niagara datapoints and Eliona assets. A common scenario is mapping multiple datapoints to a single asset with different attributes in Eliona.
* Select or add another Niagara datapoint that you want to synchronize with Eliona. Then attach an **Eliona extension** (e.g. `ElionaCovExtension`by drag and drop from the **Eliona palette** .
* Open the extension and navigate to **Asset Mapping**. Here you can overwrite the default **Global Asset ID** with an already existing ID. This lets you direct different asset mappings in Niagara to the same asset in Eliona, for example by using the existing `/Eliona/NumericWriteable` as a shared **Global Asset ID** .
* Configure different attribute names for sending and receiving data between Niagara and Eliona. In this case, the default name `Value` in `Another Value` is changed.
* When you enable the extension, the mapping automatically detects the existing asset in Niagara and links to it. If **Enable Upserts** in **Eliona Assets** is enabled, all new attributes (e.g. `Another Value`) are automatically created in the corresponding asset type in Eliona.
* When you open the Eliona asset, the current values of the two datapoints are assigned to their respective attributes in Eliona. From this point on, all changes to the datapoints are sent to and received from these attributes.
#### Customizing 1:n mapping
In this scenario, a single Niagara datapoint is mapped to multiple Eliona assets, optionally with different attributes.
* For an existing Niagara datapoint, add another **Extension Asset Mapping** to the current **Eliona extension** (e.g. `ElionaCovExtension`) by dragging and dropping it from the **Eliona palette** .
* In the new asset mapping, overwrite the default **Global Asset ID**. For example, set it to `/Eliona/NumericWriteableCopy` instead of `/Eliona/NumericWriteable`. Once you save the asset mapping, the new asset is automatically created in Niagara and in Eliona (if **Enable Upserts** is enabled). From that point on, all changes to the datapoint are both sent to and received from both assets in Eliona.
* To receive data from Eliona, you may want to use a different write slot. For example, you could use the default slot `Set` (Fallback) and additionally set the slot `Override` . You achieve this by combining the write slot with the asset attribute in the **Asset Mapping** .
* Now you can set an override value in Eliona that updates the corresponding datapoint in Niagara.
***
### Component Overview
#### Eliona Network
The **Eliona Network** is the root component that groups all **Eliona Devices** within a Niagara station.
#### Eliona Device
Each **Eliona Device** connects an Eliona instance and a specific project within that instance. This device shares its Eliona connection with all child components, such as the **Eliona Sender**, **Eliona Receiver**, **Eliona Assets**container and **Eliona Alarm Acknowledger**. The **Eliona Device** is also referenced by the **Eliona Recipient** .
#### Eliona Sender
The **Eliona Sender** is responsible for transmitting values from Niagara datapoints to Eliona. It is a child of the **Eliona Device** and uses the associated Eliona instance and project. The sender can be configured with a value buffer to handle scenarios where the connection to Eliona is temporarily unavailable.
#### Eliona Receiver
The **Eliona Receiver** receives data from Eliona and writes it to Niagara datapoints. It is a child of the **Eliona Device** and uses the same Eliona instance and project. The receiver allows configuration of the datapoint's write slot and specifies the Niagara username for the operation.
#### Eliona Assets
The **Eliona Assets**container groups and synchronizes assets with Eliona. It is a child of the **Eliona Device** and uses the connected Eliona instance and project. This container can automatically create or update assets in Eliona during synchronization. It also organizes all asset components that correspond to real assets in Eliona.
#### Eliona Asset
One **Eliona Asset**component represents a single asset in Eliona. This component is a child of the **Eliona Assets**container and contains a unique Global Asset ID. During synchronization, this Global Asset ID and the Eliona project (from the parent **Eliona Device**) determine the Asset ID in Eliona, which is then stored in the asset component. Attributes such as asset type, name, and description are also synchronized. If automatic creation or updating is enabled in the **Eliona Assets**container, assets are created or updated in Eliona; otherwise, the component references an existing asset by its ID.
#### Eliona Extension
The **Eliona Extension** monitors changes to Niagara datapoint values and triggers data transmission to Eliona via the **Eliona Sender** . This extension is attached to a Niagara datapoint and references an **Eliona Device** and uses the connected Eliona instance and project.
#### Eliona Asset Mapping
The **Eliona Asset Mapping** establishes a connection between Niagara datapoints and attributes of an asset in Eliona. It is a child of either an **Eliona Extension** or an **Alarm Extension** in Niagara, which themselves are attached to Niagara datapoints. The mapping defines a Global Asset ID that allows the corresponding **Eliona Asset**component in Niagara to be referenced and created. This component in turn links to the real asset in Eliona by storing the Asset ID after synchronization.
#### Eliona Alarm Acknowledger
The **Eliona Alarm Acknowledger** receives alarm acknowledgements from Eliona and acknowledges the corresponding alarms in Niagara. It is a child of the **Eliona Device** and uses the connected Eliona instance and project. The acknowledger allows configuration of the Niagara username for the acknowledgement operation.
#### Eliona Recipient
The **Eliona Recipient** forwards alarms from alarm classes in Niagara to Eliona. It references an **Eliona Device** and uses the connected Eliona instance and project. The recipient can be configured with an alarm buffer to handle scenarios where the connection to Eliona is temporarily unavailable.
#### Eliona API Client
The **Eliona API Client** enables direct communication with Eliona via APIv2 (see [api.eliona.io](https://api.eliona.io)).\
It is typically used to perform a wide range of operations such as reading, creating, updating, and deleting assets, alarms, and configurations in Eliona.\
The client manages authentication and connection settings and serves as a central interface for all API-driven interactions, ensuring reliable and secure integration between Niagara and Eliona.
***
### Component Configuration
#### Eliona Network
You can add the **Eliona Network** as a child of the **Drivers**container in a Niagara station. This can be done by dragging it from the **Eliona Palette** or by opening the **Driver Manager** and clicking the **New**button. Note that only one **Eliona Network** is allowed per station.
#### Eliona Device
The **Eliona Device** can be added as a child of the **Eliona Network** . You can add it by dragging it from the **Eliona Palette** . Multiple **Eliona Devices** can be created to represent different Eliona instances or projects.
| Setting | Description |
| -------------------- | ------------------------------------------------------------- |
| `Enabled` | Enables or disables the Eliona Device |
| `APIv2 URL` | URL for connecting to the Eliona APIv2 instance |
| `APIv2 Token` | Authorization token for accessing the Eliona APIv2 |
| `Project ID` | Project ID used for asset mapping and creation |
| `Connection Timeout` | Maximum time in seconds before a connection attempt times out |
**Enabled**
> Enables or disables the Eliona Device. When enabled, all related components (e.g. sender, receiver) are operational.
**APIv2 URL**
> Specifies the URL of the Eliona APIv2 instance to connect to (e.g. `https://my.eliona.io/api/v2`). This should be provided by your Eliona administrator.
**APIv2 Token**
> The authorization token required to access the Eliona APIv2. Make sure this token has both read and write permissions as needed. This should be provided by your Eliona administrator.
**Project ID**
> Defines the Eliona project ID used for referencing assets. This ID must match the project configuration in Eliona.
**Connection Timeout**
> Sets the maximum duration in seconds for a connection attempt to Eliona. If network latency is high, consider increasing this timeout. A typical value is around 5 seconds.
#### Eliona Sender
The **Eliona Sender** is automatically created as a child of the **Eliona Device** created.
| Field | Description |
| ----------------------------------- | ----------------------------------------------------- |
| `Enabled` | Enables or disables data transmission |
| `Value Buffer Size` | Sets the maximum size of the message buffer |
| `Circular Buffer` | Determines the buffer behavior when it is full |
| `Buffer Database Connection` | Configures external database connection for buffering |
| Bu`lk Sending Interval` | Interval for grouping values for bulk sending |
| Bu`lk Sending Limit` | Upper limit for grouping values for bulk sending |
| `Last Send` (Info) | Timestamp of the last successful data transmission |
| `Send Variables Count` (Info) | Number of datapoints currently being sent to Eliona |
| `Forecast Messages Per Hour` (Info) | Estimated number of messages sent per hour |
| `Forecast Bytes Per Message` (Info) | Average size of each message in bytes |
| `Value Buffer Used` (Info) | Current number of messages in the buffer |
| `Last Send Count` | Number of values sent in the last bulk operation |
| `Current Send Thread Count` | Current number of concurrent threads sending values |
| `Update Forecast` (Action) | Manually updates the forecast statistics |
| `Clear Value Buffer` (Action) | Clears all messages in the buffer |
**Enabled**
> Enables or disables the Eliona Sender. When enabled, data is transmitted to Eliona; when disabled, transmission stops.
**Value Buffer Size**
> Specifies the maximum number of messages the buffer can hold. Use **Forecast Messages Per Hour** and **Forecast Bytes Per Message**to estimate the ideal buffer size based on expected data volume.
**Circular Buffer**
> Determines how the buffer handles new messages when it has reached capacity:
>
> * **Enabled**: Overwrites the oldest messages with new ones when the buffer is full.
> * **Disabled**: Stops accepting new messages once the buffer is full.
**Buffer Database Connection**
> Allows the use of an external H2 database for buffering. If left empty, an internal memory buffer is used by default.
>
> * **Embedded Buffer Mode**: Uses a driver-managed database file (e.g. `jdbc:h2:C:/Users/username/Niagara4.9/stations/eliona/shared/values`). In Niagara, only the local shared directory is writable.
> * **Server Buffer Mode**: Connects to a server-managed H2 database (e.g. `jdbc:h2:tcp://localhost/C:/temp/values;user=sa;password=secret`).
#### Bulk Sending Interval
> Defines the time interval (in seconds) in which values are grouped before being sent in a bulk operation. The module collects values based on this interval and the set upper limit before sending them to Eliona in parallel threads.\
> If this value is set to `null` no bulk operation is used.
#### Bulk Sending Limit
> Defines the maximum number of values that can be grouped and sent in a single bulk operation. As soon as either the **Bulk Send Interval** is reached or this limit is exceeded, the collected values are sent. Correctly setting this limit in combination with the interval helps ensure efficient data transmission with minimal thread usage.
> **Note:** To optimize performance and avoid excessive parallel threads, the value for `Forecast Messages Per Hour` should be taken into account.\
> The limit can be calculated using the following formula:\
> `Forecast Messages Per Hour × 2 / 3600 / Interval` (where `×2` serves as a safety factor).\
> By appropriately adjusting this limit, more than one thread being used for sending can be prevented.
**Last Send** (Info)
> Displays the timestamp of the last successful data transmission, useful for monitoring activity.
**Send Variables Count** (Info)
> Displays the current number of unique datapoints being transmitted to Eliona.
**Forecast Messages Per Hour** (Info)
> Estimates the number of messages sent per hour based on current activity. This value is updated every 10 seconds.
**Forecast Bytes Per Message** (Info)
> Shows the average size of each message in bytes, updated every 10 seconds.
**Value Buffer Used** (Info)
> Indicates the current number of messages stored in the buffer.
#### Last Send Count (Info)
> Shows the number of values sent in the last bulk operation. This helps monitor the effectiveness of the current bulk sending configuration.
#### Current Send Thread Count (Info)
> Shows the number of parallel threads currently used for sending values. Ideally, this value should not exceed one thread at a time to ensure optimal resource usage and system stability.
**Update Forecast** (Action)
> Manually updates the forecast statistics. These statistics are updated automatically every 10 seconds.
**Clear Value Buffer** (Action)
> Clears all messages currently stored in the buffer.
#### Eliona Receiver
The **Eliona Receiver** is automatically created as a child of the **Eliona Device** created.
| Field | Description |
| ------------------------------ | -------------------------------------------------------------- |
| `Enabled` | Enables or disables the receiver |
| `Username` | Niagara user account used for writing data |
| `Default Write Slot` | Target slot for writing when no priority is specified |
| `Delay Reset to Null` | Resets the value to zero after the specified number of seconds |
| `Last Received` (Info) | Timestamp of the last received message |
| `Last Message Received` (Info) | Details of the last received message |
**Enabled**
> Enables or disables the Eliona Receiver. When enabled, data received from Eliona is written to the specified Niagara datapoints.
**Username**
> Specifies the Niagara user account used to write values to datapoints. If not specified in the incoming message, this default user is used. The user must have permissions to execute actions or write to slots. Make sure the username is valid and has the required permissions.
**Default Write Slot**
> Defines the slot in the target datapoint to which the received value is written when no priority is specified. This can also be an action slot that triggers the action with the value as an argument.
**Delay Reset to Null**
> Sets the number of seconds after which the written value is reset to `null` . If a value greater than zero is set, the value is reset after the specified delay. This delay is used as the default if no delay is defined in the asset mapping.
**Last Received** (Info)
> Displays the timestamp of the last successful data received from Eliona.
**Last Message Received** (Info)
> Displays the last message received from Eliona. This is mainly for debugging purposes and is hidden by default.
#### Eliona Assets
The **Eliona Assets**container is automatically created as a child of the **Eliona Device** created. It contains all **Eliona Asset**components.
| Field | Description |
| ---------------------------- | ----------------------------------------------------------- |
| `Upsert Enabled` | Enables automatic creation and updating of assets in Eliona |
| `Auto Save` | Automatically saves the station after assets are changed |
| `Default Global Asset ID` | Sets a default pattern for the Global Asset ID |
| `Default Asset Name` | Sets a default pattern for asset names |
| `Default Asset Description` | Sets a default pattern for asset descriptions |
| `Default Send Attribute` | Sets the default attribute for sending data to Eliona |
| `Default Status Attribute` | Sets the default status attribute for assets |
| `Default Receive Attribute` | Sets the default attribute for receiving data from Eliona |
| `Default Alarm Attribute` | Sets the default attribute for alarms |
| `Synchronize` (Action) | Starts synchronization of assets with Eliona if needed |
| `Force Synchronize` (Action) | Forces synchronization of all assets with Eliona |
**Upsert Enabled**
> Enables or disables the upsert functionality (update or insert) for assets in Eliona.
>
> * **Enabled**: Assets are automatically updated during synchronization if they exist, or inserted if they are new.
> * **Disabled**: Assets are only referenced if they exist in Eliona; they are not created or updated.
**Auto Save**
> Automatically saves the station when assets are created or changed in the **Eliona Assets**container.
**Default Global Asset ID**
> Defines the pattern for the default Global Asset ID used to uniquely reference assets in Eliona. Typically reflects the asset's parent slot path.
**Default Asset Name**
> Specifies the pattern for the default asset name in Eliona, often using the parent element's name.
**Default Asset Description**
> Sets the pattern for the default asset description, possibly including the type and display name of the parent component.
**Default Send Attribute**
> Sets the default attribute used for sending data to Eliona. Default is `"value"`.
**Default Status Attribute**
> Defines the default attribute for reporting asset status. Default is `"value_status"`.
**Default Receive Attribute**
> Sets the default attribute for receiving data from Eliona. Default is `"value"`.
**Default Alarm Attribute**
> Specifies the default attribute for alarm data. Default is `"alarm"`.
**Synchronize** (Action)
> Triggers synchronization of all assets with Eliona. If **Upsert** is enabled, assets are automatically created or updated. Otherwise, assets are only referenced if they already exist in Eliona based on their **Project ID** and **Global Asset ID** Existing assets (where a **Asset ID** is set) are skipped.
#### **Force Synchronize** (Action)
> Forces synchronization of all assets without checking synchronization status (regardless of whether a **Asset ID** is set or not). Each asset is sent to Eliona, so updates are applied even if the assets have already been synchronized.
#### Eliona Asset
One **Eliona Asset**component is automatically created when an **Eliona Asset Mapping**component is set up. The **Global Asset ID** serves as a unique identifier.
| Field | Description |
| ---------------------------- | ------------------------------------------------------------ |
| `Asset Type` | Defines the type of the asset in Eliona |
| `Global Asset ID` (Info) | Unique global identifier for referencing and synchronization |
| `Asset Name` (Info) | Name of the asset in Eliona |
| `Asset Description` (Info) | Description of the asset in Eliona |
| `Asset ID` (Info) | Referenced Asset ID in Eliona |
| `Alarm Rule ID` (Info) | Identifier for the associated alarm rule in Eliona |
| `Last Alarmed` (Info) | Timestamp of the last triggered alarm |
| `Asset Hyperlink Ord` (Info) | Link to the asset in the Eliona frontend for easy navigation |
| `Last Sync` (Info) | Timestamp of the last synchronization with Eliona |
| `Synchronize` (Action) | Starts synchronization with Eliona if needed |
| `Force Synchronize` (Action) | Forces synchronization with Eliona |
**Asset Type**
> Defines the asset type in Eliona during synchronization.
**Global Asset ID** (Info)
> Unique identifier that combines the Global Asset ID and the Project ID from the **Eliona Device** Used for synchronization.
**Asset Name** (Info)
> Name of the asset in Eliona. This is synchronized during updates.
**Asset Description** (Info)
> Description of the asset in Eliona, synchronized during updates.
**Asset ID** (Info)
> Reference to the Asset ID in Eliona, based on the Project ID and the Global Asset ID.
**Alarm Rule ID** (Info)
> Identifier for the associated alarm rule in Eliona.
**Last Alarmed** (Info)
> Timestamp of the last triggered alarm for the asset.
**Asset Hyperlink Ord** (Info)
> Provides a direct link to the asset in the Eliona frontend.
**Last Sync** (Info)
> Indicates when the asset was last synchronized with Eliona.
**Synchronize** (Action)
> Manually triggers synchronization of the asset data with Eliona. If the asset has already been synchronized (a **Asset ID** is set), the action is skipped. Otherwise, the asset is **Project ID** and **Global Asset ID** updated or referenced based on its
#### **Force Synchronize** (Action)
> Bypasses synchronization checks and forces sending the asset data to Eliona, regardless of whether the asset has already been synchronized (a **Asset ID** is set). This ensures the asset is always updated and is especially useful when a full refresh is required.
#### Eliona Asset Mapping
One **Eliona Asset Mapping**component is created as a child of Niagara datapoint extensions (either **Eliona Extension** or **Alarm Extension**). It is linked with a **Eliona Asset** using the Global Asset ID.
| Field | Description |
| -------------------- | ----------------------------------------- |
| `Global Asset ID` | Unique identifier for the asset in Eliona |
| `Asset Ord` (Info) | Reference to the asset in Niagara |
| `Map Asset` (Action) | Starts the asset mapping |
**Global Asset ID**
> Unique identifier that ensures consistent identification in Niagara and Eliona.
**Asset Ord** (Info)
> Reference to the asset within Niagara.
**Map Asset** (Action)
> Starts the mapping process for the asset.
**Eliona Value Asset Mapping**
The **Eliona Value Asset Mapping**component is automatically created as a child of the **Eliona Extension** created.
| Field | Description |
| --------------------- | -------------------------------------------------------------- |
| `Send Subtype` | Subtype for sending values (e.g. `"input"`) |
| `Send Attribute` | Attribute used when sending data to Eliona |
| `Status Attribute` | Attribute representing the status of the asset |
| `Receive Attribute` | Attribute for receiving data from Eliona |
| `Write Slot` | Slot into which received data is written |
| `Delay Reset to Null` | Resets the value to zero after the specified number of seconds |
**Send Subtype**
> Specifies the subtype for value data when sending to Eliona. Default is `"input"`.
**Send Attribute**
> Attribute used to send data to Eliona. To exclude it from sending, set the attribute name to empty.
**Status Attribute**
> Attribute representing the status of the asset in Eliona. To exclude it from sending, set the attribute name to empty.
**Receive Attribute**
> Attribute for receiving data from Eliona. To exclude it from receiving, set the attribute name to empty.
**Write Slot**
> Defines the slot in Niagara into which data from Eliona is written.
#### **Delay Reset to Null**
> Sets the number of seconds after which the written value is reset to `null` is reset. If a value greater than zero is set, the value is reset after the specified delay.
**Eliona Alarm Asset Mapping**
The **Eliona Alarm Asset Mapping**-component is created as a child of the **Alarm Extension** created when the first alarm for the parent datapoint is triggered.
| Field | Description |
| ---------------------- | ------------------------------------------- |
| `Alarm Subtype` | Subtype for alarm data (e.g. `"input"`) |
| `Alarm Attribute` | Attribute used when transferring alarm data |
| `Recipient Ord` (Info) | Reference to the alarm recipient in Niagara |
**Alarm Subtype**
> Subtype for alarm data. Default is `"input"`.
**Alarm Attribute**
> Attribute used to transfer alarm data to Eliona. To exclude it from sending, set the attribute name to empty.
**Recipient Ord** (Info)
> Reference to the alarm recipient in Niagara.
**Eliona Station Asset Mapping**
The component **Eliona Station Asset Mapping** is created as a child of the **Eliona Device** when this is created.
| **Field** | **Description** |
| ---------------- | ----------------------------------------------------- |
| **`Attributes`** | Attribute names used when sending the station status. |
**Attributes**
> Define the attribute names to be used when sending the status to Eliona. To exclude specific information from being sent, set the attribute name to empty.
#### Eliona Alarm Acknowledger
The **Eliona Alarm Acknowledger** is automatically created as a child of the **Eliona Device** created.
| Field | Description |
| --------------------------------------- | ------------------------------------------------------------ |
| `Enabled` | Enables or disables the Acknowledger |
| `Ack Alarm From Same Source` | Acknowledges all alarms from the same source |
| `Username` | Niagara user account for acknowledgements |
| `Last Alarm Acked` (Info) | Details of the last acknowledged alarm |
| `Last Alarm Acked Time` (Info) | Timestamp of the last successful acknowledgement |
| `Last Alarm Acked Failure Time` (Info) | Timestamp of the last failed acknowledgement attempt |
| `Last Alarm Acked Failure Cause` (Info) | Error message for the last failed acknowledgement attempt |
| `Total Alarms Acked Today` (Info) | Number of alarms acknowledged today |
| `Total Alarms Acked Failures` (Info) | Number of failed acknowledgements today |
| `Total Messages Received Today` (Info) | Number of acknowledgment messages received from Eliona today |
| `Last Alarm Ack Note` (Info) | Note associated with the last acknowledgement |
**Enabled**
> Enables or disables the alarm Acknowledger.
**Ack Alarm From Same Source**
> If enabled, all alarms originating from the same source are acknowledged.
**Username**
> Specifies the Niagara user account used for acknowledging alarms. The user must have the required permissions.
**Last Alarm Acked** (Info)
> Details of the last successfully acknowledged alarm.
**Last Alarm Acked Time** (Info)
> Timestamp of the last successful acknowledgement.
**Last Alarm Acked Failure Time** (Info)
> Timestamp of the last failed acknowledgement attempt.
**Last Alarm Acked Failure Cause** (Info)
> Error message explaining the cause of the last failed acknowledgement attempt.
**Total Alarms Acked Today** (Info)
> Number of alarms acknowledged today.
**Total Alarms Acked Failures** (Info)
> Number of failed acknowledgement attempts today.
**Total Messages Received Today** (Info)
> Number of acknowledgment messages received from Eliona today.
**Last Alarm Ack Note** (Info)
> A note associated with the last alarm acknowledgement.
#### Eliona Extension
The **Eliona Extension** can be added as a child of a Niagara datapoint by dragging it from the **Eliona Palette** . Multiple extensions can be created for a single datapoint.
| Field | Description |
| ------------------ | -------------------------------------------------- |
| `Enabled` | Enables the extension for data transmission |
| `Last Send` (Info) | Timestamp of the last successful data transmission |
The extension transmits and receives the value of a configurable slot (default: `out` and `set`) and, if available, its status.
**Enabled**
> Enables or disables the extension.
**Last Send** (Info)
> Shows the timestamp of the last successful data transmission.
**Eliona Interval Extension**
| Field | Description |
| ---------- | --------------------------------------------------- |
| `Interval` | Interval for data transmission (Interval Extension) |
**Interval**
> Defines the interval at which the value of the parent variable is sent to Eliona.
**Eliona COV Extension**
| Field | Description |
| ------------------ | ----------------------------------------------------------------- |
| `Change Tolerance` | Minimum change required to trigger a transmission (COV Extension) |
**Change Tolerance**
> Specifies the minimum required change in the value of the parent variable to trigger a data transmission. If set to `0` every change triggers a transmission.
#### Eliona Recipient
The **Eliona Recipient** can be added as a child of the Niagara **Alarm Service** by dragging it from the **Alarm Class** to route alarms for this class.
| Field | Description |
| --------------------------------- | ------------------------------------------------------ |
| `Time Range` | Time range in which alarms are forwarded |
| `Days Of Week` | Days of the week on which alarms are forwarded |
| `Transition` | Alarm transitions that are forwarded |
| `Route Acks` | Specifies whether alarm acknowledgements are forwarded |
| `Alarm Buffer Size` | Sets the size of the message buffer |
| `Circular Buffer` | Determines the buffer behavior when full |
| `Buffer Database Connection` | Configures external database connection for buffering |
| `Forecast Alarms Per Hour` (Info) | Estimated number of alarms sent per hour |
| `Forecast Bytes Per Alarm` (Info) | Average size of each alarm message in bytes |
| `Alarm Buffer Used` (Info) | Current number of alarms in the buffer |
| `Last Send` (Info) | Timestamp of the last successful data transmission |
| `Update Forecast` (Action) | Manually updates the forecast statistics |
| `Clear Alarm Buffer` (Action) | Deletes all alarms in the buffer |
**Time Range**
> Defines the period during which alarms are forwarded to Eliona.
**Days Of Week**
> Specifies the days on which alarms are forwarded.
**Transition**
> Determines which alarm transitions (e.g. activation, acknowledgement) are forwarded to Eliona.
**Route Acks**
> Specifies whether alarm acknowledgements in Niagara are forwarded to Eliona.
**Alarm Buffer Size**
> Specifies the maximum number of alarms the buffer can hold.
**Circular Buffer**
> Determines how the buffer handles new alarms when it is full:
>
> * **Enabled**: Overwrites the oldest alarms with new ones.
> * **Disabled**: Stops accepting new alarms when full.
**Buffer Database Connection**
> Allows the use of an external H2 database for buffering. If left empty, an internal memory buffer is used by default.
>
> * **Embedded Buffer Mode**: Uses a database file managed by the driver.
> * **Server Buffer Mode**: Connects to a server-managed H2 database.
**Forecast Alarms Per Hour** (Info)
> Estimates the number of alarms sent per hour, updated every 10 seconds.
**Forecast Bytes Per Alarm** (Info)
> Displays the average size of each alarm message in bytes.
**Alarm Buffer Used** (Info)
> Displays the current number of alarms stored in the buffer.
**Last Send** (Info)
> Timestamp of the last successful data transmission.
**Update Forecast** (Action)
> Manually updates the forecast statistics.
**Clear Alarm Buffer** (Action)
> Deletes all alarms currently stored in the buffer.
#### Eliona API Client
The **Eliona API Client** can be added by dragging it from the **Eliona Palette** . It enables direct communication with an Eliona system via APIv2 by sending custom HTTP requests to specific endpoints.
| Field | Description |
| ---------------------- | -------------------------------------------------------------------------------- |
| `Enabled` | Enables or disables the client |
| `Request On Change` | Automatically triggers the `Request`-action when a property changes |
| `Method` | HTTP method used for the API call (`GET`, `PUT`, `POST`, `DELETE`, `PATCH`) |
| `In` | JSON body inserted into the request if needed |
| `Path` | Path of the API endpoint |
| `Url` (Info) | Resulting URL based on the configuration of the **Eliona Device** and the `Path` |
| `Response Code` (Info) | HTTP response code after executing a `Request` |
| `Last Request` (Info) | Timestamp of the last request sent |
| `Last Response` (Info) | Timestamp of the last response received |
| `Request` (Action) | Manually starts a new request to Eliona |
***
**Enabled**
> Enables or disables the Eliona API Client. When disabled, no requests are sent or received.
**Request When Changed**
> Automatically triggers the `Request`-action as soon as a relevant property (e.g. `Method`, `In` or `Path`) changes.
**Method**
> Defines the HTTP method used for the API call. Available options are: `GET`, `PUT`, `POST`, `DELETE`, `PATCH`.
**In**
> Specifies the JSON body to be inserted into the request. This is used when the HTTP method requires a payload to be sent (e.g. with `POST`, `PUT` or `PATCH`).
**Path**
> Defines the path of the API endpoint relative to Eliona's base URL, which is configured in the associated **Eliona Device** is configured.
**Url** (Info)
> Displays the full URL resulting from the configuration of the **Eliona Device** and the specified `Path` .
**Response Code** (Info)
> Displays the HTTP response code of the last request (e.g. `200 OK`, `404 Not Found`, `500 Internal Server Error`).
**Last Request** (Info)
> Stores the timestamp of the last request sent to Eliona.
**Last Response** (Info)
> Stores the timestamp of the last response received from Eliona.
**Request** (Action)
> Manually starts a request based on the current configuration of the Eliona API Client.
***
### Migration Guide
Starting with version 5.0, the Niagara module has undergone major changes in its operating principles. Communication with Eliona now uses the Eliona APIv2 directly. Previously, communication was established via a TCP tunnel to a separate Niagara app within Eliona, which managed asset mapping and asset changes. Configuration in earlier versions involved defining listeners (for the TCP tunnel) and controllers (for asset mapping and the attribute settings for values and alarms).
#### Communication Settings
In the new version, instead of an IP address and port for creating a TCP tunnel to the Niagara app connector, you need an APIv2 URL and a token. These credentials should be provided by your Eliona administrator. The APIv2 credentials must be configured in the **Eliona Device**-component within Niagara.
#### Asset Mapping
In earlier versions, asset mapping was defined within the Niagara app in Eliona. The controller in the Niagara app settings contained a list of assets linked to Niagara datapoints via their handles (unique IDs of datapoints within a Niagara station). For each handle (datapoint), the asset ID and the attribute with subtype were specified. In addition, the priority (name of the slot in Niagara) was defined for output attributes that send data back to Niagara.
The new version introduces a different approach to referencing assets and attributes. The **Eliona Value Asset Mapping**, defined within a **Eliona Extension**, specifies a Global Asset ID. This Global Asset ID, combined with the Project ID from the **Eliona Device**, uniquely identifies an asset in Eliona. For each Global Asset ID, a **Eliona Asset** is created under the **Eliona Assets**-container in Niagara. During asset synchronization, this Eliona asset is linked to its corresponding asset in Eliona by setting the asset ID in the **Eliona Asset**-component.
The new **Asset Mapping** also defines the `Attributes`-settings and subtypes used when sending values to or receiving them from Eliona. If you need to define a different write slot than the `Default Write Slot` defined in the **Eliona Receiver** you can use the `Write Slot`-setting in the **Asset Mapping**-component.
You can assign multiple asset mappings with different attribute names to the same Global Asset ID. This allows you to define a single asset in Eliona that represents multiple datapoints from Niagara, each mapped to different attributes.
#### Alarm Mapping
In earlier versions, alarm mapping was defined within the Niagara app in Eliona. The controller in the Niagara app settings contained a list of alarm rules and the full slot BOrd of the corresponding alarm extensions. This setup allowed the old version to send alarms and synchronize acknowledgements.
The new version takes a different approach. The **Eliona Alarm Asset Mapping**, defined for each **Alarm Extension**, specifies a Global Asset ID. This Global Asset ID, together with the Project ID from the **Eliona Device**, uniquely identifies the asset in Eliona. An alarm rule is then created for this asset in Eliona. The asset mapping also defines an attribute name representing the alarm state: it is set to `0` when no alarm is present, and to `1`when the parent Niagara datapoint is in an alarm state.
#### Asset Import and Creation
In earlier versions, a **Eliona Service**-component was provided. This component could export asset definitions from Niagara for each datapoint and import them into a controller in the Eliona app, thereby creating the assets and asset mappings for the selected controller.
The new version provides a more convenient and flexible way to automatically create assets and mappings. By enabling the setting `Enable Upserts` in the **Eliona Assets**-container, the Eliona module checks during synchronization whether an asset with the specified Global Asset ID and Project ID exists in Eliona. If it does not exist, the asset is created and linked by setting the new asset ID in the **Eliona Asset**-component. Note that you must define the asset type in the **Eliona Asset**-component in order to create and update the asset in Eliona.
