motia/bitbylaw/ENTITY_MAPPING_CBeteiligte_Advoware.md

Entity-Mapping: EspoCRM CBeteiligte ↔ Advoware Beteiligte

Basierend auf dem Vergleich von:

• EspoCRM: CBeteiligte Entity ID 68e4af00172be7924
• Advoware: Beteiligter ID 104860

Gemeinsame Felder (direkte Übereinstimmung)

EspoCRM Feld	Advoware Feld	Typ	Notes
name	name	string	Vollständiger Name
rechtsform	rechtsform	string	Rechtsform (z.B. "GmbH", "Frau")
id	id	mixed	Achtung: EspoCRM=string, Advoware=int

Namenfelder

EspoCRM Feld	Advoware Feld	Mapping
firstName	vorname	✓ Direkt
lastName	name	✓ Bei Personen
middleName	-	❌ Kein direktes Mapping
firmenname	name	✓ Bei Firmen
-	geburtsname	← Nur in Advoware
-	kurzname	← Nur in Advoware

Kontaktdaten

EspoCRM Feld	Advoware Feld	Mapping
emailAddress	emailGesch	✓ Geschäftlich
emailAddressData (array)	email	⚠️ Komplex: Array vs. String
phoneNumber	telGesch	✓ Geschäftstelefon
phoneNumberData (array)	telPrivat	⚠️ Komplex
-	mobil	← Nur in Advoware
-	faxGesch / faxPrivat	← Nur in Advoware
-	autotelefon	← Nur in Advoware
-	internet	← Nur in Advoware

Hinweis: Advoware hat zusätzlich kommunikation Array mit strukturierten Kontaktdaten.

Adressdaten

EspoCRM Feld	Advoware Feld	Mapping
adressensIds / adressensNames	adressen (array)	⚠️ Beziehung
-	strasse	← Hauptadresse in Advoware Root
-	plz	← Hauptadresse in Advoware Root
-	ort	← Hauptadresse in Advoware Root
-	anschrift	← Formatierte Adresse

Hinweis:

• EspoCRM: Adressen als Related Entities (IDs/Names)
• Advoware: Hauptadresse im Root-Objekt + adressen Array für zusätzliche

Anrede & Titel

EspoCRM Feld	Advoware Feld	Mapping
salutationName	anrede	✓ (z.B. "Frau", "Herr")
-	bAnrede	← Briefanrede ("Sehr geehrte...")
-	titel	← Titel (Dr., Prof., etc.)
-	zusatz	← Namenszusatz

Geburtsdaten

EspoCRM Feld	Advoware Feld	Mapping
dateOfBirth	geburtsdatum	✓ Direkt
-	sterbedatum	← Nur in Advoware
-	familienstand	← Nur in Advoware

Handelsregister (für Firmen)

EspoCRM Feld	Advoware Feld	Mapping
handelsregisterNummer	handelsRegisterNummer	✓ Direkt
handelsregisterArt (z.B. "HRB")	-	❌ Nur in EspoCRM
-	registergericht	← Nur in Advoware

Bankverbindungen

EspoCRM Feld	Advoware Feld	Mapping
bankverbindungensIds / Names	bankkverbindungen (array)	⚠️ Related Entity vs. Array

Beteiligungen/Akten

EspoCRM Feld	Advoware Feld	Mapping
-	beteiligungen (array)	← Nur in Advoware

Hinweis: Advoware speichert die Akten-Beteiligungen direkt beim Beteiligten.

EspoCRM-spezifische Felder

Feld	Zweck
betnr	Beteiligten-Nummer (= Advoware betNr)
advowareLastSync	Zeitstempel der letzten Synchronisation
syncStatus	Status: "clean", "dirty", "syncing"
disgTyp	DISC-Persönlichkeitstyp
description	Notizen/Beschreibung
createdAt / createdById / createdByName	Audit-Felder
modifiedAt / modifiedById / modifiedByName	Audit-Felder
assignedUserId / assignedUserName	Zuweisungen
teamsIds / teamsNames	Team-Zugehörigkeit
deleted	Soft-Delete Flag
isFollowed / followersIds	Social Features

Advoware-spezifische Felder

Feld	Zweck
betNr	Interne Beteiligten-Nummer
rowId	Datenbank Row-ID
art	Beteiligten-Art
angelegtAm / angelegtVon	Erstellt
geaendertAm / geaendertVon	Geändert
kontaktpersonen (array)	Kontaktpersonen bei Firmen
ePost / bea	Spezielle Kommunikationskanäle

Mapping-Strategie

1. Person (Natürliche Person)

espocrm_to_advoware = {
    'firstName': 'vorname',
    'lastName': 'name',
    'dateOfBirth': 'geburtsdatum',
    'rechtsform': 'rechtsform',  # z.B. "Herr", "Frau"
    'salutationName': 'anrede',
    'emailAddress': 'emailGesch',
    'phoneNumber': 'telGesch',
}

2. Firma (Juristische Person)

espocrm_to_advoware = {
    'firmenname': 'name',
    'rechtsform': 'rechtsform',  # z.B. "GmbH", "AG"
    'handelsregisterNummer': 'handelsRegisterNummer',
    'emailAddress': 'emailGesch',
    'phoneNumber': 'telGesch',
}

3. Adressen

EspoCRM → Advoware:

• Lade Related Entity Adressen via adressensIds
• Mappe Hauptadresse zu Root-Feldern strasse, plz, ort
• Zusätzliche Adressen in adressen Array

Advoware → EspoCRM:

• Hauptadresse aus Root-Feldern
• adressen Array → Related Entities in EspoCRM

4. Kontaktdaten (Komplex)

EspoCRM emailAddressData:

[
  {
    "emailAddress": "primary@example.com",
    "primary": true,
    "optOut": false,
    "invalid": false
  }
]

Advoware kommunikation:

[
  {
    "id": 88002,
    "kommArt": 0,  // 0=Telefon, 1=Email, etc.
    "tlf": "0511/12345-60",
    "online": false
  }
]

Mapping: Erfordert Transformation basierend auf kommArt.

Sync-Richtungen

EspoCRM → Advoware (Webhook-getrieben)

1. Webhook empfängt CBeteiligte create/update/delete
2. Mappe Felder gemäß Tabelle oben
3. POST /api/v1/advonet/Beteiligte (create) oder PUT /api/v1/advonet/Beteiligte/{betNr} (update)
4. Update advowareLastSync und syncStatus in EspoCRM

Advoware → EspoCRM (Polling oder Webhook)

1. Überwache Änderungen in Advoware
2. Mappe Felder zurück
3. PUT /api/v1/CBeteiligte/{id} in EspoCRM
4. Setze syncStatus = "clean"

Konflikte & Regeln

Szenario	Regel
Beide Systeme geändert	Advoware als Master (führendes System)
Feld nur in EspoCRM	Ignorieren beim Export, behalten
Feld nur in Advoware	Null/Leer in EspoCRM setzen
betnr vs. betNr	Sync-Link: Muss identisch sein

ID-Mapping

Problem: EspoCRM und Advoware haben unterschiedliche ID-Systeme.

Lösung:

• EspoCRM betnr Feld = Advoware betNr
• Dies ist der Sync-Link zwischen beiden Systemen
• Bei Create in EspoCRM: betnr erst nach Advoware-Insert setzen
• Bei Create in Advoware: EspoCRM ID in Custom Field speichern?

Nächste Schritte

1. Mapper-Modul erstellen: bitbylaw/services/espocrm_mapper.py

   • map_cbeteiligte_to_advoware(espo_data) -> advo_data
   • map_advoware_to_cbeteiligte(advo_data) -> espo_data

2. Sync-Event-Step implementieren: bitbylaw/steps/vmh/beteiligte_sync_event_step.py

   • Subscribe to vmh.beteiligte.create/update/delete
   • Fetch full entity from EspoCRM
   • Transform via Mapper
   • Write to Advoware
   • Update sync metadata

3. Testing:

   • Unit Tests für Mapper
   • Integration Tests mit Sandbox-Daten
   • Konflikt-Szenarien testen

4. Error Handling:

   • Retry-Logic bei API-Fehlern
   • Validation vor dem Sync
   • Rollback bei Fehlern?
   • Logging aller Sync-Operationen

5. Performance:

   • Batch-Processing für mehrere Beteiligte
   • Rate Limiting beachten
   • Caching von Lookup-Daten

Beispiel-Transformation

EspoCRM CBeteiligte:

{
  "id": "68e4af00172be7924",
  "firstName": "Angela",
  "lastName": "Mustermanns",
  "rechtsform": "Frau",
  "emailAddress": "angela@example.com",
  "phoneNumber": "0511/12345",
  "betnr": 104860,
  "handelsregisterNummer": null
}

Advoware Beteiligter:

{
  "betNr": 104860,
  "vorname": "Angela",
  "name": "Mustermanns",
  "rechtsform": "Frau",
  "anrede": "Frau",
  "emailGesch": "angela@example.com",
  "telGesch": "0511/12345"
}

---

Generiert am: 2026-02-07 Basierend auf: Real-Daten-Vergleich mit scripts/compare_beteiligte.py