Self-Serve Connector View
Connector view
The Connector view transforms how you interact with API data sources in KODE OS. It moves beyond a static view to a dynamic and powerful command center, giving you real-time visibility and control over your data integrations.
To open the Connector view,
In Data Sources, select a data connection. The Connector View for that data connection appears, displaying the Analytics tab.
Connection details and activity
There are four buttons in the upper-right corner of the page that enable you to view the details of the data connection, view connection activity, and edit the connection.
Test Connections:
Details: Opens the Details panel, showing the details of the data connection.
Activity: Opens the Activity panel. You can select a date range [???]
Three-dots: Opens the Options menu. You can edit or delete the data connection and discover schedules.
Manage your connections
This article provides instructions on how to monitor, configure, and troubleshoot your data connections to help ensure operational efficiency. The connector view is divided into two tabs: Health and Analytics.
Analytics tab
The Analytics tab provides a detailed look into the data collected by your connector and provides discovery statistics. It helps you understand the volume of data processed and the status of discovered devices and points.
Overview
This section provides a high-level summary of the entities discovered and managed by the connector.
Devices: The number of discovered devices is shown here, along with a health status badge (for example, 75% OK). The modeled vs total metric indicates how many of the discovered devices have been successfully modeled within the system.
Points: This shows the total number of data points discovered, with a breakdown of how many are modeled versus the total discovered.
Schedules: Displays the number of schedules. Click View All to open the Schedules List.
Assets: Displays the number of assets. Click View All to open the Devices List.
Data Stream
The Data Stream section provides valuable insights into the volume and health of your data collection.
Collection Activity: Shows the total number of items collected In Range (in the last 7 days) and All time. It also provides a timeline of the next and last collection times and indicates how long the connector has been active.
Data Stream Graph: A detailed bar graph displays the collection activity over time. Green bars represent items that were successfully collected, while red bars show items that failed. This visual aid is crucial for identifying trends or sudden drops in data collection.
Viewing Data Collection Metrics
On the Analytics → Data Stream page, you can choose between two types of metrics:
Records Collected – Shows how many records have been collected from a specific API or data stream.
Collection Frequency – Shows how often data is being collected from the source or how often we attempted collection.
Example Usage
Select a data stream, such as CFS API, which contains a variety of records collected at different time intervals.
Choose the desired metric:
Records Collected – View the number of records collected over a specific time frame.
Collection Frequency – View how often the system collects data.
This view helps identify potential issues in data collection or confirm that the data stream is running as expected
Using Live Updates for Real-Time Monitoring
Live Updates button has been added to the data source view, enabling:
Real-time updates on the screen whenever a request is made to the API.
Monitoring specific data sources live, useful for debugging or client demonstrations.
To use:
Navigate to a specific data source.
Click Live Updates.
Observe the data refreshing as API requests occur.
This feature allows immediate insight into the system’s data collection process:
Benefits of the Data Stream Section
With these updates, users can:
Differentiate between the number of records collected and collection frequency.
Monitor hourly, daily, or weekly data streams for consistency.
Export detailed collection data for analysis.
View live updates to track real-time data collection.
These tools improve monitoring, debugging, and reporting on data stream activity.
Modify data collection frequency
To modify the data collection frequency,
On the Analytics tab, go to the Collection Activity section.
Click the pencil icon next to the current frequency setting. The Data Collection Status pop-up window appears.
Choose a new frequency from the available options.
Every: Positive number.
Time: Seconds, Minutes, Hours, or Days.
Click Apply.
Pause data collection
To pause data collection for an entity.
On the Analytics tab, go to the Collection Activity section.
Click the pencil icon next to the current frequency setting. The Data Collection Status pop-up window appears.
To the left of Data Collection Status click the slider off.
Click Apply. The connector stops fetching and storing data from that entity.
You can always restart data collection by clicking the slider on.
Health tab
The Health tab provides a real-time overview of the connector's operational status and helps you quickly identify and diagnose issues.
Uptime activity
This section offers a visual and numerical summary of your connector's performance.
Failures: The number of failures that have occurred in the selected date range is displayed prominently. A failure is an event where the connector was unable to collect data.
Uptime: The uptime percentage shows the proportion of time the connector has been running successfully.
Uptime Graph: A color-coded bar graph visualizes periods of uptime and downtime. Green sections indicate periods when the connector was up, while red sections indicate it was down.
The default time period is seven days. Use the calendar to select a different date range. You can choose from: Yesterday,
Last 2 Days, Last 7 Days, Last 30 Days, This Month, or another date.
Error Logs
The error logs in the Connector Details view are designed to make issue resolution straightforward and efficient. To access them, go to the Error Logs section within the Connector Details page by navigating to Health section. Each error includes a clear explanation of what occurred, recommended actions, and the associated raw logs for reference.
Clicking on an individual error provides additional context, such as its category and detailed guidance for addressing it. Errors are displayed in sequence, allowing users to track recurring issues and identify patterns over time. An export option is also available to download the full raw error log, which can be used for deeper troubleshooting or sharing with external teams.
Viewing Errors
Open the Connector Details view and navigate to the Error Logs section.
Select a specific API to view its errors.
Errors are displayed with:
Meaning of the error
Suggested actions
All raw error logs, including timestamps and original API messages
Understanding Error Categories
Click on an error to see the category it belongs to and recommend next steps.
Example: An “Authentication” error will show the cause and suggested actions.
Tracking Multiple Errors
If a data source has gone up and down multiple times, all occurrences will be listed.
This helps identify recurring issues and patterns in connectivity or API behavior.
Exporting Logs
Use the Export function to download all error logs, Name the file and select the needed filters.
This is useful for sharing with external teams or for in-depth troubleshooting.
The Error Logs table provides granular detail on each failure event, which is essential for troubleshooting.
Date and Time: Displays the exact timestamp of each error, helping you correlate a failure with a specific event or change.
Error Message: Provides a concise description of the error, such as a connection timeout or a refusal to connect.
Select a log entry to view more detailed information about the cause of the failure.
The Connector Details view includes enhancements designed to simplify error management and troubleshooting. Error messages are displayed in a clear, human readable format, making it easier to quickly understand what is happening with a data source. Each error provides a description of the issue, the most recent occurrence timestamp, and recommended actions, allowing users to take informed steps toward resolution.
Error logs are now displayed in a clear, easy-to-understand format.
Users can quickly identify when a data source is offline and view the last occurrence of the error.
Suggested actions are provided for each error, helping users know exactly what steps to take.
Second, errors are categorized into predefined groups, such as connection timeout, authentication issues, and network outages. This categorization helps users identify the type of problem and understand its implications. Finally, all errors are logged in detail with timestamps and original API messages, and they can be exported for sharing or further analysis. These informations collectively improve transparency, usability, and efficiency when managing connector errors.
Errors are grouped into defined categories to simplify troubleshooting.
Categories Include:
Connection Timeout
Request Timeout
Connection Closed (e.g., handshake failure)
Unreachable Network (proxy down)
VPN Down (data source offline)
Authentication Error
Gateway Not Reachable
Each category includes a clear explanation and recommended user actions.
Additional Resources
For more detailed information on error types and recommended resolutions, we can refer to the Error Categorization Documentation, which provides comprehensive explanations of each error category, its meaning, and suggested actions. The Connector Health Page is also a useful tool for real-time monitoring of APIs and data sources, helping users stay informed about the current status and quickly address any connectivity issues. These resources complement the updated error logs and offer additional guidance for maintaining data source health and performance.
Troubleshooting Common Issues
Use the information available in the new view to diagnose and resolve issues with your connector.
Check the Activity log. If you notice an unexpected dip in the uptime graph, review the activity log to see if any recent changes were made to the connector that might have caused the issue.
Verify connection details. If the connector is experiencing failures, check the connection details in the Edit view to ensure the API keys or URLs are correct.
Cross-reference with the Data Stream graph. Look for a correlation between recent changes in the activity log and any changes in the data collection activity graph. A configuration change might have impacted the number of successful items.
Step-by-Step Data Source Setup with Dynamic ID Discovery
Overview
When configuring API connectors, identifying the correct Site ID or Building ID can be one of the most time consuming steps. In many cases, these IDs are not readily available and require coordination with clients or vendors to confirm the correct values.
For supported APIs, the platform retrieves these identifiers directly from the API during setup. This allows users to validate credentials and select the appropriate IDs without needing to request them separately.
This article explains how the process works and when it applies.
How Dynamic ID Retrieval Works
For APIs that support identifier queries, the configuration process follows a guided flow after clicking on ‘Add New Connector’:
1. Enter Authentication Credentials
Depending on the API, this may include:
URL
Email and password
orURL and API key
2. Validate Credentials
After entering credentials, select Validate.
If authentication is successful:
The system confirms access
The next configuration step becomes available
3. Select Available IDs
Once credentials are validated:
The system queries the API
All accessible Site IDs and/or Building IDs are retrieved
The available options are displayed for selection
Only identifiers associated with the validated account will appear. This removes the need to manually request or confirm IDs before proceeding.
4. Complete Connector Configuration
After selecting the appropriate ID:
Configure required data streams
Define collection frequency
Review configuration details
Finalize connector setup
After completing this steps, click next and review the details and submit.
Important Notes
This functionality is available only for APIs that allow querying Site or Building IDs through their endpoints.
Not all APIs support dynamic ID retrieval.
If an API does not expose identifiers, IDs must be provided manually during configuration.
This is already completed and it’s live for the below APIs, with more coming as long as the vendor APIs support ID discovery.
CF Connect
Tork
Cove
Vantify
Kontakt
Helvar
Related Articles
Building BI - Data Sources
Building BI - Data Sources In order for Building BI to calculate and display data, it needs a Data Source. This is where all metrics, calculations, and columns originate from. Because of this, the Data Source section exists to define what data ...Navigating to Data Sources - Mobile App
To see the number and status of all integrated systems you can rely on Data Sources. Data Source is a network controller which interconnects multiple devices with KODE OS. Navigate to a building of your choice through the Sites feature in the ...Adding a new Data Source in KODE OS
The following steps will guide you on how to add a data source and import the necessary data. 1. Click on the site of your choice. 2. Navigate through the options on the left side and select "Data Sources". 3. A comprehensive list of all existing ...Multi-Point Trending
Multi-Point Trending is a powerful tool that helps building operators track and compare data from multiple devices, like chillers, pumps, AHUs, and fans, on a single chart. This feature makes it easy to monitor how different systems interact, ...Table View and Device Details Export
You usually monitor device performance, status, history, and interact with devices to increase optimum performance, but what if you could also view the device history as a table or line chart and export it as a CSV file instead? With the data ...