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 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 datapoints collected from various building systems, such as sensors and meters.
- PointTags: This table is designed to store information about tags associated with datapoints or measurements within the smart building and infrastructure system. These tags help categorize and provide context for datapoints.
- PointValues: This table stores the actual values of datapoints collected over time.
The following tables and functions are exposed by the Energy API subscription:
- EnergyMediumConsumptions: This table contains information about energy medium consumptions.
- EnergyMediumConsumptionValues: This table stores the values of energy medium consumptions over time.
- EnergyMediumConsumptionEmissions: This table stores information about emissions associated with energy medium consumptions.
- EnergyMediumConsumptionCosts: This table stores information about costs associated with energy medium consumptions.
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 data set 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 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 that is equipped with the appropriate roles and partitions. Only partitions assigned to the machine user can be used as 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 download 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 datasource credentials. By following these steps, you can ensure that the dataset remains current and that you can gain valuable insights from your data in Power BI.
- Download the Power BI dataset (.pbix file) that you want to import into the Power BI service environment.
- Open Power BI service environment by navigating to the Power BI service site and sign in with your credentials.
- On the Power BI service environment, select the My Workspace tab on the left-hand side of the screen.
- Select the Import button located at the top of the screen.
- In the Import a file section, select the Upload button.
- Select the downloaded Power BI dataset (.pbix file) from your computer and select the Open button.
- After the file is uploaded, the dataset will be imported into Power BI service environment. Wait for the import process to complete.
- 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.
- 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.
- 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.
- To refresh the imported dataset, select the ellipsis (...) button that appears when hovering over the dataset in the Power BI service environment.
- 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:
- For the datasource credentials, select Anonymous as the authentication type.
- Choose Organizational as the authentication type for the datasource credentials.
- Skip the testing of the connection by checking the provided checkbox.
The behavior of Anonymous and Organizational datasource credentials is as follows:
- Anonymous: Selecting Anonymous as the datasource 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 datasource 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 datasource 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 data set 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 data set 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 and 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 to retrieve 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 to retrieve 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, 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 datasources 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.
- Open the Query Editor in Power BI Desktop.
- Go to the Tools page and select Start Diagnostics.
- On the Home page, select Refresh all.
- Go to the Tools page, select Stop Diagnostics.
- In the Queries pane, navigate to the Diagnostics navigation tree and locate the table that starts with Diagnostics_Detailed.
- Open this table and apply the following filters:
- [Category] equals Data Source.
- [Data Source Kind] equals Web.
- [Resource] contains api.bpcloud.siemens.com.
- 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. In addition, 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, and 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, it\'s essential to 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] \<table> 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 will ensure 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_\<tagname>\' 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.