D365CE — Dataverse / Customer Engagement

Der D365CE-Konnektor verbindet die DataBridge mit Microsoft Dataverse und Dynamics 365 Customer Engagement über das offizielle Dataverse SDK. Er nutzt die Change Tracking API für eine lückenlose Erkennung aller Änderungen.

Die Mindestversion beschreibt den getesteten Stand; eine Versionsprüfung findet im Code nicht statt.

Voraussetzung: Change Tracking aktivieren

Für alle Dataverse-Tabellen, die als Quelle genutzt werden, muss Change Tracking aktiviert sein. Ohne Change Tracking kann der Konnektor keine Differenzabfragen durchführen.

Aktivierung: Power Platform Admin Center → Umgebung → Tabellen → Tabelle auswählen → Eigenschaften → Änderungsnachverfolgung aktivieren ✅

Verbindungsparameter

{
  "connectionstring": "<XRM-Connection-String>"
}

Beispiel (Client Secret Authentication):

AuthType=ClientSecret;Url=https://<org>.crm4.dynamics.com;ClientId=<id>;ClientSecret=<secret>

Die vollständige XRM-Connection-String-Referenz findet sich in der Microsoft-Dokumentation.

Zusätzlich stehen die universellen Parameter keyVaultUrl, maxPageSize, language und httpClientTimeoutSeconds zur Verfügung — siehe Verbindungen.

Tabellen- und Feldnamen

SourceTable / TargetTable

Logischer Entitätsname in Kleinbuchstaben — so wie er in den Dataverse-Metadaten steht.

SourceField / TargetField

Logischer Attributname in Kleinbuchstaben.

Unterstützte TargetKey-Typen

Bei CustomKey werden Schlüsselteile vom Typ int32, guid und string unterstützt; jeder andere Typ führt zum Abbruch (keytype … not yet supported for key …). Leere Schlüsselteile werden übersprungen — bleibt danach kein Teil übrig, gilt der Schlüssel als nicht auflösbar.

Ein KeyValue kann statt attributeName ein StaticValue enthalten; der Schlüsselteil wird dann fest gesetzt und als Typ string behandelt.

Mehrere Ziel-Schlüssel mit Rangfolge (ab v2.1)

Statt eines einzelnen TargetKey lässt sich eine Liste TargetKeys angeben. Die Schlüssel werden nach KeyRank aufsteigend geprüft; der erste Schlüssel, der im Zielsystem einen Datensatz findet, gewinnt — alle weiteren werden übersprungen.

{
  "Operations": [
    {
      "Name": "Lookup",
      "Parameters": {
        "TargetTable": "wysa_countryregion",
        "TargetKeys": [
          {
            "KeyType": "CustomKey",
            "KeyRank": 1,
            "KeyName": "wysa_externalid",
            "KeyValues": [
              { "keyName": "wysa_externalid", "attributeName": "externalId", "rank": 1 }
            ]
          },
          {
            "KeyType": "CustomKey",
            "KeyRank": 2,
            "KeyName": "wysa_code",
            "KeyValues": [
              { "keyName": "wysa_code", "attributeName": "countryRegionCode", "rank": 1 }
            ]
          }
        ]
      }
    }
  ]
}

Bestehende Mappings mit einem einzelnen TargetKey funktionieren unverändert weiter.

SourceOperations

LookupValue

Liest einen Wert aus einem verknüpften Dataverse-Datensatz nach.

{
  "Operations": [
    {
      "Name": "LookupValue",
      "Parameters": {
        "LookupType": "Attribute",
        "SourceField": "wysa_countrycode",
        "LookupTable": "wysa_country",
        "LookupField": "wysa_name",
        "UseCache": true
      }
    }
  ]
}

LookupType kennt zwei Werte. Nur der CE-Konnektor unterstützt beide:

ReadFromMessage

Liest Werte aus einer vorherigen Quellanfrage — nur in ResponseJobs. Verhalten wie beim D365BC-Konnektor.

ActivityParty

Liest ein Feld über eine ActivityParty-Beziehung. Wird für CE-Aktivitäten (E-Mails, Aufgaben, Anrufe) verwendet, bei denen Teilnehmer über den activityparty-Datensatz verknüpft sind.

{
  "Operations": [
    {
      "Name": "ActivityParty",
      "Parameters": {
        "PartyParams": {
          "TypeMask": 2,
          "SourceField": "activityid",
          "TargetField": "wysa_number",
          "TargetTable": "contact"
        }
      }
    }
  ]
}

TypeMask entspricht dem Dataverse-Feld participationtypemask und wird von der DataBridge unverändert an die Abfrage durchgereicht. Die gültigen Werte gibt die Dataverse-Plattform vor; die gebräuchlichsten sind:

Diese Tabelle ist eine Plattform-Referenz, keine Festlegung der DataBridge. Die verbindliche und vollständige Liste steht in der Microsoft-Dokumentation zur Entität activityparty.

LinkToRecord

Erzeugt eine anklickbare URL zu einem Datensatz in Dataverse.

{
  "Operations": [
    {
      "Name": "LinkToRecord",
      "Parameters": {
        "BaseUrl": "https://<org>.crm4.dynamics.com/main.aspx?appid=<AppId>&pagetype=entityrecord"
      }
    }
  ]
}

TargetOperations

Lookup

Befüllt ein Lookup-Feld in Dataverse, indem der verknüpfte Datensatz über eine Feldwert-Kombination gesucht wird. Die Operation gehört in die Spalte TargetOperation des Mappings und benötigt zwingend den Operations-Rahmen, den Namen Lookup sowie TargetTable.

{
  "Operations": [
    {
      "Name": "Lookup",
      "Parameters": {
        "TargetTable": "wysa_countryregion",
        "TargetKey": {
          "KeyType": "CustomKey",
          "KeyName": "wysa_code",
          "KeyValues": [
            { "keyName": "wysa_code", "attributeName": "countryRegionCode", "rank": 1 }
          ]
        }
      }
    }
  ]
}

Wird kein passender Datensatz gefunden, legt die DataBridge standardmäßig einen neuen an.

Weitere Parameter der TargetOperation

DoNotCreate (ab v2.1)

Ist DoNotCreate auf true gesetzt, wird der Zieldatensatz eines Lookups nur dann verknüpft, wenn er bereits existiert. Wird er nicht gefunden, bleibt das Feld leer — es entsteht kein neuer Datensatz.

{
  "Operations": [
    {
      "Name": "Lookup",
      "Parameters": {
        "TargetTable": "wysa_countryregion",
        "DoNotCreate": true,
        "TargetKey": {
          "KeyType": "CustomKey",
          "KeyName": "wysa_code",
          "KeyValues": [
            { "keyName": "wysa_code", "attributeName": "countryRegionCode", "rank": 1 }
          ]
        }
      }
    }
  ]
}

OptionMapping

Übersetzt Quellwerte in numerische Dataverse-Optionset-Werte.

{
  "Operations": [
    {
      "Name": "OptionMapping",
      "Parameters": {
        "Mapping": [
          { "Key": "Blank",                        "Value": "" },
          { "Key": "Prospect",                     "Value": "383380000" },
          { "Key": "First_x002D_time_x0020_Donor", "Value": "383380001" },
          { "Key": "Recurring_x0020_Donor",        "Value": "383380002" }
        ]
      }
    }
  ]
}

Ein leerer Value setzt das Zielfeld auf null. Ein Quellwert, der in der Liste nicht vorkommt, führt zum Abbruch (Could not find TableMapping for …).

Datentypen — Zieltyp und akzeptierte Quelltypen

Beim Schreiben bestimmt der Attributtyp des Zielfeldes aus den Dataverse-Metadaten, welche Umwandlung angewendet wird.

Sonderfälle jenseits der Tabelle:

• UniqueIdentifierAttributeMetadata sowie Primärschlüssel- und logische Attribute (z. B. statuscodename) werden beim Schreiben stillschweigend übersprungen
• FileAttributeMetadata und ImageAttributeMetadata werden nicht unterstützt (type not supported)
• Jeder sonstige, nicht aufgeführte Attributtyp führt zum Abbruch (Type … not yet implemented)

Sonderentitäten

Einige Dataverse-Entitäten werden nicht über den generischen Weg verarbeitet.

listmember — Marketinglisten

Datensätze der Entität listmember werden nicht über den generischen Schreibpfad angelegt oder gelöscht, sondern über die Dataverse-Nachrichten AddMemberList bzw. RemoveMemberList. Das Mapping muss daher die Felder listid und entityid befüllen — sie liefern die Kennungen für die beiden Nachrichten.

Entitäten ohne statuscode

Für die folgenden Entitäten wird das Attribut statuscode beim Lesen automatisch aus der Spaltenliste entfernt, weil sie es nicht besitzen:

Ein Job-Filter mit der Operation StatusCode ist für diese Entitäten folglich nicht verwendbar.

Job-Filter

Der CE-Konnektor wertet das Feld Filter des Jobs clientseitig aus: Die Datensätze werden über die Change Tracking API abgerufen und anschließend geprüft; nicht passende Datensätze werden verworfen.

Unterstützt werden die Operationen Equals, Boolean, OptionSetValue, NotNull, IsNull und StatusCode. Ein anderer Operationsname führt zum Abbruch (Undefined FilterOperation).

Syntax, Parameter und Beispiele sind unter Jobs → Filter-Syntax beschrieben.

Änderungserkennung (Watermark)

Der CE-Konnektor nutzt die Dataverse Change Tracking API. Diese liefert bei jedem Abruf einen opaken Token, der beim nächsten Aufruf übergeben wird. So werden alle Änderungen erfasst — auch wenn der Timer genau während einer Änderung ausgeführt wird.