158 lines
9.8 KiB
Markdown
158 lines
9.8 KiB
Markdown
# Technisches Konzept: SuperOffice CRM Integration
|
||
|
||
Dieses Dokument beschreibt die Integrationsstrategie zwischen **SuperOffice CRM** (führendes System für Stammdaten) und dem **Company Explorer** (KI-gestützte Anreicherungs-Engine).
|
||
|
||
## Zielsetzung
|
||
Automatisierte Anreicherung von B2B-Firmendaten im CRM mit KI-generierten Insights (z.B. Robotik-Affinität, Branchen-Einstufung), ohne die Hoheit über die Stammdaten zu gefährden.
|
||
|
||
---
|
||
|
||
## 1. Architektur: Der "SuperOffice Connector"
|
||
|
||
Wir implementieren einen dedizierten Microservice (`connector-superoffice`), der als Brücke fungiert.
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph CRM ["SuperOffice CRM (Cloud/On-Prem)"]
|
||
SO_DB[("Stammdaten<br/>(Contact)")]
|
||
SO_UDF[("KI-Felder<br/>(UDFs)")]
|
||
end
|
||
|
||
subgraph Middleware ["Integration Layer (Docker)"]
|
||
Connector["🔄 SuperOffice Connector<br/>(Python Service)"]
|
||
end
|
||
|
||
subgraph Intelligence ["GTM Engine"]
|
||
CE_API["⚡ Company Explorer API"]
|
||
CE_DB[("Enrichment DB")]
|
||
end
|
||
|
||
%% Data Flow
|
||
SO_DB -->|"1. Pull (Delta/Initial)"| Connector
|
||
Connector -->|"2. Push (Import)"| CE_API
|
||
CE_API -.->|"3. Enrichment Process"| CE_DB
|
||
CE_DB -->|"4. Result"| CE_API
|
||
Connector -->|"5. Poll Results"| CE_API
|
||
Connector -->|"6. Write-Back (Update UDFs)"| SO_UDF
|
||
|
||
%% Styling
|
||
style CRM fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
|
||
style Middleware fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
|
||
style Intelligence fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
|
||
```
|
||
|
||
## 2. Datenmodell & Erweiterung
|
||
|
||
Um die CRM-Daten sauber zu halten, schreiben wir **niemals** in Standardfelder (wie `Name`, `Department`), sondern ausschließlich in dedizierte, benutzerdefinierte Felder (**User Defined Fields - UDFs**).
|
||
|
||
### Benötigte Felder in SuperOffice (Anforderung an IT/Admin)
|
||
Folgende Felder sollten am Objekt `Company` (bzw. `Contact` in SuperOffice-Terminologie) angelegt werden:
|
||
|
||
| Feldname (Label) | Typ | Zweck |
|
||
| :--- | :--- | :--- |
|
||
| `AI Robotics Potential` | List/Select | High / Medium / Low / None |
|
||
| `AI Industry` | Text (Short) | KI-ermittelte Branche (z.B. "Logistik - Intralogistik") |
|
||
| `AI Summary` | Text (Long/Memo) | Kurze Zusammenfassung der Analyse |
|
||
| `AI Last Update` | Date | Zeitstempel der letzten Anreicherung |
|
||
| `AI Status` | List/Select | Pending / Enriched / Error |
|
||
|
||
### Benötigtes Feld im Company Explorer
|
||
| Feldname | Typ | Zweck |
|
||
| :--- | :--- | :--- |
|
||
| `external_crm_id` | String/Int | Speichert die `ContactId` aus SuperOffice zur eindeutigen Zuordnung (Primary Key Mapping). |
|
||
|
||
---
|
||
|
||
## 3. Phasenplan
|
||
|
||
### Phase 1: Initial Load (Snapshot)
|
||
*Ziel: Bestandskunden und aktive Leads einmalig bewerten.*
|
||
|
||
1. **Filter:** Der Connector lädt alle Firmen mit Status "Kunde" oder "Prospect".
|
||
2. **Import:** Daten werden via `POST /api/companies/bulk` an den Explorer gesendet. Die `ContactId` wird mitgegeben.
|
||
3. **Verarbeitung:** Der Explorer arbeitet die Queue ab (Web-Scraping -> Klassifizierung).
|
||
|
||
### Phase 2: Write-Back (Ergebnisse speichern)
|
||
*Ziel: Ergebnisse im CRM sichtbar machen.*
|
||
|
||
1. Der Connector prüft regelmäßig (`GET /api/companies?status=ENRICHED`) auf fertige Analysen.
|
||
2. Für jeden Treffer sendet er ein Update an die SuperOffice API (`PUT /Contact/{id}`).
|
||
3. Es werden nur die oben definierten UDFs aktualisiert.
|
||
|
||
### Phase 3: Continuous Sync (Polling)
|
||
*Ziel: Neue Firmen automatisch verarbeiten.*
|
||
|
||
1. **Zyklus:** Alle 60 Minuten.
|
||
2. **Logik:** "Gib mir alle Firmen, die seit `LAST_RUN` erstellt oder geändert wurden."
|
||
3. **Aktion:** Neue Firmen werden automatisch zur Analyse geschickt.
|
||
4. **Vorteil:** Keine komplexe Firewall-Konfiguration für eingehende Webhooks nötig (Outbound-Only Traffic).
|
||
|
||
---
|
||
|
||
## 4. Sicherheit & Authentifizierung
|
||
|
||
* **Authentifizierung:** Nutzung eines **System User Tokens** (Machine-to-Machine). Dies verhindert, dass Passwörter von persönlichen Accounts im Code hinterlegt werden müssen.
|
||
* **Scope:** Der API-User benötigt Lesezugriff auf `Contact` und Schreibzugriff auf die `UDFs`.
|
||
* **Datenschutz:** Es werden nur Firmendaten (Name, Webseite, Stadt) übertragen. Personenbezogene Ansprechpartner bleiben im CRM und werden nicht an die KI gesendet.
|
||
|
||
### 4.1. POC Erkenntnisse & Manueller Setup-Prozess (Feb 2026)
|
||
|
||
Während des initialen Proof of Concepts (POC) wurde der Authentifizierungs-Flow für die SOD-Umgebung (SuperOffice Development) erfolgreich etabliert. Dabei wurden folgende wichtige Erkenntnisse gewonnen:
|
||
|
||
**Problemstellung:** Ein direkter "Client Credentials Flow" (rein maschinell) ist mit dem Anwendungstyp "empty" nicht möglich. Stattdessen ist ein einmaliger, interaktiver Schritt notwendig, um einen langlebigen `refresh_token` zu generieren, der dann für die automatisierte Kommunikation genutzt werden kann.
|
||
|
||
**Durchgeführte Schritte zur Token-Generierung:**
|
||
|
||
1. **App-Konfiguration:** Im SuperOffice Developer Portal wurde für die Anwendung "Robo_GTM-Engine" die URL `http://localhost` als "Allowed redirect URL" hinzugefügt.
|
||
2. **Autorisierungs-URL:** Ein Benutzer hat die folgende, speziell konstruierte URL im Browser geöffnet, um den Autorisierungsprozess zu starten:
|
||
`https://sod.superoffice.com/login/common/oauth/authorize?client_id=[IHRE_CLIENT_ID]&redirect_uri=http%3A%2F%2Flocalhost&response_type=code`
|
||
3. **Manuelle Zustimmung:** Der Benutzer hat sich in SuperOffice eingeloggt und der Anwendung die angeforderten Berechtigungen erteilt.
|
||
4. **Code-Extraktion:** Nach der Zustimmung wurde der Browser auf eine `localhost`-URL umgeleitet. Obwohl die Seite nicht geladen wurde, enthielt die URL den notwendigen `authorization_code` (z.B. `http://localhost/?code=ABC-123...`).
|
||
5. **Token-Austausch:** Mit einem Skript wurde dieser einmalige `code` an den SuperOffice Token-Endpunkt gesendet. Im Gegenzug wurden ein kurzlebiger `access_token` und der entscheidende, langlebige `refresh_token` empfangen.
|
||
6. **Sichere Speicherung:** Der `refresh_token` wurde in der `.env`-Datei des Connectors als `SO_REFRESH_TOKEN` hinterlegt.
|
||
|
||
**Ergebnis & Aktueller Blocker:**
|
||
|
||
* **Erfolg:** Der Authentifizierungs-Handshake ist erfolgreich. Der Connector kann den `SO_REFRESH_TOKEN` nutzen, um jederzeit vollautomatisch neue, gültige `access_token` von SuperOffice zu erhalten.
|
||
* **Blocker:** Trotz gültigem `access_token` werden alle nachfolgenden API-Aufrufe (z.B. an `/api/v1/User/currentPrincipal`) von SuperOffice auf die Login-Seite umgeleitet (`HTTP 302 Found`). Dies ist ein klares Indiz dafür, dass der Token zwar gültig, aber nicht für den API-Zugriff **autorisiert** ist.
|
||
|
||
**Empfehlung für die IT:**
|
||
|
||
Die Ursache für die fehlende Autorisierung liegt sehr wahrscheinlich im Anwendungstyp "empty". Um eine echte Server-zu-Server-Integration zu ermöglichen, **muss der Anwendungstyp im SuperOffice Developer Portal auf "Server to server" geändert werden.** Dies wird voraussichtlich erfordern, dass die Schritte 2-6 erneut durchgeführt werden, um neue Tokens mit den korrekten Berechtigungen zu erhalten.
|
||
|
||
## 5. Vorbereitung für die IT
|
||
|
||
Um den Connector in Betrieb zu nehmen, benötigen wir:
|
||
1. **API Zugangsdaten:** `Client ID`, `Client Secret`, `Customer ID` (Tenant) und einen `System User Token`.
|
||
2. **UDF Definitionen:** Die `ProgId` (technischen Namen) der neu angelegten Felder (z.B. `userdef_id_123`).
|
||
|
||
## 6. Fragen an Manuel
|
||
|
||
1. Die "Lizenz-Gretchenfrage" (Development Tools)
|
||
Frage: "Manuel, du sagtest, bei Wackler sind die 'Development Tools' aktiv. Weißt du, ob das eine globale Konzern-Lizenz ist oder ob wir für den RoboPlanet-Mandanten eine eigene Subskription brauchen? Mein Dev-Portal blockiert S2S aktuell mit dem Hinweis auf fehlende Lizenzen in Production."
|
||
Ziel: Klären, ob es nur ein "Klick" im Admin-Panel ist oder ob Webkom (oder ein anderer Partner) eine neue Rechnung schreiben muss.
|
||
|
||
2. Der App-Registrierungs-Pfad
|
||
Frage: "Hast du eure App als 'Custom Application' (privat für Wackler) oder als 'Standard Application' (über einen Partner-Account) registriert? Falls ihr einen Partner-Account nutzt: Könnten wir unsere GTM-Engine darüber mitlaufen lassen, um die Lizenz-Hürde zu umgehen?"
|
||
Ziel: Prüfen, ob Manuel über ein Partner-Portal arbeitet. Partner-Apps brauchen manchmal keine Dev-Tools beim Kunden, weil der Partner die Validierung übernimmt.
|
||
|
||
3. Identifikation des "Gatekeepers"
|
||
Frage: "Wer hat bei euch den Tenant technisch aufgesetzt? War das die Webkom? Ich muss herausfinden, wer die administrative Hoheit hat, um den 'System User' für S2S freizuschalten."
|
||
Ziel: Den Namen des Ansprechpartners bei der Webkom oder intern bei Wackler-IT herausfinden.
|
||
|
||
4. Authentifizierungs-Deep-Dive (RSA vs. Token)
|
||
Frage: "Nutzt ihr für eure S2S-App den RSA-Key-Flow (JWT) oder arbeitet ihr mit einem statischen System-User-Token? Ich bereite gerade den RSA-Handshake vor und wollte wissen, was in der SuperOffice Cloud stabiler läuft."
|
||
Ziel: Fachsimpelei, um Manuel zu zeigen, dass du auf seinem Level spielst. Das öffnet Türen für Code-Sharing oder Tipps.
|
||
|
||
5. Das "Y-Tabellen" Problem
|
||
Frage: "Nutzt ihr für eure Verkaufs-App auch Zusatztabellen (Y-Tabellen) oder schreibt ihr nur in Standardfelder? Ich plane eine Tabelle für dynamische Marketing-Texte (Rolle x Branche) – gab es bei euch Probleme mit dem Cache nach Strukturänderungen?"
|
||
Ziel: Bestätigung einholen, dass Y-Tabellen mit ihrer Lizenz funktionieren. Das ist dein Beweis, dass du die Dev-Tools zwingend brauchst.
|
||
|
||
6. Authentifizierung beim S2S Call
|
||
Wie authentifiziert ihr euch beim S2S-Call? Nutzt ihr den RSA-Flow mit Zertifikaten oder habt ihr einen Partner-Proxy dazwischen?" (Wenn er "Partner-Proxy" sagt, arbeitet er über Webkom-Infrastruktur).
|
||
|
||
7. Nutzung System User
|
||
Wo habt ihr den 'System User' im CRM autorisiert?" (Er soll dir den Pfad in Einstellungen & Verwaltung zeigen).
|
||
|
||
8. Header API-Call
|
||
Könntest du mir den Header eines eurer API-Calls zeigen (natürlich ohne den echten Token)?" (Daran sehen wir sofort, ob sie die v1 REST API oder die alte SOAP-Schnittstelle nutzen). |