Kanarien CRM — Ops-Checkliste
| Was | Checkliste, damit der Social-Leistungskatalog (Kanarien-Vertrag → cockpitOS Strategie) zuverlässig funktioniert. |
| Warum | Ohne Verknüpfung oder Secret liefert cockpit_get_center_social_leistung keinen crmContract — Sync und Agent-Playbooks stoppen. |
| Wer | Plattform-Ops, Entwicklung, KAM (Nina-Rolle) |
| Wo | Render Env mallos-dashboard, Feld kanarienCenterId an shopping_centers, MCP Kanarien + cockpitOS |
1. Env-Variablen (Render / lokal)
| Variable | Pflicht | Zweck |
|---|---|---|
KANARIEN_CRM_INTEGRATION_SECRET | Ja (Prod) | Bearer für Kanarien Integration-API (/api/integration/cockpit/…) — gleicher Wert wie KANARIEN_COCKPIT_INTEGRATION_SECRET auf Kanarien (Vercel) |
KANARIEN_CRM_BASE_URL | Nein | Default: https://agency-os-crm-zeta.vercel.app |
CRM_MCP_API_KEY | Fallback | Wird nur genutzt, wenn KANARIEN_CRM_INTEGRATION_SECRET fehlt |
Kanarien (Vercel): KANARIEN_COCKPIT_INTEGRATION_SECRET oder Fallback CRM_MCP_API_KEY. Ohne gesetztes Secret antwortet die Integration-API mit 401; 404 bedeutet meist alter Deploy (Routes fehlen noch auf Production).
| Seite | Variable | Fallback |
|---|---|---|
cockpitOS Render (mallos-dashboard) | KANARIEN_CRM_INTEGRATION_SECRET | CRM_MCP_API_KEY |
| Kanarien Vercel | KANARIEN_COCKPIT_INTEGRATION_SECRET | CRM_MCP_API_KEY |
Gleicher Wert auf beiden Seiten — nur unterschiedliche Env-Namen.
Smoke: Nach Deploy ein Center mit gesetzter kanarienCenterId per AgencyOS abfragen:
GET /api/agencyos/v1/centers/{centerId}/social-strategy/leistung
Erwartung: data.crmContract gefüllt, kein crmContractError (außer Kanarien liefert Fehler).
CRM-Vollständigkeit (Bulk): GET /api/agencyos/v1/crm-completeness-watch?centerIds=…&onlyWithGaps=true — MCP: cockpit_crm_completeness_watch.
Neues Center: cockpit_create_center liefert bei fehlender kanarienCenterId warnings + nextSteps (link_cockpit_center, cockpit_social_strategy_sync_from_crm).
1b. Kanarien-DB-Migration (Pflicht für Social-Leistung)
Ohne Migration schlagen MCP tools/call und Integration-API mit Column Center.cockpitCenterId does not exist fehl. tools/list zeigt die Tools trotzdem (nur Schema/Registrierung).
| Migration | Spalten |
|---|---|
20260924180000_add_center_cockpit_center_id | Center.cockpitCenterId |
20260927100000_add_contract_social_leistung | Contract.social* (Fallback) |
Sofort (Prod-DB, read/write):
cd agency-os-crm-main
export DATABASE_URL="…" DIRECT_URL="…"
npm run db:deploy
Dauerhaft: Kanarien vercel-build führt prisma migrate deploy vor jedem Deploy aus (DATABASE_URL + DIRECT_URL auf Vercel).
Details: Kanarien-Repo docs/cockpit-integration.md (Abschnitt Migration).
2. Center-Verknüpfung (kanarienCenterId)
Spalte shopping_centers.kanarien_center_id (unique, nullable) — additiv, kein Datenverlust bei fehlender Verknüpfung.
Pfade zum Verknüpfen (kein Bulk-Destroy)
| Weg | Wann |
|---|---|
| Dashboard → Social → Strategie → Aus CRM übernehmen | Auto-Match Name/Stadt oder bestehende Verknüpfung; setzt kanarienCenterId beim Live-Sync |
Kanarien MCP link_cockpit_center | CRM-seitig Cockpit-UUID hinterlegen |
cockpit MCP cockpit_social_strategy_sync_from_crm | Body/Param kanarienCenterId; dryRun=true zuerst |
AgencyOS POST …/centers/{id}/social-strategy/sync-from-crm | Gleiche Logik wie Dashboard |
Kein dediziertes Bulk-Skript im Repo. Für viele Center: Kanarien list_social_leistung_centers + pro Treffer link_cockpit_center oder Agent-Schleife mit sync-from-crm (immer dryRun zuerst).
Read-only Audit (SQL, Shadow/Prod read-only)
Center ohne Verknüpfung:
SELECT id, name, city, kanarien_center_id
FROM shopping_centers
WHERE status != 'inactive'
AND kanarien_center_id IS NULL
ORDER BY name;
3. MCP-Tool-Kette (Agenten)
| Kanal | Robi-Name (Teams) | Kanarien MCP (tools/call) |
|---|---|---|
| Lesen | kanarien_get_center_social_contract | get_center_social_contract |
| Liste | kanarien_list_social_leistung_centers | list_social_leistung_centers |
| Schreiben | kanarien_update_center_social_leistung | update_center_social_leistung |
| Verknüpfen | kanarien_link_cockpit_center | link_cockpit_center |
Claude Desktop / direkter Kanarien-MCP: Namen ohne kanarien_-Präfix (get_center_social_contract, …). Seit Kanarien-Deploy 2026-09-27 akzeptiert /api/mcp bei tools/call auch kanarien_*-Aliase (Robi-kompatibel).
- Kanarien:
get_center_social_contract/list_social_leistung_centers - Verknüpfen:
link_cockpit_center↔ cockpitkanarienCenterId - cockpitOS:
cockpit_get_center_social_leistung— prüftcrmContractundcrmContractError - Plan:
cockpit_social_strategy_sync_from_crm(dryRun, dann live) - Operativ:
cockpit_social_strategy_status→cockpit_social_strategy_suggest
Details: Social-Strategie (Dashboard), Social-Strategie-Modul.
4. Typische Fehler (crmContractError)
| Meldung | Maßnahme |
|---|---|
| Integration nicht konfiguriert | KANARIEN_CRM_INTEGRATION_SECRET auf Render setzen, Redeploy |
kanarienCenterId fehlt | Verknüpfung herstellen (Abschnitt 2) |
| Kanarien HTTP 4xx/5xx | Kanarien-Status, Center-ID in CRM prüfen, Secret rotieren falls abgelaufen |
5. So testen
- Env gesetzt → Health/Deploy grün.
- Kanarien Smoke (ohne Secret → 401, nicht 404):
curl -s -o /dev/null -w "%{http_code}" https://agency-os-crm-zeta.vercel.app/api/integration/cockpit/centers/match - GBP Smoke (Route live → 401 ohne API-Key, nicht 404):
curl -s -o /dev/null -w "%{http_code}" https://dashboard.cockpit-os.de/api/agencyos/v1/centers/00000000-0000-0000-0000-000000000001/google-reviews cockpit_get_center_social_leistungmit bekannter Center-UUID.cockpit_social_strategy_sync_from_crmmitdryRun: true—mergedStrategyohne Schreiben.- Dashboard Strategie-Seite: „Verknüpft mit Kanarien (…)" sichtbar.
Links
- AgencyOS — Social-Strategie / Leistung
- MCP-Tool-Referenz — cockpit_social_strategy_sync_from_crm
- Kanarien Repo:
docs/cockpit-integration.md(agency-os-crm)
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/kanarien-crm-integration-ops