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.

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.
   2. Open the Mendix app into which you want to import the 'Building X Connector for Mendix'.
2. 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.
3. Search for the Connector:
   1. In the Marketplace search bar, type 'Building X Connector for Mendix'.
   2. Press Enter to search.
4. Select the Connector:
   1. From the search results, find the 'Building X Connector for Mendix'.
   2. Select the Connector to view its details.
5. 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.
   2. Select Add to proceed.
6. 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.
7. 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.
8. Test Your App:
   1. Once the Connector is integrated, thoroughly test your app to ensure it works as expected.
9. 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.

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.
2. 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.

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:

Parameter Categories¶

When performing actions with the Building X Connector, various parameter categories are utilized to configure the requests:

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.

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.

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	Operations API ReadWrite	Creates a new alarm configuration.
Add Device	bx_Device_Create	token (Token) partitionId (String) device (DeviceEntity)	DeviceEntity	Building Operations API	Operations API ReadWrite	Creates a new device.
Add Equipment	bx_Equipment_Create	token (Token) equipment (EquipmentEntity)	EquipmentEntity	Building Structure API	Structure API ReadWrite	Creates new equipment.
Add Point	bx_Point_Create	token (Token) point (PointEntity)	PointEntity	Building Structure API	Structure API ReadWrite	Creates a new point.
Update Alarm Configuration	bx_AlarmConfiguration_Update	token (Token) alarmConfiguration (AlarmConfigurationEntity)	AlarmConfigurationEntity	Building Operations API	Operations API ReadWrite	Updates an alarm configuration.
Update Device	bx_Device_Update	token (Token) partitionId (String) device (DeviceEntity) updateLocation (Boolean)	DeviceEntity	Building Operations API	Operations API ReadWrite	Updates a device.
Update Equipment	bx_Equipment_Update	token (Token) equipment (EquipmentEntity) updateLocation (Boolean)	EquipmentEntity	Building Structure API	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	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	Operations API ReadWrite	Deletes an alarm configuration.
Delete Device	bx_Device_Delete	token (Token) device (DeviceEntity)	Nothing	Building Operations API	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	Structure API ReadWrite	Deletes equipment.
Delete Point	bx_Point_Delete	token (Token) point (PointEntity)	Nothing	Building Structure API	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	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	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	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	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	Operations API Read	Retrieves a list of alarm configurations.
Get Device	bx_Device_Get	token (Token) partitionId (String) deviceId (String)	DeviceEntity	Building Operations API	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	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	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	Operations API Read	Retrieves a list of device event transitions.
Get Equipment	bx_Equipment_Get	token (Token) equipmentId (String)	EquipmentEntity	Building Structure API	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	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	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.

Security¶

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.

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.
2. If the equipment does not exist, create it.
3. 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.
4. Search for the point within the point group by its name.
5. If the point does not exist, create it within the point group for the equipment.
6. 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.