Microsoft Dynamics 365 Business Central Konnektor

Der Dynamics 365 Business Central Konnektor verbindet Syncler mit der Business Central 365 REST API 2.0 und ermöglicht eine bidirektionale Synchronisation von Entitäten wie Kunden, Kontakten, Belegen, Artikeln und weiteren Geschäftsdaten.
Der Konnektor liest das Datenschema dynamisch über den $metadata-Endpunkt der API, ergänzt Feld- und Objektnamen über die EntityDefinitions, unterstützt benutzerdefinierte APIs (Custom APIs) und kann verschachtelte Objekte (z. B. Positionsdaten in Belegen) automatisch auflösen.

Die Anmeldung erfolgt über das Microsoft 365 OAuth 2.0-Verfahren – wahlweise per Authorization Code (Delegierte Anmeldung) oder über Client Credentials (Server-zu-Server-Verbindung).

Einrichtung

Für den Zugriff auf Business Central ist eine registrierte Anwendung in Microsoft Entra ID (Azure AD) erforderlich.
Diese App stellt die Client-ID, das Secret und die Berechtigungen (Scopes) für die Verbindung bereit.

Weitere Informationen: Das OAuth 2.0-Verfahren

1. Neues System anlegen

• In Syncler ein neues System anlegen.
• Typ: „Dynamics 365 Business Central“ auswählen.
• Name und optionale Beschreibung vergeben.

2. Dynamics Business Central konfigurieren

• Firma (Company): Anzeigename des ERP-Mandanten.
• Umgebung (Environment): Name der Business Central-Umgebung, z. B. Production.
• Optional:
  • Geschachtelte Schemaobjekte konfigurieren (siehe unten).
  • Custom APIs hinzufügen, um zusätzliche Endpunkte bereitzustellen.

3. Microsoft 365 OAuth 2.0 konfigurieren

• Tragen Sie folgende Werte ein:
  • Mandant (Tenant ID)
  • Client ID
  • Optional: Client Secret und Redirect URL
• Standard-Scopes:

  https://api.businesscentral.dynamics.com/.default
  

• Authentifizierungsfluss wählen:
  • Authorization Code (delegiert/Anwendung):
    Über die Registerkarte Microsoft 365 OAuth 2.0 wird der Code abgerufen.
    Der Refresh Token wird automatisch gespeichert und regelmäßig erneuert.
  • Client Credentials (Server-zu-Server):
    Option Client-Anmeldeinformationen verwenden aktivieren.
    In diesem Modus wird kein Refresh Token benötigt.
• Validierung:
  • Beim Speichern holt der Konnektor automatisch ein Access Token.
  • Die verfügbaren Companies werden gelesen, und die zur angegebenen Firma passende Company ID wird automatisch gesetzt.

4. Einrichtung der Entra-Anwendung in Business Central

• Erstellung der Microsoft Entra-Anwendung
  • Seite Microsoft Entra-Anwendungen aufrufen und "Neu" auswählen
  • Feld Client-ID mit der Client-ID aus App befüllen
• Zuweisung von Berechtigungen
  • Inforegister Benutzerberechtigungssätze
  • erforderliche Berechtigungen zuweisen
  • optional Mandant einschränken

Geschachtelte Schemaobjekte

Geschachtelte Schemaobjekte (Nested Schema Objects) ermöglichen es, übergeordnete Datensätze (Parent) mit untergeordneten Strukturen (Child) zu kombinieren.
Dadurch können Belege und Positionen oder Organisationen und Kontakte gemeinsam verarbeitet werden.

Jede Verschachtelung benötigt drei Angaben:

• ParentName – Name des übergeordneten Objekts
• ChildName – Name des untergeordneten Objekts
• LinkName – Typ der Verknüpfung (z.B. list oder #)

Link-Typen:

• list: 1:n-Beziehung, z. B. Beleg mit Positionen
• #: Aufzählbare Unterstruktur (z. B. Kontaktinformationen eines Kunden)

Standardmäßig vordefinierte Kombinationen:

Custom APIs

Mit Custom APIs können Sie zusätzliche, in Business Central veröffentlichte API-Endpunkte in Syncler integrieren.
Diese werden wie Standardobjekte behandelt und stehen in Syncs für Lese- und Schreiboperationen sowie für gebundene Aktionen (Bound Actions) zur Verfügung.

Zur Konfiguration sind drei Angaben erforderlich:

• API Publisher – Herausgeber der API (z. B. contoso)
• API Group – Gruppierung innerhalb des API-Namespace (z. B. finance)
• API Version – Version der API (z. B. v1.0)

Beispiel:

[
  { "APIPublisher": "contoso", "APIGroup": "sales", "APIVersion": "v1.0" }
]

Nach dem Speichern werden die Custom APIs in das Schema integriert und stehen für alle Operationen zur Verfügung.

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.

Beispiel:

• Feld Status → Werte: Open, Released, Shipped, Invoiced
• Feld Type → Werte: Item, Resource, Service

Picklisten werden beim Laden des Schemas automatisch erzeugt und aktualisiert.

Aktionen

Um eine Aktion auszuführen, setzen Sie das Feld triggerAction auf true und führen anschließend eine Schreiboperation (SetData) aus – z. B. innerhalb eines Universal-Syncs. Dadurch wird die entsprechende REST-Operation (POST /Microsoft.NAV.<ActionName>) ausgeführt.

Zusammenfassung