Connector Management¶

This guide covers the day-to-day operations of managing connectors: CRUD operations, versioning, lifecycle management, and impact analysis.

Listing Connectors¶

API¶

GET /api/connectors?page=1&pageSize=20

Supports filtering via advanced filter syntax:

GET /api/connectors?where=name:contains:crm
GET /api/connectors?where=type:eq:http
GET /api/connectors?includeDeleted=true

UI¶

Navigate to Connectors in the sidebar. The list view shows:

Name, type, execution model
Category and tags
Version and schema version
Enabled/disabled status
Mock mode status
Last updated timestamp

Use the search bar and filters at the top to narrow results.

Viewing Connector Details¶

UI Tabs¶

The connector detail view has seven tabs:

Tab	Contents
Overview	Metadata, version, category, tags, execution model, enabled status
Configuration	Connection config form, `configSchema` display
Commands	List of available commands with params and outputs, inline execution
Script	Monaco editor with `floh.*` autocompletion for script source
Mocks	Mock data editor, mock script editor, mock toggle
Logs	Filtered system logs for this connector with level and time range filters
Impact	Affected workflows and steps using this connector

Updating Connectors¶

API¶

PUT /api/connectors/:id
Content-Type: application/json

{
  "description": "Updated description",
  "version": "1.1.0",
  "logLevel": "debug",
  "mockEnabled": true,
  "tags": ["crm", "sales", "v2"],
  "category": "crm"
}

Updatable Fields¶

Field	Type	Description
`name`	string	Connector name
`description`	string	Description
`version`	string	Semantic version
`enabled`	boolean	Enable/disable the connector
`executionModel`	string	Execution model
`scriptSource`	string	JavaScript source code
`configSchema`	object	Schema definition
`logLevel`	string	Minimum log level
`debugLogging`	boolean	Enable debug-level logging override
`mockEnabled`	boolean	Enable mock mode
`mockData`	object	Static mock scenarios
`mockScript`	string	Dynamic mock script
`endpointUrl`	string	External connector URL
`schemaVersion`	string	Schema version tag
`category`	string	Category
`tags`	string[]	Tags array
`icon`	string	Icon identifier

Schema Versioning¶

Connectors track schema changes through schemaVersion. Before updating a connector's schema, use the compare endpoint to detect breaking changes.

Comparing Schemas¶

POST /api/connectors/:id/compare-schema
Content-Type: application/json

{
  "configSchema": {
    "commands": {
      "listUsers": {
        "params": ["limit", "filter"],
        "description": "List users",
        "outputs": ["users", "total"]
      }
    }
  }
}

Response¶

{
  "hasBreakingChanges": true,
  "suggestedBump": "major",
  "changes": [
    {
      "type": "breaking",
      "description": "New parameter \"filter\" added to command \"listUsers\" (no default — may be required)",
      "command": "listUsers",
      "field": "filter"
    }
  ]
}

Change Classification¶

Change Type	Examples	Version Bump
Breaking	Removed command, removed parameter, removed output, removed connection config field, new required parameter without default, new required connection config field	Major
Minor	New command, new parameter with default, new output, new optional connection config field	Minor
Patch	Description changes, non-structural changes	Patch

Version Bump Rules¶

Any breaking change → major bump suggested
Any minor change (no breaking) → minor bump suggested
Only patch changes → patch bump suggested
No changes → none

Impact Analysis¶

Before modifying or deprecating a connector, check which workflows depend on it.

API¶

GET /api/connectors/:id/impact

Response¶

{
  "connectorName": "my-crm",
  "totalWorkflows": 3,
  "totalSteps": 5,
  "affectedWorkflows": [
    {
      "workflowId": "wf-123",
      "workflowName": "Employee Onboarding",
      "version": 2,
      "status": "active",
      "stepsUsingConnector": [
        {
          "stepId": "step-4",
          "stepName": "Add to CRM",
          "command": "createContact",
          "paramsUsed": ["email", "firstName", "lastName"]
        }
      ]
    }
  ]
}

Impact Analysis Workflow¶

Before updating a connector, run impact analysis to see affected workflows
Compare the new schema against the current one to detect breaking changes
If breaking changes exist, review each affected workflow and update step configurations
Update the connector with the new schema and bumped version
Test affected workflows to verify they still function correctly

Lifecycle Management¶

Enabling/Disabling¶

Disabled connectors reject execution requests with a 400 error. Disable a connector to temporarily prevent its use without deleting it.

PUT /api/connectors/:id
{ "enabled": false }

Soft Delete and Restore¶

Soft-deleted connectors are hidden from the default list view but can be restored.

DELETE /api/connectors/:id

POST /api/connectors/:id/restore

Permanent Deletion¶

Only administrators can permanently delete connectors. This action is irreversible.

DELETE /api/connectors/:id/permanent

Deprecation¶

Mark a connector as deprecated to signal that it should no longer be used in new workflows:

PUT /api/connectors/:id
{ "deprecatedAt": "2026-03-01T00:00:00Z" }

Deprecated connectors continue to function but are flagged in the UI and impact analysis.

Logging¶

Per-Connector Log Level¶

Each connector has a configurable logLevel that controls which messages are emitted:

Level	Numeric	Use Case
`trace`	0	Detailed internal tracing
`debug`	1	Development debugging
`info`	2	Normal operations (default)
`warn`	3	Warning conditions
`error`	4	Error conditions
`fatal`	5	System-critical failures

Debug Override¶

Debug-level logging can be enabled three ways (any one activates debug output):

Per-connector flag — set debugLogging: true on the connector definition:

PUT /api/connectors/:id
{ "debugLogging": true }

Global server flag — set DEBUG_LOGGING=true in the environment to enable debug for all connectors.
Console debug — set CONNECTOR_DEBUG for stdout JSON logging (does not persist to the database):

CONNECTOR_DEBUG=true            # All connectors
CONNECTOR_DEBUG=my-crm,my-erp  # Specific connectors only

When debugLogging is enabled (per-connector or globally), the connector's logLevel is overridden to debug, and all execution events — call start/end, HTTP requests/responses, timeouts, and errors — are written to the system_log table with category connector.

Viewing Logs¶

In the connector detail view, the Logs tab shows filtered entries from the system_log table where connector_id matches the current connector.

Via API:

GET /api/logs?connectorId=<connector-id>&level=error&limit=100

Secret Key Rotation¶

Re-encrypt all connector secrets with a new encryption key:

Set CONNECTOR_ENCRYPTION_KEY_PREVIOUS to the current key
Set CONNECTOR_ENCRYPTION_KEY to the new key
Call the rotation endpoint:

POST /api/connectors/rotate-keys

The response includes counts of rotated, skipped, and failed connectors.

Audit Trail¶

All connector operations are logged to the audit system:

Action	Description
`connector.registered`	New connector created
`connector.updated`	Connector configuration updated
`connector.soft_deleted`	Connector soft-deleted
`connector.restored`	Connector restored from soft-delete
`connector.permanently_deleted`	Connector permanently removed
`connector.keys_rotated`	Encryption keys rotated

Configuration Transfer¶

Connectors are included in configuration transfer exports and imports. All fields including executionModel, scriptSource, mockData, category, tags, and schemaVersion are preserved during transfer.

GET /api/config-transfer/export?entities=connectors
POST /api/config-transfer/import