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.