> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Managing connectors
> Configure, test, monitor, and manage your integration connectors in KODE OS
> 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](/products/integrations/get-started/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** — Some integrations show additional fields (for example, Organization ID or Site ID) after valid credentials are entered
Click `Next` to proceed once the fields are filled and validated.
### 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:
| Setting | Description |
| ------------ | ------------------------------------------------------------------------------ |
| **Unit** | Time unit for the interval (seconds, minutes, hours, days) |
| **Interval** | How many units between each collection cycle |
| **Start At** | The time of day to begin the first collection (HH:mm format; do not use 00:00) |
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
| Control | Description |
| -------------------- | ---------------------------------------------------------------------- |
| **Current Status** | Shows whether the connector is currently up or down |
| **Enable / Disable** | Toggle to activate or deactivate the connector (requires confirmation) |
| **Test Connection** | Verify that the credentials and configuration are valid |
| **Discover** | Start discovery for devices, schedules, or assets |
| **Refresh Cache** | Manually refresh the connector's cached data |
| **Delete** | Permanently remove the connector (requires confirmation) |
### Discovery statistics
| Statistic | Description |
| ------------- | -------------------------------------------------------------------------------- |
| **Devices** | Count of discovered, saved, and templated devices, with last discovery timestamp |
| **Schedules** | Count of discovered and saved schedules, with last discovery timestamp |
| **Assets** | Count of discovered and saved assets, with last discovery timestamp |
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
### 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.
Navigate to the connector detail page from `Data Sources`.
Click `Test Connection`. KODE OS authenticates with the external system using the configured credentials.
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
Navigate to the connector detail page.
Update credentials, polling frequency, or entity enablement as needed.
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.
Navigate to the connector detail page.
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.
Dynamic fields appear only after valid credentials are entered and validated. Ensure the base URL and authentication fields are correct. Try clicking out of the last field or pressing Tab to trigger validation.
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.