Konnektoren

• 1: D365BC — Business Central
• 2: D365CE — Dataverse / Customer Engagement
• 3: D365NAV — Microsoft Dynamics NAV
• 4: MSSQL — Microsoft SQL Server
• 5: MySQL — MySQL / MariaDB
• 6: Oracle — Oracle Database
• 7: PostgreSQL
• 8: OpenAPI — generischer REST-Konnektor

1 - D365BC — Business Central

Der D365BC-Konnektor verbindet die DataBridge mit Microsoft Dynamics 365 Business Central über die OData-v4-REST-API (API-Version 2.0). Er unterstützt sowohl Cloud-Umgebungen (OAuth2) als auch OnPremise-Installationen (Basic Auth).

Verbindungsparameter

Cloud-Umgebung (empfohlen)

{
  "clientId": "<App-Registration Client ID>",
  "clientSecret": "<App-Registration Client Secret>",
  "tenantId": "<Entra Tenant ID>",
  "environment": "<BC-Umgebungsname, z. B. production>",
  "companyId": "<Company ID (GUID)>"
}

Cloud-Umgebung mit Managed Identity (ab v2.3)

Ohne Client Secret, über die Managed Identity der Function App:

{
  "authmethod": "ManagedIdentity",
  "clientId": "<Client-ID der user-assigned Identity, optional>",
  "environment": "<BC-Umgebungsname, z. B. production>",
  "companyId": "<Company ID (GUID)>"
}

• Ohne clientId wird die system-zugewiesene Identity der Function App verwendet, mit clientId die benutzer-zugewiesene.
• clientSecret und tenantId sind nicht nötig. Der Token wird mit dem scope der Connection angefordert und rechtzeitig vor Ablauf erneuert.
• Managed Identity wird nur über authmethod aktiviert, nie automatisch.
• Voraussetzung: Die Identity ist in Business Central unter Microsoft-Entra-Anwendungen angelegt, aktiviert und mit Berechtigungssätzen versehen.

OnPremise-Umgebung

{
  "userName": "<domain\\benutzername>",
  "password": "<Passwort>",
  "url": "https://<server>:<port>/<pfad>",
  "companyId": "<Company ID (GUID)>"
}

Ist url gesetzt, wird daraus die Basisadresse gebildet (<url>/api/) und environment nicht ausgewertet. Ist url leer, verwendet der Konnektor den Cloud-Endpunkt und bildet die Adresse aus environment.

Die Auswahl des Authentifizierungsverfahrens erfolgt automatisch: Sind userName und password gesetzt, wird Basic Auth verwendet, andernfalls OAuth2 Client Credentials aus clientId, clientSecret und tenantId. Mit authmethod lässt sich die Methode ausdrücklich festlegen.

Optionale Parameter

Gelten für Cloud und OnPremise:

Die drei Diagnose-Schalter erzeugen erhebliche Datenmengen und können Geschäftsdaten im Klartext protokollieren — nur gezielt für die Dauer einer Analyse aktivieren. Vollständige Beschreibung unter Verbindungen.

Tabellen- und Feldnamen

SourceTable / TargetTable

Der Tabellenname leitet sich aus dem API-Pfad der Business-Central-API v2.0 ab — ohne den Company-Teil der URL.

SourceField / TargetField

Exakter Feldname aus der BC-API-Seite (case-sensitive). Zu finden in der BC-API-Dokumentation oder über den API-Explorer in Business Central.

Unterstützte TargetKey-Typen

Statische Schlüsselwerte (ab v2.1)

In einem KeyValue kann statt attributeName ein StaticValue angegeben werden. Der Schlüsselteil wird dann nicht aus dem Quelldatensatz gelesen, sondern fest gesetzt.

{
  "KeyType": "CustomKey",
  "KeyName": "wysa_number",
  "KeyValues": [
    { "keyName": "sourceSystem", "StaticValue": "DataBridge",   "rank": 1 },
    { "keyName": "customerNo",   "attributeName": "bcCustomerNo", "rank": 2 }
  ]
}

Statische Werte werden für die BC-Metadatentypen string, guid und int32 unterstützt. Bei jedem anderen Typ des Schlüsselfeldes bricht die Verarbeitung mit einem Fehler ab (Metadata type … not yet implemented for CreateKeyString).

SourceOperations

LookupValue

Liest einen Wert aus einer anderen BC-API-Tabelle nach.

{
  "Operations": [
    {
      "Name": "LookupValue",
      "Parameters": {
        "LookupType": "Attribute",
        "SourceField": "countryRegionCode",
        "LookupTable": "publisher/product/v1.0/countriesRegions",
        "LookupField": "name",
        "UseCache": true
      }
    }
  ]
}

LookupType kennt die beiden Werte Attribute und Name. Business Central unterstützt ausschließlich Attribute; der Wert Name führt zu einem Abbruch (SourceOperation for Lookups). Name ist dem D365CE-Konnektor vorbehalten.

ReadFromMessage

Liest einen Wert aus der BC-Antwort — nur in ResponseJobs. Das SourceField muss einen _-Prefix haben.

{
  "Operations": [
    {
      "Name": "ReadFromMessage"
    }
  ]
}

Datentypen — Zieltyp und akzeptierte Quelltypen

Beim Schreiben bestimmt der Datentyp des Zielfeldes in den BC-Metadaten, welche Umwandlung angewendet wird. Der Quelltyp stammt aus dem Feldtyp des Quellsystems und entscheidet, ob die Umwandlung gelingt.

Jeder in der Tabelle nicht genannte BC-Zieltyp führt beim Schreiben zu einem Abbruch (No Resolver defined for edmPrimitiveTypeKind …).

Schreibvorgang und Fehlerverhalten

Vor jedem Schreibvorgang sucht der Konnektor den bestehenden Zieldatensatz — je nach TargetKey-Typ über den Schlüssel oder über einen Filter. Wird ein Datensatz gefunden, erfolgt ein Update, andernfalls eine Neuanlage.

ResponseJob — BC-IDs zurückschreiben

Wenn BC beim Anlegen eines Datensatzes eine neue ID vergibt (z. B. die Kundennummer), kann diese über einen ResponseJob automatisch ins Quellsystem zurückgeschrieben werden.

Beispiel: CE-Kontakt nach BC anlegen und BC-ID zurück nach CE schreiben

Job A (Hauptjob):

SourceConnection: ce-produktion
TargetConnection: bc-produktion
Mapping:          ce-contact-to-bc-customer
ResponseJob:      bc-id-back-to-ce
IsActive:         true

Job B (ResponseJob):

SourceConnection: bc-produktion
TargetConnection: ce-produktion
Mapping:          bc-response-to-ce-contact
IsActive:         false

Mapping für Job B — das BC-ID-Feld:

Änderungserkennung (Watermark)

Business Central liefert für jede Entität ein lastModifiedDateTime-Feld, das beim Speichern automatisch aktualisiert wird.

Der Filterausdruck aus dem Job wird als OData-$filter an die BC-Anfrage angehängt. Die Regeln zur Klammerung und zum Platzhalter %watermark% sind unter Jobs → Filter-Syntax beschrieben.

2 - 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>

Alternative: Managed Identity (ab v2.3)

Statt eines Connection-Strings mit Secret kann die Verbindung über eine Managed Identity aufgebaut werden:

{
  "url": "https://<org>.crm4.dynamics.com",
  "clientid": "<Client-ID der user-assigned Identity, optional>"
}

• Ohne clientid wird die system-zugewiesene Identity der Function App verwendet, mit clientid die benutzer-zugewiesene.
• Ist connectionstring gesetzt, hat er immer Vorrang; url wird dann ignoriert.
• Sind weder connectionstring noch url gesetzt, bricht der Verbindungsaufbau mit einem Fehler ab.
• Voraussetzung: Die Identity ist in der Dataverse-Umgebung als Application User angelegt und hat eine passende Sicherheitsrolle (Power Platform Admin Center → Umgebung → Einstellungen → Benutzer + Berechtigungen → Anwendungsbenutzer).

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.

Ist der Alternativschlüssel in Dataverse nicht angelegt oder nicht aktiv, bricht die Suche mit einem Fehler ab (ab v2.3). Die Nachricht landet nach den Wiederholungen in der Dead-Letter-Queue und wird nicht als neuer Datensatz angelegt. Bis v2.2 wurde dieser Fall wie „Datensatz nicht gefunden“ behandelt, was zu Dubletten führen konnte.

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.

3 - D365NAV — Microsoft Dynamics NAV

Der D365NAV-Konnektor verbindet die DataBridge mit Microsoft Dynamics NAV über OData. Er ist auf die ältere NAV-API-Struktur ausgelegt und unterstützt auch OnPremise-Installationen mit NTLM-Authentifizierung.

Verbindungsparameter

Cloud-Umgebung (OAuth2)

{
  "clientId": "<App-Registration Client ID>",
  "clientSecret": "<App-Registration Client Secret>",
  "tenantId": "<Entra Tenant ID>",
  "environment": "<NAV-Umgebungsname>",
  "companyId": "<Company ID (GUID)>",
  "url": "https://<server>/<pfad>/"
}

OnPremise-Umgebung (NTLM)

{
  "userName": "<domain\\benutzername>",
  "password": "<Passwort>",
  "url": "https://<server>:<port>/<pfad>/",
  "baseAddress": "https://<server>:<port>/",
  "authenticationMethod": "NTLM"
}

Optionale Parameter

Die drei Diagnose-Schalter erzeugen erhebliche Datenmengen und können Geschäftsdaten im Klartext protokollieren — nur gezielt für die Dauer einer Analyse aktivieren. Vollständige Beschreibung unter Verbindungen.

Tabellen- und Feldnamen

• SourceTable / TargetTable: Name des OData-EntitySets, so wie er in $metadata steht
• SourceField / TargetField: Exakter Feldname aus der NAV-OData-API (case-sensitive)

Unterstützte TargetKey-Typen

Bei CustomKey werden die Metadatentypen int32 und string unterstützt, bei Filter die Typen string und guid. Jeder andere Typ des Schlüsselfeldes führt zum Abbruch (Metadata type … not yet implemented for CreateKeyString).

SourceOperations

LookupValue

Liest einen Wert aus einer anderen NAV-Tabelle nach — Aufbau und Parameter wie beim D365BC-Konnektor.

{
  "Operations": [
    {
      "Name": "LookupValue",
      "Parameters": {
        "LookupType": "Attribute",
        "SourceField": "countryRegionCode",
        "LookupTable": "CountryRegions",
        "LookupField": "Name",
        "UseCache": true
      }
    }
  ]
}

Unterstützt wird ausschließlich LookupType: Attribute. Der Wert Name führt zu einem Abbruch (SourceOperation for Lookups).

ReadFromMessage

Liest einen Wert aus der NAV-Antwort — nur in ResponseJobs. Das SourceField muss einen _-Prefix haben. Verhalten wie bei D365BC.

Datentypen — Zieltyp und akzeptierte Quelltypen

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

Jeder in der Tabelle nicht genannte NAV-Zieltyp führt beim Schreiben zu einem Abbruch (No Resolver defined for edmPrimitiveTypeKind …).

ResponseJob

Der NAV-Konnektor unterstützt das ResponseJob-Muster wie D365BC: Nach erfolgreichem Schreiben in NAV kann ein ResponseJob ausgelöst werden, der Felder aus der NAV-Antwort (z. B. neu vergebene Nummern) zurück ins Quellsystem schreibt. Aufbau und Konfiguration sind unter D365BC → ResponseJob beschrieben.

Änderungserkennung (Watermark)

Im Gegensatz zu Business Central gibt es kein einheitliches lastModifiedDateTime-Feld. Das korrekte Watermark-Feld hängt von der NAV-Version und der verwendeten Seite bzw. Codeunit ab. Im Zweifelsfall mit dem NAV-Administrator klären.

Der Filterausdruck aus dem Job wird als OData-$filter an die NAV-Anfrage angehängt. Die Regeln zur Klammerung und zum Platzhalter %watermark% sind unter Jobs → Filter-Syntax beschrieben.

Fehlersuche

Fehler beim Schreiben werden mit dem Text Error in NAV-Communication protokolliert, zusammen mit der verwendeten relativen Adresse sowie dem neuen und dem bestehenden Datensatz. Bis einschließlich v2.0 lautete derselbe Text irreführend Error in BC-Communication — ältere Logeinträge einer NAV-Verbindung sind also trotz BC-Nennung dem NAV-Konnektor zuzuordnen.

4 - MSSQL — Microsoft SQL Server

Der MSSQL-Konnektor ermöglicht das Lesen von Daten aus Microsoft SQL Server-Datenbanken (OnPremise und Azure SQL) und deren Übertragung in andere Systeme.

Wie die übrigen drei SQL-Konnektoren wertet MSSQL den Filter des Jobs aus und erzeugt gültiges Paging für sein Datenbanksystem.

Verbindungsparameter

{
  "connectionstring": "<ADO.NET Connection String>"
}

Beispiel (SQL Server Authentication):

Server=<server>;Database=<db>;User Id=<user>;Password=<password>;TrustServerCertificate=True;

Beispiel (Windows Authentication / Integrated Security):

Server=<server>;Database=<db>;Integrated Security=True;TrustServerCertificate=True;

Optionale Parameter

Tabellen- und Feldnamen

Der Wert aus SourceTable wird unverändert hinter FROM eingesetzt.

Änderungserkennung (Watermark)

Die Erkennung basiert auf einer Zeitstempel-Spalte in der SQL-Tabelle. Diese Spalte muss beim Einfügen oder Ändern eines Datensatzes automatisch aktualisiert werden.

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung (ORDER BY … ASC) verwendet.

Filter — die WHERE-Klausel kommt aus dem Job

Ein typischer Filter für eine MSSQL-Quelle:

{{ModifiedAt > '%watermark%'}}

Die Klammerung {{ … }} sorgt dafür, dass der Block bei leerer Watermark vollständig entfällt — der Erstlauf liest dann den gesamten Bestand. Die vollständigen Regeln stehen unter Jobs → Filter-Syntax.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist beim MSSQL-Konnektor allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

5 - MySQL — MySQL / MariaDB

Der MySQL-Konnektor ist für das Lesen von Daten aus MySQL- und MariaDB-Datenbanken vorgesehen.

Wie beim MSSQL-Konnektor wird der Inhalt des Feldes Filter am Job — nach Ersetzung des Platzhalters %watermark% — wörtlich hinter WHERE eingesetzt. Ohne Eintrag im Feld Filter entsteht keine WHERE-Klausel und der Job liest bei jedem Lauf die vollständige Tabelle. Der Ausdruck muss gültiges MySQL-SQL sein; es findet keine Parametrisierung statt. Details zur Filter-Syntax siehe MSSQL — Filter.

Verbindungsparameter

{
  "connectionstring": "<MySQL Connection String>"
}

Beispiel:

Server=<server>;Database=<db>;User=<user>;Password=<password>;

Optionale Parameter

Tabellen- und Feldnamen

Änderungserkennung (Watermark)

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung verwendet.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

6 - Oracle — Oracle Database

Der Oracle-Konnektor ist für das Lesen von Daten aus Oracle-Database-Instanzen vorgesehen.

Wie beim MSSQL-Konnektor wird der Inhalt des Feldes Filter am Job — nach Ersetzung des Platzhalters %watermark% — wörtlich hinter WHERE eingesetzt. Ohne Eintrag im Feld Filter entsteht keine WHERE-Klausel und der Job liest bei jedem Lauf die vollständige Tabelle. Der Ausdruck muss gültiges PL/SQL sein; es findet keine Parametrisierung statt. Details zur Filter-Syntax siehe MSSQL — Filter.

Verbindungsparameter

{
  "connectionstring": "<Oracle Connection String>"
}

Beispiel (TNS):

Data Source=<tns-alias>;User Id=<user>;Password=<password>;

Beispiel (Easy Connect):

Data Source=<server>:<port>/<service>;User Id=<user>;Password=<password>;

Optionale Parameter

Tabellen- und Feldnamen

Änderungserkennung (Watermark)

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung verwendet.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

7 - PostgreSQL

Der PostgreSQL-Konnektor ermöglicht das Lesen von Daten aus PostgreSQL-Datenbanken und deren Übertragung in andere Systeme.

Wie beim MSSQL-Konnektor wird der Inhalt des Feldes Filter am Job — nach Ersetzung des Platzhalters %watermark% — wörtlich hinter WHERE eingesetzt. Ohne Eintrag im Feld Filter entsteht keine WHERE-Klausel und der Job liest bei jedem Lauf die vollständige Tabelle. Der Ausdruck muss gültiges PostgreSQL-SQL sein; es findet keine Parametrisierung statt. Details zur Filter-Syntax siehe MSSQL — Filter.

Verbindungsparameter

{
  "connectionstring": "<PostgreSQL Connection String>"
}

Beispiel (Npgsql-Format):

Host=<server>;Database=<db>;Username=<user>;Password=<password>;

Optionale Parameter

Tabellen- und Feldnamen

Der Wert aus SourceTable wird unverändert hinter FROM eingesetzt.

Änderungserkennung (Watermark)

Die Spalte aus WatermarkField wird zusätzlich zu den gemappten Feldern abgefragt und für die Sortierung (ORDER BY … ASC) verwendet.

Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist allein der Lesepfad relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die Auswahl der Umwandlung verwendet.

Zahlen werden in der Kultur der Quellverbindung formatiert. Steht dort der Vorgabewert de-DE, wird ein Komma als Dezimaltrennzeichen ausgegeben — für Zielumwandlungen, die einen Textwert zwingend als en-US lesen, ist language entsprechend anzupassen.

Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite: D365BC, D365CE, D365NAV.

8 - OpenAPI — generischer REST-Konnektor

Der OpenAPI-Konnektor verbindet die DataBridge mit einer beliebigen REST-API, für die eine OpenAPI-Spezifikation (JSON oder YAML) existiert. Anders als bei den übrigen HTTP- Konnektoren werden Pfade, Wrapper-Schlüssel ({"clients": [...]} vs. {"client": {...}}) und Feldtypen nicht pro Ressource fest verdrahtet, sondern zur Laufzeit aus der Spezifikation aufgelöst. Ein Mapping muss dafür lediglich SourceTable/TargetTable auf den Ressourcennamen setzen (z. B. clients).

Verbindungsparameter

{
  "baseUrl": "https://api.example.com",
  "openApiSpecUrl": "https://api.example.com/openapi.yaml",
  "clientId": "<Client-ID>",
  "clientSecret": "<Client-Secret>",
  "tenantId": "<Entra Tenant ID>",
  "scope": "<OAuth2-Scope>",
  "tokenUrl": "https://api.example.com/oauth/token",
  "apiKeyHeader": "X-API-Key",
  "apiKeyValue": "<API-Key>",
  "customHeaders": { "X-Custom-Header": "wert" },
  "nextLinkPath": "@odata.nextLink",
  "nextPagePath": "meta.next_page",
  "pageQueryParam": "page",
  "pageSizeQueryParam": "per_page",
  "updateMethod": "PATCH",
  "authenticateSpecRequest": false
}

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

Authentifizierung

Der OpenAPI-Konnektor nutzt dieselbe Auswahllogik wie die übrigen HTTP-Konnektoren, erweitert um API-Key-Authentifizierung:

{
  "apiKeyHeader": "X-Qonto-Staging-Token",
  "apiKeyValue": "<Token>"
}

Zusätzliche statische Header (z. B. mandantenspezifische Tokens, die parallel zu OAuth2 oder API-Key benötigt werden) lassen sich unabhängig von der Authentifizierungsmethode über customHeaders mitgeben.

Tabellen- und Feldnamen

• SourceTable / TargetTable: kurzer Ressourcenname, wie er in der OpenAPI-Spezifikation als letztes Pfadsegment vorkommt (z. B. clients für /v2/clients). Der Konnektor sucht in der Spezifikation nach einem Pfad, der auf /<Ressourcenname> endet und keine Parameter enthält; ein zugehöriger Einzeldatensatz-Pfad (/v2/clients/{id}) wird automatisch mitaufgelöst.
• Alternativ kann auch der vollständige Pfad aus der Spezifikation eingetragen werden (Rückwärtskompatibilität).
• SourceField / TargetField: Feldname aus dem JSON-Schema der Ressource. Verschachtelte Felder werden mit Punktnotation adressiert (z. B. phone.country_code).

Liste- und Einzeldatensatz-Antworten müssen nicht manuell konfiguriert werden: Wrapper- Schlüssel wie {"clients": [...]} oder {"client": {...}} werden aus der Spezifikation erkannt. Fehlen entsprechende Hinweise in der Spezifikation, erkennt der Konnektor ersatzweise die gebräuchlichen Muster value, data und results als Array-Wrapper.

Unterstützte TargetKey-Typen

Wird bei CustomKey/Filter mehr als ein Datensatz gefunden, bricht die Verarbeitung mit einem Fehler ab (Found more than 1 record).

Schreiben (Upsert)

Der Konnektor prüft vor jedem Schreibvorgang, ob bereits ein Zieldatensatz existiert (GetSingleRequest bei PrimaryKey/Id/CustomKey, ein gefilterter Liste-Abruf bei Filter). Existiert er, wird nur bei tatsächlicher Werteänderung ein Update ausgelöst — identische Werte führen zu keiner Anfrage.

• Anlegen: POST auf den Collection-Pfad

• Aktualisieren: PATCH (Vorgabe) oder PUT (updateMethod) auf den Item-Pfad

• Anfrage-Body wird bei Bedarf automatisch in einen aus der Spezifikation abgeleiteten Wrapper-Schlüssel eingebettet (z. B. {"client": {...}}). Ein Job kann das über SpecialSettings gezielt abschalten:

  { "DoNotWrapRequestBody": true }
  

• Ein 409 Conflict bei Anlegen oder Aktualisieren wird als transiente Ausnahme behandelt und über die Transitive-Queue erneut verarbeitet (siehe Architektur → Retry- und Fehlerverhalten).

Löschen

Anders als die SQL-Konnektoren unterstützt der OpenAPI-Konnektor Löschungen: Der Schlüssel wird wie beim Lookup aufgelöst, anschließend folgt ein DELETE auf den Item-Pfad. Bei TargetKey vom Typ Filter wird der Datensatz zuerst gesucht. Wird keiner gefunden, schreibt der Konnektor eine Warnung ins Log und sendet kein DELETE.

InvokeAction — generische Aktionsaufrufe

Neben dem klassischen CRUD-Zyklus unterstützt die DataBridge seit dieser Version Aktions-Jobs: Ein Job mit Action = InvokeAction (technisch: jeder Wert, der nicht auf einen bekannten JobActionType passt) ruft einen benannten, nicht-CRUD-Endpunkt auf, statt einen Datensatz anzulegen oder zu ändern — z. B. POST /v2/client_invoices/{id}/send_by_einvoice.

Konfiguration:

Ablauf:

1. Der Aktionspfad wird in der Spezifikation nachgeschlagen; die HTTP-Methode wird daraus übernommen (bevorzugt POST, sonst PUT/PATCH/DELETE — die erste im Pfad gefundene, nicht-GET-Methode).
2. Pfadparameter ({id} etc.) werden aus message.Id (Parametername id) bzw. aus message.Attributes aufgelöst; ein nicht auflösbarer Parameter erzeugt lediglich eine Warnung und bleibt im Pfad stehen.
3. Ist mindestens ein Zielfeld gemappt, wird daraus ein JSON-Body gebaut und mitgeschickt.
4. Bei einem ResponseJob wird die Antwort — über den aus der Spezifikation abgeleiteten Wrapper-Schlüssel entpackt — als neue Queue-Nachricht mit ActionCode = NewUpdate weitergereicht.

Ein fehlender Aktionspfad oder eine Antwort ohne 2xx-Statuscode brechen den Job mit einer Ausnahme ab.

Job-eigene Source-/Target-Pfade (statt nur Mapping-Tabelle)

(neu, alle Konnektoren betroffen — beim OpenAPI-Konnektor besonders relevant)

Ein Job kann eigene Felder Source und Target tragen, die den SourceTable/TargetTable der referenzierten Mapping-Zeilen überschreiben. Damit lässt sich ein und dasselbe Mapping für mehrere Ressourcen bzw. Aktionspfade wiederverwenden. Details: Jobs → Source und Target.

Änderungserkennung (Watermark)

Der Watermark-Wert wird über job.WatermarkField als SelectToken-Pfad auf jedes gelesene JSON-Objekt angewendet. Der Filterausdruck (Job.Filter) wird — anders als bei D365BC/NAV — nicht in eine standardisierte Query-Syntax übersetzt, sondern unverändert als Query-String an die Liste-Anfrage angehängt; Aufbau und Platzhalter sind daher von der jeweiligen API abhängig.

EmbedChildren — eingebettete Kind-Datensätze

(Quell-Feature ist derzeit nur im D365CE-Connector implementiert, das Zielverhalten dazu liegt im OpenAPI-Konnektor)

Verweist ein Feld-Mapping über die SourceOperation EmbedChildren auf einen anderen Job, werden dessen Zeilen bereits beim Lesen in die Nachricht des Elterndatensatzes eingebettet. Beim Schreiben in eine OpenAPI-Zielressource baut der Konnektor daraus ein verschachteltes JSON-Array (z. B. Rechnungspositionen unter lines) und schreibt es als Teil der Elternanfrage — ohne Feld-für-Feld-Abgleich mit einem eventuell vorhandenen Array im Zieldatensatz. Details zur Quellseite: Architektur und D365CE.

Caching

OpenAPI-Dokument und aufgelöste Ressourcen-Metadaten (Pfade, Wrapper-Schlüssel, Schema) werden pro Prozess zwischengespeichert. Ein Neuladen der Spezifikation erfordert einen Neustart der Function App bzw. ein erneutes Kaltstart-Init.