# Building X Openness documentation # Contact [Visit Building X on siemens.com](https://www.siemens.com/en-us/products/building-x/apis/) or [Contact our experts](https://www.siemens.com/en-us/products/building-x/contact/) to unleash the power of (your) building data with our use-case optimized Building X Openness APIs. Experience seamless integration and tap into valuable insights via Building X Openness. Optimize operations, drive efficiency, and unlock new opportunities. Start your integration journey today to harness the true potential of smart buildings. Together, let's transform the way we leverage data and shape the future of your building with Building X Openness. - [Overview](overview.html) - APIs & Services - Developer's Guide - [Getting Started](dev-guide/gettingstarted.html) - [General Information](dev-guide/index.html) - [Authentication](dev-guide/howto.html) - [Try Out APIs](dev-guide/try-out.html) - Accounts API - [Overview](api/accounts-api/overview.html) - [Quick Start](api/accounts-api/quickstart.html) - [API Reference](api/accounts-api/api-reference.html) - [Changelog](api/accounts-api/changelog.html) - Building Structure API - [Overview](api/building-structure/overview.html) - [Quick Start](api/building-structure/quickstart.html) - [API Reference](api/building-structure/api-reference.html) - [Changelog](api/building-structure/changelog.html) - Building Geometry API - [Overview](api/geometry-api/overview.html) - [Quick Start](api/geometry-api/quickstart.html) - [API Reference](api/geometry-api/api-reference.html) - [Changelog](api/geometry-api/changelog.html) - Building Operations API - [Overview](api/building-operations/overview.html) - [Quick Start](api/building-operations/quickstart.html) - [API Reference](api/building-operations/api-reference.html) - [Changelog](api/building-operations/changelog.html) - Point Value Ingest API - [Overview](api/point-value-ingest-api/overview.html) - [Quick Start](api/point-value-ingest-api/quickstart.html) - [API Reference](api/point-value-ingest-api/api-reference.html) - [Changelog](api/point-value-ingest-api/changelog.html) - Streaming API - [Overview](api/streaming-api/overview.html) - [Quick Start](api/streaming-api/quickstart.html) - [API Reference](api/streaming-api/api-reference.html) - [Changelog](api/streaming-api/changelog.html) - Energy API - [Overview](api/energy-api/overview.html) - [Quick Start](api/energy-api/quickstart.html) - [API Reference](api/energy-api/api-reference.html) - [Changelog](api/energy-api/changelog.html) - Sustainability API - [Overview](api/sustainability-api/overview.html) - [Quick Start](api/sustainability-api/quickstart.html) - [API Reference](api/sustainability-api/api-reference.html) - [Changelog](api/sustainability-api/changelog.html) - Security Identities and Privileges API - [Overview](api/security-api/piam-v1/overview.html) - [Quick Start](api/security-api/piam-v1/quickstart.html) - [API Reference](api/security-api/piam-v1/api-reference.html) - [Changelog](api/security-api/piam-v1/changelog.html) - Activities API - [Overview](api/activities-v1/overview.html) - [Quick Start](api/activities-v1/quickstart.html) - [API Reference](api/activities-v1/api-reference.html) - [Changelog](api/activities-v1/changelog.html) - Security Workflow API - [Overview](api/security-api/security-workflow-v1/overview.html) - [Quick Start](api/security-api/security-workflow-v1/quickstart.html) - [API Reference](api/security-api/security-workflow-v1/api-reference.html) - [Changelog](api/security-api/security-workflow-v1/changelog.html) - Security Intrusion API - [Overview](api/security-api/security-intrusion-v1/overview.html) - [Quick Start](api/security-api/security-intrusion-v1/quickstart.html) - [API Reference](api/security-api/security-intrusion-v1/api-reference.html) - [Changelog](api/security-api/security-intrusion-v1/changelog.html) - Security Monitoring API - [Overview](api/security-api/security-monitoring-v1/overview.html) - [Quick Start](api/security-api/security-monitoring-v1/quickstart.html) - [API Reference](api/security-api/security-monitoring-v1/api-reference.html) - [Changelog](api/security-api/security-monitoring-v1/changelog.html) - Visitor Manager API - [Overview](api/visitormanager-api/overview.html) - [Quick Start](api/visitormanager-api/quickstart.html) - [API Reference](api/visitormanager-api/api-reference.html) - [Changelog](api/visitormanager-api/changelog.html) - Fire API - [Overview](api/fire/overview.html) - [Quick Start](api/fire/quickstart.html) - [API Reference](api/fire/api-reference.html) - [Changelog](api/fire/changelog.html) - Lifecycle Twin API - [Overview](api/lifecycletwin-api/overview.html) - [Quick Start](api/lifecycletwin-api/quickstart.html) - [API Reference](api/lifecycletwin-api/api-reference.html) - [Changelog](api/lifecycletwin-api/changelog.html) - Developer Guide - General - [Assets](api/lifecycletwin-api/guide/assets.html) - [Querying Data](api/lifecycletwin-api/guide/querying.html) - [Create](api/lifecycletwin-api/guide/create.html) - [Update](api/lifecycletwin-api/guide/update.html) - [Delete](api/lifecycletwin-api/guide/delete.html) - [Authentication](api/lifecycletwin-api/guide/authentication.html) - [Tasks](api/lifecycletwin-api/guide/tasks.html) - Documents - [Get/Find a Document](api/lifecycletwin-api/examples/documents/find-document.html) - [Create a Document](api/lifecycletwin-api/examples/documents/create-document.html) - [Create a Folder](api/lifecycletwin-api/examples/documents/create-folder.html) - [Modify a Document](api/lifecycletwin-api/examples/documents/modify-document.html) - [Upload New Version](api/lifecycletwin-api/examples/documents/document-new-version.html) - [Download a Document File](api/lifecycletwin-api/examples/documents/download-document.html) - [Assemblies](api/lifecycletwin-api/examples/assemblies/assemblies.html) - Configuration - [Custom Fields](api/lifecycletwin-api/examples/customfields/custom-fields.html) - Custom Tabs - [Manage Tabs](api/lifecycletwin-api/examples/custom-tabs/manage-tabs.html) - [Manage Tab Fields](api/lifecycletwin-api/examples/custom-tabs/manage-tab-fields.html) - [Manage Values](api/lifecycletwin-api/examples/custom-tabs/manage-tab-values.html) - Animations - [Animations](api/lifecycletwin-api/examples/animations/model-animations.html) - [Definition](api/lifecycletwin-api/examples/animations/example-of-animation-definition.html) - RDS and Data Points - [RDS](api/lifecycletwin-api/examples/rds/rds.html) - [Data Points (RDS Variables)](api/lifecycletwin-api/examples/rds/data-points.html) - SDKs - [Security Mobile App SDK](sdk/security/security-mobile-app-sdk.html) - [Security Manager Access PACS SDK](sdk/security/security-manager-access-pacs-sdk.html) - Resources - [Mendix Connector](resources/mendix/overview.html) - Power BI Templates - Operations and Energy - [Overview](resources/power-bi-templates/power-bi-operations-dataset-overview.html) - [Tables](resources/power-bi-templates/power-bi-operations-dataset-tables.html) - [Contact](contact.html) # Enrich Building X With the Innovations You Create The power of Building X is its ability to pull all the data from your different systems, put it into a single data pool, and then let you easily connect to it. This new level of connectivity opens up a world of possibilities for making buildings smarter. ## Welcome to the Building X Ecosystem When you connect to the cloud, you're connecting to the future of smart buildings. Building X makes it easy, powerful, and cost-effective. At Building X, Openness is a paradigm that thrives on collaborative innovation by providing open protocols and seamless integration through robust, use-case optimized, subscription-based APIs. [Try out](./dev-guide/gettingstarted.html "Try out APIs") [Contact us](contact.html "Contact us") ## Open API Portfolio Unlock the business value of data with a comprehensive API portfolio and cloud data exchange. Access building data in the cloud using familiar technologies, such as RESTful APIs and applied API standards, to build your own building applications as needed. It's your gateway to maximizing your building's potential and creating smart buildings that redefine performance and sustainability solutions. ## Third-Party Apps Choose the apps that help you perform your daily tasks and deliver tangible business results. Add different applications at different times as your smart building systems grow or change. For application developers, integration with Building X is easy and affordable, making our APIs suitable for new smart building applications. ## A Platform for Innovation and Collaboration With its openness and ability to connect users to unified building data, Building X unleashes the power of collaboration to create a dynamic, market-leading smart building ecosystem. - Integration with Building X is simple and affordable, allowing applications to be created and deployed more cost-effectively. - Building owners benefit from a wider range of available applications at a lower total cost. - Service providers can leverage data and applications to create new, smarter offerings for their customers, powered by Building X. - Through its reach and accessibility, the Building X ecosystem continues to drive innovation and collaboration, accelerating the future of intelligent buildings. # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.1.0] - 2026-04-28 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Account API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/accounts/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/accounts/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.0.2] - 2025-03-18 #### Added - Added support x-api-permission ### [1.0.1] - 2024-11-12 #### Fixed - Updated changelog. ### [1.0.0] - 2022-10-15 #### Added - Introducing the Building X - Accounts API, giving machine users information which partitions it can access # Accounts API The Accounts API enables you, or rather the calling entity, the machine user to discover in which partitions it has access. The Accounts API is organized around Customers, Partitions, UserGroups and Roles. ## Concepts & Glossary | Term | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Customer | A Customer represents a company which owns resources like `Machine Users` and `Partitions`. | | Partition | A Partition represents a logical segmentation of a Customer. It can be used to group a number of Buildings together. | | Roles | A Role is a set of permissions representing which actions a machine user with a given Role can perform in the system. | | UserGroup | User groups allow users to organize Partitions and user access in a fine-grained way. UserGroups can be used to group machine users to give them access to one or multiple Partitions by acting in a certain Role. | # Quick Start Getting started with using Accounts APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. 1. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html)- section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token`-property in the response. You can now use it by passing it in the `Authorization`-header of any subsequent API requests. The `expires_in`-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Store the token in your `TOKEN`-environmental variable ```bash export TOKEN= ``` Now you have all you need to start using the API. ## Make API requests This guide will take you through the steps you need to: 1. Find out which partitions you can access 1. Getting additional information about Partitions and Customers ### List your UserGroups The first step to perform is to list the UserGroups you have access to. This you can do by performing the `Get the usergroups of the caller` operation i.e. `GET me/usergroups`. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/accounts/me/usergroups" ``` The response contains all information about all UserGroups you (the machine user) has access to. If you have a large number of UserGroups you may need to retrieve multiple pages, see [Pagination](../../dev-guide/index.html#pagination). The most important information given for each UserGroup is the following: | Property | Description | | ---------------------------- | ------------------------------------------------------ | | `relationships.authorizedAs` | A list of Roles that the UserGroup has | | `relationships.hasAccessTo` | A list of Partitions that the UserGroups has access to | | `relationships.ownedBy` | A reference to the owning Customer | You have access to each partition mentioned above and are now able to use any other API e.g. `Building Operations API` with these partitions. To learn how to get then names of each Partition and Company please proceed to the next section. ### List Partitions Before you continue, store one of the Customer IDs for which you have access in an environmental variable, you can get the using the `Get the usergroups of the caller` operation as described above. ```bash export CUSTOMER=8db4216d-61c5-4e79-8558-164aa179bfe9 ``` To get more information about each of your Partitions you can use the `List Partitions for customer` operation. Below we specify the `include`-parameter to include the Company name of each Partition in the `included` section of the response. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/accounts/customers/$CUSTOMER/partitions?include=ownedByCustomer.name" ``` You can repeat this operation for each of the Customers you have access to. Note For more details on deprecation policies and common API features such as paging, filtering and errors, refer to the [Developer's Guide](../../dev-guide/gettingstarted.html). ## Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.2.0] - 2026-05-06 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Security Activities API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/sec-activities-v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/sec-activities-v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.1.5] - 2026-01-20 #### Fix - Fixing issue with huge payloads. ### [1.1.4] - 2025-03-05 #### Update - Rename from Security Activities API to Activities API. ### [1.1.3] - 2024-11-12 #### Added - Added linting. ### [1.1.2] - 2024-08-08 #### Added - Aligned the documentation and corrected spelling errors ### [1.0.0] - 2023-12-20 #### Added - Security Activities API released - Added API endpoints for - Activities - To fetch all the activities # Activities API Activities API enables user to retrieve events, alarms and user operation produced from access system and security manager services. Customers can use the API to integrate the Security Manager functions & data into their own workflows & applications for reporting and investigation purpose. ## Concepts & Glossary | Term | Description | | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Activity | Is an audit trail for Security Manager. Lists all events, alarms from access system and user operation from security manager services. | # Quick Start Getting started with using Activities APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. Making use of a Linux/MacOS shell in which environmental variables are set using the `export` command. In other environments it may be different, e.g. Windows uses the `set` command instead. 1. Using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, JavaScript and Java. ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html) section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token` property in the response. You can now use it by passing it in the `Authorization` header of any subsequent API requests. The `expires_in` property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed, you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to: 1. Consume activities ### List Activities To fetch the user performed activities based by `PARTITION`. `size` parameter is an optional field and based on this value the response is returned (Note: `size` should not exceed 1000). `cursor` represent the last activity `id` from which the next set of activities can be fetched along with the size parameter. In case all the activities returned on the current request, the value of `next` will be null. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/sec-activities-v1/partitions/$PARTITION/activities?page[size]=2" ``` The response contains all details of individual activities. ```bash { "links": { "self": "/activities?page[size]=2", "next": "/activities?page[size]=2&page[cursor]=6478632ea30ccb58b630b273" }, "data": [ { "type": "Activity", "id": "6478632ea30ccb58b630b272", "attributes": { "title": "Identity deleted", "description": "Identity Performance Test - Security API - First Name Performance Test - Security API - Last Name was deleted", "eventType": "Operator", "severity": "Low", "category": "User operation", "subCategory": null, "created": "2023-06-01T09:21:50.356Z", "recorded": "2023-06-01T09:21:52.868Z", "subSystem": "Siveillance Access", "origin": "Identity Management" } }, { "type": "Activity", "id": "6478632ea30ccb58b630b273", "attributes": { "title": "Identity created", "description": "Identity Performance Test - Security API - First Name Performance Test - Security API - Last Name was created", "eventType": "Operator", "severity": "Low", "category": "User operation", "subCategory": null, "created": "2023-06-01T09:21:50.356Z", "recorded": "2023-06-01T09:21:50.758Z", "subSystem": "Siveillance Access", "origin": "Identity Management" } } ] } ``` Note For more details on deprecation policies and common API features such as paging, filtering and errors, refer to the [Developer's Guide](../../dev-guide/gettingstarted.html). # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.5.0] - 2026-05-06 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Building Operation API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/operations/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/operations/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.4.0] - 2025-10-01 #### Added - Add Fault API endpoints: - `GET /faults` - Get all the faults that were active in a specified time range according to the given query parameters. - `GET /faults/{faultId}` - Get the specified Fault. - `PATCH /faults/{faultId}` - Update the state of Fault. - `GET /faults/{faultId}/occurrences` - Get all the occurrences for the given fault. - `GET /fault-statistics` - Get fault statistics for the given building. - Add WorkOrder API endpoints: - `GET /workorders` - Get the list of all workorders. - `POST /workorders` - Creates a new workorder (supports Alarm-based, Fault-based, and Generic types). - `GET /workorders/{workorderId}` - Get the workorder for the given workorderId. - `PATCH /workorders/{workorderId}` - Update the workorder for the given workorderId. - `GET /workorders/{workorderId}/assignments` - Get a list of assignments for a given workorder id. - `POST /workorders/{workorderId}/assignments` - Add assignment to workorder. - `PUT /workorders/{workorderId}/assignments` - Set Assignments for the Workorder. - Add Teams API endpoints: - `GET /teams` - Retrieves a list of all teams that match the specified filters. - `POST /teams` - Creates a new team for a customer with the specified name, description, domain, and assigned buildings. - `GET /teams/{teamId}` - Get the details of specific team. - `PATCH /teams/{teamId}` - Updates an existing team's name, description, domain, and buildings. - `GET /teams/{teamId}/members` - Retrieves a list of all members within a specific team. - `PATCH /teams/{teamId}/members` - Add a list of members within a specific team. ### [1.3.17] - 2024-11-12 #### Fixed - Updated changelog. ### [1.3.16] - 2024-08-29 #### Fixed - Fix code responses in specification. ### [1.3.15] - 2024-08-08 #### Added - Aligned the documentation and corrected spelling errors ### [1.3.5] - 2023-06-06 #### Added - 'Add point values' operation. Enabling import of point values. Point value ingestion is exposed for evaluation purposes until the new subscription is released by September 2023. - 'Create device' operation. Device creation is exposed for evaluation purposes until the new subscription is released by September 2023. ### [1.3.0] - 2023-03-20 #### Added - Adding Alarm Configuration management operations - 'List event transition history'-operation #### Updated - Deprecated 'Get Event', which is replaced with 'List event transition history'. ### [1.2.0] - 2022-07-07 #### Added - Added multiple new properties to `Point` model for a uniform access, independent of Edge Application: - description - isActive - unit - enum - minimum - maximum - precision - commandingSemantic - function - Added new properties to `PointValue` model for a uniform access, independent of Edge Application: - targetValue - qualityOfValue #### Updated - Removed the `pattern` definition and any uuid references as IDs may have other formats ### [1.0.7] - 2022-05-22 #### Fixed - Multiple minor documentation improvements, regarding `include`-params and device relationships ### [1.0.5] - 2022-04-21 #### Fixed - Removed `included` from response model of 'Get Single Device' as it is not supported ### [1.0.4] - 2022-03-22 #### Added - First version of 'Operations API' # Building Operations API The Building Operations API enables you to read data from data points or issue commands to actuator points. Commanding enables you to e.g. change set-point values on a thermostat or open or close a valve. The Building Operations API is organized around the `Device`-, `Point`- and `PointValue`- resources. A device can host several points capable of either sensing information from the building such as temperature or air quality, or capable of receiving and processing commands. The data that is measured by data points is called point values and you can specify the time interval for which to fetch data. ## Concepts & Glossary | Term | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Device | A Device can be any electronic equipment with some computing ability that has a firmware or supports the installation of software. Examples are pumps, dampers, valves, sensors, detectors, limit switches, remote/local switches or automation devices. | | Point | Points represent the interface to data in a system. Points are classifying data and give a semantic context to it. Examples for a Point are a Room Control for Temperature with a temperature set point. | | PointValue | Object which represents a measurement or set value of a Point. | | Event | An Event represents a non-normal (non-quiescent) state in building automation systems and is caused by an abnormal situation (technical: like fault, alarm, detector exclusion, range violation but also human: manually creating an alarm/task, request/call). | | Location | A structure or part of a structure where a Device can be located | | Workorder | A Workorder represents a task or job that needs to be carried out within the building operations, such as maintenance, repair, or inspection activities. Workorders can be created, updated, retrieved, and assigned to specific teams or individuals. They provide a structured way to manage operational activities and ensure proper tracking of work progress. | | Fault | A Fault represents a detected abnormal condition or malfunction within a building system. Faults can be monitored, updated, and analyzed to understand their occurrences and overall impact on the building’s performance. | | Team | A Team represents a group of people responsible for performing tasks or managing specific areas of the building operations. Teams can be created, updated, retrieved, and managed to ensure collaboration and assignment of responsibilities. | A building typically contains multiple different `Devices`. The `Devices` host `Points` which can be of the following types: sensor, command or set-point. `Points` that are either sensors or set-points can have measured or aggregated time-series `PointValues` which can be filtered by time interval. ## Devices Some devices are connected directly to the Building X cloud and some make use of other devices to manage the connection. When a device relies on another device to connect to the cloud, it has a relationship called `hasGateway` defined, referring to the device it uses as a gateway to Building X. ## Points Any device may have points, regardless of whether the device is directly connected to the cloud or not. A building system can generate Faults that highlight abnormal conditions, which in turn lead to Workorders documenting the required activities, and these Workorders are assigned to Teams that ensure the issues are resolved effectively. ## Workorders Workorders are used to manage tasks and operational activities in the building environment. They enable a structured approach to handling different kinds of work, ensuring proper planning, execution, and tracking. A workorder can be created to document a maintenance activity, an inspection, or a repair. Once created, it can be updated with additional details such as its description, priority, or due date. Workorders can then be assigned to individuals or teams so that responsibilities are clear, and their progress can be tracked throughout the lifecycle of the task. They serve as a reliable tool for monitoring the status of ongoing activities, keeping a history of what has been completed, and ensuring that all work within the building operations is properly documented and followed through until completion. ## Faults Faults represent abnormal conditions or malfunctions in building systems and play an important role in monitoring operational health. They allow building operators to identify and analyze issues that may affect performance or safety. Faults can be retrieved to get an overview of all the problems detected in a partition or for a specific fault identifier. The state of a fault can be updated as its condition evolves, for instance when it is acknowledged or resolved. Each fault can also be examined in detail by looking at its occurrences, which provide insights into how frequently the issue arises and under what circumstances. Additionally, aggregated statistics about faults in a building can be accessed to better understand their overall impact, supporting both reactive and preventive maintenance strategies. In this way, the management of faults ensures that technical issues are not only detected but also documented, analyzed, and addressed effectively. ## Teams Teams represent groups of people that are responsible for carrying out tasks or managing specific aspects of building operations. They can be created for a customer with a defined name, description, and domain, and can be linked to certain locations or buildings. Once created, a team can be updated to reflect changes in its responsibilities or organizational context. Teams can also be retrieved to view details such as their members, scope, and associated locations. Members can be added to or managed within a team, ensuring that the right individuals are assigned to the right groups. This structure supports collaboration, accountability, and clear allocation of work across the building operations. Teams therefore serve as a foundation for organizing human resources, enabling efficient execution of workorders, and ensuring smooth communication and responsibility management within the building environment. ### System Attributes In Building X some point properties are completely managed by the platform. In the Building Operations API those are defined in the API specification and include `dataType` and `name`. In addition, there are other properties contained in the `systemAttributes`-object. The content of the `systemAttributes` is not marshaled by the Building Operations API and depends on the SW versions and configuration of devices and gateways connecting to Building X. As such, they may appear differently depending on the building and mentioned configurations. In addition, these properties may change outside of the API lifecycle, e.g., when updating firmware of the gateway device or software of the edge application. # Quick Start Getting started with using Building Operations APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. 1. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html)- section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token`-property in the response. You can now use it by passing it in the `Authorization`-header of any subsequent API requests. The `expires_in`-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to perform to read values, e.g. temperature measurements, from a Point. We will assume you don't yet know the id of the Point, meaning that before you can get the temperature data for the Point you must discover the Point by listing Locations, Devices and Points. ### List Locations The first step to perform is to list the buildings in your partition. This you can do by performing the `List Locations` operation. Below we specify the `include` -parameter to include the address of each building in the `included` section of the response. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/locations?filter[type]=Building&include=hasPostalAddress" ``` The response contains all buildings in your partition. If you have a large number of buildings you may need to retrieve multiple pages, see [Pagination](../../dev-guide/index.html#pagination). Select the `id` property of one of the locations in the response and set it in an environmental variable. E.g. if the `id` is `8db4216d-61c5-4e79-8558-164aa179bfe9` then set it using the following command: ```bash export LOCATION=8db4216d-61c5-4e79-8558-164aa179bfe9 ``` ### List Devices The next step is to list the devices available in your building. This is achieved by using the `List Devices` operation. In this example also the optional `include` -parameter is specified, it's useful to retrieve the name and connectivity status of the devices. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/devices?filter[hasLocation.data.id]=$LOCATION&include=hasFeatures.DeviceInfo,hasFeatures.Connectivity" ``` The response contains a list of all devices with their location defined as the building you specified. To also get the devices that are potentially behind the first set of devices we must use the `List devices behind a gateway` operation. This must be done for each device retrieved above. Imagine we have retrieved one device with id `7d4293a7-5c61-47e2-b010-9ba913c016e4`, then we can get the devices behind it by performing the following operation: ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/devices/7d4293a7-5c61-47e2-b010-9ba913c016e4/devices&include=hasFeatures.DeviceInfo,hasFeatures.Connectivity" ``` Once you have performed the second request for each of the devices in the first set you have all the devices in your building. Any of these devices may host points. That means that to be certain to retrieve all points in your building you must perform the `List Points` operation, explained in the next section, for each of the devices. If your use case is well defined and you have a well-known hierarchy in your setup you can of course use that knowledge, e.g. by using the `modelName` or `DeviceInfo` to only query some devices for points. ### List Points for Device The `List Points` operation retrieve point for a certain device. By specifying the optional `field`-parameter, also the latest known value will be present in the response. Assuming the `DEVICE` environmental variable contains the id of the device you are interested in you can perform the following request: ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/devices/$DEVICE/points?field[Point]=pointValue" ``` The response contains a list of all points for the device. Select the `id` property and store in the `POINT`-variable. E.g. ```bash export POINT=a850ec9a-daf6-4630-9c22-af680e82b3a4 ``` ### List Values To get the time series data or PointValues you can use the `List Values` operation. To use this operation you will need to specify the query parameter `filter[timestamp][from]` with a valid date-time in the RFC3339 (UTC) format. The recommended value for trying is to specify the current time minus one hour. E.g. `2021-10-25T23:00:00.000Z` ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/points/$POINT/values?filter[timestamp][from]=2021-10-25T23:00:00.000Z" ``` In the response, you will find the latest values, e.g. temperature or air quality readings for the point. ### Commanding Points You can change the value of a point by using the `Update Point` operation. The following example will set the value of the point to `2`. ```bash curl -X PATCH "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/points/$POINT" \ -H "Content-Type: application/vnd.api+json" \ -H "Authorization: Bearer $TOKEN" \ -d "{ \"data\": { \"type\": \"Point\", \"id\": \"$POINT\", \"attributes\": { \"pointValue\": { \"value\": \"2\" } } } }" ``` Note Even though the `Update Point` operation itself is successful, it does not mean that the point's state is reflected immediately. There can be a delay of up to a minute until the value is applied to the point. It's also possible that the command is discarded due to automation applications with higher priority already commanding the point. ### List Events To get current and past events and alarms for a device, the `List Events` operation can be used: ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/devices/$DEVICE/events" ``` ### Create Device To create a new device, the `Create Device` operation can be used: ```bash curl -X 'POST' \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/devices" \ -H "Accept: application/vnd.api+json" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ -d "{ \"data\": { \"type\": \"Device\", \"attributes\": { \"modelName\": \"string\", \"serialNumber\": \"string\" } } }" ``` In the response, you will find the device is created for the given modelName & serialNumber. ### Add point values To add point values, the `Post values` operation can be used. Push 1 to 100 values for given point in a batch. Only one pointValue per millisecond will be stored. pointValues are dropped if there are timestamp conflicts, i.e. if a pointValue with the same timestamp already exists. Example with following pointValues: - 2022-07-11T11:11:30.333 - 2022-07-11T11:11:30.222 - 2022-07-11T11:11:30.333 - 2022-07-11T11:11:30.444 The first is accepted (it's the first for time "30.333"). The second is also accepted. The third is dropped because it's the same timestamp as the first. The fourth is accepted again. The indices of dropped pointValues are listed in the response (0-based), in this example there is one conflict with index "2". If there is no conflict status 204 is returned instead of 202. Note: Use query parameter `overwrite=true` to force overwriting of conflicting values. ```bash curl -X 'POST' \ "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/points/$POINTID/values" \ -H "Accept: application/vnd.api+json" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ -d "{ \"data\": [ { \"type\": \"PointValue\", \"attributes\": { \"timestamp\": \"2000-05-11T10:32:54.964Z\", \"value\": \"12.66\" } } ] }" ``` In the response, you will find the values added for the pointId. Note For more details on deprecation policies and common API features such as paging, filtering and errors, refer to the [Developer's Guide](../../dev-guide/gettingstarted.html). # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.1.0] - 2026-04-28 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Structure API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/structure/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/structure/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date. ### [1.0.35] - 2025-09-12 - Enrich Point with additional attributes: unit, enum, systemAttributes ### [1.0.34] - 2025-02-04 - Fixed maestro version in order to realign to 1.0.31 - Fixed vulnerabilities ### [1.0.33] - 2024-11-12 #### Updated - Updated changelog ### [1.0.32] - 2024-11-12 #### Updated - Aligned the documentation and corrected spelling errors ### [1.0.30] - 2024-06-18 #### Updated - Fix minor issue with schema from 'Create Equipment' and 'Update Equipment' ### [1.0.28] - 2024-03-12 #### Updated - Updating spec from `Structure API` -> `Building Structure API`. ### [1.0.25] - 2023-09-29 #### Updated - Fixes to specification to reflect that client generated IDs are not supported when creating Point and Equipment. ### [1.0.24] - 2023-06-06 #### Added - 'Create Point' operation. Creation of points is exposed for evaluation purposes until the new subscription is released by September 2023. ### [1.0.23] - 2023-05-25 #### Updated - Fix typo of "writeable" - Fix inconsistency, "/has-points" should take an array as primary data ### [1.0.22] - 2023-05-15 #### Added - Point.source property ### [1.0.16] - 2022-12-15 #### Added - Equipment, PointGroups endpoints to enable management of building equipment topology ### [1.0.1] - 2022-09-28 #### Updated - Location ID schema ### [1.0.0] - 2022-09-27 #### Added - Structure API released # Building Structure API The Building Structure API enables you to create and manage a structural representation of your buildings in Building X. The API also helps you manage the location of equipment inside buildings and enables you to programmatically automate data setup. The Building Structure API is organized around elements of building structures, called Locations, e.g. Building, Floor and Room ## Concepts & Glossary | Term | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Location | A Location is the basic element describing the topological structure of a site or building, i.e. the common base class of a Campus, Building, Floor, Room etc. | | Campus | A Campus is a grouping of multiple Buildings and Outside spaces (directly or via CampusParts). Typically it is physically represented by a fence, vegetation or street. It could be a contiguous area like an enfenced airport or a looser aggregation like an government district (with foreign buildings between). | | CampusPart | In larger or disjoint campuses, there might be the need for a subsection, e.g. the 'science campus' or the 'west shore campus'. | | Building | A building is generally a structure built for a purpose that has a roof and walls and stands more or less permanently in one place. Typical examples are a house, factory, or shop; but if necessary also a cave, tower, tent or even a ship could be called a building. | | BuildingPart | In a larger or structured building, there might be the need for a subgrouping, e.g. the 'left wing' or the 'south part'. | | Outside | On a campus or even as part of a building, there can be outside areas, e.g. the lawns between buildings, the pavement to the end of the building lot, the carpark or delivery ramp, or a balcony or roof-top restaurant. | | Floor | A floor is a horizontal / level part of a building with a surface that could be used by people (for living, work, storage, recreation, etc), depending on context, they are also called storey/story, level or deck. Multiple floors can be stacked up vertically to form a multi-floor building. | | FloorArea | A floor-area is a subsection of an floor, which - unlike rooms - is not separated by walls to which entry is possible by a door or similar as to the floor itself. Normally, areas are large enough for many persons to move about or conduct the intended activity. | | MultifloorArea | A multifloor-area is a vertical crosssection of multiple floors, like a lecture room, cinema theatre, lobby that spreads the height of multiple floors and can be typically accessed on multiple levels. | | Room | A room is an indoor space enclosed within four walls (and a roof or ceiling) to which entry is possible by a door or similar, which connects it either to a passageway, to another room, or to the outdoors. Normally, rooms are large enough for several persons to enter and move about or conduct the intended activity. Typically, the height of a room is the full height of the floor it is part of. | | RoomSegment | Often, a floor is implicitly divided into a grid or into segments that later on might turn into rooms by adding walls. Such segments often contain technical preparations for possible rooms (e.g. pillars, grids, window arrangement, piping or wiring). | | Device | A Device can be any electronic equipment with some computing ability that has a firmware or supports the installation of software. Examples are pumps, dampers, valves, sensors, detectors, limit switches, remote/local switches or automation devices. | # Quick Start Getting started with using Building Structure APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. 1. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html)- section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token`-property in the response. You can now use it by passing it in the `Authorization`-header of any subsequent API requests. The `expires_in`-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to: 1. Consume an existing Building, including all parts, possibly created using the Data Setup App 1. Creating a Building hierarchy ### List Buildings The first step to perform is to list the buildings in your partition. This you can do by performing the `List Locations` operation. Below we specify the `include` -parameter to include the address of each building in the `included` section of the response. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/structure/partitions/$PARTITION/locations?filter[type]=Building&include=hasPostalAddress" ``` The response contains all buildings in your partition. If you have a large number of buildings you may need to retrieve multiple pages, see [Pagination](../../dev-guide/index.html#pagination). Select the `id` property of one of the locations in the response and set it in an environmental variable. E.g. if the `id` is `8db4216d-61c5-4e79-8558-164aa179bfe9` then set it using the following command: ```bash export LOCATION=8db4216d-61c5-4e79-8558-164aa179bfe9 ``` ### List Parts of a Building The next step is to list the parts of the building. This is achieved by using the `List Location Parts` operation. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/structure/partitions/$PARTITION/locations/$LOCATION/relationships/has-parts" ``` The response contains a list of direct and transitive parts of the specified location with their location defined as the building you specified. I.e. if your building has Floors and those Floors have Rooms the response will contain all those Floors and Rooms. If you wish to perform some logic on the Building hierarchy or visualize a tree you need to assemble the tree yourself. It is straightforward and done by using the hierarchical relationships e.g. `isFloorOf` and `isRoomOf`. ### Creating a Location Hierarchy All locations have a parent, or in other words, they have an `isPartOf`-relationship to a higher level Location, except Campus and Building. Buildings are optionally related to Campuses or CampusParts. This means to create a hierarchy we must start with the top-level Location. To create a Building we also must provide a reference to and `Address`-resource. Optionally in can be provided using the `include`-feature of the API, we will use this in our example. Create a file named `newbuilding.json`. Paste in the following content below but please change the `id` of the Address to something unique, e.g. by creating a new UUID using [uuidgenerator.net](https://www.uuidgenerator.net/). Note that 'data/relationships/data/id' must match the 'included[0]/id' ```json { "data": { "type": "Building", "attributes": { "label": "My Place", "timeZone": "Europe/Zurich" }, "relationships": { "hasPostalAddress": { "data": { "id": "05085306-9c1d-4cee-b92a-04c07e4b1945", "type": "Address" } } } }, "included": [ { "id": "05085306-9c1d-4cee-b92a-04c07e4b1945", "type": "Address", "attributes": { "locality": "Springfield", "countryCode": "USA", "region": "Indiana", "postalCode": "10101", "street": "33 Park Way" } } ] } ``` You are now ready to create the Building by performing the `Create Location` operation: ```bash curl -H "Authorization: Bearer $TOKEN" \ -X POST -d @newbuilding.json -H "Content-Type: application/vnd.api+json" \ "https://eu.buildingx.siemens.com/api/openness/structure/partitions/$PARTITION/locations" ``` In the response, you will find the generated id for your Building. Now you can continue by creating floors and using the Building-ID. If the BuildingID was `79d8fd89-6c82-40b6-aa5a-9a570d3ae88a` the request body to create a floor would look like this: ```json { "data": { "type": "Floor", "attributes": { "label": "My Floor", "floorNumber": 1 }, "relationships": { "isFloorOf": { "data": { "id": "79d8fd89-6c82-40b6-aa5a-9a570d3ae88a", "type": "Building" } } } } } ``` ### Add points to point-groups To add points to point-groups, the `Post /point-groups/{point-groupId}/points` operation can be used. ```bash curl -X 'POST' \ "https://eu.buildingx.siemens.com/api/openness/structure/partitions/$PARTITION/point-groups/$POINTGROUPID/points" \ -H "Accept: application/vnd.api+json" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ -d "{ \"data\": { \"type\": \"Point\", \"attributes\": { \"name\": \"hvac 2134444\", \"description\": \"HVAC controller\", \"dataType\": \"number\", \"maximum\": 100, \"minimum\": 100, \"precision\": 0.1, \"commandingSemantic\": \"writeable\", \"function\": \"sensor\" } } }" ``` In the response, it will add points to the point-groups. Note For more details on deprecation policies and common API features such as paging, filtering and errors, refer to the [Developer's Guide](../../dev-guide/gettingstarted.html). # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.3.0] - 2026-05-5 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Energy API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/energy/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/energy/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.2.6] - 2026-03-13 #### Added - Added support x-api-permission. ### [1.2.5] - 2024-11-12 #### Added - Added linting. ### [1.2.4] - 2024-08-08 #### Added - Aligned the documentation and corrected spelling errors ### [1.1.0] - 2024-01-12 #### Added - First version of `Energy API` ### [1.1.1] - 2024-01-22 #### Added - Spec update - requirements for deploy Energy API gateway ### [1.1.2] - 2024-01-23 #### Added - Spec update for related envs # Energy API The Energy API enables you to read energy consumption, emission, or cost data for a location or a meter in the granularity and for the period of interest. The API is available as an add-on in combination with an active Building X Energy Manager subscription. Building X Energy Manager customers with a `Navigator conversion` subscription cannot use the API. ## Concepts & Glossary | Term | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Medium-consumption | A Medium-Consumption determines the consumption of some medium for some discipline (today `consumption groups`) of a location (e.g., building) or a meter equipment over a period. | | Consumption | Consumption provides the consumption of a location or measured by a Meter-Equipment that is derived from its meter readings. | | Costs | Consumption provides the consumption of a location or measured by a Meter-Equipment that is derived from its meter readings. | | Emissions | Emissions provide the emissions calculated based on defined emission conversion factors in Building X Energy Manager and the measured consumption. | *Usage of APIs is subject to an agreement between customer and Siemens. To the extent nothing specific is agreed, the Siemens terms and conditions agreed in the Siemens subscription manager shall apply.* # Quick Start Getting started with using Energy APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html) section to construct the Create Token request. ## Make API requests This guide will take you through the steps you need to perform to extract your energy consumption, emission, or cost data for a location or a meter in the granularity and for the period of interest. - Identify MediumConsumption ID - Read Consumption per building - Read Consumption per meter equipment > **Note for usage:**\ > Currently, we cannot identify the point which is streamed to Navigator. Extension of equipment types required to identify `Interface PointId` Assumption: Today, you manually assign one point to the meter equipment. → PointId can be identified via Equipment endpoints. # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.1.0] - 2026-06-17 #### Added - Support for hardware tree based response in the configuration API. ## [1.1.0-rc1] - 2026-05-18 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Fire API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/fire/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/fire/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.0.3] - 2025-10-06 #### Removed - Commands API endpoint ### [1.0.2] - 2025-07-31 #### Updated - Enforce commanding for geofence enabled ### [1.0.1] - 2025-06-06 - Enable location API - Add new points API ### [1.0.0] - 2025-05-27 #### Fix - deprecate locations API ### [0.0.20] - 2025-05-15 #### Updated - Update response body of Configuration API ### [0.0.19] - 2025-03-12 #### Added - Site Information and Channels API, supports retrieving channels data along with its dynamic data ### [0.0.18] - 2024-11-05 #### Added - New Commands API ### [0.0.16] - 2024-11-05 - Added linting ### [0.0.15] - 2024-11-05 - Added Parent CustomerText Level 1, 2, 3 Attributes for the events API ### [0.0.14] - 2024-09-25 - revert deprecate locations API ### [0.0.13] - 2024-09-24 - Added fire.api-manager.openapi.yaml to the package in the dist subfolder ### [0.0.12] - 2024-09-23 - Enhance Fire API offering for events by adding event source as response ### [0.0.11] - 2024-08-08 - Aligned the documentation and corrected spelling errors ### [0.0.10] - 2023-05-28 - deprecate locations API ### [0.0.7] - 2023-09-28 #### Updated - added panel device example for the /device API ### [0.0.6] - 2023-07-21 #### Updated - remove page[limit] query parameter for the /device API ### [0.0.5] - 2023-07-15 #### Updated - Update Base url path of fire API for the developer portal ### [0.0.3] - 2023-06-27 #### Updated - Update env configuration for Fire APIs ### [0.0.1] - 2023-05-26 #### Added - First version of 'Fire API' # Fire API The Fire API enables you or rather the calling entity, the machine user to get all events of site if it has access to the partition of the site. ## Concepts & Glossary | Term | Description | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Location | A structure or part of a structure where a Device can be located | | Device | A Device can be any electronic equipment with some computing ability that has a firmware or supports the installation of software. Examples are pumps, dampers, valves, sensors, detectors, limit switches, remote/local switches or automation devices. | | Event | An Event represents a non-normal (non-quiescent) state in building automation systems and is caused by an abnormal situation (technical: like fault, alarm, detector exclusion, range violation but also human: manually creating an alarm/task request/call). | ## Devices Some devices are connected directly to the Building X cloud and some make use of other devices to manage the connection. When a device relies on another device to connect to the cloud, it has a relationship called `hasGateway` defined, referring to the device it uses as a gateway to Building X. # Quick Start Welcome to the Fire API Quick Start guide! This document will walk you through the essential steps to authenticate and interact with the Fire APIs, from account creation to making your first API requests. ## Prerequisites Before you begin, ensure you have: - Access to the Fire API portal. - Credentials for a machine user (`clientId`, `clientSecret`, and `partitionId`). - A terminal environment (Linux/MacOS shell or Windows command prompt). - [curl](https://curl.se/) installed, or another HTTP client of your choice. ## Step 1: Create an Account and Machine User To access the Fire APIs, you need to create an account and register a machine user. Follow the instructions in the [Getting Started](../../dev-guide/gettingstarted.html) guide to obtain your `clientId`, `clientSecret`, and `partitionId`. ## Step 2: Obtain a JSON Web Token (JWT) Authenticate your machine user by generating a JWT. This token will be used to authorize your API requests. ### Example: Generate a Token Set your credentials as environment variables: ```bash export CLIENT_ID= export CLIENT_SECRET= ``` **Endpoint:** `POST https://siemens-bt-015.eu.auth0.com/oauth/token` **Body Parameters:** - `client_id` (string, required): Your machine user's client ID. - `client_secret` (string, required): Your machine user's client secret. - `audience` (string, required): The audience for the token, typically the API identifier. - `grant_type` (string, required): The OAuth2 grant type, usually `client_credentials`. **Example:** ```bash curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` > **Note:** > > - The above example uses a Linux/MacOS shell. On Windows, use `set` instead of `export`. > - You can use any HTTP client or programming language to make these requests. #### Example Response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` - The `access_token` is your JWT. - The `expires_in` value (in seconds) indicates how long the token is valid (typically 24 hours). Set your token and partition as environment variables for convenience: ```bash export PARTITION= export TOKEN= ``` ## Step 3: Make API Requests With your token and partition ID, you can now interact with the Fire API. ### 3.1 List Locations Retrieve all buildings (locations) within your partition. **Endpoint:** `GET partitions/{$partitionId}/locations` **Path Parameters:** - `partitionId` (string, required): The unique identifier of the partition. **Example:** ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/fire/partitions/$PARTITION/locations" ``` - The response includes a list of locations, each with an `id` property. - For large partitions, refer to the [Pagination](../../dev-guide/index.html#pagination) section. Store a location ID for later use: ```bash export LOCATION= ``` ### 3.2 Get Location by ID Retrieve details for a specific location. **Endpoint:** `GET partitions/{$partitionId}/locations/{$locationId}` **Path Parameters:** - `partitionId` (string, required): The unique identifier of the partition. - `locationId` (string, required): The unique identifier of the location. **Example:** ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/fire/partitions/$PARTITION/locations/$LOCATION" ``` - Replace `$LOCATION` with the desired location ID. ### 3.3 List Devices List all devices in your selected building. **Endpoint:** `GET partitions/{$partitionId}/devices` **Path Parameters:** - `partitionId` (string, required): The unique identifier of the partition. **Example:** ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/fire/partitions/$PARTITION/devices" ``` - Devices are associated with locations (buildings). ### 3.4 List Events Retrieve past events and alarms for a specific device. You can filter events based on timestamp ranges using query parameters. **Endpoint:** `GET partitions/{$partitionId}/devices/{$deviceId}/events` **Path Parameters:** - `partitionId` (string, required): The unique identifier of the partition. - `deviceId` (string, required): The unique identifier of the device. **Query Parameters:** - `filter[timestamp][from]` (string, optional): Start of the timestamp range (ISO 8601 format). - `filter[timestamp][to]` (string, optional): End of the timestamp range (ISO 8601 format). **Example:** ```bash curl -G -H "Authorization: Bearer $TOKEN" \ --data-urlencode "filter[timestamp][from]=2024-05-01T00:00:00Z" \ --data-urlencode "filter[timestamp][to]=2024-05-31T23:59:59Z" \ "https://eu.buildingx.siemens.com/api/openness/fire/partitions/$PARTITION/devices/$DEVICE/events" ``` - Replace the timestamp values with your desired date and time range in ISO 8601 format. - The response will include events within the specified time window. ### 3.5 Get Location Configuration Retrieves the configuration details for a specific location. This endpoint allows clients to fetch settings and parameters associated with a given location, such as thresholds, enabled features, and other configuration elements. **Endpoint:** `GET partitions/{$partitionId}/locations/{$locationId}/configuration` **Path Parameters:** - `partitionId` (string, required): The unique identifier of the partition. - `locationId` (string, required): The unique identifier of the location. **Example:** ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/fire/partitions/$PARTITION/locations/$LOCATION/configuration" ``` ### 3.6 Get Last Values for Points Fetch the most recent values for specified points. This endpoint is useful for monitoring and displaying the latest state or value of various points. **Endpoint:** `GET partitions/{$partitionId}/points/lastValues` **Path Parameters:** - `partitionId` (string, required): The unique identifier of the partition. **Query Parameters:** - `pointIds` (string, required): Comma-separated point IDs to retrieve the last values for. **Note:** You can specify up to 50 point IDs per request. - `lastChangedLatest` (string, optional): Only return the latest value for each point up to and including this timestamp (ISO 8601 format). **Example:** ```bash curl -G -H "Authorization: Bearer $TOKEN" \ --data-urlencode "pointIds=," \ --data-urlencode "lastChangedLatest=2024-06-01T12:00:00Z" \ "https://eu.buildingx.siemens.com/api/openness/fire/partitions/$PARTITION/points/lastValues" ``` - Replace ``, ``, etc., with the desired point IDs (up to 50 per request). - Set `lastChangedLatest` to the latest timestamp you want to include (optional). - The response will include the latest values for each specified point, up to the given timestamp if provided. #### Response The response contains an array of objects, each representing the last value for a requested point. Each object includes at least the following fields: - `id`: The point ID. - `value`: The latest value for the point. - `createdAt`: The timestamp when the value was recorded. Depending on the point type, the `value` and additional fields may vary. Below are examples of possible responses for different point types: Automatic Detector Test ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "value": "TEST_SUCCESSFUL", "createdAt": "2021-03-08T13:51:40.541Z" } ``` Possible `value`: `TEST_SUCCESSFUL`, `TEST_FAILED`, `NOT_REACHABLE` Possible `failureDetails`: `COMPENSATION`, `GRID`, `COVER` Manual Test Activation ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "NORMAL" } ``` Possible `value`: `NORMAL`, `TEST` Automatic External Alarm Indicator Test ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "TEST_SUCCESSFUL" } ``` Possible `value`: `TEST_SUCCESSFUL`, `TEST_FAILED`, `TEST_DISABLED`, `NOT_REACHABLE`, `NO_EAI_CONFIGURED` Operating Years ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "14.32" } ``` Value is a number in years. Beam Compensation Value ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "82" } ``` Value is a number in percent. Compensation Value ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "82" } ``` Value is a number in percent. Compensation Level ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "MEDIUM" } ``` Possible `value`: `LOW`, `MEDIUM`, `HIGH` Grid Value ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "10" } ``` Value is a number. Grid Level ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": "MINOR" } ``` Possible `value`: `NO`, `MINOR`, `MAJOR`, `FAULT` Sensitivity ```json { "id": "1fd1dd0c-c696-41cd-9898-1386f5cde725", "createdAt": "2021-03-08T13:51:40.541Z", "value": 12 } ``` Value is a number. > **Note:**\ > The response of the lastValue API can be any of these types, and each response will always include at least `value`, `createdAt`, and `id` fields. Refer to the API documentation for the full list of supported point types and value formats. **Example:** ```bash curl -G -H "Authorization: Bearer $TOKEN" \ --data-urlencode "pointIds=," \ --data-urlencode "lastChangedLatest=2024-06-01T12:00:00Z" \ "https://eu.buildingx.siemens.com/api/openness/fire/partitions/$PARTITION/points/lastValues" ``` - Replace ``, ``, etc., with the desired point IDs (up to 50 per request). - Set `lastChangedLatest` to the latest timestamp you want to include (optional). - The response will include the latest values for each specified point, up to the given timestamp if provided. > **Note:**\ > For more information on deprecation policies, pagination, filtering, and error handling, see the [Developer's Guide](../../dev-guide/gettingstarted.html). ## Visual Overview ## Configuration API usage ______________________________________________________________________ You are now ready to start building with the Fire API! For advanced usage, troubleshooting, and best practices, consult the [Developer's Guide](../../dev-guide/gettingstarted.html). # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.0.13] - 2026-05-5 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Geometry API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/geometry/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/geometry/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.0.11] - 2024-08-08 #### Added - Aligned the documentation and corrected spelling errors ### [1.0.9] - 2024-04-16 #### Added - First version of Geometry API # Building Geometry API The Building Geometry API enables you to create and interact with 2D geometry of building floorplans. This API is organized around the `Floorplan`, and `Geometry` resources. A floorplan contains geometry in the form of a GeoJSON FeatureCollection. ## Concepts & Glossary | Term | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Floorplan | A Floorplan represents meta data about the 2D geometry of a certain floor. This meta data included the angle (transformation) and centerpoint (origo) of the contained geometries. A floorplan relates to a `Floor` as defined in Structure API. | | Geometry | Is a GeoJSON FeatureCollection where each Feature represents either a `Room`, `RoomSegment`, `FloorArea` or `Equipment`, as defined in Structure API. | # Quick Start Getting started with using Building Geometry API involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export` command. In other environments it may be different, e.g. Windows uses the `set` command instead. 1. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html) section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token` property in the response. You can now use it by passing it in the `Authorization` header of any subsequent API requests. The `expires_in` property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. As an option, you can find your `partitionId` by using the Accounts API. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to perform to retrieve the 2D geometry of a floor. As a prerequisite, it is recommended to lookup a `floorId` either in the Data Setup application or using the Structure API. In the rest of this document we assume that the `floorId` is `20cfac0b-d3ae-415e-af95-861d46e5fdda`. ### Find Floorplan The first step to perform is to list the floorplans in your partition and specifying a filter for your floor. This you can do by performing the `List Floorplans` operation and a filter for the the `representsFloor.data.id` property. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/geometry/partitions/$PARTITION/floorplans?filter[representsFloor.data.id]=20cfac0b-d3ae-415e-af95-861d46e5fdda" ``` The response contains all floorplans for the specified floor (floorId). If you have a large number of buildings you may need to retrieve multiple pages, see [Pagination](../../dev-guide/index.html#pagination). Select the `id` property of one of the floorplans in the response and set it in an environmental variable. E.g. if the `id` is `8db4216d-61c5-4e79-8558-164aa179bfe9` then set it using the following command: ```bash export FLOORPLAN_ID=8db4216d-61c5-4e79-8558-164aa179bfe9 ``` ### Get Geometry The next step is to fetch the geometry available in your floorplan. This is achieved by using the `List Geometry` operation. ```bash curl -H "Authorization: Bearer $TOKEN" \ "https://eu.buildingx.siemens.com/api/openness/geometry/partitions/$PARTITION/floorplans/$FLOORPLAN_ID/geometry" ``` The response contains a GeoJSON-document that can be processed by your application or rendered by multiple commercial and open source components or online tools. # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [2.0.6] - 2025-02-06 ### Added - Server URLs updated ## [2.0.5] - 2024-11-08 ### Added - Added POST method for tasks - Required select header for the GET, PUT and DELETE methods ## [2.0.2] - 2024-07-16 ### Added - Fixed spelling issues ## [2.0.1] - 2024-07-10 ### Added - Fixed typos - Fixed lint issues ## [2.0.0] - 2024-03-22 ### Added - Renamed to `Lifecycle Twin API` - Cleaned up the references from the invalid methods - Restructured the Endpoints ## [1.0.0] - 2023-06-22 ### Added - First version of 'Ecodomus API' # Lifecycle Twin API The Lifecycle Twin API enables you to create and manage various objects in the Lifecycle Twin. The Lifecycle Twin API is organized around: - Portfolio, Companies, Sites, Buildings - User, User Groups, Roles - Assets, Documents, Jobs - Model, View, Import, Export - Issues, Tags, Surveys ## Concepts & Glossary | Term | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Portfolio | A customer subscription to Lifecycle Twin. Brings together customer's configurations, sites and building data. | | Company | A company describes the contact information of the organization. A company basically tied to the user or used as a manufacturer for an equipment. | | Site | A site is a grouping of multiple Buildings and Outside spaces. Typically it is physically represented by a fence, vegetation or street. It could be a contiguous area like a fenced-in airport or a looser aggregation like a government district (consisting of multiple individual buildings). | | Document | A document is generally a file which is directly related to a site, building or other assets. A document includes drawings, operations manuals, instructions, floor plans and others. Documents may contains 3D models as well. | | Building | A building is generally a structure built for a purpose that has a roof and walls and stands more or less permanently in one place. Typical examples are a house, factory, or shop; but if necessary also a cave, tower, tent or even a ship or bridge could be called a building. | | Zone | Zones represent the where aspect of building automation, combining functional and spatial aspects. Examples are comfort zones, fire alarm zones or lighting zones. | | Floor | A floor is a horizontal / level part of a building with a surface that could be used by people (for living, work, storage, recreation, etc), depending on context, they are also called storey/story, level or deck. Multiple floors can be stacked up vertically to form a multi-floor building. | | Room | A room is an indoor space enclosed by walls (and a roof or ceiling) to which entry is possible by a door or similar, which connects it either to a passageway, to another room, or to the outdoors. Normally, rooms are large enough for several persons to enter and move about or conduct the intended activity. | | Room Segment | Often, a floor is implicitly divided into a grid or into segments that later on might turn into rooms by adding walls. Such segments often contain technical preparations for possible rooms (e.g. pillars, grids, window arrangement, piping or wiring) | | Type | Describes common specifications of a component like physical dimension, color, manufacturer, etc. Typically it provides definition of a model. Type doesn't represents a physical instance. | | Component | Physical instance of a device or equipment. It can be any object like Wall, Pipe, Pipe Segment, Door, etc. | | Category | Its a property of a Component and Type which group them by functional purposes. | | System | A System contains a machinery and heavy equipment installed for the operation of a service. A system consists of partial systems, aggregates and components (equipment). | | Sub System | A part of a System. Represents smaller section of it. | | Task | Based on the use case a task represents an issue, work order or task related with a component, room or document or a registration of an event or emergency in a building or construction site. All tasks have a workflow and use responsible to the contribution of it. | | Inspection | An inspection is an order to execution of examination of a component or space. Inspection is characterized by digital form needs to be populated on execution. | | Survey | A functionality that enables the collection of information about a component on a mobile device via the use of digital forms for the purpose of collecting general information to solicit information during construction or operations. Surveys are created on the web desktop application and executed on mobile application. | | Reminder | An escalation of the overdue tasks to generate downloadable PDF reports of statuses and details of each task | # Quick start ## Get the API key Contact with the Lifecycle Twin support to retrieve the CLIENT_ID and CLIENT_SECRET. These to key are required for the authentication via API ## Authenticate Before making any calls to the Lifecycle Twin API need to authenticate and retrieve the `access_token` ### Request ```html POST /api/token HTTP/1.1 Host: eu-ecodomus-services.siemens.com Content-Type: application/x-www-form-urlencoded client_id=your_id&client_secret=your_secret&username=username&password=pwd&grant_type=password ``` ### Response ```json { "access_token": "PELPIm2Mn1-JzbZRqrUxa.............ICGvNGR-Y", "token_type": "bearer", "expires_in": 604799, "refresh_token": "2a66b5d105e141d.....2b80a8b7b35ea5bc91", "user_sid": "8b6c047f-0000-0000-0000-1ceb7331eaf7" } ``` For the further calls you need to use `access_token` See the [Authentication](guide/authentication.html) page for details. ```text curl -X POST \ https://eu-ecodomus-services.siemens.com/api/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&grant_type=password&username=[LOGIN]&password=[PASSWORD]' ``` ## Fetch the data Lifecycle Twin API offers methods to receive a list of objects of a particular type, and methods for receiving a particular object of the specified type using object’s unique ID. The following headers are required within HttpHeader: **Select** – this header contains a list of fields that need to be populated ```json {"Id", "Name", "CustomFields" : {"Id", "Value"}} ``` This request will return an entity or a list of entities which will have fields Id, Name, and a list of custom fields – CustomFields, where each field from CustomFields will have fields Id, Value populated. Note Currently the API does not guarantee populating ONLY those fields which are specified in the header. In some cases, other fields will be also populated. But the fields specified in the header will be populated. **Filter** – contains filter description. This filter will be used to receive a list of objects of a particular type. It is used only in the request for a list of objects. ```json {"Contains" : {"Name" : "100W - 277V"}} ``` A request with this Select header will return objects where Name field contains a value “100W – 277V”. A list of fields available for filtering is defined by the object schema. *Sample* ```json {"equals":{"CustomFields[4be891a7-58c8-4f14-8b5b-e878fe3016f3].Value":3}} ``` A request with this Select header will return objects where field Value contains a value “3” for CustomField with identifier equal to `4be891a7-58c8-4f14-8b5b-e878fe3016f3`. # Example of animation definition ## C# Classes to serialize to JSON ```csharp ``` ### JSON Sample ```json { "Animations": [ { "Conditions": [ { "RDSVar": "D-227A (level m3)", "Type": "Less", "Value1": 22, "Value2": null } ], "LogicalOperation": "OR", "AnimationType": "Color", "Parameters": "{\"Speed\":1.0,\"Color\":\"#00FF00\"}", "IsBlinked": false }, { "Conditions": [ { "RDSVar": "D-227A (level m3)", "Type": "Range", "Value1": 22, "Value2": 24 } ], "LogicalOperation": "OR", "AnimationType": "Color", "Parameters": "{\"Speed\":5.0,\"Color\":\"#FF9900\"}", "IsBlinked": true }, { "Conditions": [ { "RDSVar": "D-227A (level m3)", "Type": "Greater", "Value1": 24, "Value2": null } ], "LogicalOperation": "OR", "AnimationType": "Color", "Parameters": "{\"Speed\":10.0,\"Color\":\"#FF0000\"}", "IsBlinked": true } ], "Models": [ { "Id": "98cccd8e-feaa-4927-ad86-34db0b7357b9", "Ids": [ "c5578d57-a838-43f7-b942-0f0e5ddcde12-000c755e" ] } ] } ``` # Model animations Animations allows to visualize state of equipment in a model by applying the visual effects to a model object. There are following animation types are supported: - **Color**. Colors an object with the given color. Optionally object can blink with the given frequency. - **Outline**. Draw an object outline with the given color, width, intensity and blurring of the outline. Optionally can blink with the given frequency. Outline can be set to be visible through other objects. Also requires more client hardware resources. Not recommended to use too much outlines especially with the complicated geometry objects - **Rotation**. Rotates object clockwise be the vertical axis. ## Get list of animations ### Request **GET** `/models/animations/raw` | Parameter | Description | | ----------------- | ------------------------------------------------------ | | **clientname** | (*mandatory*) Portfolio name | | **Authorization** | (*mandatory*) Authentication token | | **select** | (*optional*) List of fields to include into the result | | **filter** | (*optional*) Filter parameters | | **Sort** | (*optional*) Sorting parameters | ### Response sample ```json [ { "Name": "Test animation", "Definition": "{\"Models\":[{\"Id\":\"f6e60649-aea1-4c3b-a627-0bf83f00b3f8\",\"Ids\":[\"68e3adeb-69f1-4edd-9fea-ebebe475ab3d-001843f8\",\"68e3adeb-69f1-4edd-9fea-ebebe475ab3d-001843f4\",\"68c03d5f-e7b7-47a0-8abb-9f13b8991453-00169e77\"]}],\"Animations\":[{\"Conditions\":[{\"RDSVar\":\"\",\"Type\":\"Equals\",\"Value1\":true}],\"LogicalOperation\":\"AND\",\"AnimationType\":\"Color\",\"Parameters\":\"{\\\"Speed\\\":10.0,\\\"Color\\\":\\\"#1E90FF\\\"}\",\"IsBlinked\":true}]}", "Id": "5abb3958-7b71-46ca-8eba-8b4143e65d21" }, { "Name": "Pump state", "Definition": "{\"Models\":[{\"Id\":\"f6e60649-aea1-4c3b-a627-0bf83f00b3f8\",\"Ids\":[\"68e3adeb-69f1-4edd-9fea-ebebe475ab3d-00184401\"]}],\"Animations\":[{\"Conditions\":[{\"RDSVar\":\"HSS_A0_L1009_0000ITP_PE09_PV\",\"Type\":\"Greater\",\"Value1\":10}],\"LogicalOperation\":\"AND\",\"AnimationType\":\"Color\",\"Parameters\":\"{\\\"Speed\\\":10.0,\\\"Color\\\":\\\"#1E90FF\\\"}\",\"IsBlinked\":true},{\"Conditions\":[{\"RDSVar\":\"HSS_A0_L1009_0000ITP_PE09_PV\",\"Type\":\"Greater\",\"Value1\":50}],\"LogicalOperation\":\"AND\",\"AnimationType\":\"Color\",\"Parameters\":\"{\\\"Speed\\\":20.0,\\\"Color\\\":\\\"#0000FF\\\"}\",\"IsBlinked\":true}]}", "Id": "1bee937f-aec6-4579-8284-b50149bf63aa" } ] ``` ## Create animation **POST** `/models/animations/raw` ### Payload example ```json { "Name": "Pump state", "Definition": "{\"Models\":[{\"Id\":\"f6e60649-aea1-4c3b-a627-0bf83f00b3f8\",\"Ids\":[\"68e3adeb-69f1-4edd-9fea-ebebe475ab3d-00184401\"]}],\"Animations\":[{\"Conditions\":[{\"RDSVar\":\"HSS_A0_L1009_0000ITP_PE09_PV\",\"Type\":\"Greater\",\"Value1\":10}],\"LogicalOperation\":\"AND\",\"AnimationType\":\"Color\",\"Parameters\":\"{\\\"Speed\\\":10.0,\\\"Color\\\":\\\"#1E90FF\\\"}\",\"IsBlinked\":true},{\"Conditions\":[{\"RDSVar\":\"HSS_A0_L1009_0000ITP_PE09_PV\",\"Type\":\"Greater\",\"Value1\":50}],\"LogicalOperation\":\"AND\",\"AnimationType\":\"Color\",\"Parameters\":\"{\\\"Speed\\\":20.0,\\\"Color\\\":\\\"#0000FF\\\"}\",\"IsBlinked\":true}]}" } ``` ## Modify animation **PUT** `/models/animations/raw/{animationId}` ### Payload example ```json { "Name": "Pump state", "Definition": "{\"Models\":[{\"Id\":\"f6e60649-aea1-4c3b-a627-0bf83f00b3f8\",\"Ids\":[\"68e3adeb-69f1-4edd-9fea-ebebe475ab3d-00184401\"]}],\"Animations\":[{\"Conditions\":[{\"RDSVar\":\"HSS_A0_L1009_0000ITP_PE09_PV\",\"Type\":\"Greater\",\"Value1\":10}],\"LogicalOperation\":\"AND\",\"AnimationType\":\"Color\",\"Parameters\":\"{\\\"Speed\\\":10.0,\\\"Color\\\":\\\"#1E90FF\\\"}\",\"IsBlinked\":true},{\"Conditions\":[{\"RDSVar\":\"HSS_A0_L1009_0000ITP_PE09_PV\",\"Type\":\"Greater\",\"Value1\":50}],\"LogicalOperation\":\"AND\",\"AnimationType\":\"Color\",\"Parameters\":\"{\\\"Speed\\\":20.0,\\\"Color\\\":\\\"#0000FF\\\"}\",\"IsBlinked\":true}]}", "Id": "1bee937f-aec6-4579-8284-b50149bf63aa" } ``` # Assemblies ## Get type assemblies **GET** /types/{typeId}/assemblies Returns list of assemblies for the given type **Output example**: ```json [ { "Name": "AC Units", "Items": [], "Id": "277831b4-915d-4c1a-9a71-f061706eb571" } ] ``` ## Create type assembly **POST** /types/{typeId}/assemblies Create assembly for the given type **Body**: ```json { "Name": "AC Units", } ``` ## Get type assembly items **GET** /types/{typeId}/assemblies/{assemblyId}/items *Returns list of items for the given assembly\** **Output example**: ```json [ { "Type": { "Name": "Air Conditioner (Outdoor Unit)", "IsMajor": false, "Specifications": [], "Assets": [], "AssetsCount": 0, "Id": "f9a85305-a7c3-495d-a23e-be60dcabf33c" }, "Id": "5297a696-35e0-46a8-b5a9-60b25d5dc1f0" }, { "Type": { "Name": "Air Conditioner (Indoor Unit)", "IsMajor": false, "Specifications": [], "Assets": [], "AssetsCount": 0, "Id": "6a525842-b1fb-457d-988c-aaeb7c1b0864" }, "Id": "b8f8b69d-db90-4c02-adb8-b6f6c28fe63e" } ] ``` ## Create type assembly item **POST** /types/{typeId}/assemblies/{assemblyId}/items Creates an assembly item of the given assembly **Body**: ```json { "Type": { "Id": "f9a85305-a7c3-495d-a23e-be60dcabf33c" }, "AssemblyType": { "Id": "18A57A89-F5C4-488C-82CF-8BB0BDEBAD3E" } } ``` ## Get asset assemblies **GET** /assets/{assetId}/assemblies Returns list of assemblies for the given asset **Output example**: ```json [ { "Name": "AC Units", "Items": [], "Id": "277831b4-915d-4c1a-9a71-f061706eb571" } ] ``` ## Get asset assembly items **GET** /assets/{assetId}/assemblies/{assemblyId}/items *Returns list of items for the given assembly\** **Output example**: ```json [ { "Type": { "Name": "Air Conditioner (Outdoor Unit)", "IsMajor": false, "Specifications": [], "Assets": [], "AssetsCount": 0, "Id": "f9a85305-a7c3-495d-a23e-be60dcabf33c" }, "Asset": { "Name": "AC-OU-1", "LocationsCount": 0, "Id": "657915b9-f680-4363-9442-d0cea4a2551c" }, "Id": "5297a696-35e0-46a8-b5a9-60b25d5dc1f0" }, { "Type": { "Name": "Air Conditioner (Indoor Unit)", "IsMajor": false, "Specifications": [], "Assets": [], "AssetsCount": 0, "Id": "6a525842-b1fb-457d-988c-aaeb7c1b0864" }, "Id": "b8f8b69d-db90-4c02-adb8-b6f6c28fe63e" } ] ``` ## Link assets to the assembly **PUT** /assets/{assetId}/assemblies/{assemblyId}/items/{assemblyItemId} Creates the linkup of asset to a given assembly item. The asset must be relevant to the assembly item type **SELECT** {"Asset"} **Body**: ```json { "Asset": { "Id": "657915b9-f680-4363-9442-d0cea4a2551c" } } ``` # Manage tab fields ## Fetch tab fields The method returns the fields, associated with the given tab **GET** /{entityName}/tabs/{tabId} **Output example**: ```json [ { "Order": 0, "Field": { "Name": "Employee Code", "IsSystem": false, "IsReadonly": false, "MaxLength": 0, "AllowMultipleValues": false, "Id": "00000000-0000-0000-0000-000000000000" }, "IsRequired": false, "IsHidden": false, "Id": "b447f15d-2998-48d1-8302-b24b0b6acd22", "EntityType": 0 }, { "Order": 1, "Field": { "Name": "Employee Name", "IsSystem": false, "IsReadonly": false, "MaxLength": 0, "AllowMultipleValues": false, "Id": "00000000-0000-0000-0000-000000000000" }, "IsRequired": false, "IsHidden": false, "Id": "02135de9-bbb9-40e0-b078-d2c4ec6bc0d7", "EntityType": 0 }, { "Order": 2, "Field": { "Name": "Trade", "IsSystem": false, "IsReadonly": false, "MaxLength": 0, "AllowMultipleValues": false, "Id": "00000000-0000-0000-0000-000000000000" }, "IsRequired": false, "IsHidden": false, "Id": "58530794-b70f-45a1-8064-97b2cda482cf", "EntityType": 0 } ] ``` ## Assign a field to a tab The method links a field to a given custom tab **POST** /{entityName}/tabs/{tabid}/fields **Body**: ```json { "Order": 2, "Field": { "Id": "8b773b85-a6cd-4dc8-bdb5-941983f27599" } } ``` Order property defines the order of the field in a tab. **Return value** Id of the created linkup ```json { "Value": "aeebf9fa-6926-4530-b064-687fc83c5c00" } ``` ## Unassign field from a tab Unlink the field from a custom tab **DELETE** /{entityName}/tabs/{tabId}/fields/{linkupId} # Manage tab value ## Get values of custom tab Returns the values of given entity for a custom tab **GET** /{entityName}/{entityId}/tabs/{tabId}/values **Output example**: ```json [ { "Id": "1a97acd9-27af-4ba6-b4f3-431f6c39a44d", "Fields": [ { "Id": "8b773b85-a6cd-4dc8-bdb5-941983f27599", "Name": "Trade" }, { "Id": "d37272b1-7546-499b-a47d-e1e3c4ce03c4", "Name": "Hours worked" }, { "Id": "14c06acc-5379-45e1-a0ea-5d4bdbbc81cc", "Name": "Employee Code" }, { "Id": "f1c4124f-0795-40b7-9048-6112a86dfbe8", "Name": "Employee Name" } ], "Values": [ { "Record": [ "MAINT", 7.0, "ECO-STT", "Stan Tang" ] }, { "Record": [ "MAINT", 2.0, "ECO-LHT", "Lenny Hong" ] }, { "Record": [ "MAINT", 5.0, "ECO-SCC", "Suise Chaing" ] } ] } ] ``` ## Set the values for a custom tab The method sets the values for a given tab. The method replace the entire set of data for a tab. To clean the value need to call the method with the empty values **POST** /{entityName}/{entityId}/tabs/{tabId}/values **Body**: ```json { "Id": "1a97acd9-27af-4ba6-b4f3-431f6c39a44d", "Fields": [ { "Id": "14c06acc-5379-45e1-a0ea-5d4bdbbc81cc" }, { "Id": "f1c4124f-0795-40b7-9048-6112a86dfbe8" }, { "Id": "8b773b85-a6cd-4dc8-bdb5-941983f27599" }, { "Id": "d37272b1-7546-499b-a47d-e1e3c4ce03c4" } ], "Values": [ { "Record": [ "ECO-STT", "Stan Tang", "MAINT", 7 ] }, { "Record": [ "ECO-LHT", "Lenny Hong", "MAINT", 2 ] }, { "Record": [ "ECO-SCC", "Suise Chaing", "MAINT", 5 ] } ] } ``` **Example**: # Manage tabs ## Get custom tabs for an entity Returns list of assemblies for the given type **GET** /{entityName}/tabs **Output example**: ```json [ { "Name": "Book Labor", "Order": 0, "EntityType": "issue", "Id": "1a97acd9-27af-4ba6-b4f3-431f6c39a44d" } ] ``` ## Create a new custom tab for an entity Create new custom tab for the given entity type **POST** /{entityName}/tabs **Body**: ```json { "Name" : "Permits", "Order" : 1 } ``` Order property defines the order of the tabs in the UI. **Return value** Id of the created tab ```json { "Value": "b3bf0c6f-1fcc-4e4b-9eae-48798e94d258" } ``` ## Update existing custom tab Update name or order of the existing custom tab **PUT** /{entityName}/tabs/{tabId} **Select**: `{"Name", "Order"}` **Body**: ```json { "Order" : 1, "Name" : "Permits*" } ``` ## Delete custom tab Delete existing custom tab by given id **DELETE** /{entityName}/tabs/{tabId} # Custom fields ## Get list of custom fields ### Request **GET** `/customfields` | Parameter | Description | | ----------------- | ------------------------------------------------------ | | **clientname** | (*mandatory*) Portfolio name | | **authorization** | (*mandatory*) Authentication token | | **select** | (*optional*) List of fields to include into the result | | **filter** | (*optional*) Filter parameters | | **sort** | (*optional*) Sorting parameters | ### Response sample ```json [ { "Name": "Address", "FieldType": { "Name": "Text", "DataType": 3, "Description": "The attribute data should be interpreted as a string of text.", "IsSystem": true, "Id": "110cc2e6-5cae-4e6c-a435-19fe184acee0" }, "IsSystem": false, "IsReadonly": false, "MaxLength": 0, "Id": "ba37e9b8-f7c4-4a21-a0c7-2154260ee732" } ] ``` ## Get list of custom field types ### Request **GET** `/customfields/types` | Parameter | Description | | ----------------- | ------------------------------------------------------ | | **clientname** | (*mandatory*) Workspace name | | **Authorization** | (*mandatory*) Authentication token | | **select** | (*optional*) List of fields to include into the result | | **filter** | (*optional*) Filter parameters | | **Sort** | (*optional*) Sorting parameters | ### Available fields ```json {"Id", "Name", "DataType", "Description", "Values": {"Id", "Name"}} ``` ### Response sample ```json [ { "Name": "Dropdown", "DataType": 3, "Values": [ { "Name": "Value 1", "Id": "141393a5-7fb3-4559-858f-ca1c2d231c7a" }, { "Name": "Value 2", "Id": "0aa6bffe-28d7-4418-8631-2152424bebfd" } ], "IsSystem": false, "Id": "4e004b9b-c474-4926-904b-d1dcc41a048c" } ] ``` ## Get list of custom field type values ### Request **GET** `/customfields/types/{fieldTypeId:guid}/values` ## Get object structure group **GET** `/{entityType}/groups` ## Get fields in the object structure group **GET** `/{entityType}/groups/{groupId}/fields` ## Get object structure group (for a category) **GET** `/categories/{categoryId}/{entityType}/groups` ## Get fields in the object structure group (for a category) **GET** `/categories/{categoryId}/{entityType}/groups/{groupId}/fields` # Create document **Endpoint** - `/documents/upload` HTTP Method – **POST** ## Request ### Headers | Parameter | Description | | ----------------- | ---------------------------------- | | **clientname** | (*mandatory*) Portfolio name | | **authorization** | (*mandatory*) Authentication token | | **projectId** | (*mandatory*) Project identifier | ### Body Type – form-data ### Keys Name: A, Type: Text, Value:JSON ,described the document object. The sample of the JSON can be retrieved using the Get/Find Documents method Name:B, Type: File, Value – document file ### Example of the Document JSON ```json { "Name": "2012-03-23-Duplex-Programming.xlsx", "Parent": { "Id": "723d3996-6b6d-4429-93bc-0d9bb4472e31" }, "Files": [ { "Size": 158064, "Name": "2012-03-23-Duplex-Programming.xlsx", "ContentType": "application/octet-stream" } ] } ``` Note - Id is a mandatory field where ID is the ID of a folder. Without Parent Id you will be able create a new document, but you will not find in the in use interface. - Files is an array, but you always must specify only one file - Need to pass the file size in bytes explicitly (will be solved in the future) ## Response HTTP status code 200 ### Body In the Response result there is Id of the created document Media type: application/json **Example**: ```json { "Value": "841054dd-ce63-4e93-b176-0753ff2ec1eb" } ``` # Create folder **Endpoint** - `/documents` HTTP Method – **POST** ## Request ### Headers | Parameter | Description | | ----------------- | ---------------------------------- | | **clientname** | (*mandatory*) Portfolio name | | **authorization** | (*mandatory*) Authentication token | | **projectId** | (*mandatory*) Project identifier | ### Body JSON of the folder definition **Media type** : application/json **Example:** ```json { "Name": "DWG Drawings", "Parent": { "Id": "723d3996-6b6d-4429-93bc-0d9bb4472e31" }, "IsFolder": **true** } ``` Note - Id is a mandatory field where ID is the ID of a folder. Without Parent Id you will be able create a new folder, but you will not find in the in use interface. - IsFolder: true is mandatory to create a folder ## Response HTTP status code 200 ### Body In the Response result there is Id of the created folder Media type: application/json **Example**: ```json { "Value": "9c2e4b64-ab91-470b-92ff-62d78263478e" } ``` # Document new version Lifecycle Twin API doesn't have a logic to create a new version automatically for the file with the same name. API provides the method to check if the new version must be created or not. Normally the process to create a new version requires 2 steps: - Check if the document with the same file name already exist - Upload the new file to the existing document ## Check if document exist Use the standard GET query with the relevant filter **GET** /{entityName}/tabs | Header | Value | | ---------- | ------------------------------------------------------------ | | **filter** | {"equals":{"Files.Name":"Screenshot 2022-12-20 180429.png"}} | **Output example**: ```json [ { "Name": "Screenshot 2022-12-20 180429.png1", "Files": [ { "Name": "Screenshot 2022-12-20 180429.png", "Size": 0, "SourceType": 0, "CreatedOn": "0001-01-01T00:00:00Z", "Version": 0, "TotalFileParts": 0, "FilePart": 0, "Id": "9eae91b1-0c89-8777-5d70-dcc238af074e" } ], "Version": 0, "Parent": { "Name": "RME_basic_sample_project", "Version": 0, "IsFolder": false, "SubFoldersCount": 0, "ChildrenCount": 0, "IsAutoName": false, "CheckedOut": false, "Id": "2320efac-0214-49ad-ae5d-a1a99eb5b6c6" }, "Id": "9c5dc8bd-57c9-4196-adc6-9ec2369df975" } ] ``` ## Upload new version **PUT** /documents/{documentId}/upload | Header | Value | | ------ | ------------------------------------------- | | select | {"Files": {"Id", "ContentType"}, "Version"} | **Body** - Multipart **First part**: ```json { "Id": "{documentId}", "Files": [ { "Name": "Screenshot 2022-12-20 180429.png", "ContentType": "image/png", "FilePart": 1 } ] } ``` Second part - file stream Note - Files.Name must be exactly the same as the name of the file in the document. Otherwise the new version will not be created - ContentType is mandatory and defined by the host application - FilePart is mandatory and equals 1 # Download document **Endpoint** - `/entities/{documentId}/files/{fileId}` HTTP Method – **GET** ## Request ### Headers | Parameter | Description | | ----------------- | ---------------------------------- | | **clientname** | (*mandatory*) Portfolio name | | **authorization** | (*mandatory*) Authentication token | | **projectId** | (*mandatory*) Project identifier | ## Response Response body will have the content of the downloaded file Note \*\*\*GET /documents\*\* endpoint can be used to get the documentId. Using *select* header, user can include *Files* to get the file details # Find document ## Get/Find Documents **Endpoint** - `/documents` HTTP Method **GET** The method returns list of documents or folders by specified criteria. ### Request #### Headers | Parameter | Description | | ----------------- | -------------------------------------------------------- | | **clientname** | (*mandatory*) Portfolio name | | **authorization** | (*mandatory*) Authentication token | | **projectId** | (*mandatory*) Project identifier | | **select** | (*optional*) List of fields to include into the result | | **filter** | (*optional*) Filter parameters | | **sort** | (*optional*) Sorting parameters | | **pagination** | (*optional*) Returns only the part of the requested data | #### Use cases Most uses cases to get documents and/or folder are solved by the proper filter 1. Get the root folder. All folders and files must be unloaded into the root folder. Need to get root folder id then pass this Id as a parent Id. ```json {"bool":{"must":[{"equals":{"IsFolder":true}}, {"is\empty": "Parent"}]}} ``` 1. Get subfolders of the folder ```json {"bool":{"must":[{"equals":{"IsFolder":true}}, {"equals": {"Parent.Id": "723d3996-6b6d-4429-93bc-0d9bb4472e31"}}]}} ``` 1. Find a document by name (in the entire project) ```json {"bool":{"must":[{"equals":{"IsFolder":false}}, {"equals": {"Name": "230500-AHU C1 Performance Data.pdf"}}]}} ``` 1. Find a document by name (in the specific folder) ```json {"bool":{"must":[{"equals":{"IsFolder":false}}, {"equals": {"Parent.Id": "723d3996-6b6d-4429-93bc-0d9bb4472e31"}}, {"equals": {"Name": "230500-AHU C1 Performance Data.pdf"}}]}} ``` 1. Find the documents with filtering by custom filed ```json {"bool":{"must":[{"equals":{"CustomFields[f6194a0f-4d4b-451d-9eb0-62d24f58b72c].Value":"A1"}},{"equals":{"Name":"03-Maintenance Guide A"}}]}} ``` 1. Find the documents updated after a certain time ```json {"bool":{"must":[{"equals":{"IsFolder":false}}, {"greater\than\or\equals": {"ModifiedOn": "2021-03-26T13:19:29.683Z"}}]}} ``` # Modify document ## Modify document metadata **Endpoint** - `/documents/` HTTP Method – **PUT** ### Request #### Headers | Parameter | Description | | ----------------- | ------------------------------------------------------ | | **clientname** | (*mandatory*) Portfolio name | | **authorization** | (*mandatory*) Authentication token | | **projectId** | (*mandatory*) Project identifier | | **select** | (*optional*) List of fields to include into the result | #### Body JSON of the document metadata **Media type** : application/json **Example**: ```json { "Id": "841054dd-ce63-4e93-b176-0753ff2ec1eb", "Name": "2012-03-23-Duplex-Programming.xlsx", "Category": { "Id": "734e44c5-fcf8-e011-b8c2-00101832264b" } } ``` Note - The ID in the JSON and ID in the endpoint must be the same - The **Select** header is used to specify what properties must be updated. This approach allows you to specify only the fields you want to update without passing other properties. In case if one or another property is not updated, please check it is included to the select - You cannot specify that custom field must be updated. In case if you update one custom field, need to specify "CustomFields" in the header and pass all custom field values in JSON. #### Response HTTP status code 204 # Data points Formerly RDS Variables ## Fetch Data points The method returns the list of data points for a given portfolio **GET** /variables ### Output example ```json [ { "Name": "CHS_M1_L3003_CVS0011_000_0000_AM_2.1", "Type": 0, "Comment": "Module 1.T1.AHU1.1. Alarm 2", "Rds": { "Name": "Simulation", "Host": "http://aeuc1c015009a.ad003.siemens.net/simulated-rds/", "Value": 0, "Port": 0, "Enable": true, "Id": "6297c24b-76c6-44dc-825d-92d9d6b2e68f" }, "StringValue": "False", "Id": "ef811a85-da4b-400f-bcaa-9e4351423855" }, { "Name": "CHS_M1_L3003_CVS0011_000_0000_AM_2.10", "Type": 0, "Comment": "Module 1.Т1.AHU1.1. Alarm 2", "Rds": { "Name": "Simulation", "Host": "http://aeuc1c015009a.ad003.siemens.net/simulated-rds/", "Value": 0, "Port": 0, "Enable": true, "Id": "6297c24b-76c6-44dc-825d-92d9d6b2e68f" }, "StringValue": "True", "Id": "d8ea9c4c-bc00-4e4b-a3f1-3369d74fd483" } ] ``` For the CRUD operations use the relevant POST, GET, PATCH and DELETE methods. # RDS ## Fetch RDS The method returns the list of remote data services for a given portfolio **GET** /rds ### Output example ```json [ { "Name": "Simulation", "Host": "http://aeuc1c015009a.ad003.siemens.net/simulated-rds/", "Value": 0, "Port": 0, "Enable": true, "Id": "6297c24b-76c6-44dc-825d-92d9d6b2e68f" } ] ``` ## Fetch devices The method returns the list of devices for the given RDS **GET** /rds/{rdsId}/remotedevices ### Output example ```json [ { "Id": "268bd558-360b-46b5-9d27-c125e8f20103", "Name": "A0_4ShUO1_502", "Options": { "IP": "10.98.208.28", "Port": 502, "Unit": 0, "HighByteFirst": false, "HighRegisterFirst": false, "UseGroupRead": false, "UseServerCache": false, "DevicePort": 0, "Net": 0, "Timeout": 0, "Retries": 0 }, "Protocol": 11 }, { "Id": "aaaa0461-c3cd-4557-b942-fe30c2854220", "Name": "A0_4ShUO1_502****", "Options": { "IP": "10.98.208.41", "Port": 502, "Unit": 0, "HighByteFirst": false, "HighRegisterFirst": false, "UseGroupRead": false, "UseServerCache": false, "DevicePort": 0, "Net": 0, "Timeout": 0, "Retries": 0 }, "Protocol": 11 } ] ``` ### List of protocols for device ```csharp public enum Protocol { OPCDA = 1, MODBUSRTU = 2, MODBUSTCP = 3, BACNETIP = 4, BACNETTCP = 5, BACNETMSTP = 6, LOCALDB = 7, SMARTCONNECTOR = 8, PI_WEB = 9, MQTT = 10, MODBUSTCP2 = 11, /// /// SmartConnector (Single Tag Value Request) REST protocol /// SMARTCONNECTOR_SR = 12, } ``` ## Fetch tags The method returns the list of devices linked with the given device. Note The method **doesn't** return the list of all available tags on this device **GET** /rds/{rdsId}/remotedevices/{deviceId} ### Output example ```json [ { "Id": "2fea9f56-7498-4d61-b0be-195e91528894", "Name": "DGP_A0_4ShUO001_00_p788", "IODeviceId": "268bd558-360b-46b5-9d27-c125e8f20103", "Address": "1/3/12788", "Type": 13, "ObjectType": 0, "EndZeroScale": 0.0, "EndFullScale": 0.0, "RawZeroScale": 0.0, "RawFullScale": 0.0, "IsFolder": false }, { "Id": "e2d88815-a7db-4204-96b4-e70d6802bc34", "Name": "DGP_A0_4ShUO001_00_p789", "IODeviceId": "268bd558-360b-46b5-9d27-c125e8f20103", "Address": "1/3/12789", "Type": 13, "ObjectType": 0, "EndZeroScale": 0.0, "EndFullScale": 0.0, "RawZeroScale": 0.0, "RawFullScale": 0.0, "IsFolder": false } ] ``` ### List of types for tag ```csharp public enum RemoteTagType { /// /// Boolean type: TRUE to FALSE /// BOOL = 1, /// /// Byte type: 0 to 255 /// BYTE, /// /// Byte type: -128 to 127 /// SBYTE, /// /// Unicode 16 bit character: U+0000 to U+FFFF /// CHAR, /// /// Decimal, 28-29 significant digits: (-7.9 x 10^28 to 7.9 x 10^28) / 10^(0 to 28) /// DECIMAL, /// /// Double, 15-16 digits: +-5.0*10^-324 to +-1.7*10^308 /// DOUBLE, /// /// Float, 7 digits: -3.4*10^38 to +3.4*10^38 /// FLOAT, /// /// Signed integer, 32 bit value: -2 127 483 648 to 2 147 483 647 /// INT, /// /// Unsigned integer, 32 bit value: 0 to 4 294 967 295 /// UINT, /// /// Signed 64 bit integer: - 9 223 372 036 854 775 808 to 9 223 372 036 854 775 807 /// LONG, /// /// Unsigned 64 bit integer: 0 to 18 446 774 073 709 551 615 /// ULONG, /// /// General type for all others /// OBJECT, /// /// Signed 16 bit integer: -32768 to 32767 /// SHORT, /// /// Unsigned 16 bit integer: 0 to 65535 /// USHORT, /// /// Zero or more Unicode characters /// STRING } ``` For the CRUD operations use the relevant POST, GET, PATCH and DELETE methods. # Assets The section describes the main methods to manage Assets ## Types **Endpoint** - `/types` The endpoint is used to manage Types. Specification and schema can be found in the [API Reference](../api-reference.html) ### Additional endpoints **Endpoint** - `/types/{typeId}/assemblies` Manages assemblies of a given type. More details you can find in the [Assemblies](../examples/assemblies/assemblies.html) page ## Components **Endpoint** - `/assets` The endpoint is used to manage Component. Specification and schema can be found in the [API Reference](../api-reference.html) ### Additional endpoints **/assets/{assetId}/systems** - To manage systems of a component with the given ID. **/assets/{assetId}/assemblies** - To manage assemblies of a given component. More details you can find in the [Assemblies](../examples/assemblies/assemblies.html) page ## Rooms **Endpoint** - `/location` The endpoint is used to manage Rooms & segments. ## Systems **Endpoint** - `/systems` The endpoint is used to manage systems. ## Zones **Endpoint** - `/zone` The endpoint is used to manage Zones. ### Additional endpoints **/zones/{zoneId}/locations** - To manage spaces of a zone with a given ID Specification and schema can be found in the [API Reference](../api-reference.html) ## Floors **Endpoint** -- `/floors` The endpoint is used to manage Floors. Specification and schema can be found in the [API Reference](../api-reference.html) ## Building **Endpoint** - `/facilities` The endpoint is used to manage Buildings. Specification and schema can be found in the [API Reference](../api-reference.html) # Authentication Lifecycle Twin API is using Json Web Token (JWT) for authentication. The tokens are created by the server, signed with a secret key and passed over to the client, which is using this token for authentication. Call the `api/token` endpoint to obtain the token The token endpoint is found at: {{ApiUrl}}/token The following parameter must be include to the **Body**: | Parameter | Description | | ----------------- | ---------------------------------------------------------------------- | | **client_id** | (*mandatory*) The client ID provided by Lifecycle Twin Support | | **client_secret** | (*mandatory*) The client secret key provided by Lifecycle Twin Support | | **grant_type** | (*mandatory*) password | | **username** | (*mandatory*) Your Lifecycle Twin username | | **password** | (*mandatory*) Your Lifecycle Twin password | Response sample: ```json { "access_token": "I-Iy4rCh2zTVQlk.....vMKExs-9tjjF4zgvKm9IunuAg", "token_type": "bearer", "expires_in": 604799, "refresh_token": "254120b05398496689d3de9754def62a781be8028d9d40549d4d46e310d4132f", "user_sid": "87fbd0ac-3230-4839-a5a8-3eb9f96acdea" } ``` # Create POST is used to send data to the server to create/update a resource. The data sent to the server with POST is stored in the request body of the HTTP request. **POST** `/clientprojects` ```bash POST /api/clientprojects HTTP/1.1 clientname: authorization: ``` ***Request Body*** ```json { "Name": "My Project", "Latitude": 57, "Longitude": 13, "OwnerOrganization": { "Id": "bb601d80-0c8d-4a4d-bece-230ad4b12d9c" }, "LeadOrganization": { "Id": "bb601d80-0c8d-4a4d-bece-230ad4b12d9c" }, "Location": { "Id": "af9d605a-fae6-4ed4-b123-d37dea32f0c3" } } ``` ***Response*** The response will have Status Code 200 (OK) if the resource successfully created. Response body will have {Id} of the created resource. # Delete The DELETE method deletes the specified resource. The {id} of the resource to be deleted needs to specified as a query parameter **DELETE** `/clientprojects/{id}` ```bash PUT /api/clientprojects HTTP/1.1 clientname: authorization: select: {"Name", "Latitude", "Longitude"} ``` ***Response*** The response will have Status Code 204 (No Content) if the request accepted. # Querying data The GET method is used to query information from Lifecycle Twin. GET method without {id} parameter returns all the resources of the requested type. In the example below, the GET API returns all the Sites (Projects) from the requested Portfolio (Client). Note The **clientname** and **authorization** HTTP headers are mandatory for all the API requests. Refer [Quick Start](../quickstart.html) to generate **authorization** token. **GET** `/clientprojects` ```bash GET /api/clientprojects HTTP/1.1 clientname: authorization: select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}} ``` In addition to the mentioned headers, **projectid** HTTP header is also mandatory while interacting with Site specific resources. **GET** `/documents` ```bash GET /api/clientprojects HTTP/1.1 clientname: authorization: projectid: select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}} ``` ## Examples ### Query all sites **GET** `/clientprojects` ```bash GET /api/clientprojects HTTP/1.1 clientname: authorization: select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}} ``` GET method with {id} parameter returns a specific resource which matches the {id} value. ### Get information of a specific site by id **GET** `/clientprojects/2f4978fe-ab1c-4d66-be94-2086d0887a86` #### Request ```bash GET /api/clientprojects HTTP/1.1 clientname: authorization: select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}} ``` #### Response ```json [ { "Name": "Building1", "IsEnabled": false, "CreatedOn": "2022-10-18T14:32:17.023Z", "Location": { "Name": "Zug", "ChildrenCount": 0, "Id": "4dc758d7-ab1c-4f4b-bd42-fd95c3cd8236" }, "Id": "2f4978fe-ab1c-4d66-be94-2086d0887a86", "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00" } ] ``` While querying the data, user can specify field selection, filtering, sorting and pagination using HTTP Headers ## Selecting User can specify the list of fields/ properties they would like to include in the response using *select* HTTP header to improve the performance and reduce the number of data to be transferred. Some of the fields are returned in the result, regardless if they specified in the *select* header or not. The good practice is do not include the fields you don't need for the certain scenario. Especially the referenced fields and collections. On the backend side it generates *JOIN* query, and in some cases may significantly impact to the performance. The *select* header supports fields of the nesting properties as well. The syntax of the select header is close to the JSON. ```json {"Field1", "Field2", "Field3": {"Field1OfField3", "Field2OfField3"}} ``` Use *select* header in all GET queries The list of available fields for an entity can be found in the [API Reference](../api-reference.html) In case of specifying an incorrect field, the exception will be thrown. ### Example of the request **GET** `/clientprojects` ```bash GET /api/clientprojects HTTP/1.1 clientname: authorization: select: {"Name", "Id", "CreatedOn", "CityName", "ModifiedOnLocal","OwnerOrganization", "Latitude", "Longitude", "Location": {"Id", "Name"}} ``` ### Response ```json [ { "Name": "Building1", "IsEnabled": false, "CreatedOn": "2022-10-18T14:32:17.023Z", "Location": { "Name": "Zug", "ChildrenCount": 0, "Id": "4dc758d7-ab1c-4f4b-bd42-fd95c3cd8236" }, "Id": "2f4978fe-ab1c-4d66-be94-2086d0887a86", "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00" }, { "Name": "Building2", "IsEnabled": false, "CreatedOn": "2022-10-18T14:32:17.023Z", "Location": { "Name": "Zurich", "ChildrenCount": 0, "Id": "4dc758d7-xy1c-4f4b-bd42-fd95c3cd8236" }, "Id": "2f4978fe-xy1c-4d66-be94-2086d0887a86", "CreatedOnLocal": "2022-10-18T14:32:17.023+00:00" } ] ``` ## Filtering User can specify the filter condition to filter the objects using **filter** HTTP header. It is the powerful mechanism allow user to restrict the query results and find the required information. Filters are used not only for to search the objects, but also to fetch the related entities. For example, to get the list of components which belong to a room, the [/assets](assets.html) endpoint must be used with the filter by room (location) The following filter clauses are supported: | Clause | Description | | -------------------------- | ----------- | | **contains** | | | **any** | | | **ends_with** | | | **equals** | | | **greater_than** | | | **greater_than_or_equals** | | | **is_empty** | | | **less_than** | | | **less_than_or_equals** | | | **starts_with** | | | **in** | | Note Usage of proper clause may significantly affect to the performance. Use *equals* instead of *contains* may increase the performance up to 10 times. Correct clause based on your use cases. ### Simple filter by one property ```json {"clause":{"member":"value"}} {"equals":{"Name":"ISB-020-000--000_1000319"}} ``` ### Simple filter by one property of the referenced field ```json {"clause":{"Property.Field":"value"}} {"Equals":{"Systems.Id":"b7da56c7-f498-40f7-9104-80ba51cd62ba"}} ``` ### Filter by field of the collection property ```json {"clause":{"CollectionProperty[].Field":"value"}} {"equals":{"ModelObjects[].ObjectId":"41958798-cb80-4c0b-bfaf-63e53192c615-0007b076"}} ``` ### Example of the request **GET** `/clientprojects` ```html GET /api/clientprojects HTTP/1.1 clientname: authorization: filter: {"Contains" : {"Name" : "Building1"}} select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}} ``` ## Sorting User can order your data in the response using **sort** HTTP header. ### Syntax ```json {"Property": "OrderType"} ``` **OrderType** must be *descending* or *ascending* Note It is required to use sorting if you fetch the data by pages. In case if you fetch all the data, it is required to use sorting by the unique field, for example, *Id*. Otherwise the data on the different pages can be duplicated and not all records will be returned. ### Example of the request **GET** `/clientprojects` ```html GET /api/clientprojects HTTP/1.1 clientname: authorization: filter: {"Contains" : {"Name" : "Building1"}} sort: {"Name": "descending"} select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}} ``` ## Pagination User can specify pagination (page number and number of records per page) using the **pagination** HTTP header ### Syntax ```json {"page" : pageNumber, "size" : pageSize} ``` Note It is recommended do not use the large page size especially with the large number of referenced fields in the **select** header as it may impact to the performance. Normally, the page size should not exceed 1000 records ### Example of the request **GET** `/clientprojects` ```html GET /api/clientprojects HTTP/1.1 clientname: authorization: filter: {"Contains" : {"Name" : "Building1"}} sort: {"Name": "ascending"} select: {"Name", "Id", "CreatedOn", "CityName", "Latitude", "Longitude", "Location": {"Id", "Name"}} Pagination: {"page" : 0, "size" : 20} ``` The above request will return the first 20 records as response # Tasks The section describes the main methods to manage Tasks **Endpoint** - `/issues/` The main endpoint to manage Tasks. Refer to the [querying](querying.html), [creating](create.html) and [update](update.html) pages for more details ## Get activities of a tasks **GET** /bcf/issues/{issueId}}/comments ## Post a new comment into the task activity **POST** /bcf/issues/{issueId}/comments/upload The [multipart form-data](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2) is used to send the the payload for the comment. The first part contains the JSON payload of the comment, and the second part - attached image (optional) ### Example ```bash curl --location 'https://us-ecodomus-services.siemens.com/api/bcf/issues/d7ea5b6e-7ae8-4ea4-83a2-c2f78e903e18/comments/upload' \ --header 'clientname: ABC' \ --header 'Authorization: bearer 3Z0Qx...' \ --header 'projectId: d7b3ae7a-b72f-4430-aaaf-063cd3939b37' \ --form 'a="{\"Comment\": \"With Image\"}"' \ --form 'b=@"/D:/Downloads/image.png"' ``` ## Change task status **PUT** /workflows/issues/move/{issueId}/from/{statusFrom}/to/{statusTo} The endpoint change the status of the task with the given ID # Update PUT is used to send data to the server to create/update a resource. The data sent to the server with PUT is stored in the request body of the HTTP request. **PUT** `/clientprojects/{id}` ```bash PUT /api/clientprojects HTTP/1.1 clientname: authorization: select: {"Name", "Latitude", "Longitude"} ``` ***Request Body*** ```json { "Name": "My Project", "Latitude": 57, "Longitude": 13 } ``` ***Response*** The response will have Status Code 204 (No Content) if the request accepted. **Note:** The request body should only contain the fields which needs to be updated. No other properties should be included in the request body. The fields which needs to be updated should also be added in the "select" HTTP custom header. ## Remove/ Empty field value Removing/ emptying value of a fields can be done as below **PUT** `/clientprojects/{id}` ```bash PUT /api/clientprojects HTTP/1.1 clientname: authorization: select: {"Name", "CityName"} ``` ***Request Body*** ```json { "Name": "My Project - New", "CityName": "" } ``` # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.2.0] - 2026-04-28 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Point Ingest API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/ingest/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/ingest/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.1.0] - 2026-04-27 #### Added - New endpoint `POST /points/covs` for multi-point batch value ingestion (up to 50 points per request) - Support for `covAttributes` and `targetValue` fields on point values - Multi-status (207) response for partial failure reporting ### [1.0.8] - 2025-03-17 #### Modify - Modify attribute for permissions ### [1.0.7] - 2024-08-09 #### Fixed - Fix response code ### [1.0.6] - 2024-08-08 #### Added - Aligned the documentation and corrected spelling errors ### [1.0.0] - 2023-11-10 #### Added - First version of 'Point Value Ingest API' # Point Value Ingest API The Point Value Ingest API enables you to set values of Points. The data that is measured by data points is called point values. The API provides two ingestion modes: - **Single-point ingestion:** Push 1 to 100 values for a single point using `POST /points/{pointId}/values`. - **Multi-point batch ingestion:** Push 1 value for up to 50 points in a single request using `POST /points/covs`. ## Concepts & Glossary | Term | Description | | ---------- | ---------------------------------------------------------------- | | PointValue | The data that is measured by data points is called point values. | # Quick Start Getting started with using add Point Value Ingest API involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: ```text 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export` command. In other environments it may be different, e.g. Windows uses the `set` command instead. 2. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ``` ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html) section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token` property in the response.You can now use it by passing it in the `Authorization` header of any subsequent API requests.The `expires_in` property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to perform to add point values. ### Add point values To add point values, the `Post values` operation can be used. Push 1 to 100 values for given point in a batch. Only one pointValue per millisecond will be stored. PointValues are dropped if there are timestamp conflicts, i.e. if a pointValue with the same timestamp already exists. Example with following pointValues: - 2022-07-11T11:11:30.333 - 2022-07-11T11:11:30.222 - 2022-07-11T11:11:30.333 - 2022-07-11T11:11:30.444 The first is accepted (it's the first for time "30.333"). The second is also accepted. The third is dropped because it's the same timestamp as the first. The fourth is accepted again. The indices of dropped pointValues are listed in the response (0-based), in this example there is one conflict with index "2". If there is no conflict status 204 is returned instead of 202. Note: Use query parameter 'overwrite=true' to force overwriting of conflicting values. ```bash curl -X 'POST' \ "https://eu.buildingx.siemens.com/api/openness/ingest/partitions/$PARTITION/points/$POINTID/values" \ -H "Accept: application/vnd.api+json" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ -d "{ \"data\": [ { \"type\": \"PointValue\", \"attributes\": { \"timestamp\": \"2000-05-11T10:32:54.964Z\", \"value\": \"12.66\" } } ] }" ``` In the response, you will find the values added for the pointId. ### Add point values for multiple points To add point values for multiple points at once, use the `POST /points/covs` endpoint. Push 1 time-series value for 1 to 50 points in a batch. Existing values are always overwritten. ```bash curl -X 'POST' \ "https://eu.buildingx.siemens.com/api/openness/ingest/partitions/$PARTITION/points/covs" \ -H "Accept: application/vnd.api+json" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ -d "{ \"data\": [ { \"type\": \"Point\", \"id\": \"$POINTID_1\", \"attributes\": { \"values\": { \"type\": \"PointValue\", \"attributes\": { \"timestamp\": \"2000-05-11T10:32:54.964Z\", \"value\": \"12.66\" } } } }, { \"type\": \"Point\", \"id\": \"$POINTID_2\", \"attributes\": { \"values\": { \"type\": \"PointValue\", \"attributes\": { \"timestamp\": \"2000-05-11T10:32:54.964Z\", \"value\": \"22.50\" } } } } ] }" ``` A successful request returns status 204 (No Content). If some points fail while others succeed, a 207 (Multi-Status) response is returned with details about unprocessed entries and errors. Note For more details on deprecation policies and common API features such as paging, filtering and errors, refer to the [Developer's Guide](../../dev-guide/gettingstarted.html). ## Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.4.0] - 2026-05-6 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Security PIAM API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/sec-piam-v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/sec-piam-v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.3.3] - 2025-03-18 ### Bug Fixes - add missing error codes ([d084f46](https://code.siemens.com/horizon/api-manager/security-api/security-api-piam-specification/commit/d084f4670fdae3b80376669f3b0b14c5a4cc1ec7)) ### [1.3.2] - 2024-12-23 #### Revision - Updated changelog.md ### [1.3.1] - 2024-11-14 #### Revision - Aligned the changelog ### [1.3.0] - 2024-09-25 #### Features - I add properties to identity api ([24ec0a5](https://code.siemens.com/horizon/api-manager/security-api/security-api-piam-specification/commit/24ec0a5aed7e712e65876358c3d3a60f57ddca6d)) ### [1.2.0] - 2024-09-04 #### Added - Include `externalId` attribute in privileges retrieval ### [1.1.1] - 2024-08-08 #### Added - Aligned the documentation and corrected spelling errors ### [1.0.0] - 2023-10-20 #### Added - Security Physical Identity and Access Management API released - Added API endpoints for - Identities - To perform Create, Update, Delete and Read identity - Privileges - Retrieve list of configure privileges - Assign privileges to an identity # Security Identities and Privileges API The Identities and Privileges API enables you to create and manage Identities and assign configured privileges to an identity. This enables customers to programmatically manage identities, privileges in Security Manager. Customers can use the API to integrate the Security Manager functions & data into their own workflows & applications. ## Concepts & Glossary | Term | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------- | | Identity | Identity is a user in access control system. Customers can manager their users, assign access rights to their premise. | | Privilege | Privilege is a set of access rights to manage user access to the premises with specified period. | # Quick Start Getting started with using Security Identities and Privileges APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. Making use of a Linux/MacOS shell in which environmental variables are set using the `export` command. In other environments it may be different, e.g., Windows uses the `set` command instead. 1. Using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, JavaScript and Java. ## Create an account and a machine user The [Getting Started](../../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../../dev-guide/howto.html) section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token` property in the response. You can now use it by passing it in the `Authorization` header of any subsequent API requests. The `expires_in` property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed, you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to: 1. Consume and create identities 1. Consume privileges ### List Identities To fetch the user based by `PARTITION`. `size` parameter is an optional field and based on this value the response are returned (Note: `size` should not exceed 1000). `cursor` represent the last identity (identity from last page) `id` from which the next set of identities can be fetched along with the size parameter. In case all the identities returned on the current request, on the next request, the `next` will be same as `self` value with empty `data` returned as response. ```bash curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ "https://eu.buildingx.siemens.com/api/openness/sec-piam-v1/partitions/$PARTITION/identities?page[size]=2" ``` The response contains all details of individual identities. ```bash { "links": { "self": "/identities?page[size]=2", "next": "/identities?page[size]=2&page[cursor]=7945" }, "data": [ { "id": 7944, "type": "Identity", "attributes": { "firstName": "Christoper", "lastName": "Adam", "email": "christoper.adam@siemens.com", "credentials": [ { "cardNumber": "12345", "id": "cf8112e0-3350-420b-b817-bc4bc9a58727", "validity": { "validForUnlimitedTime": true, "validFromUtc": "2024-03-13T00:00:00Z", "validToUtc": "0001-01-01T00:00:00Z" }, "active": false } ], "properties": { "departmentId": "R&D", "location": "Germany" } } }, { "id": 7945, "type": "Identity", "attributes": { "firstName": "Lucy", "lastName": "Clare", "email": "lucy.clare@siemens.com", "credentials": [ { "cardNumber": "123", "id": "bf8112e0-3350-420b-b817-bc4bc9a58727", "validity": { "validForUnlimitedTime": true, "validFromUtc": "2024-03-13T00:00:00Z", "validToUtc": "0001-01-01T00:00:00Z" }, "active": false } ] "properties": { "departmentId": "R&D", "location": "Germany" } } } ] } ``` ### Add Identity To add new identity. The request body should contain the `type` and `attributes` fields. Data inside `properties` field are dynamic and should be aligned with Identity Type selected for the customer. ```bash curl -X "POST" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ "https://eu.buildingx.siemens.com/api/openness/sec-piam-v1/partitions/$PARTITION/identities" ``` with request body ```bash { "type": "Identity", "attributes": { "firstName": "James", "lastName": "Smith", "email": "james.smith@siemens.com", "credentials": [{ "cardNumber": "1211", "validity": { "validForUnlimitedTime": true, "validFromUtc": "2024-03-13T00:00:00Z", "validToUtc": "0001-01-01T00:00:00Z" }, "active": false }], "properties": { "departmentId": "R&D", "location": "Germany" } } } ``` The response contains newly created identity. ```bash { "links": { "self": "/identities", }, "data": { "id": 7946, "type": "Identity", "attributes": { "firstName": "James", "lastName": "Smith", "email": "james.smith@siemens.com", "credentials": [{ "cardNumber": "1211", "id": "dc8112e0-3350-420b-b817-bc4bc9a58727", "validity": { "validForUnlimitedTime": true, "validFromUtc": "2024-03-13T00:00:00Z", "validToUtc": "0001-01-01T00:00:00Z" }, "active": false }] } } } ``` ### Update Identity To update an identity. The request body should contain the `type` and `attributes` fields. `attributes` field shall contain only the modified fields to be updated, its not required to include fields which are unchanged. If new credential is added or changes in existing credential, `credentials` field should have the complete data with all credentials details. Credentials field of the Identity will be replaced with the `credentials` field from the update request. `properties` field shall have only the modified property. ***If the identity is configured as Readonly Identity type, except `credentials` all other fields in the update request will be skipped*** sample request body ```bash { "type": "Identity", "attributes": { "lastName": "Tom", "email": "james.tom@siemens.com", "properties": { "departmentId": "Operation" } } } ``` ### List Privileges To fetch the privileges based by `PARTITION`. ```bash curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/vnd.api+json" \ "https://eu.buildingx.siemens.com/api/openness/sec-piam-v1/partitions/$PARTITION/privileges" ``` The response contains all details of individual privileges. ```bash { "links": { "self": "/privileges" }, "data": [ { "id": 11423, "type": "Privilege", "attributes": { "name": "Privilege sample", "description": "Privilege description", "externalId" : "10" } }, { "id": 11424, "type": "Privilege", "attributes": { "name": "Privilege sample", "description": "Privilege description", "externalId" : "11" } } ] } ``` Note For more details on deprecation policies and common API features such as paging, filtering and errors, refer to the [Developer's Guide](../../../dev-guide/gettingstarted.html). # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [0.4.0] - 2026-05-01 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Security Intrusion API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/sec-intrusion/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/sec-intrusion/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [0.3.0] - 2025-09-25 - Add field "LastConfigChangeUtc" to determine when the intrusion system configuration has changed ### [0.2.0] - 2025-07-28 - Add installation number ### [0.1.1] - 2025-05-19 #### Bug Fixes - Add permission to call system and fixed ### [0.0.9] - 2025-05-16 #### Bug Fixes - Use *partitionId* instead of *partition_id* ### [0.0.8] - 2025-05-08 #### Added - First version of Security Intrusion API # Security Intrusion API This REST API allows you to retrieve information about all cloud-enabled Intrusion systems. An Intrusion system consists of one or multiple on-premise control panels connected to various field devices, such as detectors and input/output devices. To enable cloud connectivity, you need to install the Siveillance Intrusion Edge App and configure it to connect to the desired Intrusion control panel. ## Concepts & Glossary | Term | Description | | ------------- | ----------------------------------------------------------------- | | System | An Intrusion System consisting of one or multiple control panels. | | Control Panel | A hardware controller where an Intrusion Firmware is running on. | # Quick Start Sample quickstart for Reference API Getting started with using Reference APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. 1. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ## Create an account and a machine user The [Getting Started](../../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../../dev-guide/howto.html)- section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl {{env.issUrl}} \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"{{env.audience}}\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token`-property in the response. You can now use it by passing it in the `Authorization`-header of any subsequent API requests. The `expires_in`-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [1.2.0] - 2026-05-06 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Security Monitoring API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/sec-monitoring/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/sec-monitoring/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.1.0] - 2026-04-17 #### Feature - Add new endpoint: `/accesses/per-hour` ### [1.0.0] - 2026-03-05 #### Feature - Release of Security Monitoring API # Security Monitoring API Security Monitoring API allows to retrieve data of access events. ## Endpoints - Accesses: - per-day: allows to retrieve the count of accesses of unique identities per day - per-hour: allows to retrieve the count of accesses of unique identities per hour ## Concepts & Glossary | Term | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | Access event | Access granted event that is triggered by person | | Unique identity | Unique individual, identified by used credential. An identity can use different types of credential | # Quick Start Sample quickstart for Monitoring API Getting started with using Monitoring APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: ```text 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. 2. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ``` ## Create an account and a machine user The [Getting Started](../../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../../dev-guide/howto.html)- section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl {{env.issUrl}} \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"{{env.audience}}\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token`-property in the response. You can now use it by passing it in the `Authorization`-header of any subsequent API requests. The `expires_in`-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to perform to retrieve Monitoring API endpoints. # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.1.0] - 2026-05-01 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Self Service API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/sec-workflow/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/sec-workflow/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.0.0] - 2025-03-11 #### Added - v1 of Security Workflow API # Security Workflow API The Security Workflow API enables you to retrieve workflows and start workflow instances, which are the 2 resources of the API. ## Concepts & Glossary | Term | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Workflows | A generic definition of a process consisting of several tasks and actions. | | Workflow Instance | One specific instance of a workflow, tied to concrete actions and people. An instance is created using a workflow as a form of "blueprint". | # Quick Start Sample quickstart for Reference API Getting started with using Reference APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. **Attention** In the following examples we are: ```text 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. 2. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ``` ## Create an account and a machine user The [Getting Started](../../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../../dev-guide/howto.html)- section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl {{env.issUrl}} \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"{{env.audience}}\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token`-property in the response. You can now use it by passing it in the `Authorization`-header of any subsequent API requests. The `expires_in`-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests This guide will take you through the steps you need to perform to call and use the Security Workflow API. ### Workflows Before you can create a workflow instance, you need to get the `Id` of the respective workflow. You can do so, by executing the following request: ```sh curl -H "Authorization: Bearer $TOKEN" "{{buildingxopenness.env.selfServiceApiUrl}}/partitions/$PARTITION/api/v1/workflows?showInSsp=true" ``` #### Example Response ```text [ { "id": "dd52c89a-e5b3-49fe-9f7c-6c72ee5ac0d8", // you will need this in the next step "name": "Your Workflow", "description": "Your Workflow's description", "active": true } ] ``` You might see a translation key as a name and description, depending on the configuration. Please keep in mind you will need to include the query parameter. If you don't, you will likely receive a `403 Forbidden`. ### Workflow Instances Once you have obtained the `Id` of the workflow you want to start, find out which payload the workflow requires, which is dependant on the process' definition. Set them as the environmental variable `PAYLOAD` (as shown in the curl). They have to be a JSON-object, which can contain any content. Then, do the following request: ```sh curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{ "workflowId": "dd52c89a-e5b3-49fe-9f7c-6c72ee5ac0d8", "instanceVariables": $PAYLOAD }' "{{buildingxopenness.env.selfServiceApiUrl}}/partitions/$PARTITION/api/v1/workflow-instances" ``` This will return a `204 No Content` if everything went as expected. Keep in mind that errors in the workflow itself will not be visible at this point. If there's a mistake with the content of the `instanceVariables` you will not be informed by the API. # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.0.4] - 2026-05-01 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Streaming API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/streaming/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/streaming/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.0.2] - 2026-03-03 #### Update - Update description. ### [1.0.0] - 2026-03-01 #### Added - Release of Streaming API # Streaming API Streaming API for real-time data streams for points. ## Concepts & Glossary | Term | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Point Stream | A Point Stream determines the real-time data flow for specific sensor points (e.g., temperature, pressure) from IoT devices to registered webhook endpoints over a defined period. | | Webhook Registration | Webhook Registration is the process where clients register HTTP endpoints to receive real-time notifications for specific point data events. | | Event Publishing | Event Publishing is the separate process where the Point Vertical system publishes sensor data to SQS queues for processing and delivery to registered webhooks. | | Partition | A Partition represents a logical grouping or tenant boundary that isolates streaming subscriptions and events for different customers or organizational units. | | Stream Subscription | A Stream Subscription defines which specific points a webhook endpoint wants to monitor, including filtering criteria and delivery preferences. | | Webhook Secret | A Webhook Secret is a shared key used to authenticate and verify the integrity of webhook deliveries using HMAC signatures for secure communication. | | Dead Letter Queue | A Dead Letter Queue (DLQ) stores failed webhook delivery attempts for manual review and reprocessing when endpoints are temporarily unavailable. | # Quick Start Getting started with using Streaming APIs involves the following steps: 1. Obtain a JSON Web Token (JWT) for your machine user role. 1. Register webhook endpoints for real-time notifications. 1. Test webhook deliveries with sample events. > **Note:** In the following examples we are: > > 1. Making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. > 1. Using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ## Authentication o use the Streaming API, you need a valid JWT token with the required permissions. Please visit [Authentication](../../dev-guide/howto.html) section to construct the Create Token request. ## Using Your Token Once you have obtained your JWT token, set it as an environment variable along with your partition ID and webhook configuration: ```bash export PARTITION= export TOKEN= export WEBHOOK_URL= export WEBHOOK_SECRET= # Optional: for webhook signature verification ``` You can now use the token by passing it in the `Authorization` header of all API requests. ## Make API requests This guide will take you through the steps you need to perform to register webhooks and start receiving real-time notifications. ### Register Point Stream Webhook Before you can receive point data notifications, you need to register a webhook for specific sensor points. You can do so by executing the following request: ```sh curl -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "webhookUrl": "https://test-api.com/test/webhook", "pointIds": [ "88d45219-a0cf-4509-8f3d-84d15e6a9c44" ], "webhookSecret": "webhook-secret-key" }' \ "https://https://eu.buildingx.siemens.com/api/openness/streaming/v1/partitions/$PARTITION/streams?type=point-stream" ``` **Note:** The `webhookSecret` field is optional. If omitted, webhook payloads will not include signature verification. #### Example Response ```json { "id": "12345678-1234-1234-1234-123456789012", "type": "point-stream", "attributes": { "partitionId": "1bcaafc3-d4d3-43e1-ab64-89d8518d5951", "webhookUrl": "https://test-api.com/test/webhook", "pointIds": [ "88d45219-a0cf-4509-8f3d-84d15e6a9c44" ], "status": "active", "createdAt": "2025-11-17T14:30:22Z", "updatedAt": "2025-11-17T14:30:22Z" } } ``` The `id` is your stream identifier that you can use to manage this subscription later. ### List Your Stream Subscriptions To view all your registered webhooks: ```sh # List point stream subscriptions curl -H "Authorization: Bearer $TOKEN" \ "https://https://eu.buildingx.siemens.com/api/openness/streaming/v1/partitions/$PARTITION/streams?type=point-streams" ``` ### Webhook Payload Examples Once registered, your webhook endpoint will receive POST requests whenever point data changes occur. Each webhook delivery contains the updated point information in the following structure: #### Point Data Event When a point value changes, your webhook will receive a payload like this: ```json { "changed": 1, "createdAt": "2025-12-03T06:09:21.915Z", "id": "6360e1ef-18b5-457c-a488-47t4f4b60e29", "lastUpdatedAt": "2025-12-03T06:09:28.077Z", "qualityOfValue": 0, "value": "22" } ``` **Field Descriptions:** - `changed`: Indicates the change status (1 = changed, 0 = no change) - `createdAt`: Timestamp when the point was initially created - `id`: Unique identifier for the point - `lastUpdatedAt`: Timestamp of the most recent update - `qualityOfValue`: Quality indicator for the data (0 = good quality) - `value`: The current value of the point Your webhook endpoint must respond with a `2xx` HTTP status code to acknowledge successful receipt. Failed deliveries will be retried and eventually sent to the Dead Letter Queue if they continue to fail. ### Verify Webhook Signatures (Optional) If you provided a webhook secret during registration, you can verify webhook signatures to ensure authenticity: ```python import hmac import hashlib def verify_webhook_signature(payload, signature, secret): expected_signature = hmac.new( secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected_signature}", signature) ``` ### Manage Stream Subscriptions You can get entities, add/remove entities, or delete your stream subscriptions as needed: ```sh # Get all points in a point stream curl -X GET \ -H "Authorization: Bearer $TOKEN" \ "https://https://eu.buildingx.siemens.com/api/openness/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID/entities?type=point-streams" # Add or update points in a point stream curl -X PUT \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "pointIds": [ "88d45219-a0cf-4509-8f3d-84d15e6a9c49" ] }' \ "https://https://eu.buildingx.siemens.com/api/openness/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID/entities?type=point-streams" # Remove specific points from a point stream curl -X DELETE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "pointIds": [ "88d45219-a0cf-4509-8f3d-84d15e6a9c49" ] }' \ "https://https://eu.buildingx.siemens.com/api/openness/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID/entities?type=point-stream" # Delete entire point stream subscription curl -X DELETE \ -H "Authorization: Bearer $TOKEN" \ "https://https://eu.buildingx.siemens.com/api/openness/streaming/v1/partitions/$PARTITION/streams/$STREAM_ID?type=point-stream" ``` The GET operation returns a list of entities. The entity DELETE operation returns the updated stream. The stream DELETE operations return a `204 No Content` response if successful. # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.1.1] - 2026-06-23 #### Added - Added `licensedAgainstPartitionId` header. When provided, quota is drawn from the subscription tied to this partition instead of any active subscription for the customer. The partition must belong to the same customer. Useful when a customer has multiple active subscriptions for the same API. ## [1.1.0] - 2026-05-01 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Sustainability API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/sustainability/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/sustainability/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [1.0.0] - 2026-03-01 #### Added - Release of Sustainability API. # Sustainability API The Sustainability API enables you to read utility data assets such as energy consumption, cost data for a customer and for the period of interest. The API is available as an add-on in combination with an active Building X Sustainability Manager subscription. ## Concepts & Glossary | Term | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | Consumption | It provides the consumption of a location or measured by a Meter-Equipment that is derived from its meter readings. | | Cost | Cost refers to cost generated by the energy consumption of a building. | # Quick Start Welcome to the Sustainability API Quick Start guide! This document will walk you through the essential steps to authenticate and interact with the Sustainability APIs, from account creation to making your first API requests. ## Prerequisites Before you begin, ensure you have: - Access to the Fire API portal. - Credentials for a machine user (`clientId`, `clientSecret`, and `customerId`). - A terminal environment (Linux/MacOS shell or Windows command prompt). - [curl](https://curl.se/) installed, or another HTTP client of your choice. ## Step 1: Create an Account and Machine User To access the Fire APIs, you need to create an account and register a machine user. Follow the instructions in the [Getting Started](../../dev-guide/gettingstarted.html) guide to obtain your `clientId`, `clientSecret`. You need to get your `customerID` as well. ## Step 2: Obtain a JSON Web Token (JWT) Authenticate your machine user by generating a JWT. This token will be used to authorize your API requests. ### Example: Generate a Token Set your credentials as environment variables: ```bash export CLIENT_ID= export CLIENT_SECRET= ``` **Endpoint:** `POST {{buildingxopenness.env.issUrl}}` **Body Parameters:** - `client_id` (string, required): Your machine user's client ID. - `client_secret` (string, required): Your machine user's client secret. - `audience` (string, required): The audience for the token, typically the API identifier. - `grant_type` (string, required): The OAuth2 grant type, usually `client_credentials`. **Example:** ```bash curl {{buildingxopenness.env.issUrl}} \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"{{buildingxopenness.env.audience}}\", \"grant_type\":\"client_credentials\" }" ``` > **Note:** > > - The above example uses a Linux/MacOS shell. On Windows, use `set` instead of `export`. > - You can use any HTTP client or programming language to make these requests. #### Example Response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` - The `access_token` is your JWT. - The `expires_in` value (in seconds) indicates how long the token is valid (typically 24 hours). ## Step 3: Make API Requests With your token and customer ID, you can now interact with the Sustainability API. ### Retrieve Utility Data You can fetch the utility data for a customer by performing the GET `Utility Data` operation. **Endpoint:** `GET customers/{$customerID}/assets/utility-data` **Path Parameters:** - `customerID` (string, required): The unique identifier of the customer. **Query Parameters:** - `customerName` (string, required): Name of the customer. - `pageSize` (number, optional): Specifies the response size. - `serviceType` (string, optional): Specifies the service type. **Example:** You can fetch the utility data for a customer by performing the GET `Utility Data` operation. ```bash curl -H "Authorization: Bearer $TOKEN" \ "{{buildingxopenness.env.sustainabilityApiUrl}}/customers/$CUSTOMER/assets/utility-data" ``` - The response includes a list of buildings with utility data assets for customers. - For large customers, refer to the [Pagination](../../dev-guide/index.html#pagination) section. # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### [0.1.0] - 2026-05-07 #### IMPORTANT CHANGES - **API Endpoint Update:** New domain and API path for the Visitor Manager API. - **Old Endpoint:** `https://api.bpcloud.siemens.com/visitormanager/v1/*` - **New Endpoint:** `https://eu.buildingx.siemens.com/api/openness/visitormanager/v1/*` - **Action Required:** Please update your integrations to use the new endpoint. - **Grace Period:** The old domain will continue to be supported for a grace period. A separate notification will be sent to all customers regarding the deprecation date ### [0.0.1] - 2026-03-01 #### Feature - Release of Visitor Manager API # Visitor Manager API Visitor Manager API enables you to retrieve and manage visitor information within the Building X ecosystem. ## Concepts & Glossary | Term | Description | | ---------- | ------------------------------------------------------- | | Visitor | Identifies the person who is visiting the campus | | Visit | Identities the invite for which a visitor is invited to | | Assignment | Links the visitor to a visit | # Quick Start Sample quickstart for Visitor Manager API Reference Getting started with using Visitor Manager APIs involves the following steps: 1. Create an account and a machine user. 1. Create a JSON Web Token (JWT) by using the machine user credentials. 1. Make API requests using the JWT. Note In the following examples we are: 1. making use of a Linux/MacOS shell in which environmental variables are set using the `export`-command. In other environments it may be different, e.g. Windows uses the `set`-command instead. 1. using the `curl` as a client. But the API can be used in any programming language with an HTTP Client, e.g. Go, Python, NodeJS, Javascript and Java. ## Create an account and a machine user The [Getting Started](../../dev-guide/gettingstarted.html) page documents the required steps to get a hold of the `clientId`, `clientSecret` and `partitionId`. ## Create a token Use the values described in the [Authorization](../../dev-guide/howto.html)- section to construct the Create Token request. ### Example request ```bash export CLIENT_ID= export CLIENT_SECRET= curl {{env.issUrl}} \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"{{env.audience}}\", \"grant_type\":\"client_credentials\" }" ``` To run this example yourself, set the `CLIENT_ID` and `CLIENT_SECRET` first. ### Example response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token`-property in the response. You can now use it by passing it in the `Authorization`-header of any subsequent API requests. The `expires_in`-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. Now you have all you need to start using the API. As a last step of preparation set the token and `partitionId` as environmental variables. ```bash export PARTITION= export TOKEN= ``` ## Make API requests Refer the [API Reference](api-reference.html) for the available endpoints and their usage. # Developer's Guide The Siemens Building X APIs are based on the [JSON:API](https://jsonapi.org/) specification. On top of JSON:API we have applied some conventions of our own. This document aims to describe those and give you other useful information to get started and operate an application based on our APIs. ## Authentication You can use your Machine User credentials to obtain an API Token using the OAuth 2.0 Client Credentials grant. The token endpoint is found at: `https://siemens-bt-015.eu.auth0.com/oauth/token` | Parameter | Value | | --------------- | ------------------------------------------------------------- | | `client_id` | (mandatory) The *client_id* you received when registering | | `client_secret` | (mandatory) The *client_secret* you received when registering | | `audience` | (mandatory) `https://horizon.siemens.com` | | `grant_type` | (mandatory) `client_credentials` | For information on how to create you own client credentials, or Machine User, check out the [Getting Started](gettingstarted.html). Refer to [Authentication](howto.html) for more hands-on guidance. ### Token Validity The token has limited validity. After expiry you may create a new token by repeating the create token flow. The JWT itself, as well as the response of the create token request, will provide information about the expiry time. In the JWT there is a `exp` claim, and in the response, there is a `expires_in` property. ## Filtering Filters are provided as query string parameters using the `filter` family style. The available filters for each list operation are described in the API Reference. #### Example Filter devices with `serialNumber` of value `12345`. ```http GET /partitions/5435b9ac-8823-9e89-804bd4710e90/devices?filter[serialNumber]=12345 ``` ## Pagination Paging functionality is provided as query string parameters using the `page` family style. The available paging strategy and specific options for each list operation are described in the API Reference. ### Controlling Page Size Page size is controlled by using the `page[limit]` param. #### Example Set the maximal number of records to receive in the response to `5`. ```text GET /partitions/5435b9ac-8823-9e89-804bd4710e90/devices?page[limit]=5 ``` ### Navigating Pages Navigation links are provided within the `links` property using different keys to represent different targets as described in the table below. | Key | Description | | ----- | ------------------------- | | self | the current page of data | | first | the first page of data | | last | the last page of data | | prev | the previous page of data | | next | the next page of data | Keys are omitted to indicate that a particular link is unavailable. When listing resources, e.g. devices, there are typically one or two links present. `self` is always present and `next` is present if there is a next page to fetch. When the `next` link is no longer in the response, then there are no more pages to fetch. ## Inclusion of related resources Building X APIs adhere to the JSON:API specification. For some operations the `include` parameter is supported. If the `include` parameter is specified for an operation it can be used with the defined values. This gives you the option to include resources that appear in the `relationships` without performing another request to the server. When used, the response will contain a top-level property `included` which contains the requested resources. In addition, there is a parameter called `field`, available for some operations. By specifying it, the client can retrieve certain fields that are not otherwise in the response. ## Request ID Every response contains a response header called `X-Request-Id`. The value of the header is a unique identifier of the transaction. Use this and share with the Development Team when reporting problems. ### Example Response ```http HTTP/1.1 400 Bad Request X-Request-Id: 2e92b826-8d7f-4a86-bf84-241c02c1b90a ``` ## JSON Error Object | Term | Description | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | A unique identifier for this particular occurrence of the problem. | | status | The HTTP status code applicable to this problem, expressed as a string value. | | code | An application-specific error code, expressed as a string value. | | title | A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. | ### Example Response ```json { "errors":[ { "id": "2e92b826-8d7f-4a86-bf84-241c02c1b90a", "status": "400", "code": "34-0001", "title": "Missing mandatory property 'name'" } ] } ``` ## HTTP Status Codes | Term | Description | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action. | | 201 | The request has been fulfilled, resulting in the creation of a new resource. | | 202 | The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs. | | 204 | The server successfully processed the request and is not returning any content. | | 400 | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing). | | 401 | Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. | | 403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort. This code is also typically used if the request provided authentication via the WWW-Authenticate header field, but the server did not accept that authentication. | | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. | | 405 | A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource. | | 406 | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. | | 409 | Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates. | | 429 | The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes. | | 500 | A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. | | 503 | The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state. | | 504 | The server was acting as a gateway or proxy and did not receive a timely response from the upstream server. | ## Standards & Formats | Term | Description | | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [RFC 3339 Date and Time on the Internet: Timestamps](https://tools.ietf.org/html/rfc3339) | The chosen way to represent time and dates. | | [The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749) | OAuth 2.0 for authorization and `client_credentials` grant type. | | [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) | The representation of geographical coordinates. | | [Project Haystack](https://project-haystack.org/) | Project Haystack is an open source initiative to streamline working with data from the Internet of Things in the domain of Building Automation. | | [RFC7946 The GeoJSON Format](https://datatracker.ietf.org/doc/html/rfc7946) | GeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON). | | [JSON:API](https://jsonapi.org/) | JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests. JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability. | ## Policies ### Rate Limitation Each client may make 10 API request per second. If you have additional requirements please contact us. Exceeding the rate limit will result in a `429` error. ### Compatibility Policy The APIs will evolve over time by the introduction of new properties and endpoints. Prepare your parsers for new properties, so that they are allowed in order not to break the client. ### Backwards Compatibility As much as possible, we strive not to change the behavior of existing properties. However, the behavior of an API may change without warning if the existing behavior is incorrect or constitutes a security vulnerability. ### Deprecation We reserve the right to deprecate APIs in full or in part. Usually this is only done after introducing improved ways to achieve the same goals. When deprecating an API, we will notify all registered users at least 3 months in advance. # Getting Started The Siemens Building X APIs enable you to retrieve up-to-date information from your building. To use our APIs, depending on whether you already have a customer account or not, you can either go directly to the [Building X API Manager](#api-manager), or try out the APIs using our [sandbox environment](#sandbox-environment) and Developer Portal. Are you interested in obtaining a customer account or connecting your building? Contact Siemens Regional Support. ## API Manager If you already have a customer account and a connected building: 1. Log in to [API Manager](https://eu.buildingx.siemens.com/openness/). 1. Go to the **Machine Users** page and create a new machine user. Ensure that your machine user has the correct user groups assigned. Note down your `clientId` and `clientSecret`. 1. Go to the **API documentation** page, select your machine user and partition, then generate the token by providing the client secret key. 1. You are ready to call the APIs! Select the APIs of interest from the navigation and try out your first calls. Note You need to have the role `Company Administrator` to perform the above steps. If you cannot see the **Machine Users** menu, contact the administrator in your organization to help you perform the steps. ## Sandbox environment If you don't have a customer account, you can still try out our APIs: 1. [Request access via the developer dashboard](https://dashboard.accounts.developer.siemens.com/request-access/1000) to our sandbox environment. The credentials are granted immediately and you can inspect them on the [My Credentials](https://dashboard.accounts.developer.siemens.com/credentials) page. 1. Once you obtain the credentials, refer to the [Authentication](howto.html) page to learn how to obtain an authorization token. 1. To start calling our APIs directly from the Developer Portal, go to our [try-out page](try-out.html). Click the "Authorize" button to enter your token and start testing the APIs. Note Currently, the Fire and LifecycleTwin APIs are not part of the sandbox environment. Please use [Contact Us](../contact.html) to request access. # Authentication This chapter aims to provide hands-on examples on how to authenticate by creation of an authorization token and making a sample call. ### Example Request Use the sample below and fill your `client_id` and `client_secret` to request an authorization token: ```bash export CLIENT_ID= export CLIENT_SECRET= curl https://siemens-bt-015.eu.auth0.com/oauth/token \ -H 'content-type: application/json' \ -d "{ \"client_id\":\"$CLIENT_ID\", \"client_secret\":\"$CLIENT_SECRET\", \"audience\":\"https://horizon.siemens.com\", \"grant_type\":\"client_credentials\" }" ``` ### Example Response ```json { "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt", "token_type": "Bearer", "expires_in": 86400 } ``` The token, or JWT (JSON Web Token), is the value of the `access_token` property in the response. You can now use it by passing it in the `Authorization` header of any subsequent API requests. The `expires_in` property represents the number of seconds your token is valid for, usually the value corresponds to 24 hours. When this time has elapsed you will need to create a new token. For example, when using the **Operations API** to list **Devices**: ```bash export TOKEN=eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt export PARTITION=1bcaafc3-d4d3-43e1-ab64-89d8518d5951 curl -H "Authorization: Bearer $TOKEN" "https://eu.buildingx.siemens.com/api/openness/operations/partitions/$PARTITION/devices" ``` Note Your token is valid for a limited time and your application will need to refresh it at regular intervals. Warning Make sure to store your token in a safe place, never share it or store it in source control. Anyone with access to your token can access the system on your behalf. # Try Out Info In order to try out APIs, please see [Authentication](howto.html) to obtain the token and authorize via the button. You can obtain the partition ID from the Accounts API. # Building X Connector for Mendix The Building X Connector for Mendix simplifies the creation of new business value using LowCode powered by Mendix and the Building X platform. This Connector provides a domain model encompassing all core entities exposed by Building X. It also offers actions for retrieving, creating, updating, and deleting these entities, which become available in the Mendix toolbox upon installing the Connector. This document will guide you through the structure of the Connector, enabling you to build innovative applications. ## Firewall Settings for Building X Cloud The following tables describe the Building X cloud endpoints used by the Siemens ID login service, applications, and the machine user. All data communication via the Internet is encrypted using Transport Layer Security (TLS) 1.2 or higher. Building X uses modern cloud principles (such as content delivery networks) to achieve high availability and scalability. The cloud endpoint DNS names can be resolved to a wide range of IP addresses based on caller context and backend state. To access the Building X APIs, connections must be established to all cloud endpoints listed in Building X platform, Building X Data Onboarding, and in the following table. ### Service Endpoints API Manager is a service that provides the capability to manage access to APIs in Building X. | Service | Cloud Endpoint | TCP-Port | | ----------------------- | ------------------------------------------------------------------------------------------------- | -------- | | API Manager application | | 443 | | API Entry | [https://eu.buildingx.siemens.com/api/openness/](https://eu.buildingx.siemens.com/api/openness/*) | 443 | ## Importing the Building X Connector This guide will walk you through the steps to import the 'Building X Connector for Mendix' from the Mendix Marketplace into your Mendix application. **Prerequisites**: - A Mendix account - Access to Mendix Studio Pro - An existing Mendix app or a new app created Complete the following steps to import the Building X Connector for Mendix. 1. **Open Your Mendix App**: 1. Launch Mendix Studio Pro. 1. Open the Mendix app into which you want to import the 'Building X Connector for Mendix'. 1. **Access the Mendix Marketplace**: 1. In the top menu, select `App` and then select `Marketplace` from the dropdown list.\ The Mendix Marketplace opens within the Studio Pro interface. 1. **Search for the Connector**: 1. In the Marketplace search bar, type 'Building X Connector for Mendix'. 1. Press `Enter` to search. 1. **Select the Connector**: 1. From the search results, find the 'Building X Connector for Mendix'. 1. Select the Connector to view its details. 1. **Import the Connector**: 1. On the Connector details page, select `Download`.\ Once the download is complete, you will see a prompt to add the Connector to your app. 1. Select `Add` to proceed. 1. **Configure the Connector**: 1. After adding the Connector, you must configure it to work with your app.\ Follow the documentation provided with the Connector for specific configuration steps. This typically involves setting up API keys, endpoints, and other necessary settings. 1. **Use the Connector in Your App**:\ With the 'Building X Connector for Mendix' imported and configured, you can now start using it in your Mendix app. 1. Navigate to the relevant part of your app where you want to utilize the Connector and implement it as needed. 1. **Test Your App**: 1. Once the Connector is integrated, thoroughly test your app to ensure it works as expected. 1. **Check for Issues**: 1. Check for any issues or errors and consult the Connector’s documentation for troubleshooting tips. ## Concepts This chapter outlines the key architectural concepts for the **Building X Connector for Mendix**. ### Entity Model The Connector provides a comprehensive entity model that includes entities that can be retrieved from or stored with Building X. This rich entity model streamlines application development, making the development process easier and more efficient. #### Non-persistence The entity model exposed by the Connector is intentionally non-persistent to reduce potential concurrency issues when executing multiple requests simultaneously. When integrating the Connector, the application has the flexibility to customize the Connector's domain model into persistent entity classes within its architecture and data storage model. This customization allows the application to tailor the data model to its unique use cases and storage requirements, efficiently optimizing performance and resource utilization. ### Authentication and Token Management The Connector automatically handles token management, ensuring seamless authentication for users. It only requests a new token when the current token expires, streamlining the authentication process and improving the user experience. The BX Authenticate action takes a machine user ID and secret as input. It returns a token that is valid for at least another 5 minutes, providing secure access to the underlying Building X APIs. ### Associations In Mendix, it's best to design pages from a domain model once the relationships between entities are established. This allows Mendix to navigate between entities and populate UI elements. However, this approach may retrieve too many Referenced Entities when loading a single entity from a data store or service. When using persistent entities, Mendix addresses this with the *Retrieve by Association* option in the `Retrieve Objects` action, which loads Referenced Entities as needed. By default, Referenced Entities are not loaded until requested, streamlining data retrieval. The Connector handles entity retrieval and association differently due to the fact that child entities cannot always be loaded directly from their parent entity when querying the Building X platform. When entities are loaded from Building X into a microflow, the associated entities become linked with the retrieved entity. If the associated entity is missing, the Connector creates a new instance of the referenced entity, only initializing its `Identifier` attribute. Once loaded, the entity instance integrates into the microflow context, ensuring smooth data flow and operation. Initialize the referenced entity before or after the action requiring it. The Connector manages Referenced Entities in the same microflow context, promoting efficient data reuse and integration. This approach not only enhances performance and productivity but also fosters seamless navigation across entities within microflows and pages. In a microflow, you can either create the referenced entity from Building X or create it from your local data store. This ensures that all associated entities are initialized correctly, which is important for navigating entity relationships in Mendix. The `BX Track Entities` action adds entities to a list of tracked entities. This list helps manage associations when an entity with associations is loaded by a retrieved entity from the Platform. The tracked and thus loaded entity references are used to associate entities with each other. If an associated entity is not already tracked, a new instance of the entity is created, with only the Identifier field set. The `BX Fetch Referenced Entities` action retrieves all entities that are referenced by the entities you have already retrieved, ensuring that all necessary related data is included in the microflow. When used, this action identifies all entities that are referenced by the currently retrieved entities in the context of the current microflow. For each referenced entity, only the Partition ID and Identifier are initialized, while all other fields retain their default values. Once this action is executed, all uninitialized entities are retrieved, ensuring that all fields of entities used in the microflow are populated. When fetching partially initialized entities that contain new references to other entities, the referenced entities remain uninitialized. An additional call to the action is required to fully initialize those entities. Info The `Fetch Referenced Entities` action uses multi-threading to send multiple requests to Building X to retrieve entities simultaneously. By default, a maximum of 32 threads (and thus 32 simultaneous requests) are used to retrieve referred entities as efficiently as possible. Info For every entity to be initialized, a request is sent to Building X. Therefore, it may be more efficient to load the desired entities in a batch using a corresponding list action, such as `Get Location List`. When restoring entities from the local datastore, prepopulate a `List` object and supply it to the action requiring initialized entities. Mendix transmits entities from the client to the server using the `List` object as a parameter value for the action. This allows the retrieval action to reuse the populated entities. #### Example 1 Consider a scenario where you want to initialize a list of `EquipmentEntity` entities from Building X. Once the `Get Equipments` action is executed, a list of `equipment` is available. The association to `equipment type` is made, but because the `EquipmentType` entity itself is not loaded, only the `Identifier` attribute is set. #### Example 2 Consider a scenario where you want to initialize a list of `EquipmentEntity` entities from Building X where the `Equipment Type` can be selected from a dropdown list in your application. In this scenario, you need to execute the `Get Equipment Types` and `Get Equipments` actions. Because entity instances are shared within the context of a microflow, it does not matter if the `Get Equipment Types` action is performed before or after the `Get Equipments` action. In either order, the `equipment` and `equipment type` entities are populated and associated. If the `Get Equipments` action precedes the `Get Equipment Types` action, the `Equipment` entities are linked to an `Equipment Type`, but only the `Identifier` of this entity is established. Subsequently, upon executing the `Get Equipment Types` action, all attributes of the `Equipment Type` entities are populated. If the `Get Equipments` action precedes the `Get Equipment Types` action, the `Equipment` entities are linked to an `Equipment Type`, but only the `Identifier` of this entity is established. Subsequently, upon executing the `Get Equipment Types` action, all attributes of the `Equipment Type` entities are populated. #### Example 3 Consider a scenario where you want to initialize a list of `EquipmentEntity` entities without retrieving the already loaded `EquipmentTypeEntity` entities stored in the local database. In this situation, you can instantiate `EquipmentTypeEntity` from the local database and include them in the list while retrieving `EquipmentEntity` entities using the `associatedEquipmentTypes` parameter. This strategy of using a pre-populated list not only encourages reuse of equipment type references but also improves efficiency within your application. ### Identity Handling In Building X, the management of identifiers is crucial for creating, updating, and retrieving various entities within the platform. For most entities in Building X, the platform automatically generates unique identifiers. This simplifies the process for developers, as they do not need to manually create or manage these identifiers. When an entity is created, the platform generates a unique identifier and includes it in the response payload after the action is executed. This ensures that each entity can be uniquely and reliably identified within the platform. While the platform generally handles identifier generation, there is an exception for `LocationEntity` entities. Developers have the option to provide their own identifiers when creating location entities. These client-generated identifiers must be in the Universally Unique Identifier (UUID) version 4 format. The pattern for these UUIDs follows the regular expression: `^[A-Z]?[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$`. ### Tags Handling The `Tag` entity is designed to facilitate the definition and management of tag names and values for entities that support tagging, such as `LocationEntity` or `PointEntity`. Tag values can be either the boolean marker "true" or an array of strings. Before using tags, the `BuildingX_Connector.Tag` relationship must refer to a valid instance of a domain entity that extends the functionality of the `EntityWithTags` entity, such as `LocationEntity` or `PointEntity`. Additionally, tag names must not be null or empty. Tags with null or empty names or values are excluded without generating an error. When a tag's value is empty or equals the string `true`, it is stored as a marker. Otherwise, the string value is saved in an array of strings. If a tag with the same name is created multiple times, all unique values are consolidated into the array of strings, excluding any empty strings. Tags are organized by their names, ensuring that values are unique within each tag. After processing, all tag names are trimmed of leading and trailing whitespace, while the tag values remain unchanged. ## Error Handling When executing an action within Building X, exceptions may occur in the following scenarios: - Invalid input parameters are detected for the action. - Validation for creating or updating an entity fails. - The HTTP error code returned by the underlying endpoint does not indicate success (200 OK). In such cases, it's crucial to utilize Mendix's default error handling functionality to gracefully manage these failed requests. For instance, configuring a microflow within Mendix can effectively address the exception by logging the error, notifying administrators, or presenting a user-friendly error message to the end user. This approach ensures a smoother user experience and facilitates efficient troubleshooting and issue resolution. ## Minimal Microflow The minimal microflow consists of the following steps: 1. **Authenticate Machine User and Request Token**: Call the `BX Authenticate` action to obtain a token. 1. **Building X Action**: Provide the obtained token as input to the Get, Create, Update, or Delete action. For example the `Get Devices` or `Create Equipement` action. Info It is recommended to retrieve these configurations from a persistent settings entity associated with the current user to securely store and manage this data. Alternatively, constants can be utilized with different Mendix configuration profiles to identify machine user credentials. ## Actions This chapter describes the action naming and parameter conventions, as well as a comprehensive list of all actions provided by the Connector. ### Action Naming The Connector follows a consistent approach for managing entities. The following actions are available for every entity: | Action | Description | | ----------------- | ---------------------------------------------------------------------------------------------- | | Get `` | Retrieves all entities that match the given filter parameters. | | Get `` | Fetches a single entity by its identifier. | | Add `` | Add a new entity from the newly created non-persistent entity. The created entity is returned. | | Update `` | Updates the given non-persistent entity and returns the updated entity. | | Delete `` | Deletes the given entity. | Note Data retrieval is applicable to all entities with the corresponding API subscription and access rights. Some entities support only reading. ### Parameter Categories When performing actions with the Building X Connector, various parameter categories are utilized to configure the requests: | Category | Description | | -------------- | --------------------------------------------------------------------------------------- | | Authorization | Token required to access the underlying API endpoint. | | Identification | Parameters used to identify the entity, such as the company or partition and entity ID. | | Filters | Filters applied to select a subset of the requested entities. | | Parameters | Additional parameters used to include supplementary data or configure the action. | | Associations | List of already-loaded entities to reuse as associated entities. | These categories help structure the inputs required for interacting with the Building X Connector efficiently. ## Action Overview This table provides an overview of the various actions available within the BuildingX Connector. Each action is listed with its associated name, input parameters, and output. These actions facilitate interactions with BuildingX's services, enabling functionalities such as authorization, fetching and updating entities, managing equipment, and handling energy consumption data. Convert the 'Endpoint' column to hyperlinks, use the second last part, before api-reference, of the url as the hyperlink text. Export MkDocs style and include all rows until 'bx_Device_Create'. Convert the 'Endpoint' column to hyperlinks, use the second last part, before api-reference, of the url as the hyperlink text. Export MkDocs style and include all rows until 'bx_Device_Create'. ### General The Connector provides several actions to ease development effort, offering streamlined micflows for tasks such as data retrieval and updates. Each action includes clear inputs, outputs, and API endpoints, ensuring efficient integration and enhancing functionality for developers. | Name | Action | Input Parameters | Output | Description | | -------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **BX Authorize** | bx_Authorize | MachineUserId (String) MachineUserSecret (String) | Token | Authorizes a machine user and retrieves a token. | | **BX Get Location Children** | bx_Location_Children_Get | token (BuildingX_Connector.Token) parentLocation (BuildingX_Connector.LocationEntity) recursive (Boolean) includeSelf (Boolean) | List of BuildingX_Connector.LocationEntity | This action retrieves child locations for a specified parent location. It allows for the inclusion of the parent location and recursive retrieval of all child locations. If child locations are not loaded, they are fetched from the Platform using the provided token and parent location details. | | **BX Fetch Referenced Entities** | bx_FetchReferencedEntities | token (BuildingX_Connector.Token) | Nothing | Retrieves all entities that are used as references by the entities retrieved from the Platform. | | **BX Track Entities** | bx_TrackEntities | List of EntityWithIdentifier | Nothing | Adds entities to a list of tracked entities. This list is used to manage associations when an entity, which has associations, is loaded by a retrieved entity from the Platform. | ### Building Twin The Connector provides several actions to ease development effort, including those specifically aimed at facilitating the creation and management of digital twins for buildings. These actions enable developers to efficiently retrieve, update, and synchronize building data, enhancing the accuracy and responsiveness of applications that rely on digital representations of real-world buildings. Notably, Building Twin does not include Life Cycle Twin functionalities. | Name | Action | Input Parameters | Output | API endpoint | Roles | Description | | ---------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------- | | **Add Address** | bx_Address_Create | token (Token) partitionId (String) address (AddressEntity) | AddressEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Creates a new address. | | **Add Location** | bx_Location_Create | token (Token) partitionId (String) location (LocationEntity) includeReferredEntities (Boolean) | LocationEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Creates a new location. | | **Delete Address** | bx_Address_Delete | token (Token) address (AddressEntity) | Nothing | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Deletes an address. | | **Delete Location** | bx_Location_Delete | token (Token) partitionId (String) location (LocationEntity) | Nothing | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Deletes a location. | | **Get Address** | bx_Address_Get | token (Token) partitionId (String) | LocationEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a specific address. | | **Get Addresses** | bx_Addresses_Get | token (Token) partitionId (String) associatedCountries (List of CountryEntity) | List of AddressEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a list of addresses. | | **Get Building Types** | bx_Locations_BuildingTypes_Get | token (Token) partitionId (String) | List of BuildingTypeEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a list of building types. | | **Get Countries** | bx_Countries_Get | token (Token) partitionId (String) | List of CountryEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a list of countries. | | **Get Location** | bx_Location_Get | token (Token) partitionId (String) locationId (String) | LocationEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a specific location. | | **Get Locations** | bx_Locations_Get | token (Token) partitionId (String) includeReferredEntities (Boolean) includeHistoricalData (Boolean) associatedEquipments (List of EquipmentEntity) | List of LocationEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a list of locations. | | **Update Address** | bx_Address_Update | token (Token) partitionId (String) address (AddressEntity) | AddressEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Updates an address. | | **Update Location** | bx_Location_Update | token (Token) partitionId (String) location (LocationEntity) includeReferredEntities (Boolean) | LocationEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Updates a location. | ### Building Automation The Connector provides several actions to ease development effort, including those tailored for building automation. These actions enable developers to effectively control and monitor building systems such as HVAC, lighting, and security. By utilizing these micflows, developers can streamline the integration of automation functionalities into their applications, ensuring buildings operate efficiently and securely. | Name | Action | Input Parameters | Output | API endpoint | Roles | Description | | --------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | | **Add Alarm Configuration** | bx_AlarmConfiguration_Create | token (Token) alarmConfiguration (AlarmConfigurationEntity) | AlarmConfigurationEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API ReadWrite | Creates a new alarm configuration. | | **Add Device** | bx_Device_Create | token (Token) partitionId (String) device (DeviceEntity) | DeviceEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API ReadWrite | Creates a new device. | | **Add Equipment** | bx_Equipment_Create | token (Token) equipment (EquipmentEntity) | EquipmentEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Creates new equipment. | | **Add Point** | bx_Point_Create | token (Token) point (PointEntity) | PointEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Creates a new point. | | **Update Alarm Configuration** | bx_AlarmConfiguration_Update | token (Token) alarmConfiguration (AlarmConfigurationEntity) | AlarmConfigurationEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API ReadWrite | Updates an alarm configuration. | | **Update Device** | bx_Device_Update | token (Token) partitionId (String) device (DeviceEntity) updateLocation (Boolean) | DeviceEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API ReadWrite | Updates a device. | | **Update Equipment** | bx_Equipment_Update | token (Token) equipment (EquipmentEntity) updateLocation (Boolean) | EquipmentEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Updates equipment. | | **Update Point in Point Group** | bx_PointGroup_HasPoints | token (Token) partitionId (String) pointGroupId (String) pointId (String) operation (Enumeration PointGroup_Point_Operation) | Nothing | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Checks if a point group has specific points. | | **Delete Alarm Configuration** | bx_AlarmConfiguration_Delete | token (Token) alarmConfiguration (AlarmConfigurationEntity) | Nothing | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API ReadWrite | Deletes an alarm configuration. | | **Delete Device** | bx_Device_Delete | token (Token) device (DeviceEntity) | Nothing | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API ReadWrite | Device deletion is currently not supported. This feature will be available in a future update. | | **Delete Equipment** | bx_Equipment_Delete | token (Token) equipment (EquipmentEntity) | Nothing | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Deletes equipment. | | **Delete Point** | bx_Point_Delete | token (Token) point (PointEntity) | Nothing | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API ReadWrite | Deletes a point. | | **Get Last Values in PointGroup** | bx_PointGroup_GetLastValues | token (Token) partitionId (String) pointGroupId (String) | List of BuildingX_Connector.PointValueEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves the latest values for all points within the specified point group. | | **Get Point** | bx_Point_Get | token (Token) partitionId (String) pointId (String) | PointEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a specific point. | | **Get Points** | bx_Points_Get | token (Token) partitionId (String) includeReferredEntities (Boolean) includeHistoricalData (Boolean) associatedLocations (List of LocationEntity) associatedEquipments (List of EquipmentEntity) associatedPointTypes (List of PointTypeEntity) | List of PointEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a list of points. | | **Get Point Values** | bx_PointValues_Get | token (BuildingX_Connector.Token) partitionId (String) pointId (String) filterFrom (Date and time) filterTo (Date and time) | List of BuildingX_Connector.PointValueEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves historical data for a specific point. | | **Get Alarm Configurations** | bx_AlarmConfigurations_Get | token (Token) partitionId (String) pointId (String) | List of AlarmConfigurationEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API Read | Retrieves a list of alarm configurations. | | **Get Device** | bx_Device_Get | token (Token) partitionId (String) deviceId (String) | DeviceEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API Read | Retrieves a specific device. | | **Get Devices** | bx_Devices_Get | token (Token) partitionId (String) includeDeviceInfo (Boolean) includeConnectivity (Boolean) filterByGatewayId (String) filterByLocationId (String) associatedLocations (List of LocationEntity) associatedTimeZones (List of TimeZoneEntity) | List of DeviceEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API Read | Retrieves a list of devices. | | **Get Device Events** | bx_DeviceEvents_Get | token (Token) partitionId (String) deviceId (String) associatedDevices (List of DeviceEntity) | List of DeviceEventEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API Read | Retrieves a list of device events. | | **Get Device Events Transitions** | bx_DeviceEventsTransitions_Get | token (Token) partitionId (String) deviceId (String) eventId (String) associatedDevices (List of DeviceEntity) | List of DeviceEventEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API Read | Retrieves a list of device event transitions. | | **Get Equipment** | bx_Equipment_Get | token (Token) equipmentId (String) | EquipmentEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a specific piece of equipment. | | **Get Equipments** | bx_Equipments_Get | token (Token) partitionId (String) includeHistoricalData (Boolean) associatedLocations (List of LocationEntity) associatedPoints (List of PointEntity) includeReferredEntities (Boolean) | List of EquipmentEntity | [Building Structure API](https://developer.siemens.com/building-x-openness/api/building-structure/api-reference.html) | Structure API Read | Retrieves a list of equipment. | | **Command Point** | bx_Point_Command | token (Token) partitionId (String) pointId (String) value (Decimal) | Boolean | [Building Operations API](https://developer.siemens.com/building-x-openness/api/building-operations/api-reference.html) | Operations API ReadWrite | Commands a specific point with a given value. | ### Energy The Connector provides several actions to ease development effort, including those designed for building energy management. These actions empower developers to monitor and optimize energy consumption, track costs, and analyze emissions. By leveraging these micflows, developers can seamlessly integrate energy management features into their applications, enhancing sustainability and operational efficiency. | Name | Action | Input Parameters | Output | API endpoint | Roles | Description | | ------------------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------- | | **Get Energy Medium Consumptions** | bx_EnergyMediumConsumptions_Get | token (Token) partitionId (String) filterFrom (Date and time) filterTo (Date and time) filterByMediumType (Enumeration EnergyMediumConsumption_MediumTypes) associatedEquipments (List of EquipmentEntity) associatedMediumConsumptions (List of EnergyMediumConsumptionEntity) | List of EnergyMediumConsumptionEntity | [Building Energy API](https://developer.siemens.com/building-x-openness/api/energy-api/api-reference.html) | Energy API Read | Retrieves a list of energy medium consumptions. | | **Get Energy Medium Consumption Cost** | bx_EnergyMediumConsumptionCost_Get | token (Token) partitionId (String) mediumConsumptionId (String) from (Date and time) to (Date and time) unit (Enumeration EnergyMediumConsumption_Currencies) interval (Enumeration EnergyMediumConsumption_Intervals) associatedMediumConsumptions (List of EnergyMediumConsumptionEntity) | List of EnergyMediumConsumptionValueEntity | [Building Energy API](https://developer.siemens.com/building-x-openness/api/energy-api/api-reference.html) | Energy API Read | Retrieves a list of energy medium consumption costs. | | **Get Energy Medium Consumption Emission** | bx_EnergyMediumConsumptionEmission_Get | token (Token) partitionId (String) mediumConsumptionId (String) from (Date and time) to (Date and time) unit (Enumeration EnergyMediumConsumption_EmissionsUnits) interval (Enumeration EnergyMediumConsumption_Intervals) associatedMediumConsumptions (List of EnergyMediumConsumptionEntity) | List of EnergyMediumConsumptionValueEntity | [Building Energy API](https://developer.siemens.com/building-x-openness/api/energy-api/api-reference.html) | Energy API Read | Retrieves a list of energy medium consumption emissions. | | **Get Energy Medium Consumption Usage** | bx_EnergyMediumConsumptionUsage_Get | token (Token) partitionId (String) mediumConsumptionId (String) from (Date and time) to (Date and time) unit (Enumeration EnergyMediumConsumption_UsageUnits) interval (Enumeration EnergyMediumConsumption_Intervals) associatedMediumConsumptions (List of EnergyMediumConsumptionEntity) | List of EnergyMediumConsumptionValueEntity | [Building Energy API](https://developer.siemens.com/building-x-openness/api/energy-api/api-reference.html) | Energy API Read | Retrieves a list of energy medium consumption usage. | ### Security | Name | Action | Input Parameters | Output | API endpoint | Roles | Description | | --------------------------------- | -------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------- | | **Get Security Assignments** | bx_SecurityAssignments_Get | token (BuildingX_Connector.Token) partitionId (String) identity (String) | List of BuildingX_Connector.PrivilegeEntity | [Building Operations API](https://developer.siemens.com/building-x-openness/api/security-api/piam-v1/api-reference.html) | Security API Read | Retrieves security assignments for a specific identity. | | **Get Security Alarm and Events** | bx_SecurityEvents_Get | token (BuildingX_Connector.Token) partitionId (String) | List of BuildingX_Connector.SecurityEventEntity | [Security Alarms and Events API](https://developer.siemens.com/building-x-openness/api/activities-v1/api-reference.html) | Security API Read | Retrieves security events for a specific partition. | | **Get Security Identities** | bx_SecurityIdentities_Get | token (BuildingX_Connector.Token) partitionId (String) | List of BuildingX_Connector.IdentityEntity | [Identities and Privileges API](https://developer.siemens.com/building-x-openness/api/security-api/piam-v1/api-reference.html) | Security API Read | Retrieves security identities for a specific partition. | | **Get Security Privileges** | bx_SecurityPrivileges_Get | token (BuildingX_Connector.Token) partitionId (String) | List of BuildingX_Connector.PrivilegeEntity | [Identities and Privileges API](https://developer.siemens.com/building-x-openness/api/security-api/piam-v1/api-reference.html) | Security API Read | Retrieves security privileges for a specific partition. | ## Building X Subscriptions The Building X Connector leverages various Building X APIs to facilitate its operations. To explore and review the available API products that underpin these functionalities, please visit the [Xcelerator Marketplace](https://xcelerator.siemens.com/global/en/all-offerings.html?selectedFilters=1-b371c5c2-1633-4bf4-a171-66241aa8a11b%3B2-8e07596f-2368-4d1b-ba11-9cf46160a42e%3B3-f30e97f8-089e-4847-9e97-9a66e8dffc68). ## Use Cases Building X integrated with Mendix offers powerful capabilities for developing and maintaining applications with significantly reduced effort compared to high-code alternatives ### How to Get Devices Behind a Gateway In scenarios where multiple devices are connected through a gateway device, the gateway acts as a mediator, relaying information between the external network and the internal devices. The gateway uses network scanning, device discovery protocols, and its management interface to list all connected devices. This process is crucial for monitoring, controlling, and updating devices seamlessly. To retrieve device information from devices connected to this gateway, additional actions are required. See the `DS_GetDevicesBehindGateway` microflow from the *Building X Connector for Mendix* Sample App for details. ### How to Get the Last Value Per Device or Equipment To obtain the most recent readings or status updates from various devices or equipment, you need to query the point group that contains these values. The point group for a device or equipment can be retrieved using its filter. Once the point group is retrieved, you can request the latest values for all points within that group. See the `DS_GetPointGroup_Points` microflow from the *Building X Connector for Mendix* Sample App for details. This approach ensures that you have the most up-to-date information for monitoring and decision-making purposes. ### How to Ingest Sensor Readings and Sync Master Data This use case provides a guide on integrating external sensors, covering essential steps such as retrieving or creating equipment using the sensor ID, obtaining and handling point groups, managing points within these groups, and ingesting sensor measurements into corresponding points. These processes ensure integration and synchronization of sensor data, significantly enhancing the capability to effectively utilize sensor information. 1. Retrieve the equipment using the external ID, which corresponds to the sensor ID. 1. If the equipment does not exist, create it. 1. Obtain the point group using the equipment ID. This step can be repeated until the point group is created after a new device is created; point groups are created asynchronously, so there may be a slight delay. 1. Search for the point within the point group by its name. 1. If the point does not exist, create it within the point group for the equipment. 1. Ingest the sensor measurement value for the specified point, which belongs to the point group of the equipment representing the sensor. This process ensures that sensor readings are accurately captured and associated with the correct sensor metadata for further analysis and action. # Power BI Operations and Energy Dataset Explore the smart building and infrastructure operations dataset derived from the Building X Openness APIs. This page provides insight into various tables, their purpose, and detailed column descriptions for effective data analysis and management. ## Energy and Building Performance Dashboards in Power BI The Operations dataset serves as the foundation for the design of the Energy and Building Performance Dashboard within Power BI, leveraging the capabilities of both Power BI and the Building X platform. Its primary goal is to provide a holistic view of multiple facets associated with building portfolios, including information related to locations, equipment, devices, points, and point values. It leverages the following tables and functions: The following tables are exposed by the Operations API subscription: - **Devices**: This table contains information about various devices within the building, including their specifications and connections. - **Points**: This table contains individual data points collected from various building systems, such as sensors and meters. - **PointTags**: This table is designed to store information about tags associated with data points or measurements within the smart building and infrastructure system. These tags help categorize and provide context for data points. - **PointValues**: This table stores the actual values of data points collected over time. The following tables and functions are exposed by the Energy API subscription: - **EnergyMediumConsumptions**: This table contains information about energy medium consumption. - **EnergyMediumConsumptionValues**: This table stores the values of energy medium consumption over time. - **EnergyMediumConsumptionEmissions**: This table stores information about emissions associated with energy medium consumption. - **EnergyMediumConsumptionCosts**: This table stores information about costs associated with energy medium consumption. The following tables and functions are always exposed: - **Partitions**: This table is used to create and manage partitions, allowing for the organization and division of groups and subscriptions based on dataset access permissions. - **Locations**: This table stores information about different locations within a building, including their characteristics, contact details, and geographic coordinates. - **LocationTags**: This table is used to store information about tags associated with various physical locations within smart buildings and infrastructure. Tags provide additional details and categorization for locations. - **EquipmentTypes**: This table defines various types of equipment used within the building. It categorizes equipment types and provides descriptive details. - **Equipment**: This table contains detailed information about specific equipment within the building, such as devices, machinery, or systems. - **TimeTable**: This table displays time in various formats, including hour, minute, and second, as well as AM/PM format. It also includes labels for hour, minute, and second, a time key, and different hour and minute bins. A TimeTable is useful in Power BI for easy analysis and manipulation of time-based data, enabling detailed analysis and greater insights. Time intelligence functions in Power BI support efficient business analytics using periods or time frames. - **GenerateDateTable**: This function generates a comprehensive date table, incorporating various date-related columns such as year, month, day, quarter, week, and fiscal date attributes. Additionally, it calculates age, offsets, and includes user-specified options for the fiscal year start and the first day of the week. ### Key Metrics and Visualizations Create Power BI dashboards to track energy consumption trends and compare data across locations or equipment types. Evaluate building performance through KPI dashboards, considering factors like energy efficiency, temperature control, and occupancy. Assess equipment efficiency and pinpoint improvement opportunities. Implement device monitoring for prompt anomaly detection. Leverage historical data for in-depth analysis, trend identification, and informed decisions in energy management and building performance. - **Energy Consumption**: Create dashboards to monitor and analyze energy consumption trends, including historical data and comparisons between different locations or equipment types. - **Building Performance**: Develop KPI (Key Performance Indicator) dashboards to evaluate building performance based on factors like energy efficiency, temperature control, and occupancy. - **Equipment Efficiency**: Utilize equipment data to assess the efficiency of various equipment types and identify opportunities for improvement. - **Device Monitoring**: Implement real-time monitoring of devices and their data points to detect anomalies or issues promptly. - **Historical Analysis**: Leverage historical time-series data from devices to perform in-depth historical analysis, identify trends, and make informed decisions regarding energy management and building performance. ## Configuring Building X To access the Openness APIs, it is essential to create a dedicated machine user equipped with the appropriate roles and partitions. Only partitions assigned to the machine user can be used with the Building X Connector. You can manage machine users from the **Machine User** view within the **API Manager** application. Please refer to the **API Manager** User Guide for detailed instructions. ### Roles and Permissions The machine user should be associated with the following roles. Create user groups containing these roles and then assign these user groups to the machine user: - Structure API Machine User Read - Operations API Machine User Read ## Configuring Power BI Service This chapter describes the aspects of importing, configuring, and refreshing the Building X dataset within the Power BI service environment. ### Importing the Downloaded Dataset This chapter explains the process of importing the Building X Power BI dataset into the Power BI Web environment. You will learn how to configure parameters in the Settings view and how to update the dataset with the appropriate data source credentials. By following these steps, you can ensure that the dataset remains current and that you gain valuable insights from your data in Power BI. 1. Download the Power BI dataset (.pbix file) that you want to import into the Power BI service environment. 1. Open the Power BI service environment by navigating to the [Power BI service site](https://app.powerbi.com) and signing in with your credentials. 1. In the Power BI service environment, select the **My Workspace** tab on the left-hand side of the screen. 1. Select the **Import** button located at the top of the screen. 1. In the **Import a file** section, select the **Upload** button. 1. Select the downloaded Power BI dataset (.pbix file) from your computer and select the **Open** button. 1. After the file is uploaded, the dataset will be imported into the Power BI service environment. Wait for the import process to complete. 1. Once the import is complete, select the **Settings** option for the imported dataset. It can be found by hovering over the dataset and clicking on the ellipsis (...) button that appears. 1. In the **Settings** view, scroll down until you find the **Parameters** section. This section contains the parameters that need to be set up for the imported dataset. See the *Parameters* chapter for a description of the parameters. 1. After setting up all the parameters, select the **Apply** button to save the changes. ### Refreshing the Dataset This chapter explains how to refresh the Building X Power BI dataset in the Power BI Web environment. 1. To refresh the imported dataset, select the ellipsis (...) button that appears when hovering over the dataset in the Power BI service environment. 1. From the dropdown menu, select the **Refresh Now** option. This starts the refresh and data Building X retrieval process for the dataset. During the refresh process, Power BI may prompt you to provide data source credentials. In such cases, follow these steps: 1. For the data source credentials, select **Anonymous** as the authentication type. 1. Choose **Organizational** as the authentication type for the data source credentials. 1. Skip the testing of the connection by checking the provided checkbox. The behavior of **Anonymous** and **Organizational** data source credentials is as follows: - **Anonymous**: Selecting **Anonymous** as the data source credentials means that the dataset will connect to the data source without any user authentication. This is typically used when the data source allows anonymous access or when the dataset does not require any specific user credentials to retrieve the data. - **Organizational**: Choosing **Organizational** as the data source credentials means that the dataset will use the user's organizational account credentials to connect to the data source. This requires the user to have appropriate permissions and access rights to the data source within their organization. By selecting **Anonymous** and **Organizational** as the data source credentials, you can ensure that the dataset refreshes properly and accesses the required data from the data source based on the appropriate authentication type. ## Dataset Parameters This chapter describes the Power BI Operations dataset parameters. | **Parameter** | **Description** | **Data Type** | **Required** | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------ | | **CustomerId** | This parameter represents the unique identifier of the customer or organization for which the data is being retrieved. It is used to ensure data access and authorization for the specific customer. The CustomerId can be found in the **Overview** view of the **Accounts** application. Obtain the CompanyId by accessing the Options menu of the **Company** tile. Select the **Copy Company Details** option and paste the contents of the clipboard into a text editor to obtain the Company Id. | Text | Yes | | **OperationsPartitionIds** | This parameter allows for data retrieval based on specific partition identifiers. Partitions represent logical divisions of data within the company. Multiple values can be specified, separated by semicolons, to retrieve data related to specific partitions, enabling more refined data selection. The PartitionId can be found in the **Machine User** view in the **API Manager** application by selecting the designated machine user and reviewing the details view. Only the first 10 partitions in the dataset will be used. This parameter is used to list partitions with the Operations API subscription. | Text | Yes | | **EnergyPartitionIds** | This parameter allows for data retrieval based on specific partition identifiers. Partitions represent logical divisions of data within the company. Multiple values can be specified, separated by semicolons, to retrieve data related to specific partitions, enabling more refined data selection. The PartitionId can be found in the **Machine User** view in the **API Manager** application by selecting the designated machine user and reviewing the details view. Only the first 10 partitions in the dataset will be used. This parameter is used to list partitions with the Energy API subscription. | Text | Yes | | **MachineUserClientId** | The Machine User Client ID is used for authentication when accessing the data. It ensures that the request is authorized and authenticated, allowing secure access to Building X Openness APIs. | Text | Yes | | **MachineUserSecret** | The Machine User key is a confidential authentication token used alongside the Machine User Client ID to verify and authorize the request. It adds an additional layer of security to Building X Openness. Machine users can be managed from the **Machine User** view in the **API Manager** app. | Any | Yes | | **PointValuesFrom** | This parameter specifies the start date for retrieving point values (time series data). Data is retrieved from this specified date forward, providing a way to filter and focus on specific time periods. See the *Limitations* chapter for point value limitations. | DateTime | Yes | | **PointTagsFilter** | This parameter filters the table of points and point values based on tag names and optional tag values. Specify multiple tags separated by semicolons. If both a tag name and a tag value are specified, separated by "=", only points with exact tag and value matches are included. Tag values are case-sensitive. If only a tag name is specified, any point containing that tag will be included. | Text | No | | **UseProductionEnvironment** | This parameter determines whether to use the production environment for data retrieval. When set to `true`, it indicates the use of the Building X production environment, ensuring data access from the production environment. If set to `false`, the dataset connects to the Building X test environment. | Logical (Boolean) | Yes | ## Limitations The following limitations apply. | **Limitation** | **Limit** | **Description** | | ------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Maximum partitions** | 10 | To ensure responsive performance, the Power BI dataset imposes a limit that allows retrieval of a maximum number of partitions. | | **Maximum Data Point Values Stored** | 1,000,000 | To ensure responsive performance, the Power BI dataset imposes a limit that allows retrieval of a maximum number of data point values across all configured partitions. This limit is critical to prevent performance degradation, especially when working with large datasets. | | **Maximum Data Point Values per Point Retrieved** | 250,000 | To ensure responsive performance, the Power BI dataset enforces a limit on the number of data point values per individual data point. The most recent time series values are stored in the PointValue table. This limit is critical to prevent performance degradation, especially when working with large datasets. | | **Time Period** | 12 months | There is a limit to the maximum time frame for retrieving data point values. This limit applies regardless of the date specified in the PointValuesFrom parameter. | If parameters are changed, the data sources must be refreshed. See the *Refreshing the Dataset* chapter for more information. ## Openness API Subscription The Power BI dataset uses Openness APIs to retrieve data. Openness APIs are offered per call quota, so each time the Power BI dataset is refreshed, it consumes API calls and increases the quota counter. The number of API calls made depends on the setup of Building X, including partitions, devices, points, and data point values. **Consumed API calls** To accurately determine the number of API calls made by Power BI with each dataset refresh, follow these steps in Power BI Desktop. Please note that Power BI Service does not have a built-in feature for capturing diagnostics or detailed query performance statistics like Power Query in Power BI Desktop does. 1. Open the **Query Editor** in Power BI Desktop. 1. Go to the **Tools** page and select **Start Diagnostics**. 1. On the **Home** page, select **Refresh All**. 1. Go to the **Tools** page and select **Stop Diagnostics**. 1. In the **Queries** pane, navigate to the Diagnostics navigation tree and locate the table that starts with **Diagnostics_Detailed**. 1. Open this table and apply the following filters: 1. [Category] equals **Data Source**. 1. [Data Source Kind] equals **Web**. 1. [Resource] contains **eu.buildingx.siemens.com**. 1. On the **Transform** page, select **Statistics** and choose **Count Values**. The total number of API calls will now be displayed. ## Tags Tags in Building X are dynamic and powerful tools designed to streamline the categorization and filtering of data. They empower users with the flexibility to define custom tag names and assign values to facilitate the identification of locations, points, and devices within the building. The Building X Power BI dataset seamlessly converts all tags into separate columns, each with a `Tag_` prefix, improving data organization and accessibility. Additionally, when tag values are displayed as single-element lists, this feature intelligently converts them to single values. This simplifies data filtering and makes it more intuitive and user-friendly, ultimately enabling more accurate data analysis and efficient data management. In addition to the expanded Tag columns, the LocationTags and PointTags tables also enable filtering of the tag-owning tables based on the tag and its values. Tags without a value or with an empty text value are automatically set to `true` during conversion because these tags are considered marker tags. This simplifies filtering processes and ensures that tags without explicit values can be used for filtering. Tag names and values are case-sensitive. ## Troubleshooting This chapter describes problems and their solutions. ### Access to the resource is forbidden If you receive a "Forbidden Access" error when accessing the Power BI dataset, it indicates that one or more tables have failed to load. To resolve this issue, ensure that the following configuration items are correct in **API Manager** and **Power BI**: - Verify the **MachineUserClientId**, **MachineUserSecret**, **CompanyId**, and **PartitionIds** parameter values. - Verify the partitions assigned to the machine user in **API Manager**. See the *Configuring Building X* chapter for more information. ### The credentials provided for the Web source are invalid If you receive this error when accessing the Power BI dataset, it indicates that one or more tables have failed to load. To resolve this issue, ensure that the following configuration items are correct in **API Manager** and **Power BI**: - Check that the **MachineUserClientId** has the correct roles assigned. See the *Configuring Building X* chapter for more information. ### Data is missing When not all data is present in the tables, review the following documentation and configuration items: - Confirm expectations align with the information in the *Limitations* chapter. - Verify the accuracy of the **PartitionIds**, **PointValuesFrom**, and **PointTagsFilter** parameter values. ### Error: Unable to combine data The error message `[Unable to combine data] is accessing data sources that have privacy levels that cannot be used together. Please rebuild this data combination.` occurs when data sources with incompatible privacy levels are merged. To resolve this issue, review the data sources, adjust their privacy levels, and rebuild the data combination. This ensures data security and compliance. See the *Refreshing the Dataset* chapter for more information. ### Error: Tag column does not exist in the rowset The error message `The 'Tag_' column does not exist in the rowset` indicates that the specified Tag column cannot be found in the referenced table. This typically occurs when the tag is used as a filter in tables or dashboards but is no longer defined in the **Data Setup** platform application for the configured company or partitions. To resolve this, remove the referenced column from tables and dashboard filters. # Tables This chapter describes the Power BI Operations table and column definitions. ## Partitions The Partitions table is used to create and manage partitions, allowing for the organization and division of groups and subscriptions based on dataset access permissions. | **Column Name** | **Data Type** | **Description** | | --------------- | ------------- | -------------------------------- | | **Id** | text | Unique identifier for partitions | | **Name** | text | Name of the partition | | **Description** | text | Description of the partition | ## Locations The Locations table stores information about different locations within a building, including their characteristics, contact details, and geographic coordinates. | **Column Name** | **Data Type** | **Description** | | ----------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Id** | text | Unique identifier for locations | | **PartitionId** | text | Identifier of the associated partition | | **Type** | text | Type of location (e.g., campus, building, room, floor) | | **Label** | text | Label or name for the location | | **TimeZone** | text | Time zone of the location | | **Description** | text | Description of the location | | **ExternalId** | text | External identifier for the location | | **Coordinate_X** | number | X-coordinate of the location | | **Coordinate_Y** | number | Y-coordinate of the location | | **PrimaryContactName** | text | Name of the primary contact for the location | | **PrimaryContactEmail** | text | Email of the primary contact | | **PrimaryContactPhone** | text | Phone number of the primary contact | | **HasPostalAddressId** | text | Identifier of associated postal address | | **Tag\_\*** | any | Each location-specific tag is represented as an individual column, making it effortless to access and filter data based on each tag | | **CreatedAt** | datetime | Timestamp of creation | | **UpdatedAt** | datetime | Timestamp of last update | | **CreatedBy** | text | Creator of the location | | **UpdatedBy** | text | Last updater of the location | Note: Prefiltered tables are also available for Campus, Building, Floor, and Room location types. ## LocationTags The LocationTags table is used to store information about tags associated with various physical locations within smart buildings and infrastructure. Tags provide additional details and categorization for locations. | **Column Name** | **Data Type** | **Description** | | --------------- | ------------- | ----------------------------------------------------------------------------------------------------------- | | **LocationId** | text | The identifier for a specific location | | **TagName** | text | The name of the tag associated with the location | | **TagValue** | any | The value of the tag, which can be of various data types, providing specific information about the location | ## EquipmentTypes The EquipmentTypes table defines various types of equipment used within the building. It categorizes equipment types and provides descriptive details. | **Column Name** | **Data Type** | **Description** | | ------------------- | ------------- | --------------------------------------------- | | **Id** | text | Unique identifier for equipment types | | **Type** | text | Type of equipment | | **PartitionId** | text | Identifier of the associated partition | | **Name** | text | Name of the equipment type | | **Description** | text | Description of the equipment type | | **Domain** | text | Domain or category of the equipment type | | **Deprecated** | text | Indicates if the equipment type is deprecated | | **Iri** | text | Model description for the equipment type | | **HasParentTypeId** | text | Identifier of the parent equipment type | | **HasParentType** | text | Type of the parent equipment type | | **CreatedAt** | datetime | Timestamp of creation | | **UpdatedAt** | datetime | Timestamp of last update | | **CreatedBy** | text | Creator of the equipment type | | **UpdatedBy** | text | Last updater of the equipment type | ## Equipment The Equipment table contains detailed information about specific equipment within the building, such as devices, machinery, or systems. | **Column Name** | **Data Type** | **Description** | | ---------------------- | ------------- | ----------------------------------------------- | | **Id** | text | Unique identifier for equipment | | **PartitionId** | text | Identifier of the associated partition | | **EquipmentTypeId** | text | Identifier of the associated equipment type | | **Name** | text | Name of the equipment | | **Notes** | text | Additional notes or information about equipment | | **ExternalId** | text | External identifier for equipment | | **SerialNumber** | text | Serial number of the equipment | | **Model** | text | Model information for the equipment | | **ManufacturingYear** | number | Year when the equipment was manufactured | | **ManufacturedBy** | text | Manufacturer of the equipment | | **InstallationDate** | datetime | Date when the equipment was installed | | **IsControlledById** | text | Identifier of the controlling equipment | | **IsControlledByType** | text | Type of the controlling equipment | | **IsPartOfId** | text | Identifier of the parent equipment | | **IsPartOfType** | text | Type of the parent equipment | | **FeedsId** | text | Identifier of equipment feeds | | **FeedsType** | text | Type of equipment feeds | | **LocationId** | text | Identifier of the associated location | | **LocationType** | text | Type of the associated location | | **CreatedAt** | datetime | Timestamp of creation | | **UpdatedAt** | datetime | Timestamp of last update | | **CreatedBy** | text | Creator of the equipment | | **UpdatedBy** | text | Last updater of the equipment | ## Devices The Devices table contains information about various devices within the building, including their specifications and connections. | **Column Name** | **Data Type** | **Description** | | ------------------- | ------------- | --------------------------------------------- | | **Id** | text | Unique identifier for devices | | **PartitionId** | text | Identifier of the associated partition | | **ModelName** | text | Name or model of the device | | **SerialNumber** | text | Serial number of the device | | **ProfileName** | text | Name of the device's profile | | **ProfileNotes** | text | Additional notes or details about the profile | | **HasGatewayType** | text | Type of the associated gateway | | **HasGatewayId** | text | Identifier of the associated gateway | | **HasLocationType** | text | Type of the associated location | | **HasLocationId** | text | Identifier of the associated location | ## Points The Points table contains individual data points collected from various building systems, such as sensors and meters. | **Column Name** | **Data Type** | **Description** | | ---------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Id** | text | Unique identifier for data points | | **PartitionId** | text | Identifier of the associated partition | | **DeviceId** | text | Identifier of the associated device | | **EquipmentId** | text | Identifier of the associated equipment | | **PointGroupId** | text | Identifier of the associated point group | | **Name** | text | Name or label of the data point | | **Description** | text | Description of the data point | | **DataType** | text | Type of data collected (e.g., temperature, humidity) | | **IsActive** | logical | Indicates if the data point is active or not | | **Unit** | text | Measurement unit of the data point | | **SourceType** | text | Type of point source (e.g., PointNB) | | **Minimum** | number | Minimum value recorded for the data point | | **Maximum** | number | Maximum value recorded for the data point | | **Precision** | number | Precision or accuracy of the data point | | **CommandingSemantic** | text | Semantic information for commanding the point | | **Function** | text | Function or purpose of the data point | | **Tag\_\*** | any | Each point-specific tag is represented as an individual column, making it effortless to access and filter data based on each tag value | | **CreatedAt** | datetime | Timestamp of creation | | **UpdatedAt** | datetime | Timestamp of last update | ## PointTags The PointTags table is designed to store information about tags associated with data points or measurements within the smart building and infrastructure system. These tags help categorize and provide context for data points. | **Column Name** | **Data Type** | **Description** | | --------------- | ------------- | --------------------------------------------------------------------------------------------------------------- | | **PointId** | text | The identifier for a specific data point or measurement | | **TagName** | text | The name of the tag associated with the data point | | **TagValue** | any | The value of the tag, which can vary in data type, providing specific information or context for the data point | All tags defined with the data point are included, regardless of the value of the *PointTagsFilter* parameter, to reflect the data point configuration. ## PointValues The PointValues table stores the actual values of data points collected over time. | **Column Name** | **Data Type** | **Description** | | ------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Id** | text | Unique identifier for data point values | | **PartitionId** | text | Identifier of the associated partition | | **PointId** | text | Identifier of the associated data point | | **Timestamp** | datetime | Timestamp of the data point value | | **Value** | text | Actual value recorded at the timestamp | | **QualityOfValue** | numeric | Measurement reliability using the following values: 0: Good - Signifying high-quality, trustworthy data. 1: Bad - Generic Error - Denoting unclear or unspecified issues. 2: Bad - Communication Error - Indicating problems in data transmission. 3: Bad - Configuration Error - Relating to errors in system setup. 4: Bad - Off-Normal - Highlighting measurements outside expected parameters (user defined). 5: Bad - Gap - Identifying missing or incomplete data (user defined). | ## EnergyMediumConsumptions The EnergyMediumConsumptions table contains information about energy medium consumptions. | **Column Name** | **Data Type** | **Description** | | --------------- | ------------- | --------------------------------------------------------- | | **Id** | text | Unique identifier for energy medium consumptions | | **PartitionId** | text | Identifier of the associated partition | | **Name** | text | Name of the energy medium consumption | | **Disciplines** | record | Disciplines associated with the energy medium consumption | | **Reference** | record | Reference information for the energy medium consumption | ## EnergyMediumConsumptionValues The EnergyMediumConsumptionValues table stores the values of energy medium consumptions over time. | **Column Name** | **Data Type** | **Description** | | ----------------------- | ------------- | ------------------------------------------------------- | | **MediumConsumptionId** | text | Identifier of the associated energy medium consumption | | **PartitionId** | text | Identifier of the associated partition | | **Timestamp** | datetime | Timestamp of the energy medium consumption value | | **Value** | number | Actual value recorded at the timestamp | | **Unit** | text | Measurement unit of the energy medium consumption value | ## EnergyMediumConsumptionEmissions The EnergyMediumConsumptionEmissions table stores information about emissions associated with energy medium consumptions. | **Column Name** | **Data Type** | **Description** | | ----------------------- | ------------- | ---------------------------------------------------------- | | **MediumConsumptionId** | text | Identifier of the associated energy medium consumption | | **PartitionId** | text | Identifier of the associated partition | | **Timestamp** | datetime | Timestamp of the energy medium consumption emission | | **Value** | number | Actual value recorded at the timestamp | | **Unit** | text | Measurement unit of the energy medium consumption emission | ## EnergyMediumConsumptionCosts The EnergyMediumConsumptionCosts table stores information about costs associated with energy medium consumptions. | **Column Name** | **Data Type** | **Description** | | ----------------------- | ------------- | ------------------------------------------------------ | | **MediumConsumptionId** | text | Identifier of the associated energy medium consumption | | **PartitionId** | text | Identifier of the associated partition | | **Timestamp** | datetime | Timestamp of the energy medium consumption cost | | **Value** | number | Actual value recorded at the timestamp | | **Unit** | text | Measurement unit of the energy medium consumption cost | # Security Manager Access PACS SDK Building X's existing customers rely on on-premises legacy Physical Access Control Systems (PACS). These systems hold valuable data, which we can import. For more details, please have a look at the SDK documentation. The Security Manager Access PACS SDK is a comprehensive Software Development Kit tailored for software developers from both partners and end customers. It caters to those seeking to seamlessly integrate third-party access control systems into Building X. ## Key Benefits Our PACS SDK serves as a robust toolset, enabling smooth and efficient integration of third-party access control systems into Building X. - The PACS SDK allows the integration of any third-party access control system into Building X, tailored to meet diverse customer requirements. - Experience advanced access capabilities to enrich your software applications. - One SDK provides a unified approach for seamless integration with third-party access control systems. - Detailed documentation supports developers throughout the development process. ## Request To request the Security Manager Access PACS SDK, please use the [form](https://forms.office.com/r/eenQfQQvy3). # Security Manager Access Mobile SDK The Security Manager Access Mobile SDK from Siemens empowers you to integrate access functionality into your own mobile applications. With this SDK, your custom mobile apps can unlock doors by simply holding the mobile device up to a reader. The SDK is available for both Android and iOS platforms. ## Key Benefits Make the most of the advanced access functionality offered by our Mobile SDK to enhance your mobile applications. Seamlessly integrate Siemens security solutions for a superior user experience. - One SDK for seamless integration with all vendor systems. - Easy-to-use API for quick and efficient integration. - Comprehensive documentation to support development. ## Request To request the Security Manager Access Mobile SDK, please use the [form](https://forms.office.com/r/aAAGCc9DYG).