diff --git a/connector-superoffice/README.md b/connector-superoffice/README.md index aa29bb5c..7e779b67 100644 --- a/connector-superoffice/README.md +++ b/connector-superoffice/README.md @@ -1,153 +1,114 @@ -# SuperOffice Connector (POC) +# SuperOffice Connector ("The Butler") - GTM Engine -Dies ist der Microservice zur Anbindung von **SuperOffice CRM** (SOD / Cloud) an die **GTM-Engine**. -Der Connector nutzt die **REST API (v1)** und authentifiziert sich via **OAuth 2.0** (Refresh Token Flow). +Dies ist der Microservice zur Anbindung von **SuperOffice CRM** an die **GTM-Engine**. +Der Connector agiert als "Butler": Er bereitet im Hintergrund hyper-personalisierte Marketing-Texte vor und legt sie im CRM ab, damit der Vertrieb sie mit minimalem Aufwand versenden kann. -## 1. Status Quo (Februar 2026) +## 1. Architektur: Das "Butler-Modell" -Der **Proof of Concept (POC)** ist erfolgreich abgeschlossen. -- **Verbindung:** Erfolgreich hergestellt (`Cust55774`). -- **Authentifizierung:** Funktioniert automatisch via Refresh Token (gehärtet via `load_dotenv(override=True)`). -- **Daten schreiben (Erfolg):** - - **Firmen (Contacts):** Erfolgreich angelegt (inkl. Name, URL, OrgNr). - - **Personen (Persons):** Erfolgreich angelegt und mit Firmen verknüpft (inkl. E-Mail). - - **Verkauf (Sale):** Erfolgreich angelegt. - - **Projekt (Project):** Erfolgreich angelegt und Person als Mitglied hinzugefügt. - - **UDF-Felder:** Erfolgreich aktualisiert für `Contact` und `Person`. - - **Sync to CE:** Erfolgreiche Übertragung der Firmendaten an den Company Explorer. +Wir haben uns gegen eine komplexe Automatisierung *innerhalb* von SuperOffice (via CRMScript-Trigger) entschieden, da die DEV-Umgebung limitiert ist und die Logik extern flexibler ist. -## 2. Einrichtung & Installation +**Der Datenfluss:** +1. **Master-Daten (Notion):** Pains & Gains werden pro Vertical in Notion gepflegt. +2. **Text-Matrix (Lokal):** Das Skript `build_matrix.py` "multipliziert" die Vertical-Daten mit den Rollen-Daten, generiert via Gemini die finalen Texte und speichert sie in einer lokalen SQLite DB (`marketing_matrix.db`). +3. **Polling & Injection (Daemon):** Das Skript `polling_daemon_final.py` läuft periodisch, prüft auf Änderungen an Kontakten in SuperOffice und "injiziert" die passenden Texte aus der lokalen Matrix-DB in die UDF-Felder. -### Voraussetzungen -* Python 3.11+ -* Zugriff auf die `.env` Datei im Root-Verzeichnis (siehe unten). +```mermaid +graph TD + subgraph "A: Strategie & Content" + NotionDB["🏢 Notion DB
(Industries & Roles)"] + end + + subgraph "B: Lokale Engine (Python)" + MatrixBuilder["⚙️ build_matrix.py"] + GeminiAPI["🧠 Gemini API"] + MatrixDB[("💾 marketing_matrix.db")] + PollingDaemon["🤖 polling_daemon_final.py"] + end + + subgraph "C: CRM-System" + SuperOfficeAPI["☁️ SuperOffice API"] + Contact["👤 Contact / Person
(mit UDFs)"] + end + + NotionDB -->|1. Liest Pains/Gains| MatrixBuilder + MatrixBuilder -->|2. Promptet| GeminiAPI + GeminiAPI -->|3. Generiert Texte| MatrixBuilder + MatrixBuilder -->|4. Speichert in DB| MatrixDB + + PollingDaemon -->|5. Prüft Änderungen| SuperOfficeAPI + PollingDaemon -->|6. Holt passende Texte| MatrixDB + PollingDaemon -->|7. Schreibt in UDFs| SuperOfficeAPI + SuperOfficeAPI -->|8. Aktualisiert| Contact +``` + +## 2. Kern-Komponenten (Skripte) + +* **`superoffice_client.py`:** + * Das Herzstück. Eine Python-Klasse, die die gesamte Kommunikation mit der SuperOffice API kapselt (Auth, GET, PUT, Search). + * Beherrscht Paginierung, um auch große Datensätze zu verarbeiten. + +* **`build_matrix.py`:** + * Der "Content Generator". + * Liest Pains/Gains aus Notion. + * Iteriert über definierte Verticals und Rollen. + * Nutzt Gemini, um die spezifischen Textbausteine (`Subject`, `Intro`, `SocialProof`) zu erstellen. + * Speichert das Ergebnis in der `marketing_matrix.db`. + +* **`polling_daemon_final.py`:** + * Der Automatisierungs-Motor. + * Läuft in einer Schleife (z.B. alle 15 Minuten) nur zu Geschäftszeiten (Mo-Fr, 7-18 Uhr). + * Fragt SuperOffice nach kürzlich geänderten Kontakten. + * Nutzt ein **Hash-System**, um zu prüfen, ob sich eine *relevante* Eigenschaft (Vertical oder Rolle) geändert hat, um unnötige API-Schreibvorgänge zu vermeiden. + * Wenn eine Änderung erkannt wird, stößt er den Update-Prozess an. + +* **`normalize_persona.py`:** + * Ein Hilfs-Skript (Classifier), um Jobtitel auf unsere 4 Archetypen (Operativ, Infrastruktur, Wirtschaftlich, Innovation) zu mappen. + +## 3. Setup & Konfiguration ### Installation ```bash -cd connector-superoffice -../.venv/bin/pip install -r requirements.txt +# In einer Python 3.11+ Umgebung: +pip install -r requirements.txt ``` -### Konfiguration (.env) -Die Authentifizierung erfordert folgende Variablen in der zentralen `.env`: - +### Konfiguration (`.env`) +Der Connector benötigt eine `.env` Datei im Root-Verzeichnis mit folgendem Inhalt: ```ini +# Gemini API Keys (DEV für Tests, PROD für Live-Tools) +GEMINI_API_KEY_DEV="AIza..." +GEMINI_API_KEY_PROD="AIza..." +GEMINI_API_KEY=${GEMINI_API_KEY_DEV} # Setzt den Default + +# Notion +NOTION_API_KEY="secret_..." + # SuperOffice Client Configuration -SO_SOD="" # Aus dem Developer Portal -SO_CLIENT_SECRET="" # Aus dem Developer Portal -SO_CONTEXT_IDENTIFIER="CustXXXXX" # Deine Tenant ID (z.B. Cust55774) - -# Authentication Token -SO_REFRESH_TOKEN="" - -# (Optional / Legacy S2S Configuration - aktuell nicht genutzt) -# SO_PRIVATE_KEY="..." -# SO_SYSTEM_USER_TOKEN="..." - -# Company Explorer Configuration (Optional Override) -# CE_API_URL="http://company-explorer:8000" -# CE_API_USER="admin" -# CE_API_PASSWORD="gemini" +SO_CLIENT_ID="" +SO_CLIENT_SECRET="" +SO_CONTEXT_IDENTIFIER="CustXXXXX" +SO_REFRESH_TOKEN="" +SO_ENVIRONMENT="sod" # oder "online" für Produktion ``` -## 3. Nutzung +## 4. SuperOffice Konfiguration (Admin) -### Verbindungstest & Demo -Führt einen Login durch, sucht nach einer Test-Firma und legt bei Bedarf einen Demo-Account mit Ansprechpartner an. +Folgende **Benutzerdefinierte Felder (UDFs)** müssen angelegt sein: -```bash -cd connector-superoffice -../.venv/bin/python main.py -``` +| Objekt | Feldname (Label) | Typ | ProgId (Beispiel) | Zweck | +| :--- | :--- | :--- | :--- | :--- | +| Firma | Contact Vertical | Liste | `SuperOffice:5` | Speichert die Vertical ID. | +| Firma | AI Challenge Satz | Text | `SuperOffice:6` | Speichert den firmen-spezifischen Hook. | +| Person | Person Role | Liste | `SuperOffice:3` | Speichert die Rollen ID. | +| Person | Marketing Subject | Text | `SuperOffice:5` | Speichert den generierten Betreff. | +| Person | Marketing Intro | Text | `SuperOffice:6` | Speichert die generierte Einleitung. | +| Person | Marketing Proof | Text | `SuperOffice:7` | Speichert den generierten Social Proof. | +| Person | AI Copy Hash | Text | `SuperOffice:8` | Speichert den Hash zur Versionierung. | -### Verfügbare Methoden (SuperOfficeClient) -- `find_contact_by_criteria(...)`: Suche nach Name, URL oder OrgNr. -- `create_contact(...)`: Erstellt eine neue Firma. -- `create_person(...)`: Erstellt einen Ansprechpartner (verknüpft mit ContactId). -- `create_sale(...)`: Erstellt einen Verkauf/Opportunity. -- `create_project(...)`: Erstellt ein Projekt und fügt optional eine Person als Mitglied hinzu. -- `update_entity_udfs(...)`: Aktualisiert UDFs für Kontakte und Personen. +## 5. "Gotchas" & Lessons Learned (POC) -### Felder entdecken -Listet alle verfügbaren Felder (inkl. UDFs) auf, um die technischen Namen (`ProgId`) für das Mapping zu finden. - -```bash -../.venv/bin/python discover_fields.py -``` - -## 4. Technische Details & "Gotchas" - -### Subdomain-Auflösung (`app-sod`) -Eine wichtige Erkenntnis des POCs war, dass die Standard-API-URL `sod.superoffice.com` nicht für alle Tenants funktioniert. -Der `AuthHandler` wurde so angepasst, dass er (für diesen Tenant) **`https://app-sod.superoffice.com`** als Basis-URL erzwingt. -* *Code-Stelle:* `auth_handler.py` -> `refresh_access_token` - -### OAuth vs. System User -Ursprünglich war ein "Server-to-Server" (S2S) Flow mittels RSA-Zertifikaten geplant. Da der Zugriff auf den System-User-Token im SOD-Tenant `Cust55774` aufgrund von UI-Änderungen und Berechtigungen erschwert war, wurde auf den **OAuth 2.0 Refresh Token Flow** ("Plan B") gewechselt. -* **Vorteil:** Einfacher einzurichten, Token ist "ewig" gültig (solange er genutzt wird). -* **Nachteil:** Muss einmalig manuell via Browser generiert werden (bereits erledigt). - -### Lessons Learned (Feb 2026): Zugriff auf Zusatz-Tabellen (Extra Tables) -Der Versuch, auf eine neu erstellte Zusatz-Tabelle (`ExtraTableId 1` / `y_marketing_copy`) zuzugreifen, hat eine tiefgreifende Blockade aufgedeckt, die über einfache Benutzerrechte hinausgeht. - -1. **Direkter API-Zugriff (Table & Archive) ist blockiert:** - * Sowohl der `GET /api/v1/Table/Extra1` als auch der `GET /api/v1/Archive/dynamic?providerName=extra_table_1` Endpunkt scheiterten konsistent mit `403 Forbidden` oder `405 Method Not Allowed`, selbst mit vollen Administratorrechten für den API-Benutzer. - * Die spezifische Fehlermeldung `"Archive provider DotSyntaxProvider has no registered entities..."` deutet auf ein Konfigurations- oder Lizenzproblem im Mandanten hin, das den API-Zugriff auf Zusatz-Tabellen generell verhindert. - -2. **CRMScript als Workaround:** - * Um die Blockade zu umgehen, wurde ein CRMScript-Proxy (`GTM_Proxy`) implementiert, der über `POST /api/v1/Scripts/GTM_Proxy/Execute` erreichbar ist. - * **Erfolg:** Der Endpunkt des Proxys selbst ist erreichbar (kein `403`-Fehler). - * **Blocker:** Der Proxy meldet bei der Ausführung einen `500 Internal Server Error`. Dies bedeutet, dass das Skript selbst bei der internen Ausführung auf einen Fehler stößt – höchstwahrscheinlich, weil es ebenfalls von der zugrundeliegenden Berechtigungsblockade betroffen ist. - -**Schlussfolgerung:** Der einzig gangbare Weg, um mit Zusatz-Tabellen zu interagieren, ist die **Fehlerbehebung und korrekte Konfiguration des `GTM_Proxy` CRMScripts** direkt in SuperOffice. Der direkte API-Weg ist für diesen Mandanten derzeit nicht verfügbar. - -## 5. Nächste Schritte - -### Detaillierter Plan: Marketing Automation (SuperOffice-zentrisch) - -Der Versand von hyper-personalisierten E-Mails aus SuperOffice heraus ist ein zentrales Ziel. Das Vorgehen wird sich auf die Vorbereitung der E-Mails durch den Connector konzentrieren, während der Versand und die finale Kontrolle im SuperOffice-Client durch den Endbenutzer erfolgen. - -#### Anwenderplan für die Marketing Automation (Ihre Beschreibung) - -1. **Wichtig: Versand aus SuperOffice heraus:** Der Versand sollte aus SuperOffice heraus erfolgen (wir haben alle technischen Erforderungen ergriffen, um die E-Mail aus SuperOffice heraus in unserem Namen zu senden und vertrauenswürdig erscheinen zu lassen). Dies ist wichtig, um Transparenz zu haben (man sieht im System genau, was passiert ist). -2. **Versand im NAMEN des angemeldeten CRM-Users:** Der Versand erfolgt im NAMEN des angemeldeten CRM-Users / Account-Verantwortlichen. Ggf. muss er sogar manuell einen Knopf drücken, damit etwas passiert. -3. **Statuswechsel bei Antwort:** Der Statuswechsel bei Antwort _kann_ ein manueller Prozess sein – wenn wir dies sinnvoll automatisieren können (bei eingehender Antwort automatisch Status auf "hat geantwortet" setzen wäre auch denkbar, wenn dies technisch möglich ist). -4. **Crafting der E-Mail (Vorab-Generierung):** Das "Crafting" der E-Mail ist für mich wichtiger als die reine Automation des im Wochenabstand Aussendens: Eine E-Mail besteht aus einem unternehmensspezifischen Satz, der gezielt die Herausforderungen des Unternehmens in Bezug auf Roboter als Herausforderung formuliert. Dieser Satz wird VORAB am Account gespeichert, nicht erst zur Laufzeit. Der zweite Teil der E-Mail besteht aus einer rollen- und branchenspezifischen "Antwort" auf die in Satz 1 formulierte Herausforderung, die als logische Schlussfolgerung den Einsatz unserer Roboter ins Feld führt. Im weiteren wird ein persönlicher Buchungslink zu einer Erstberatung des ABSENDERS ergänzt. (Dies ist unsere CTA, es gibt nichts anderes, was er klicken soll). Abgeschlossen wird die E-Mail durch einen Social Proof, der wiederum branchen- und rollenspezifische KPIs, die die Referenz durch Einsatz unserer Lösungen erreicht hat, aufführt. Die rollen- und branchenspezifischen Texte werden ebenfalls VORAB generiert. Sie liegen in einem eigenen Entitätstypen "marketingansprache". Der unternehmensspezifische Satz wird am Contact (Firma) gespeichert. -5. **Zusammenführen im E-Mail-Template:** Im E-Mail-Template werden dann alle Felder zusammengebracht. Da Satz 1 immer eine Herausforderung formuliert (egal welche dies ist) und Satz 2 immer eine Auflösung dieser Herausforderung formuliert, passt es am Ende so gut zusammen, dass niemand merkt, dass diese beiden Sätze nie voneinander wussten. -6. **E-Mail-Signatur:** Die E-Mail-Signatur (Name, Telefon, E-Mail) werden vom USER gezogen, der den Prozess anstößt. - -#### Architekturentwurf: "Der Butler-Service" - -Dieser Plan wird durch ein "Butler-Service"-Modell umgesetzt, bei dem der Connector die E-Mail-Inhalte intelligent vorbereitet und SuperOffice als Sendeplattform und "Single Source of Truth" für den Status dient. - -**Phase 1: Die Vorbereitung (Unser Connector, der Butler)** -Der Connector läuft im Hintergrund (z.B. alle Stunde) und führt folgende Aufgaben aus: - -1. **Identifiziere Kandidaten:** Er fragt die SuperOffice API: "Gib mir alle Firmen (`Contact`), die für eine Ansprache vorgesehen sind (z.B. in einem bestimmten `Project` oder mit einem Status `Ready_for_Crafting`)." -2. **Generiere Satz 1 (Unternehmens-spezifisch):** Für jede Firma ruft der Connector die Company Explorer API auf und generiert den hyper-personalisierten "Herausforderungs-Satz". -3. **Speichere Satz 1:** Der Connector speichert diesen Satz in einem neuen, benutzerdefinierten Text-Feld (UDF) direkt an der Firma (`Contact`) in SuperOffice. Vorschlag: `AI_Challenge_Sentence`. -4. **Hole Satz 2 & Social Proof (Rollen/Branchen-spezifisch):** Der Connector weiß, welche Rolle und Branche der Ansprechpartner hat. Er greift auf die "marketingansprache"-Bibliothek zu (diese kann in einer einfachen Datenbank oder sogar einer JSON-Datei liegen, die der Connector verwaltet) und holt die passenden Textbausteine. -5. **Stelle die E-Mail zusammen:** Der Connector kombiniert nun alles: - * Satz 1 (vom `Contact`-Feld) - * Satz 2 (aus der Bibliothek) - * Social Proof (aus der Bibliothek) -6. **Speichere den E-Mail-Entwurf:** Der komplette, fertige E-Mail-Text wird in einem zweiten, großen UDF-Textfeld gespeichert, diesmal aber an der **Person**, dem Ansprechpartner. Vorschlag: `AI_Email_Draft`. -7. **Setze den Status:** Der Connector aktualisiert den `MA-Status` der Person auf `Ready_to_Send`. - -**Phase 2: Die Ausführung (Der SuperOffice User)** -Der Vertriebsmitarbeiter hat eine extrem einfache Aufgabe: - -1. **Dashboard-Ansicht:** Er öffnet in SuperOffice eine Selektion oder ein Projekt, das ihm alle Kontakte mit dem Status `Ready_to_Send` anzeigt. -2. **Klick, Klick, Senden:** Er öffnet den Kontakt. Im E-Mail-Editor von SuperOffice gibt es eine Vorlage. Diese Vorlage tut nichts anderes, als den Inhalt des Feldes `AI_Email_Draft` zu laden, den persönlichen Buchungslink des Mitarbeiters und seine Signatur hinzuzufügen. -3. **Manuelle Kontrolle:** Er kann den Text kurz überfliegen, wenn er möchte, und klickt auf **"Senden"**. -4. **Status-Update:** Nach dem Senden ändert er den `MA-Status` manuell auf `Sent_Week1`. - -#### Erforderliche UDFs für die Marketing Automation - -Um diesen Plan umzusetzen, werden die folgenden UDFs in SuperOffice benötigt (Anlage durch den Admin): - -1. Am Objekt **`Contact` (Firma):** Ein Textfeld. Vorschlag: `AI_Challenge_Sentence` -2. Am Objekt **`Person` (Ansprechpartner):** Ein großes Textfeld (Memo/Long Text). Vorschlag: `AI_Email_Draft` -3. Am Objekt **`Person` (Ansprechpartner):** Ein Listenfeld. Vorschlag: `MA_Status` mit den Werten `Init`, `Ready_to_Craft`, `Ready_to_Send`, `Sent_Week1`, `Sent_Week2`, `Replied`, `Paused`. - -**Wichtiger Blocker:** Das Erstellen von E-Mail-Aktivitäten per API ist aktuell blockiert, da das E-Mail-Modul in der Zielumgebung (SOD) nicht aktiviert oder konfiguriert zu sein scheint. Dies führt zu einem `500 Internal Server Error` bei API-Aufrufen. Die Implementierung dieser Funktionalität im Connector ist daher bis auf Weiteres ausgesetzt. +* **API-URL:** Der `sod` Tenant `Cust55774` ist nur über `https://app-sod.superoffice.com` erreichbar, nicht `sod.superoffice.com`. +* **Listen-IDs:** Die API gibt IDs von Listenfeldern im Format `[I:26]` zurück. Der String muss vor der DB-Abfrage auf den Integer `26` geparst werden. +* **Dev-System Limits:** Die Textfelder im DEV-System sind auf 40 Zeichen limitiert. Die generierten Texte müssen vor dem Senden gekürzt werden. +* **Y-Tabellen:** Der direkte API-Zugriff auf Zusatz-Tabellen ist in diesem Mandanten blockiert (`403 Forbidden`). Daher der Workaround mit UDFs. +* **CRMScript Trigger:** Die Erstellung von Triggern ist im DEV-System nicht möglich. Daher die Umstellung auf den externen Polling-Daemon.