Microsoft Dynamics 365 Customer Engagement Konnektor

Der Microsoft Dynamics 365 Customer Engagement (CE) Konnektor stellt die Schnittstelle zwischen Syncler und Dynamics 365 CE bereit.
Er ermöglicht die bidirektionale Synchronisation von Daten über die offizielle Dynamics Web-API und unterstützt sowohl lesende als auch schreibende Vorgänge auf Entitäten wie Kontakte, Accounts, Leads, Opportunities, Aktivitäten u. v. m.

Die Authentifizierung erfolgt über Microsoft OAuth 2.0 (Authorization Code Flow oder Client Credentials Flow).
Für die Einrichtung ist eine App-Registrierung in Microsoft Entra ID (Azure AD) erforderlich.

Voraussetzungen

Zur Nutzung des Konnektors wird eine registrierte Anwendung in Microsoft Entra ID benötigt.
Diese liefert die erforderlichen Anmeldeinformationen (Mandant, Client-ID, Geheimschlüssel, Redirect URI).

Registrierung der Anwendung

1. Öffnen Sie das Registrierungsportal:
   https://go.microsoft.com/fwlink/?linkid=2083908
2. Melden Sie sich mit Ihrem Microsoft-Konto an und wählen Sie „Neue Registrierung“.
3. Geben Sie einen Namen für die App an und klicken Sie auf „Registrieren“.
4. Notieren Sie sich:
   • Anwendungs-ID (Client)
   • Verzeichnis-ID (Mandant)
5. Öffnen Sie den Bereich API-Berechtigungen und fügen Sie die Berechtigung
   Dynamics CRM → user_impersonation hinzu.
6. Für Client-Anmeldeinformationen:
   • Erstellen Sie unter Zertifikate & Geheimnisse ein neues Geheimnis.
   • Tragen Sie es im Feld Client-Geheimschlüssel im Konnektor ein.
   • Aktivieren Sie die Option Client-Anmeldeinformationen verwenden.
7. Für OAuth 2.0 mit Benutzeranmeldung:
   • Definieren Sie eine Redirect URI, z. B. https://admin.syncler.com/oauth-callback.html.
   • Diese muss in der App-Registrierung hinterlegt werden.
8. Einrichtung der Entra-Anwendung in Dynamics 365 (Application user)
   • Power Platform admin center (https://admin.powerplatform.microsoft.com/)
   • Verwalten und Umgebungen auswählen
   • Ihre Umgebung Einstellungen aufrufen, dann Benutzer und Berechtigungen und Anwendungsbenutzer
   • Registrierte App hinzufügen und Sicherheitsrollen zuweisen

Einrichtung

1. Neues System anlegen

• Erstellen Sie in Syncler ein neues System mit dem Typ „Dynamics 365 Customer Engagement“.
• Geben Sie Name und Beschreibung an.

2. Verbindung konfigurieren

• Tragen Sie die folgenden Werte ein:
  • Verzeichnis-ID (Mandant)
  • Anwendungs-ID (Client)
  • Optional: Client-Geheimschlüssel
  • Redirect URI
  • Web-API-Endpunkt (z. B. https://org.crm4.dynamics.com/api/data/v9.2/)
    • Melden Sie sich dazu in Dynamics 365 an (make.powerapps.com) und wählen Sie die Umgebung aus. Mit dem Zahnrad oben rechts können Sie die Entwicklerressourcen aufrufen. Unter Instanz-Web-API finden Sie die spezifische URL für Ihre Instanz.
  • Scopes (z. B. https://org.crm4.dynamics.com/.default)
• Aktivieren Sie bei Bedarf Client-Anmeldeinformationen verwenden.

3. OAuth 2.0 Anmeldung durchführen

• Bei Verwendung der Benutzeranmeldung:
  • Starten Sie die Authentifizierung über die Registerkarte Microsoft 365 OAuth 2.0.
  • Melden Sie sich bei Microsoft an und gewähren Sie der App Zugriff.
  • Nach der Bestätigung wird ein Refresh Token gespeichert.

Picklisten

Der Konnektor erzeugt automatisch Auswahllisten (Picklists) auf Basis der in den Metadaten enthaltenen Enum-Typen.
Diese Listen stehen anschließend für Transformationen, Feldzuordnungen und Validierungen in Syncs zur Verfügung.

Picklisten werden beim Laden des Schemas automatisch erzeugt und aktualisiert.

Funktionen

Lesen von Daten

• Über die Web-API werden einzelne oder mehrere Datensätze abgefragt.
• Filter können im OData-Syntax angegeben werden.
• Abfragen lassen sich flexibel über Universal Syncs definieren.
• Lookup-Felder werden automatisch behandelt (siehe Abschnitt Besonderheiten).

Lesen von Abfragen

• Lesende Abfragen werden direkt über den Web-API-Endpunkt ausgeführt.
• Im Sync wird nur der relative URL-Teil (ohne führenden /) angegeben.

Schreiben von Daten

• Datensätze können angelegt, geändert oder gelöscht werden.
• Lookup-Felder werden automatisch im korrekten API-Format konvertiert.
• Löschvorgänge werden unterstützt.

Besonderheiten

Lookup-Felder

Lookup-Felder (z. B. Kunde, Suche, Bezug) erfordern eine spezielle Behandlung, die der Konnektor automatisch vornimmt. Dies ist nur beim Schema-basierten Lesen möglich. Im Abfrage-basierten Lesen werden alle Daten des Resultats direkt übergeben. In diesem Fall steht der Wert nicht unter der eigentlichen Feldbezeichnung zur Verfügung. Wenn nach Werten in diesen Feldern gefiltert werden soll, muss die Variante "_entityid_value" verwendet werden.

Wenn ein Feld ein oder mehrere Lookup-Ziele hat, werden diese in der Feldbeschreibung im Schema dargestellt. Einfache Ziele werden durch den Konnektor automatisch behandelt, solange es sich um eine bekannte Zielentität handelt. Bei Zielen, die nicht in den verfügbaren Schemaobjekte vorhanden sind, muss die Wertübergabe anders erfolgen.

Lesen:

• Dynamics liefert Lookup-Werte in Feldern mit dem Suffix _entityid_value.
• Der Konnektor überträgt diese Werte in die eigentlichen Felder.

Schreiben:

• Lookup-Felder werden als Feldname@odata.bind übergeben.

Beispiele:

Bekannte Entität:

transactioncurrencyid → transactioncurrencies(83883308-7ad5-ea11-a813-000d3a33f3b4)

Die Entität "transactioncurrency" ist bekannt und einem Feld "transactioncurrencyid" kann direkt der ID-Wert zugewiesen werden.

Unbekannte Entität:

accounts|:|83883308-7ad5-ea11-a813-000d3a33f3b4|;|
→ Feld@odata.bind : accounts(83883308-7ad5-ea11-a813-000d3a33f3b4)

Damit die Wertübergabe an die Web-API möglich ist, muss der Wert in Feldnotation angegeben werden. Für die Bezeichnung muss der CollectionName der Entität verwendet werden.

Mehrfache Ziele (z. B. Kunde):

account|:|83883308-7ad5-ea11-a813-000d3a33f3b4|;|
→ Feld_account@odata.bind : accounts(83883308-7ad5-ea11-a813-000d3a33f3b4)

Wenn mehrere Ziele möglich sind, z.B. beim Feldtyp Kunde, muss die Wertübergabe generell in Feldnotation erfolgen. Die Bezeichnung definiert dabei das gewünschte Ziel und der CollectionName wird über das Schemaobjekt ermittelt.