> ## 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 (also called a datasource) is the configured instance of an integration that connects KODE OS to a specific external system. This guide covers the full lifecycle of a connector -- from initial setup through daily operations.
## 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/password, API key, OAuth client credentials, or certificates
* **Dynamic fields** -- Some integrations show additional fields (e.g., Organization ID, Site ID) that are automatically populated 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 pre-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, must not be 00:00) |
Each integration defines minimum and maximum polling intervals. The configuration will prevent you from setting 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 if no data is received
* The ping frequency for health checks
## Connector Detail Page
After creating a connector, the connector detail page provides a central dashboard for managing it. This page is divided into several sections.
### Status and Controls
| Control | Description |
| -------------------- | -------------------------------------------------------------------------------------------- |
| **Current Status** | Shows whether the connector is currently up or down |
| **Enable / Disable** | Toggle to activate or deactivate the datasource (requires confirmation) |
| **Test Connection** | Verify that the credentials and configuration are valid by connecting to the external system |
| **Discover** | Initiate discovery for devices, schedules, or assets |
| **Refresh Cache** | Manually trigger a cache refresh for the connector's data |
| **Delete** | Permanently remove the connector from the system (requires confirmation) |
### Discovery Statistics
Track the state of discovered entities:
| Statistic | Description |
| ------------- | ------------------------------------------------------------------------------ |
| **Devices** | Count of Discovered / Saved / Templated devices, with last discovery timestamp |
| **Schedules** | Count of Discovered / Saved schedules, with last discovery timestamp |
| **Assets** | Count of Discovered / Saved assets, with last discovery timestamp |
### Entity Details
Each enabled entity type has its own section showing:
* **Collection Chart** -- Visual timeline of data collection count over time
* **Enable / Disable** -- Toggle the entity on or off (requires confirmation)
* **Polling Frequency** -- Current interval and the ability to adjust it
* **Non-Sensor Table** -- If the entity is a non-sensor type (alarms, audit logs, work orders), a table view of collected records
### Timeseries Chart
A chart showing the connector's collected timeseries data over time, providing a quick visual indicator of data flow health.
### Error Logs
A table of recent errors encountered during collection, authentication, or discovery. Each log entry includes a timestamp, error type, and message.
### Activity Log
Historical log of all operations performed 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 relying on a connector for data collection, test it:
1. Navigate to the connector detail page
2. Click **Test Connection**
3. KODE OS authenticates with the external system using the configured credentials
4. 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
To update a connector's configuration:
1. Navigate to the connector detail page
2. Edit the fields you need to change (credentials, polling frequency, entity enablement)
3. Save the changes
4. Run **Test Connection** to verify the updated settings work
## Deleting a Connector
Deleting a connector is permanent and cannot be undone. All associated devices, points, and collected data references are removed.
To delete a connector:
1. Navigate to the connector detail page
2. Click **Delete**
3. Confirm the deletion in the confirmation 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 error 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 is working 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" (the device may be offline in the external system), and vice versa. If the connector status is "Down," check credentials and network connectivity first.