Finalize SuperOffice production migration and multi-campaign architecture (v1.8)
This commit is contained in:
@@ -201,18 +201,18 @@ Um die Zertifizierung für den SuperOffice App Store zu erhalten, mussten kritis
|
||||
* **Lösung:** Umstellung auf **`PATCH`**. Wir senden nun nur noch die *tatsächlich geänderten Felder* (Delta).
|
||||
* **Implementierung:** Der Worker baut nun ein `patch_payload` (z.B. `{'Position': {'Id': 123}}`) und nutzt den dedizierten PATCH-Endpunkt. Dies wurde explizit von SuperOffice für die Zertifizierung gefordert.
|
||||
|
||||
### 11. Production Environment (Live Feb 26, 2026)
|
||||
### 11. Production Environment (Live Feb 27, 2026)
|
||||
|
||||
Nach erfolgreicher Zertifizierung durch SuperOffice wurde der Connector auf die Produktionsumgebung umgestellt.
|
||||
|
||||
* **Tenant:** `Cust26720`
|
||||
* **Environment:** `online3` (zuvor `sod`)
|
||||
* **Endpoint:** `https://online3.superoffice.com/Cust26720/api/v1`
|
||||
* **Authentication:** Umstellung auf Produktions-Client-ID und -Secret.
|
||||
* **Authentication:** Umstellung auf Produktions-Client-ID und -Secret erfolgreich verifiziert (Health Check OK).
|
||||
|
||||
**Wichtig:** SuperOffice nutzt Load-Balancing. Die Subdomain (`online3`) kann sich theoretisch ändern. Die Anwendung prüft dies dynamisch, aber die Basis-Konfiguration sollte den aktuellen Tenant-Status widerspiegeln.
|
||||
|
||||
### 12. Lessons Learned: Production Migration (Feb 26, 2026)
|
||||
### 12. Lessons Learned: Production Migration (Feb 27, 2026)
|
||||
|
||||
Der Wechsel von der Staging-Umgebung (`sod`) zur Produktion (`onlineX`) brachte spezifische technische Hürden mit sich:
|
||||
|
||||
@@ -224,24 +224,59 @@ Der Wechsel von der Staging-Umgebung (`sod`) zur Produktion (`onlineX`) brachte
|
||||
* **Problem:** In der Staging-Umgebung lautet der API-Host meist `app-sod.superoffice.com`. In der Produktion wird das `app-` Präfix oft nicht verwendet oder führt zu Zertifikatsfehlern.
|
||||
* **Lösung:** Der `SuperOfficeClient` wurde so flexibilisiert, dass er in der Produktion direkt auf `{env}.superoffice.com` zugreift.
|
||||
|
||||
3. **Refresh Token Lebenszyklus:**
|
||||
* Ein Refresh Token ist an die **Client ID** gebunden. Beim Wechsel der App-Umgebung (Staging -> Produktion) muss zwingend ein neuer Refresh Token über den Auth-Flow generiert werden.
|
||||
3. **Environment Variables Persistence:**
|
||||
* **Problem:** Docker-Container behalten Umgebungsvariablen oft im Cache ("Shadow Configuration"), selbst wenn die `.env`-Datei geändert wurde.
|
||||
* **Lösung:** Zwingendes `docker-compose up -d --force-recreate` nach Credentials-Änderungen.
|
||||
|
||||
### 13. Post-Migration To-Dos (Manual & Discovery)
|
||||
### 13. Post-Migration Configuration (Cust26720)
|
||||
|
||||
Nach dem technischen Switch müssen folgende Schritte in der SuperOffice-Produktionsumgebung (`Cust26720`) manuell durchgeführt werden:
|
||||
Die Konfiguration in der `.env` Datei wurde für die Produktion wie folgt finalisiert:
|
||||
|
||||
| Funktion | UDF / ID | Entity |
|
||||
| :--- | :--- | :--- |
|
||||
| **Subject** | `SuperOffice:19` | Person |
|
||||
| **Intro Text** | `SuperOffice:20` | Person |
|
||||
| **Social Proof** | `SuperOffice:21` | Person |
|
||||
| **Unsubscribe** | `SuperOffice:22` | Person |
|
||||
| **Campaign Tag** | `SuperOffice:23` | Person |
|
||||
| **Opener Primary** | `SuperOffice:86` | Contact |
|
||||
| **Opener Sec.** | `SuperOffice:87` | Contact |
|
||||
| **Vertical** | `SuperOffice:83` | Contact |
|
||||
| **Summary** | `SuperOffice:84` | Contact |
|
||||
| **Last Update** | `SuperOffice:85` | Contact |
|
||||
|
||||
### 14. Kampagnen-Steuerung (Usage)
|
||||
|
||||
Das System unterstützt mehrere Outreach-Varianten über das Feld **`MA_Campaign`** (Person).
|
||||
|
||||
1. **Standard:** Bleibt das Feld leer, werden die Standard-Texte ("standard") für Kaltakquise geladen.
|
||||
2. **Spezifisch:** Wird ein Wert gewählt (z.B. "Messe 2026"), sucht der Connector gezielt nach Matrix-Einträgen mit diesem Tag.
|
||||
3. **Fallback:** Existiert für die gewählte Kampagne kein spezifischer Text für das Vertical/Persona, wird automatisch auf "standard" zurückgegriffen.
|
||||
|
||||
### 15. Advanced Implementation Details (v1.8)
|
||||
|
||||
Mit der Version 1.8 des Workers wurden kritische Optimierungen für den produktiven Betrieb (online3) implementiert, um API-Stabilität und Datenintegrität zu gewährleisten.
|
||||
|
||||
#### A. Atomic PATCH Strategy
|
||||
Um "Race Conditions" und unnötigen API-Traffic zu vermeiden, bündelt der Worker alle Änderungen an einem Kontakt-Objekt in einem einzigen **Atomic PATCH**.
|
||||
* **Betroffene Felder:** `Address` (Postal & Street), `OrgNr` (VAT), `Urls` (Website) und alle `UserDefinedFields`.
|
||||
* **Vorteil:** Entweder alle Daten werden konsistent übernommen, oder der Call schlägt kontrolliert fehl. Dies verhindert, dass Teil-Updates (z.B. nur die Adresse) von nachfolgenden UDF-Updates überschrieben werden.
|
||||
|
||||
#### B. REST Website-Sync (The `Urls` Array)
|
||||
SuperOffice REST akzeptiert kein direktes Update auf `UrlAddress` via PATCH. Stattdessen muss das `Urls` Array manipuliert werden.
|
||||
* **Logik:** Der Worker prüft, ob die KI-entdeckte Website bereits im Array vorhanden ist. Wenn nicht, wird sie als neues Objekt mit der Beschreibung `"AI Discovered"` an den Anfang der Liste gestellt.
|
||||
* **Format:** `"Urls": [{"Value": "https://...", "Description": "AI Discovered"}]`.
|
||||
|
||||
#### C. Kampagnen-Auflösung via `:DisplayText`
|
||||
Um den Klarnamen einer Kampagne (z.B. "Messe 2026") statt der internen ID (z.B. `[I:123]`) zu erhalten, nutzt der Worker eine OData-Optimierung.
|
||||
* **Technik:** Im `$select` Parameter wird das Feld `SuperOffice:23:DisplayText` angefordert.
|
||||
* **Ergebnis:** Der Worker erhält direkt den sauberen String, der zur Steuerung der Textvarianten im Company Explorer dient. Zusätzliche API-Abfragen zur Listenauflösung entfallen.
|
||||
|
||||
#### D. Feldlängen & Truncation
|
||||
Standard-UDF-Textfelder in SuperOffice sind oft auf **254 Zeichen** begrenzt. Da das AI-Dossier (Summary) deutlich länger sein kann, kürzt der Worker den Text hart auf **132 Zeichen** (+ "..."). Dies stellt sicher, dass der gesamte `PATCH` Request nicht aufgrund eines "Field Overflow" von der SuperOffice-Validierung abgelehnt wird.
|
||||
|
||||
---
|
||||
|
||||
1. **UDFs anlegen (Admin):**
|
||||
* Erstellen der benutzerdefinierten Felder an **Contact** (Opener, Industry, Summary, Status) und **Person** (Subject, Bridge, Proof).
|
||||
* Anlegen der Liste für **Verticals** (Branchen) in den Einstellungen.
|
||||
2. **Discovery (IDs ermitteln):**
|
||||
* Ausführen von `python3 connector-superoffice/discover_fields.py`, um die neuen `ProgIDs` (z.B. `SuperOffice:12`) und Listen-IDs zu ermitteln.
|
||||
3. **Konfiguration aktualisieren:**
|
||||
* Eintragen der neuen IDs in die `.env` Datei (`UDF_SUBJECT`, `VERTICAL_MAP_JSON` etc.).
|
||||
4. **Webhook registrieren:**
|
||||
* Ausführen von `python3 connector-superoffice/register_webhook.py`, um den Live-Webhook auf `https://floke-ai.duckdns.org/...` zu schalten.
|
||||
5. **E-Mail Templates:**
|
||||
* Templates in SuperOffice so anpassen, dass sie die neuen UDF-Variablen (z.B. `{udf:SuperOffice:X}`) nutzen.
|
||||
|
||||
## Appendix: The "First Sentence" Prompt
|
||||
This is the core logic used to generate the company-specific opener.
|
||||
|
||||
Reference in New Issue
Block a user