# OpenBOS > The OpenBOS App enables the integration and synchronization between BuildingPro Suites and [ABB Ability™ Building Edge](https://new.abb.com/low-voltage/products/building-automation/building-edge) (using the OpenBOS software). #### Overview This manual provides instructions for configuring, installing, and using the OpenBOS App to manage resources and synchronize data between BuildingPro Suites and OpenBOS Edge. #### Required Steps in OpenBOS Building Edge The complete documentation for using the Edge Editor, a tool integrated into the Building Edge for configuration, is available [here](https://library.abb.com/d/9AKK108467A9325). Below, it will be referred to as the **Edge Editor Doc**, and the content corresponds to Revision G of the English version. #### Topology and Services Building data is captured by the Building Edge, assigned to assets, and sent to the ABB Ability Cloud. From there, the assets are retrieved via the BuildingPro Suites app and automatically created. ![Building Edge Schema Example](https://raw.githubusercontent.com/eliona-smart-building-assistant/open-bos-app/refs/heads/develop/user_guide/building_edge_schema.png) #### Initial Installation The following configurations must be made during the initial installation: **Local Configuration** As soon as the Building Edge is switched on, it can be accessed via a browser via LAN port 1 or 2. Follow the further steps according to the **Edge Editor Doc** (pages 23–32). **Cloud Configuration** For the Edge to be connected to the cloud, it must be in a network with internet access. Adjust the IP address accordingly (see **Edge Editor Doc**, page 43). To access the ABB Cloud, a personalized login must be created. Then follow the steps in the **Edge Editor Doc** (pages 33–40). **General Setup** Next, check the general settings and adjust or complete them if necessary according to the **Edge Editor Doc**, pages 42–81. #### Integration of Field Data To retrieve data points from a bus system, a new network for the corresponding protocol must be created under "Field Network." The **Ability Cloud** is accessible at: Follow the steps according to the **Edge Editor Doc** (pages 112–123). #### Adding Devices and Data Points To add devices and data points, the **CSV import** can be used. It is recommended to first export an (empty) CSV file and fill it with data. #### Allow Access via API For BuildingPro Suites to receive updates of data points, each data point must be configured for API subscriptions: 1. In the **Library/Asset Template**: 2. Select your asset. 3. Click on the **Edit pencil icon**. 4. Go to **API Subscription**. 5. Activate the desired subscription. 6. Don't forget to click on **Save** (top right in the bar next to "API Subscription"). ![Activate API Subscription](https://raw.githubusercontent.com/eliona-smart-building-assistant/open-bos-app/refs/heads/develop/user_guide/api_subscription.png) #### Registering the App in OpenBOS To connect BuildingPro Suites with your OpenBOS Edge, the Edge must be configured to allow API connections. Contact ABB support for more information. You must provide the public API URL of BuildingPro Suites: `https://{your-eliona-domain.io}/apps-public/open-bos`. BuildingPro Suites requires the **Gateway ID, Client ID, and Client Secret** for authentication. #### Installation Install the OpenBOS App via the BuildingPro Suites App Store. #### Configuration The OpenBOS App requires a configuration via the BuildingPro Suites settings interface. The following steps are required to configure the app. #### Configuring the OpenBOS App Configurations can be created in BuildingPro Suites under `Settings > Apps > OpenBOS`, which opens the app's [Generic Frontend](https://doc.eliona.io/collection/v/eliona-english/manuals/settings/apps). Here you can use the `\configs` endpoint with the POST method. Each configuration requires the following data: | Attribute | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gwid` | The ID of the gateway device used in the API requests. | | `clientID` | The client ID for OAuth 2.0 authentication. | | `clientSecret` | The client secret for OAuth 2.0 authentication. | | `appPublicAPIURL` | URL of the public API of this app. Is automatically derived from the request. Example: "https\://{your-eliona-instance.io}/apps-public/open-bos". | | `enable` | Flag to activate or deactivate the retrieval from this API. Default: `true`. | | `refreshInterval` | Interval in seconds for retrieving data from the API. Default: `24`. | | `requestTimeout` | Timeout for API queries in seconds. Default: `120`. | | `active` | Is set to `true` by the app when it is running and to `false` when it is stopped. Read-only. | | `tenantIDs` | List of BuildingPro Suites tenant IDs for data collection. For each tenant ID, all smart devices are automatically created as assets in BuildingPro Suites, with the mappings stored in the OpenBOS app. Example: `["42", "99"]`. | Example of a complete configuration file in JSON format: ```json { "gwid": "1234acbd-3faa-ab32-ab32-21c3876ba", "clientID": "4321dcba-3faa-ab32-ab32-21c3876ba", "clientSecret": "your-client-secret", "appPublicAPIURL": "https://{your-eliona-instance.io}/apps-public/open-bos", "enable": true, "refreshInterval": 24, "requestTimeout": 120, "tenantIDs": [ "42", "99" ] } ``` Some fields have default values, so a minimalist configuration file can look like this: ```json { "gwid": "1234acbd-3faa-ab32-ab32-21c3876ba", "clientID": "4321dcba-3faa-ab32-ab32-21c3876ba", "clientSecret": "your-client-secret", "tenantIDs": [ "42" ] } ``` ### Continuous Asset Creation After configuration, the app starts Continuous Asset Creation (CAC). Recognized resources are automatically created as assets in BuildingPro Suites, and the user who configured the app is informed via the BuildingPro Suites notification system. Structuring Assets After creation, the assets in BuildingPro Suites are organized in the same structure as in OpenBOS. This structure remains synchronized, and changes in BuildingPro Suites (e.g., renaming an asset or moving a room to another building) are overwritten with the next ontology update. The only exception are the root assets. These are created in the top-level directory and correspond to the top level of the OpenBOS location structure. As a rule, there is one "Site" in this role. Another root asset is the "OpenBOS unassigned", which contains unassigned assets and data points. You can rename or move the root assets as you wish, whereby the entire ontology is also moved. It is not possible to change GAIs in BuildingPro Suites for assets. #### Asset Filtering If not all assets from OpenBOS are to be imported into BuildingPro Suites, an asset filter can be defined to include only certain assets. The app can filter assets by ID, name, and templateID (for assets and rooms). The instructions for creating a filter can be found in the [Asset Filter documentation](https://doc.eliona.io/collection/dokumentation/einstellungen/apps/asset-filter). #### Asset Types Asset types are automatically created and synchronized from the OpenBOS asset templates. | BuildingPro Suites | OpenBOS | | ------------------ | ----------------------------------------------------------- | | Asset type | Asset template | | Attribute - Input | Data point with direction "Feedback" | | Attribute - Output | Data point with direction "Command" or "CommandAndFeedback" | | Attribute - Info | Property | | Limits | Min/Max | | Unit | Unit | | Value mapping | Enums | Complex data types from OpenBOS are split into separate attributes in BuildingPro Suites. #### Orphaned Data Points If an asset is deleted in OpenBOS but an alarm is still linked to this data point, this data point is retained in the ontology. BuildingPro Suites adopts this behavior and assigns such data points to the "OpenBOS unassigned" asset. ### Alarms Alarms triggered in OpenBOS are synchronized with BuildingPro Suites. They are created in BuildingPro Suites as alarm rules of the type "External" and are controlled by updates from OpenBOS. When an alarm is triggered in OpenBOS, it also appears in BuildingPro Suites and is removed accordingly when it ends in OpenBOS. > External Alarms are alarms that are not managed by BuildingPro Suites. Alarm rules are displayed so that users can tag and categorize them, but BuildingPro Suites is not responsible for checking whether an alarm should be triggered. An external system (in this case, OpenBOS) is responsible for alarm control. If an alarm requires an acknowledgment, it can be acknowledged in BuildingPro Suites, and this acknowledgment is synchronized with OpenBOS. ### Monitoring the App Status Along with asset creation, an asset named "OpenBOS app" is also created. It serves to inform users about the status of the app - it signals whether the app is running (asset status -> Active/Inactive) and what its status is - the status attribute. If the app status is not "OK", this means that the app may not be functioning correctly. If the error status persists, please let us know by submitting an error report.