Skip to main content

Kanarien CRM — Ops-Checkliste

WasCheckliste, damit der Social-Leistungskatalog (Kanarien-Vertrag → cockpitOS Strategie) zuverlässig funktioniert.
WarumOhne Verknüpfung oder Secret liefert cockpit_get_center_social_leistung keinen crmContract — Sync und Agent-Playbooks stoppen.
WerPlattform-Ops, Entwicklung, KAM (Nina-Rolle)
WoRender Env mallos-dashboard, Feld kanarienCenterId an shopping_centers, MCP Kanarien + cockpitOS

1. Env-Variablen (Render / lokal)​

VariablePflichtZweck
KANARIEN_CRM_INTEGRATION_SECRETJa (Prod)Bearer für Kanarien Integration-API (/api/integration/cockpit/…) — gleicher Wert wie KANARIEN_COCKPIT_INTEGRATION_SECRET auf Kanarien (Vercel)
KANARIEN_CRM_BASE_URLNeinDefault: https://agency-os-crm-zeta.vercel.app
CRM_MCP_API_KEYFallbackWird 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).

SeiteVariableFallback
cockpitOS Render (mallos-dashboard)KANARIEN_CRM_INTEGRATION_SECRETCRM_MCP_API_KEY
Kanarien VercelKANARIEN_COCKPIT_INTEGRATION_SECRETCRM_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).

MigrationSpalten
20260924180000_add_center_cockpit_center_idCenter.cockpitCenterId
20260927100000_add_contract_social_leistungContract.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)​

WegWann
Dashboard → Social → Strategie → Aus CRM übernehmenAuto-Match Name/Stadt oder bestehende Verknüpfung; setzt kanarienCenterId beim Live-Sync
Kanarien MCP link_cockpit_centerCRM-seitig Cockpit-UUID hinterlegen
cockpit MCP cockpit_social_strategy_sync_from_crmBody/Param kanarienCenterId; dryRun=true zuerst
AgencyOS POST …/centers/{id}/social-strategy/sync-from-crmGleiche 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)​

KanalRobi-Name (Teams)Kanarien MCP (tools/call)
Lesenkanarien_get_center_social_contractget_center_social_contract
Listekanarien_list_social_leistung_centerslist_social_leistung_centers
Schreibenkanarien_update_center_social_leistungupdate_center_social_leistung
Verknüpfenkanarien_link_cockpit_centerlink_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).

  1. Kanarien: get_center_social_contract / list_social_leistung_centers
  2. Verknüpfen: link_cockpit_center ↔ cockpit kanarienCenterId
  3. cockpitOS: cockpit_get_center_social_leistung — prüft crmContract und crmContractError
  4. Plan: cockpit_social_strategy_sync_from_crm (dryRun, dann live)
  5. Operativ: cockpit_social_strategy_status → cockpit_social_strategy_suggest

Details: Social-Strategie (Dashboard), Social-Strategie-Modul.


4. Typische Fehler (crmContractError)​

MeldungMaßnahme
Integration nicht konfiguriertKANARIEN_CRM_INTEGRATION_SECRET auf Render setzen, Redeploy
kanarienCenterId fehltVerknüpfung herstellen (Abschnitt 2)
Kanarien HTTP 4xx/5xxKanarien-Status, Center-ID in CRM prüfen, Secret rotieren falls abgelaufen

5. So testen​

  1. Env gesetzt → Health/Deploy grün.
  2. 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
  3. 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
  4. cockpit_get_center_social_leistung mit bekannter Center-UUID.
  5. cockpit_social_strategy_sync_from_crm mit dryRun: true — mergedStrategy ohne Schreiben.
  6. Dashboard Strategie-Seite: „Verknüpft mit Kanarien (…)" sichtbar.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/kanarien-crm-integration-ops