Floke
ff62024ef7
Establishes the initial structure for the SuperOffice connector. Implements the complete, iterative authentication process, culminating in a successful refresh token exchange. Documents the process and the final blocker (API authorization) in the integration plan, awaiting IT action to change the application type to 'Server to server'.
128 lines
7.2 KiB
Markdown
128 lines
7.2 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`).
|