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)>"
}

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.

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.