| 1 | # Adding a Connector (AI Agent Checklist) |
| 2 | |
| 3 | Use this when introducing a new backend connector integration and wiring it through UI/API. |
| 4 | |
| 5 | ## Scope |
| 6 | |
| 7 | This checklist covers: |
| 8 | - connector bootstrap record |
| 9 | - verify dispatch wiring |
| 10 | - connector utility client + verifier |
| 11 | - route wiring |
| 12 | - frontend endpoint/UI integration |
| 13 | |
| 14 | ## 1) Add Connector to Seed Data |
| 15 | |
| 16 | File: `backend/app/db/db_populate.py` |
| 17 | |
| 18 | Actions: |
| 19 | 1. Update `get_connectors_list()` with your new connector tuple. |
| 20 | 2. Pick exactly one auth mode flag via `accepts_key`: |
| 21 | - `host_only` |
| 22 | - `api_key` |
| 23 | - `username_password` |
| 24 | - `file` |
| 25 | 3. If needed, define `extra_data_key` env var for `connector_extra_data`. |
| 26 | 4. Ensure env var naming matches `load_connector_data()` prefix rule: |
| 27 | - `connector_name.upper().replace("-", "_").replace(" ", "_")` |
| 28 | |
| 29 | Result: |
| 30 | - connector appears in `/api/connectors` after startup seed. |
| 31 | |
| 32 | ## 2) Implement Connector Utility Module |
| 33 | |
| 34 | File path (new): `backend/app/connectors/<service>/utils/universal.py` |
| 35 | |
| 36 | Minimum functions to provide: |
| 37 | 1. `verify_<service>_connection(connector_name: str)` |
| 38 | 2. `create_<service>_client(connector_name: str = "<Connector-Display-Name>")` |
| 39 | |
| 40 | Implementation requirements: |
| 41 | - Pull credentials via `get_connector_info_from_db` from `backend/app/connectors/utils.py`. |
| 42 | - Return consistent verify payload: |
| 43 | - `{"connectionSuccessful": bool, "message": str}` |
| 44 | - Raise `HTTPException` for hard failures in runtime client creation. |
| 45 | |
| 46 | ## 3) Register Verify Dispatch |
| 47 | |
| 48 | File: `backend/app/connectors/services.py` |
| 49 | |
| 50 | Actions: |
| 51 | 1. Import your verifier function. |
| 52 | 2. Add service class (pattern: `<ServiceName>Service`) implementing `verify_authentication`. |
| 53 | 3. Add mapping in `get_connector_service()` `service_map`: |
| 54 | - key must match DB `connector_name` exactly. |
| 55 | |
| 56 | If omitted, `/api/connectors/verify/{id}` will return unsupported/None behavior. |
| 57 | |
| 58 | ## 4) Add Connector Routes (If Exposing Feature APIs) |
| 59 | |
| 60 | Typical files: |
| 61 | - `backend/app/connectors/<service>/routes/*.py` |
| 62 | - `backend/app/connectors/<service>/services/*.py` |
| 63 | - `backend/app/connectors/<service>/schema/*.py` |
| 64 | |
| 65 | Router wiring: |
| 66 | 1. Add/modify router module `backend/app/routers/<service>.py`. |
| 67 | 2. Include route groups with appropriate prefixes/tags. |
| 68 | 3. Add top-level include in `backend/copilot.py`: |
| 69 | - `from app.routers import <service>` |
| 70 | - `api_router.include_router(<service>.router)` |
| 71 | |
| 72 | Without step 3, routes compile but are unreachable. |
| 73 | |
| 74 | ## 5) Frontend Endpoint Wiring |
| 75 | |
| 76 | Primary files: |
| 77 | - `frontend/src/api/endpoints/connectors.ts` |
| 78 | - optional new endpoint file if connector has dedicated APIs (pattern in `frontend/src/api/endpoints/*.ts`) |
| 79 | - `frontend/src/api/index.ts` (export) |
| 80 | |
| 81 | Checklist: |
| 82 | 1. Reuse generic `/connectors` endpoints if only configuring/verifying credentials. |
| 83 | 2. Add dedicated endpoint wrapper(s) for new connector-specific backend routes. |
| 84 | 3. Ensure payload type definitions exist/update in `frontend/src/types/*.d.ts`. |
| 85 | |
| 86 | ## 6) Frontend UI Wiring |
| 87 | |
| 88 | Connector configuration UI already exists: |
| 89 | - View: `frontend/src/views/Connectors.vue` |
| 90 | - List: `frontend/src/components/connectors/ConnectorsList.vue` |
| 91 | - Item: `frontend/src/components/connectors/ConnectorItem.vue` |
| 92 | - Form: `frontend/src/components/connectors/ConfigForm/ConfigForm.vue` |
| 93 | |
| 94 | Checklist: |
| 95 | 1. Ensure DB flags (`connector_accepts_*`) drive the correct form type. |
| 96 | 2. Add connector logo asset if needed (`frontend/public/images/connectors/<lowercase-name>.svg`). |
| 97 | 3. Add any connector-specific screens/routes only if required: |
| 98 | - route map: `frontend/src/router/index.ts` |
| 99 | |
| 100 | ## 7) Environment + Secrets |
| 101 | |
| 102 | Update `.env.example` with required connector vars so bootstrap is deterministic. |
| 103 | |
| 104 | Rules: |
| 105 | - Do not hardcode secrets in code. |
| 106 | - Read credentials from DB connector config at runtime. |
| 107 | - Keep placeholder defaults non-production. |
| 108 | |
| 109 | ## 8) Validation Steps |
| 110 | |
| 111 | 1. Start stack and call `GET /api/connectors` to confirm seed row exists. |
| 112 | 2. Configure connector in UI (`/connectors`). |
| 113 | 3. Call `POST /api/connectors/verify/{id}` and check `connectionSuccessful`. |
| 114 | 4. Exercise at least one runtime endpoint that uses `create_<service>_client`. |
| 115 | |
| 116 | ## Common Pitfalls |
| 117 | |
| 118 | - TLS verification mismatch: |
| 119 | - many existing connectors use `verify=False`/`verify_certs=False` for self-signed deployments. |
| 120 | - if you enable strict TLS, make it explicit and configurable. |
| 121 | - Timeout defaults too low/high: |
| 122 | - define per-connector timeouts; include retries only when safe. |
| 123 | - Wrong auth header format: |
| 124 | - token connectors often require exact header names/prefixes (`Authorization: Bearer ...`, custom headers, etc.). |
| 125 | - Connector name mismatch: |
| 126 | - DB seed name and `service_map` key must be identical. |
| 127 | - Router not included at top level: |
| 128 | - adding route files alone is insufficient; include in `backend/copilot.py`. |
| 129 | - Missing frontend export/wiring: |
| 130 | - endpoint file exists but not exported in `frontend/src/api/index.ts`. |