​

Adding a Connector (AI Agent Checklist)

Use this when introducing a new backend connector integration and wiring it through UI/API.

​

Scope

This checklist covers:

• connector bootstrap record
• verify dispatch wiring
• connector utility client + verifier
• route wiring
• frontend endpoint/UI integration

​

1) Add Connector to Seed Data

File: backend/app/db/db_populate.py Actions:

1. Update get_connectors_list() with your new connector tuple.
2. Pick exactly one auth mode flag via accepts_key:
   • host_only
   • api_key
   • username_password
   • file
3. If needed, define extra_data_key env var for connector_extra_data.
4. Ensure env var naming matches load_connector_data() prefix rule:
   • connector_name.upper().replace("-", "_").replace(" ", "_")

Result:

• connector appears in /api/connectors after startup seed.

​

2) Implement Connector Utility Module

File path (new): backend/app/connectors/<service>/utils/universal.py Minimum functions to provide:

1. verify_<service>_connection(connector_name: str)
2. create_<service>_client(connector_name: str = "<Connector-Display-Name>")

Implementation requirements:

• Pull credentials via get_connector_info_from_db from backend/app/connectors/utils.py.
• Return consistent verify payload:
  • {"connectionSuccessful": bool, "message": str}
• Raise HTTPException for hard failures in runtime client creation.

​

3) Register Verify Dispatch

File: backend/app/connectors/services.py Actions:

1. Import your verifier function.
2. Add service class (pattern: <ServiceName>Service) implementing verify_authentication.
3. Add mapping in get_connector_service() service_map:
   • key must match DB connector_name exactly.

If omitted, /api/connectors/verify/{id} will return unsupported/None behavior.

​

4) Add Connector Routes (If Exposing Feature APIs)

Typical files:

• backend/app/connectors/<service>/routes/*.py
• backend/app/connectors/<service>/services/*.py
• backend/app/connectors/<service>/schema/*.py

Router wiring:

1. Add/modify router module backend/app/routers/<service>.py.
2. Include route groups with appropriate prefixes/tags.
3. Add top-level include in backend/copilot.py:
   • from app.routers import <service>
   • api_router.include_router(<service>.router)

Without step 3, routes compile but are unreachable.

​

5) Frontend Endpoint Wiring

Primary files:

• frontend/src/api/endpoints/connectors.ts
• optional new endpoint file if connector has dedicated APIs (pattern in frontend/src/api/endpoints/*.ts)
• frontend/src/api/index.ts (export)

Checklist:

1. Reuse generic /connectors endpoints if only configuring/verifying credentials.
2. Add dedicated endpoint wrapper(s) for new connector-specific backend routes.
3. Ensure payload type definitions exist/update in frontend/src/types/*.d.ts.

​

6) Frontend UI Wiring

Connector configuration UI already exists:

• View: frontend/src/views/Connectors.vue
• List: frontend/src/components/connectors/ConnectorsList.vue
• Item: frontend/src/components/connectors/ConnectorItem.vue
• Form: frontend/src/components/connectors/ConfigForm/ConfigForm.vue

Checklist:

1. Ensure DB flags (connector_accepts_*) drive the correct form type.
2. Add connector logo asset if needed (frontend/public/images/connectors/<lowercase-name>.svg).
3. Add any connector-specific screens/routes only if required:
   • route map: frontend/src/router/index.ts

​

7) Environment + Secrets

Update .env.example with required connector vars so bootstrap is deterministic. Rules:

• Do not hardcode secrets in code.
• Read credentials from DB connector config at runtime.
• Keep placeholder defaults non-production.

​

8) Validation Steps

1. Start stack and call GET /api/connectors to confirm seed row exists.
2. Configure connector in UI (/connectors).
3. Call POST /api/connectors/verify/{id} and check connectionSuccessful.
4. Exercise at least one runtime endpoint that uses create_<service>_client.

​

Common Pitfalls

• TLS verification mismatch:
  • many existing connectors use verify=False/verify_certs=False for self-signed deployments.
  • if you enable strict TLS, make it explicit and configurable.
• Timeout defaults too low/high:
  • define per-connector timeouts; include retries only when safe.
• Wrong auth header format:
  • token connectors often require exact header names/prefixes (Authorization: Bearer ..., custom headers, etc.).
• Connector name mismatch:
  • DB seed name and service_map key must be identical.
• Router not included at top level:
  • adding route files alone is insufficient; include in backend/copilot.py.
• Missing frontend export/wiring:
  • endpoint file exists but not exported in frontend/src/api/index.ts.