Mit diesem Formular können Sie fehlende, unklare oder fehlerhafte Inhalte in der Dokumentation melden und Verbesserungsvorschläge machen. Ihr Feedback hilft uns, die Qualität und Vollständigkeit kontinuierlich zu verbessern.
API und Schnittstellenbeschreibungen
1. Zusammenfassung und Grundstruktur
Posteingang: Die Azure Function schreibt bei jedem empfangenen Event einen Eintrag in eine definierte Posteingangstabelle im RDS Portal. Dieser Eintrag enthält den Ereignis-Code und dient als Information, dass ein bestimmtes Event eingetreten ist.
Aufgabenwarteschlange: Zwischen RDS und Azure Function besteht eine Warteschlange, über die die Webhooks bzw. Events übermittelt werden. Die Azure Function liest diese Warteschlange regelmäßig (gemäß Einrichtung) aus und verarbeitet die dort abgelegten Nachrichten.
Leistungsumfang der Azure Function: Die Azure Function prüft die empfangenen Events gegen eine festgelegte Liste gültiger Codes (Datenentitäten), validiert diese und schreibt sie in die Posteingangstabelle. Sie signalisiert ausschließlich, dass ein To Do vorhanden ist – es findet kein direkter Datenaustausch oder Datenabgleich statt, sondern nur eine Event-Benachrichtigung.
Mehrfachinstallation und Datenbankverbindungen: Die Azure Function kann mit mehr als einer Business Central-Datenbank verbunden werden. In diesem Fall muss sie jedoch mehrfach installiert und konfiguriert werden, damit jede Datenbank separat bedient wird. Wichtig: Dies ist in Zusammenarbeit mit RDS zu erfolgen.
2. Woher weiß die Azure Function, welche Events gültig sind?
Feste Liste von Events (Datenentität): Es gibt eine zentrale Liste von gültigen Ereigniscodes, die in einer speziellen Einrichtungstabelle in Business Central hinterlegt ist. Diese Tabelle wird über eine API-Page bereitgestellt, über die die Azure Function diese Daten ausliest.
Erweiterung der Event-Liste: Die Liste kann nur durch individuelle Entwicklung erweitert werden.
Ein Administrator oder Berater kann dies nicht einfach über die Benutzeroberfläche ändern.
Änderungen erfordern direkten Eingriff in den Code oder die Datenstruktur von Business Central.
Wichtig: Wenn in einem Kundenprojekt neue Events hinzukommen, muss RDS entsprechend informiert werden, damit die Azure Function und das System weiterhin korrekt funktionieren.
3. Kommunikationsweg und Datenfluss
Keine direkten Daten: RDS sendet ausschließlich Webhooks mit Ereigniscodes. Keine personenbezogenen Daten oder Detailinformationen werden übertragen.
http-Requests: Der Transfer der geänderten/neuen Daten aus der RDS Datenbank (z. B. Kontaktdaten, Banktdaten, etc.) erfolgt ausschließlich über http-Requests zwischen RDS hin zu Business Central und umgekehrt (gemäß der WebHook). Business Central reagiert auf die empfangenen WebHooks, indem es gezielt Daten vom RDS Portal abfragt. Dies geschieht über http-Requests, die den oberen Kommunikationsweg nutzen.
Azure Function: Die Azure Function agiert lediglich als Signalgeber und Hinweisgeber:
Sie meldet, dass ein bestimmtes Ereignis eingetreten ist.
Die tatsächliche Verarbeitung und Reaktion auf diese Events erfolgt anschließend innerhalb von Business Central, basierend auf den Einträgen in der Posteingangstabelle.
RDS Proxy Infrastruktur Einrichtung
Die RDS Portal Extension setzt eine Bereitstellung und Einrichtung von Azure Komponenten durch die GOB-Infrastruktur voraus. Dazu ist eine Azure Subscription beim Kunden unumgänglich. Folgende Schritte müssen in Kooperation mit der GOB-Infrastruktur durchgeführt werden.
Azure Functions Bereitstellung
In der Azure Subscription des Kunden muss eine Azure Function bereitgestellt werden. Der Dienst soll mit folgenden Kennzahlen angelegt werden:
| Einstellung | Wert |
|---|---|
| Do you want to deploy code or container image? | Code |
| Runtime stack | .NET |
| Version | 8 (LTS) Isolated |
| Operating System | Windows |
| Hosting | Consumption (Serverless) |
Nach der Bereitstellung der Azure Ressource muss die aktuelle Version des RDS-Proxy deployed werden. Für das Deployment steht eine ZIP-Datei im Freigabe Verzeichnis zur Verfügung.
Unter Microsoft Learn findet sich eine Anleitung zur Bereitstellung einer Azure Function via ZIP-Deployment: Zip push deployment for Azure Functions | Microsoft Learn
Skript zum Deployen von ZIP-Packages
Import-Module Az.Websites
Update-AzConfig -EnableLoginByWam $false # Aufgrund von aktuellen Bug im AZ-Modul
Connect-AzAccount -Tenant "TenantID" -Subscription "SubscriptionID"
Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <zip-file-path>
App-Registration Bereitstellung
Die App-Registration wird im SaaS benötigt, bei On-Premises ist sie optional.
Detaillierte Informationen zur Einrichtung einer App-Registration finden Sie in der Microsoft-Dokumentation: Using Service to Service Authentication - Business Central | Microsoft Learn
Die nachfolgenden Schritte zur Einrichtung in Business Central sind stets zu beachten. Auf On-Premises-Systemen ist die BC-Konfiguration entsprechend anzupassen.
Azure Functions Einrichtung
Folgende Einstellungen sind in der Azure Function zu setzen:
| SETTINGS → ENVIRONMENT VARIABLES | Beschreibung |
|---|---|
| Runtime:AuthenticationType | Basic oder OAuth abhängig vom gewählten Authentifizierungstyp |
| Basic:Username | Benutzername des Business Central Servicebenutzer nur in Kombination mit AuthenticationType: Basic |
| Basic:Password | Passwort des Business Central Servicebenutzer nur in Kombination mit AuthenticationType: Basic |
| OAuth:TenantId | Tenant-ID des Kunden-Tenant nur in Kombination mit AuthenticationType: OAuth |
| OAuth:ClientId | Client-ID der angelegten App-Registration nur in Kombination mit AuthenticationType: OAuth |
| OAuth:ClientSecret | Client-Secret der angelegten App-Registration nur in Kombination mit AuthenticationType: OAuth |
| OAuth:ApplicationUri | SaaS: https://api.businesscentral.dynamics.com On-Premises: In der App-Registrierung definierte AnwendungsUri nur in Kombination mit AuthenticationType: OAuth |
| RdsInterfaceApi:ApiUri | SaaS: https://api.businesscentral.dynamics.com/v2.0/[user domain name]/[environment name]/api On-Premises: [host]:[port]/[instance]/api |
| RdsInterfaceApi:CompanyId | BC-Company-ID |
| RdsInterfaceApi:Tenant | (Optional) z. B. default |