Verknüpfungen zwischen Objekttypen

Bei der Synchronisation verschiedener Objekttypen (z. B. Firma ↔ Kontakt, Kontakt ↔ Verkaufschance) müssen häufig auch deren Beziehungen/Verknüpfungen übertragen werden.
Spezialisierte Syncs erledigen dies in der Regel automatisch. Werden unbekannte Objekttypen oder Konstellationen mit dem Universal Sync verwendet, muss die Verknüpfungslogik explizit konfiguriert werden.

Grundprinzipien

• Ziel: Im Zielsystem soll eine korrekte Referenz (ID) auf das verknüpfte Objekt stehen (z. B. Kontakt.AccountId = Firma.Id).
• Pfadwahl: Zwei etablierte Wege:
  1. Verknüpfung über Datensatz-Abbildungen (bevorzugt)
  2. Verknüpfung über Suchen (wenn keine Abbildungen verfügbar sind)
• Zeitliche Abhängigkeiten: Verknüpfungen gelingen nur, wenn die benötigten Ziel-IDs bereits bekannt sind (siehe Abhängigkeiten in der Ausführung).

Ansatz A – Verknüpfungen über Datensatz-Abbildungen (empfohlen)

Wenn die beteiligten Objekttypen mit Datensatz-Abbildungen synchronisiert werden, existiert bereits eine Zuordnung von Quell-ID → Ziel-ID.

Vorteile

• Keine zusätzlichen Zielsystem-Abfragen (schneller, API-schonend)
• Eindeutige Ergebnisse aus eigener Datenbank
• Robust gegen Zielsystem-Änderungen, solange Abbildungen konsistent sind

Vorgehen (Schritt für Schritt)

1. Transformation hinzufügen:
   In der Transformation des Syncs eine neue Aktion „Datensatz-Abbildung abfragen“ einfügen.

2. Sync auswählen:
   Im Feld „Sync“ jenen Sync wählen, der den zu verknüpfenden Objekttyp überträgt
   (Beispiel: Für Kontakt.AccountId den Sync, der Firma synchronisiert).

3. Richtung & Suchwert festlegen:

   • Quell- oder Ziel-ID für die Suche wählen (abhängig davon, welche ID Sie im aktuellen Datensatz besitzen).
   • Im Suchfeld einen Platzhalter auf ein Quellfeld setzen, das die ID des verknüpften Datensatzes enthält
     (z. B. #CompanyId#).

4. Präfix (optional):
   Für die lesbaren Ergebnisfelder einen Präfix vergeben (z. B. GDM_).

5. Resultat-Felder nutzen:
   Die Transformation ergänzt automatisch (mit Präfix):

   • SourceId – ID auf Quellseite der Abbildung
   • TargetId – Ziel-ID für die Verknüpfung
   • TargetIsDeleted – Kennzeichen, falls Ziel im Zielsystem nicht (mehr) vorhanden ist

6. Feldzuordnung:
   Weisen Sie <Präfix>TargetId dem Zielfeld zu (z. B. Kontakt.AccountId ← #GDM_TargetId#).

Hinweis bei zusammengesetzten IDs:
Hat ein System mehrere ID-Felder pro Datensatz (Composite Keys), verwendet die Abbildung eine Feldnotation (z. B. NameA|:|KeyA|;|NameB|:|KeyB|;|).
Der Suchwert muss dieser Notation entsprechen – konstruieren Sie ihn aus mehreren Platzhaltern innerhalb der Transformation.

Beispiel (Kontakt → Firma)

• Gegeben: Kontakt.CompanySourceId (Quell-ID der Firma)
• Transformation:
  • Aktion: Datensatz-Abbildung abfragen (Sync: Firma-Sync)
  • Suche über Quell-ID = #CompanySourceId#
  • Präfix = GDM_
• Zuordnung: Kontakt.AccountId ← #GDM_TargetId#
• Prüfung (Vorbedingung):

  '#GDM_TargetId#' <> ''
  

Ansatz B – Verknüpfungen über Suchen im Zielsystem

Wenn keine Datensatz-Abbildungen verfügbar sind, kann die Ziel-ID per Suche ermittelt werden.
Voraussetzung: Das Zielsystem unterstützt Abfragen/Suchen und liefert eindeutige Treffer.

Nachteile

• Zusätzliche Abfragen → längere Laufzeit
• Erhöhter API-Verbrauch
• Risiko mehrdeutiger Treffer (keine eindeutige Zuordnung)

Transformationen für Abfragen

• „Daten abfragen“
  Suche in Quelle oder Ziel anhand eines Schemaobjekts. Unterstützt Filter (SQL/OData/Systemspezifisch), Sortierung und Spaltenauswahl.
• „Abfrage ausführen“
  Freies Abfrage-Statement (SQL/URL) gegen eine beliebige Verbindung – ähnlich einem Abfrage-Sync.

Vorgehen (empfohlen mit „Daten abfragen“)

1. Verbindung: Zielsystem wählen (es wird die Ziel-ID benötigt).
2. Tabelle/Scheme: Relevantes Schemaobjekt (z. B. Account) auswählen.
3. Filter: Systemspezifische Suchbedingung formulieren
   • 26. 2. OData: ?$filter=ExternalId eq '#CompanySourceId#'
4. Sortierung (optional): Eindeutigkeit unterstützen (z. B. UpdatedAt desc).
5. Spaltenauswahl: Mindestens ID-Feld übernehmen, mit Präfix (z. B. ZQ_TargetId) in die Quelldaten schreiben.
6. Feldzuordnung: Kontakt.AccountId ← #ZQ_TargetId#.

Optimierung: Speichern Sie – wenn möglich – die Quell-ID als Referenz im Ziel (z. B. Account.ExternalId = ERP.CompanyId). Das erhöht die Eindeutigkeit und vereinfacht Filter.

Abhängigkeiten in der Ausführung

Verknüpfungen gelingen nur, wenn die Ziel-ID vorliegt.

• Vorbedingung für Neuanlage: Datensatz zurückstellen, bis ID vorhanden ist:

  '#ZQ_TargetId#' <> ''

• Wiederholungen: Anzahl über „Maximale Anzahl an fortlaufenden Wiederholungen“ begrenzen/steuern.

• Abläufe/Verkettungen: Reihenfolge (z. B. Firma vor Kontakt) mit Ablauf absichern.

Fehlerbilder & Behandlung

Best Practices

• Abbildungen bevorzugen, Suchweg nur bei Bedarf.
• Eindeutige Schlüssel (ExternalId/Composite Keys) im Ziel etablieren.
• Vorbedingung nutzen, um Reihenfolge sicherzustellen.
• Performance: Abfragen sparsam einsetzen.

Flussübersicht

    flowchart TD
      A[Kontakt - Quelle] --> X2[Transform: Daten abfragen<br/>im Ziel → ZQ_TargetId]
      X2 --> V{Vorbedingung '#ZQ_TargetId#' <> ''?}
      V -- Ja --> Z[Kontakt speichern: AccountId = ZQ_TargetId]
      V -- Nein --> R[Wiederholung im nächsten Lauf]