75 lines
4.5 KiB
Markdown
75 lines
4.5 KiB
Markdown
# SuperOffice Connector ("The Muscle") - GTM Engine v2.0
|
|
|
|
Dies ist der Microservice zur bidirektionalen Anbindung von **SuperOffice CRM** an die **Company Explorer Intelligence**.
|
|
Der Connector agiert als intelligenter Bote ("Muscle"): Er nimmt Webhook-Events entgegen, filtert Rauschen heraus, fragt das "Gehirn" (Company Explorer) nach Instruktionen und schreibt Ergebnisse (Marketing-Texte, Branchen-Verticals, Rollen) ins CRM zurück.
|
|
|
|
## 1. Architektur: "Noise-Reduced Event Pipeline"
|
|
|
|
Wir nutzen eine **Event-gesteuerte Architektur** mit integrierter Rauschunterdrückung, um die CRM-Last zu minimieren und Endlosschleifen zu verhindern.
|
|
|
|
**Der Datenfluss:**
|
|
1. **Auslöser:** Ein User ändert Stammdaten in SuperOffice.
|
|
2. **Filterung (Noise Reduction):** Der Webhook-Receiver ignoriert sofort:
|
|
* Irrelevante Entitäten (Sales, Projects, Appointments, Documents).
|
|
* Irrelevante Felder (Telefon, E-Mail, Fax, interne Systemfelder).
|
|
* *Nur strategische Änderungen (Name, Website, Job-Titel, Position) triggern die Pipeline.*
|
|
3. **Queueing:** Valide Events landen in der lokalen `SQLite`-Queue (`connector_queue.db`).
|
|
4. **Provisioning:** Der Worker fragt den **Company Explorer** (:8000): "Was ist die KI-Wahrheit für diesen Kontakt?".
|
|
5. **Write-Back:** Der Connector schreibt die Ergebnisse (Vertical-ID, Persona-ID, E-Mail-Snippets) via REST API zurück in die SuperOffice UDF-Felder.
|
|
|
|
## 2. 🚀 Go-Live Checkliste (User Tasks)
|
|
|
|
Um das System auf der Produktivumgebung ("Live") in Betrieb zu nehmen, müssen folgende Schritte durchgeführt werden:
|
|
|
|
### Schritt A: SuperOffice Registrierung (IT / Admin)
|
|
Da wir eine **Private App** nutzen, ist keine Zertifizierung nötig.
|
|
1. Loggen Sie sich ins [SuperOffice Developer Portal](https://dev.superoffice.com/) ein.
|
|
2. Registrieren Sie eine neue App ("Custom Application").
|
|
* **Redirect URI:** `http://localhost`
|
|
* **Scopes:** `Contact:Read/Write`, `Person:Read/Write`, `List:Read`, `Appointment:Write`.
|
|
3. Notieren Sie sich **Client ID**, **Client Secret** und den **Token** (falls System User genutzt wird).
|
|
|
|
### Schritt B: Konfiguration & Mapping
|
|
1. **Credentials:** Tragen Sie die Daten aus Schritt A in die `.env` Datei auf dem Server ein (`SO_CLIENT_ID`, etc.).
|
|
2. **Discovery:** Starten Sie den Container und führen Sie einmalig das Discovery-Tool aus, um die IDs der Felder in der Live-Umgebung zu finden:
|
|
```bash
|
|
python3 connector-superoffice/discover_fields.py
|
|
```
|
|
3. **Mapping Update:** Tragen Sie die ermittelten IDs in die `.env` ein:
|
|
* `VERTICAL_MAP_JSON`: Mappen Sie die CE-Branchen auf die SuperOffice "Business"-IDs.
|
|
* `PERSONA_MAP_JSON`: Mappen Sie die Rollen (z.B. "Influencer", "Wirtschaftlicher Entscheider") auf die SuperOffice "Position"-IDs.
|
|
|
|
### Schritt C: Webhook Einrichtung (SuperOffice Admin)
|
|
Gehen Sie in SuperOffice zu **Einstellungen & Verwaltung -> Webhooks** und legen Sie einen neuen Hook an:
|
|
* **Target URL:** `http://<IHRE-SERVER-IP>:8003/webhook?token=<SECRET_AUS_ENV>`
|
|
* **Events:** `contact.created`, `contact.changed`, `person.created`, `person.changed`.
|
|
|
|
### Schritt D: Feiertags-Import
|
|
Damit der Versand an Feiertagen pausiert:
|
|
1. Kopieren Sie den Inhalt von `connector-superoffice/import_holidays_CRMSCRIPT.txt`.
|
|
2. Führen Sie ihn in SuperOffice unter **CRMScript -> Execute** aus.
|
|
|
|
## 3. Business Logik & Features
|
|
|
|
### 4.1. Persona Mapping ("Golden Record")
|
|
Das Feld `Position` (Rolle) in SuperOffice wird als Ziel-Feld für die CE-Archetypen genutzt.
|
|
* **Logik:** Der CE analysiert den Jobtitel (z.B. "Einkaufsleiter") -> Mappt auf "Influencer".
|
|
* **Sync:** Der Connector setzt das Feld `Position` in SuperOffice auf den entsprechenden Wert (sofern in der Config gemappt).
|
|
|
|
### 4.2. Vertical Mapping
|
|
KI-Verticals (z.B. "Healthcare - Hospital") werden auf die SuperOffice-Branchenliste gemappt. Manuelle Änderungen durch User im CRM werden aktuell beim nächsten Update überschrieben (Master: CE).
|
|
|
|
## 4. Testing & Simulation
|
|
|
|
Verwenden Sie `test_full_roundtrip.py`, um die Kette zu testen, ohne E-Mails zu versenden. Das Skript erstellt stattdessen **Termine** in SuperOffice als Beweis.
|
|
|
|
```bash
|
|
# Startet Simulation für Person ID 2
|
|
python3 connector-superoffice/tests/test_full_roundtrip.py
|
|
```
|
|
|
|
## 5. Roadmap (v2.1)
|
|
|
|
* [ ] **Manual Override Protection:** Schutz manueller Änderungen (Vertical/Rolle) durch den User vor Überschreiben durch die KI.
|
|
* [ ] **Notion Dashboard:** KPI-Reporting.
|
|
* [ ] **Lead-Attribution:** Automatisches Setzen der `Sale.Source` auf "Marketing Automation". |