Skip to main content
Configure, test, monitor, and manage your integration connectors in KODE OS
A connector is the configured instance of an integration that connects KODE OS to a specific external system. Connectors appear on the Data Sources page. This guide covers the full lifecycle of a connector, from initial setup through daily operations. If you have not created a connector yet, start with the Quickstart.

Adding a connector

The connector setup follows a three-page configuration flow.

Page 1 — Credentials and settings

Enter the required connection details for the integration. The exact fields vary by integration, but typically include:
  • URL — The base URL or IP address of the external system
  • Authentication — Username and password, API key, OAuth client credentials, or certificates
  • Dynamic fields — Vendor lists such as sites, locations, stores, and similar values, loaded after you select Validate Credentials

Validate credentials

After you select Validate Credentials, KODE OS loads vendor fields in the background and shows progress. Vendor fields include sites, locations, stores, and similar lists. Errors state the cause, such as authentication failed, vendor timed out, or vendor error, and you can retry. When a vendor returns no options for a multi-select vendor field, type comma-separated IDs into that field and save. Click Next to proceed once the fields are complete.

Page 2 — Entity enablement

Toggle which data entities you want this connector to collect. Each integration supports one or more entity types:
  • Point History — Time-series sensor data
  • Audit Log — Access and security events
  • Alarm — Alert and fault notifications
  • Work Order — Maintenance task records
  • Schedule Sync — Schedule state synchronization
Entity toggles are enabled by default. Disable any entity types you do not need for this connector.

Page 3 — Polling frequency

Configure how often KODE OS collects data for each enabled entity: Each integration defines minimum and maximum polling intervals. The configuration prevents values outside the allowed range. If Collect Data Ping is enabled, you can also configure:
  • The threshold for marking connectors, devices, or points as inactive when no data is received
  • The ping frequency for health checks
Collect Data Ping is a health check that watches whether data still arrives on schedule. When it is enabled, KODE OS can mark connectors, devices, or points inactive if no data arrives within the threshold you set.

Connector detail page

After you create a connector, the connector detail page is the central place to manage it.

Status and controls

Discovery statistics

Templated devices are devices that already have an ontology or device template applied in Cloud BMS.

Entity details

Each enabled entity type has its own section showing:
  • Collection chart — Timeline of data collection count over time
  • Enable / Disable — Toggle the entity on or off (requires confirmation)
  • Polling frequency — Current interval and controls to change it
  • Non-sensor table — For non-sensor entities (alarms, audit logs, work orders), a table of collected records
Each non-sensor data table shows which date column the start and end range applies to. Examples include Created At (Local) and Collected At. Entities without a date filter column show no label.

Timeseries chart

A chart of the connector’s collected time-series data over time. Use it as a quick visual check of data flow health.

Error logs

A table of recent errors from collection, authentication, or discovery. Each entry includes a timestamp, error type, and message.

Activity log

A historical log of operations on this connector, including configuration changes, discovery runs, and status changes.

Webhook configuration

For webhook-based integrations, this section displays:
  • The webhook URLs that the external system should send data to
  • The expected payload structure for each URL
  • Verification status

Testing a connection

Before you rely on a connector for data collection, test it.
1

Open the connector

Navigate to the connector detail page from Data Sources.
2

Run Test Connection

Click Test Connection. KODE OS authenticates with the external system using the configured credentials.
3

Review the result

The result shows Success or Failed with an error message.A successful test confirms that:
  • The URL is reachable from KODE OS
  • The credentials are valid
  • The API version or driver version is compatible
  • The external system is responding correctly

Modifying a connector

1

Open the connector

Navigate to the connector detail page.
2

Edit settings

Update credentials, polling frequency, or entity enablement as needed.
3

Save and retest

Save the changes, then run Test Connection to verify the updated settings.

Deleting a connector

Deleting a connector is permanent and cannot be undone. All associated devices, points, and collected data references are removed.
1

Open the connector

Navigate to the connector detail page.
2

Delete

Click Delete and confirm in the dialog.

Troubleshooting

Verify the URL is correct and reachable from the KODE OS network. Check that firewalls allow outbound connections on the required port. Ensure the credentials have not expired. For OAuth integrations, you may need to regenerate the client secret.
A down status means the last collection attempt failed. Check the error logs on the connector detail page for specific messages. Common causes include expired credentials, network changes, or the external system being temporarily unavailable.
Verify the entity is enabled on the connector detail page. Check that the polling frequency is within the allowed range. If the entity was recently enabled, wait for the first polling interval to pass before data appears.
Select Validate Credentials after you enter the connection details. KODE OS loads vendor fields in the background and shows progress.If the load fails, the error states the cause, such as authentication failed, vendor timed out, or vendor error. You can retry after you read that message.When a vendor returns no options for a multi-select vendor field, type comma-separated IDs into that field and save.
The connector status and individual device statuses are independent. The connector status verifies that the connection to the external API works and that the credentials are valid. Individual device statuses reflect whether each device is reporting data. A connector can show Up while a device shows Down, and the reverse can also happen. If the connector status is Down, check credentials and network connectivity first.
Last modified on November 2, 2026