Breeze Interface for Dynamics 365 BC - de-DE
Handbuch zur Administration und Nutzung von Breeze Interface for Microsoft Dynamics 365 Business Central. Die Breeze Interface App stellt eine schlüsselfertige Schnittstelle für die Abholung von Stammdaten und Buchung von Einkaufsbelegen für DEXPRO Breeze Solutions und andere externe Workflow- bzw. ECM-Systeme bereit. Mithilfe der Interface App können XML- (JSON) basierte Daten empfangen und direkt in Dynamics 365 Business Central als Standard-Eingangsbeleg verarbeitet bzw. als Buchungssatz bereitgestellt werden.
- Systemvoraussetzungen
- Installation
- Konfiguration & Administration
- Berechtigungssätze
- DEXPRO Core
- Breeze Interface Einrichtung
- Dokumentenklassen Einrichtung
- Zielvorlagen Einrichtung
- Generische Zusatzfelder
- OAuth 2.0 Einrichtung (nur für SaaS)
- Breeze Workflow
- Anwendung / Nutzung
- Extension Entwicklung
Systemvoraussetzungen
Systemvoraussetzungen zur Nutzung von Breeze Interface for Dynamics 365 BC
Unterstützte Microsoft Dynamics 365 Business Central Versionen
Die Microsoft Dynamics 365 Business Central Integration ist auf Grund von technischen Mindestvoraussetzungen ab folgender Version möglich:
Unterstützte Microsoft Dynamics 365 Business Central Versionen
Voraussetzung zum Betrieb ist, dass die jeweilige Microsoft Dynamics 365 Business Central Version sich noch im regulären Support befindet. Der erweiterte Support (extended Support) wird ausgeschlossen.
Unterstützte BREEZE Versionen
Für den Anschluss von BREEZE an Microsoft Dynamics 365 Business Central und für den Betrieb wird ein lizensiertes BREEZE System benötigt.
- ab Documents Version: Documents 5h #2311
- ab DEXPRO Invoice Solution Version: Invoice 1.1.015
Installation
Lizenzen
Microsoft
Informationen zu den Microsoft Business Central Lizenzen.
Squeeze Extract
Das DEXPRO Squeeze Extract System welches an Business Central angeschlossen werden soll benötigt eine gültige Kunden-Lizenz.
Bezug der DEXPRO Module
Detailliertere Informationen finden Sie hier.
OnPrem
Für OnPrem Installationen wird auf Anfrage eines registrierten Resellers / Partners ein Runtime Package mit den benötigten Apps zur Verfügung gestellt. Diese werden durch den Partner der Kundenlizenz hinzugefügt und im Anschluss in das Microsoft Dynamics Business Central eingespielt.
Cloud
Für Cloud Installationen benötigt man lediglich Zugriff auf den Microsoft AppSource. Hier werden die benötigten DEXPRO Apps heruntergeladen.
Konfiguration & Administration
Berechtigungssätze
Um die Module nutzen zu können, muss den jeweiligen Anwendern der passende Berechtigungssatz zugewiesen werden.
Folgende werden mit ausgeliefert:
- DXP Core Admin - DEXPRO Core Administrator
- DXP Core User - DEXPRO Core Benutzer
- DXP BREEZE Admin - DEXPRO BREEZE Administrator
- DXP BREEZE User - DEXPRO BREEZE Benutzer
DEXPRO Core
Der DEXPRO Core verwaltet die einzelnen DEXPRO Apps und deren Dokumente pro Mandant.
Es werden alle Belege, welche über die unterschiedlichen DEXPRO Module in Microsoft Dynamics 365 Business Central eingelaufen und verarbeitet worden sind, angezeigt. Zur Nachvervollgung von einzelnen Belegen wird auf eine globale Nummernserie, welche über alle DEXPRO Apps genutzt wird, gesetzt. Dies bietet den Vorteil, dass die Anwender mit nur einer Nummernserie pro Beleg arbeiten.
Weitere Informationen finden sie hier.
Breeze Interface Einrichtung
In der Breeze Interface Einrichtung wird die Verarbeitung innerhalb der App eingerichtet.
Start
Einrichtung kopieren
Hiermit wird die Einrichtung in andere Mandanten kopiert.
Navigation
Dokumentenklassen Einrichtung
Über diesen Menüpunkt erreichen Sie die Einrichtung für die SQUEEZE Dokumentenklassen.
Zielvorlagen Einrichtung
Über diesen Menüpunkt erreichen Sie die Zielvorlagen Einrichtung. Hier werden Zielvorlagen für das Breeze Interface verwaltet.
Generische Zusatzfelder
Über diesen Menüpunkt erreichen Sie die generischen Zusatzfelder. Hier können kundenspezifische Zusatzfelder eingerichtet werden.
Allgemein
In diesem FastTab kann man die Nutzung dieser App aktivieren/deaktivieren.
Nummernserie
Hier wird die Nummernserie für die Breeze Interface Belege hinterlegt.
Dokumentenklassen Einrichtung
In der SQUEEZE Dokumentenklassen Einrichtung wird die Zuordnung zwischen der jeweiligen Dokumentenklasse und Ihrer Exportschnittstelle vorgenommen. Des Weitern wird hier die Feldzuordnung jeder Dokumentenklasse heruntergeladen und so ein Set an Standard Feldern und deren Verwendung in Microsoft Dynamics 365 Business Central hergestellt.
Die Dokumentenklassen Einrichtung ist App übergreifend und wird über den DEXPRO Core verwaltet.
Vorgang
Feldzuordnung herunterladen
Hiermit wird die Feldstruktur der SQUEEZE Dokumentenklasse heruntergeladen. Diese werden für die Metadaten-Zuordnung benötigt.
Navigation
Metadaten-Zuordnung
Über diesen Menüpunkt erreichen Sie die Metadaten-Zuordnung. In dieser wird definiert welche Felder wie an Microsoft Dynamics 365 Business Central übertragen werden sollen.
Liste
Dokumentenklassen
In dieser Übersicht werden alle eingerichteten Dokumentenklassen aufgelistet.
Karte
Dokumentenklasse
Hier wird jede Dokumentenklasse individuell eingerichtet.
Allgemein
In diesem Fastab wird der Name der Dokumentenklasse, der nächste Prozessschritt, sowie die automatische Anreicherung der Positionen eingerichtet.
Breeze Interface
Hier legt man die Standard Zielvorlage für diese Dokumentenklasse fest.
Folgende gibt es im Standard:
Zielvorlagen Einrichtung
Hier werden Zielvorlagen für das Breeze Interface verwaltet. Im Standard sind diese Vorlagen verfügbar:
Allgemein
Hier sehen Sie welche Zielvorlage gerade bearbeitet wird.
Plausibilitätsprüfung
Hier können bestimmte Plausibilitätsprüfungen pro Zielvorlage deaktiviert werden.
Generische Zusatzfelder
Hier können Kundenspezifische Felder hinzugefügt werden, welche unser Standard Template erweitern oder davon abweichen. Dieses Mapping sorgt dafür, dass diese zusätzlichen Inhalte an die richtigen Stellen zugeordnet werden.
Zu jedem technischen JSON Feldnamen wird das entsprechende BC Feld zugewiesen.
OAuth 2.0 Einrichtung (nur für SaaS)
Der Zugriff auf Webservices in Microsoft Dynamics 365 Business Central (BC) ist in der SaaS Variante nur noch per OAuth 2.0 möglich. Die notwendige Einrichtung der App in Azure Active Directory sowie deren Verknüpfung mit BC wird im folgenden dargestellt.
Azure Portal
Azure Portal öffnen und zu Microsoft Entra ID navigieren
Unter App registrations eine neue App anlegen
API permissions (Berechtigungen) anlegen
Die Application (client) ID kann an dieser Stelle bereits kopiert und abgelegt werden (wird später benötigt)
Client secret anlegen und sicher ablegen
Business Central
Microsoft Entra-Anwendungen öffnen und einen neuen Eintrag anlegen
Microsoft Entra-Anwendungen einrichten
- Client ID eintragen
- Beschreibung eintragen (Beschreibung ist etwas irreführend. Es handelt sich hier eher um einen Benutzernamen)
- Benutzerberechtigungssätze individuell vergeben
- (Optional)
- Anwendung aktivieren
Breeze Workflow
Um unseren Breeze Invoice Workflow an Dynamics 365 BC anzuschließen lesen Sie bitte dieses Handbuch.
Anwendung / Nutzung
Hier wird der Prozesses von der Bereitstellung validierter Squeeze Einkaufsbelege an externe Workflows bis zur Buchungsübergabe freigegebener Belege beschrieben.
Breeze Interface Belege
Hier werden alle Belege welche sich im Breeze Prozess befinden aufgelistet.
Statuswerte
- WaitingForRetrieval: Der Beleg ist bereit und wartet darauf vom Workflow System abgeholt zu werden.
- Retrieved: Der Beleg wurde vom Workflow abgeholt.
- Processed: Der Beleg wurde erfolgreich verarbeitet.
- Error: Der Beleg weist zumindest einen Fehler auf, welcher im Workflow korrigiert werden muss.
- Rejected: Der Beleg wurde vom Workflow System als abgelehnt gekennzeichnet.
- WaitingForJson: Der Beleg wartet auf die Anreicherung der Json Datei.
- ChangeCompany: Der Beleg wartet darauf vom Hintergrundprozess verarbeitet und in einen anderen Mandanten übertragen zu werden.
Übergabe in die ungebuchten EK-Belege
Nach der Freigabe des EK-Belegs durch das Workflow System wird der Beleg an das Breeze Interface übergeben. Im Anschluss findet eine Plausibilitätsprüfung im Interface statt. Wenn die Prüfung erfolgreich war, wird ein ungebuchter EK-Beleg angelegt.
Wenn die Plausibilitätsprüfung fehlschlug, wird der Beleg auf den Status "error" gesetzt und die Fehlermeldung an der jeweiligen Stelle in der Json Struktur des Belegs angehängt. Nun wartet der Beleg wieder auf Abholung und Korrektur durch den Workflow.
Der ungebuchte EK-Beleg wird mit allen Daten aus der Json Struktur angelegt. Sollten Anhänge aus dem Prozess angehängt worden sein, werden auch diese mit an den ungebuchten Beleg übergeben.
Breeze Interface API
Hier finden Sie die Dokumentationen zu folgenden Produkten:
- Rechnungen / Invoice
- Bestellanfragen - Procurement
- Auftragsbestätigungen - Order Confirmation
- Lieferscheine - Delivery Note
Extension Entwicklung
In diesem Kapitel werden wichtige Integration Events und Beispiele aufgeführt, die bei der Entwicklung einer Extension für Breeze Interface helfen. Wichtig: Anpassungen dürfen nur durch entsprechend geschulte Berater/Entwickler durchgeführt werden. Diese befinden sich außerdem immer außerhalb des Standard-Supports durch DEXPRO.
Leitfaden zur Implementierung einer individuellen Belegerstellung
Überblick
Diese Dokumentation bietet eine Anleitung zur Implementierung benutzerdefinierter Dokumentenerstellungsprozesse unter Verwendung des Integration Event OnDocumentCreation
im DEXPRO Core-Framework. Während die Standardimplementierung Einkaufsbelege (Tablelle 38,39) erstellt, zeigt dieser Leitfaden, wie Sie Ihre eigene Dokumentenerstellungslogik mithilfe der bereitgestellten JSON-Daten implementieren können.
Voraussetzungen
Folgende Einstellung ist vor der Validierung eines Belegs in der Dokumentenklassen Einrichtung vorzunehmen:
- Nächster Prozessschritt: Breeze Interface
- Zielvorlage: Keine
Sie haben einen Beleg mit der App DEXPRO Squeeze validiert und in den nächsten Prozessschritt Breeze Interface übertragen? Dann sehen Sie diesen jetzt im Breeze Interface in einer Wartestellung (WaitingForRetrieval). An diesem Punkt besteht die Möglichkeit, den validierten Beleg in einen Genehmigungsworkflow zu überführen, um diesen nach erfolgter Genehmigung zurückzumelden und in den Prozess der Zielbelegerstellung zu übergeben - weitere Information zur Breeze Interface API finden sie hier.
Sobald Sie den Status des Breeze Belegs in "Processed" geändert haben, wird dieser an den DEXPRO Core zur weiteren Verarbeitung gemeldet - dies ist der Integrationspunkt, an dem Sie ansetzen müssen.
Integrationspunkt
Der zentrale Integrationspunkt ist das OnDocumentCreation
-Ereignis in Codeunit 70954599 “DXP Doc. Creation Def. Impl.” in der App DEXPRO Core. Dieses Ereignis wird während der Dokumentenverarbeitung ausgelöst und ermöglicht die Implementierung einer benutzerdefinierten Dokumentenerstellungslogik.
Ereignis-Signatur
[IntegrationEvent(false, false)]
local procedure OnDocumentCreation(JObject: JsonObject; var CreatedDocumentRecordId: RecordId)
Parameter
JObject
: Enthält die vollständigen JSON-Daten mit den DokumentinformationenCreatedDocumentRecordId
: Muss mit der RecordId des erstellten Dokuments gesetzt werden
Implementierungsleitfaden
Schritt 1: Subscriber-Codeunit erstellen
Zunächst erstellen Sie eine Codeunit, die das OnDocumentCreation-Ereignis abonniert:
codeunit 50100 "Custom Document Creation"
{
[EventSubscriber(ObjectType::Codeunit, Codeunit::"DXP Doc. Creation Def. Impl.", 'OnDocumentCreation', '', false, false)]
local procedure OnDocumentCreation(JObject: JsonObject; var CreatedDocumentRecordId: RecordId)
begin
// Your implementation here
CreateCustomDocument(JObject, CreatedDocumentRecordId);
end;
}
Schritt 2: Dokumentenerstellungslogik implementieren
Hier ein Beispiel für die Implementierung der benutzerdefinierten Dokumentenerstellung:
local procedure CreateCustomDocument(JObject: JsonObject; var CreatedDocumentRecordId: RecordId)
var
CustomHeader: Record "Custom Document Header";
CustomLine: Record "Custom Document Line";
JsonHelper: Codeunit "DXP Json Helper";
HeaderJObject: JsonObject;
LinesJArray: JsonArray;
LineJToken: JsonToken;
LineNo: Integer;
begin
// 1. Create Header
CustomHeader.Init();
CustomHeader."Document Type" := GetDocumentType(JObject);
CustomHeader."Vendor No." := CopyStr(JsonHelper.ValAsTxt(JObject, 'vendorNo', true), 1, MaxStrLen(CustomHeader."Vendor No."));
CustomHeader."Document Date" := JsonHelper.ValAsDate(JObject, 'docDate', true);
CustomHeader."Posting Date" := JsonHelper.ValAsDate(JObject, 'postingDate', true);
CustomHeader."Document Reference" := CopyStr(JsonHelper.ValAsTxt(JObject, 'docReference', true), 1, MaxStrLen(CustomHeader."Document Reference"));
CustomHeader.Insert(true);
// 2. Process Lines
LinesJArray := JsonHelper.ReadJArrayFromObj(JObject, 'lines');
LineNo := 10000;
foreach LineJToken in LinesJArray do begin
CustomLine.Init();
CustomLine."Document No." := CustomHeader."No.";
CustomLine."Line No." := LineNo;
CustomLine."Item No." := CopyStr(JsonHelper.ValAsTxt(LineJToken.AsObject(), 'no', true), 1, MaxStrLen(CustomLine."Item No."));
CustomLine.Quantity := JsonHelper.ValAsDec(LineJToken.AsObject(), 'qty', true);
CustomLine."Unit Price" := JsonHelper.ValAsDec(LineJToken.AsObject(), 'unitPrice', true);
CustomLine.Insert(true);
LineNo += 10000;
end;
CreatedDocumentRecordId := CustomHeader.RecordId;
end;
JSON-Struktur
Die JSON-Eingabe folgt dieser Struktur:
{
"type":"Invoice",
"vendorNo":"K00170",
"iban":"DE58520503530052599766",
"vatRegNo":"DE540026784",
"barcode":"123456789",
"docDate":"2023-07-13",
"serviceDate":"2023-07-13",
"postingDate":"2025-01-23",
"postingDesc":"Die ist eine Buchungsbeschreibung.",
"docReference":"R308154",
"orderNo":"B23106029",
"netAmount":7894.71,
"netAmount2":0.0,
"netAmount3":0.0,
"taxRate":19.0,
"taxRate2":0.0,
"taxRate3":0.0,
"taxAmount":1499.99,
"taxAmount2":0.0,
"taxAmount3":0.0,
"totalAmount":9394.7,
"currency":"EUR",
"assignedTo":"BERND.FEDDERSEN",
"note":"Die ist eine Bemerkung!",
"dimensions":{
"ABTEILUNG":"PROD",
"EINKÄUFER":"BF",
"KOSTENTRÄGER":"IT"
},
"dimensionSetID":27,
"customFields":{
"docClass":"DXP Invoice / Credit Memo",
"namesAndValues":[
{
"name":"Customer_No",
"value":"01121212"
},
{
"name":"Custom_Date",
"value":"2025-01-26"
}
]
},
"orderMatchDifference":"false",
"lines":[
{
"orderNo":"B23106029",
"orderLineNo":10000,
"receiptNo":"ELIEF107004",
"receiptLineNo":10000,
"vendorItemNo":"",
"type":"Item",
"no":"90002",
"description":"JogiTek G 1337 Gaming-Headset",
"qty":17.0,
"uom":"STÜCK",
"unitPrice":99.99,
"lineDisc":0.0,
"netAmount":1699.83,
"totalAmount":2022.8,
"taxRate":19.0,
"vatBusPostingGroup":"INLAND",
"vatProdPostingGroup":"MWST.19",
"dimensions":{
"ABTEILUNG":"PROD",
"BEREICH":"30",
"EINKÄUFER":"BF",
"KOSTENTRÄGER":"IT",
"VERKAUFSKAMPAGNE":"WINTER"
},
"dimensionSetID":53,
"genProdPostingGroup":"HANDEL",
"genBusPostingGroup":"INLAND",
"deferralCode":"",
"quantityDifference":"false",
"unitPriceDifference":"false",
"discountDifference":"false",
"receiptDateDifference":"false",
"customFields":{
"docClass":"DXP Invoice / Credit Memo",
"namesAndValues":[
{
"name":"Custom_Field_1",
"value":"Text in Zeile 10000"
},
{
"name":"Custom_Field_2",
"value":"2025-01-31"
}
]
}
},
{
"orderNo":"B23106029",
"orderLineNo":30000,
"receiptNo":"ELIEF107004",
"receiptLineNo":30000,
"vendorItemNo":"",
"type":"Item",
"no":"90005",
"description":"Sumsing Galaxy 23",
"qty":12.0,
"uom":"STÜCK",
"unitPrice":349.99,
"lineDisc":0.0,
"netAmount":4199.88,
"totalAmount":4997.86,
"taxRate":19.0,
"vatBusPostingGroup":"INLAND",
"vatProdPostingGroup":"MWST.19",
"dimensions":{
"ABTEILUNG":"PROD",
"BEREICH":"50",
"EINKÄUFER":"BF",
"KOSTENTRÄGER":"IT",
"VERKAUFSKAMPAGNE":"WINTER"
},
"dimensionSetID":55,
"genProdPostingGroup":"HANDEL",
"genBusPostingGroup":"INLAND",
"deferralCode":"",
"quantityDifference":"false",
"unitPriceDifference":"false",
"discountDifference":"false",
"receiptDateDifference":"false",
"customFields":{
"docClass":"DXP Invoice / Credit Memo",
"namesAndValues":[
{
"name":"Custom_Field_1",
"value":"Text in Zeile 20000"
},
{
"name":"Custom_Field_2",
"value":"2025-01-30"
}
]
}
},
{
"orderNo":"B23106029",
"orderLineNo":20000,
"receiptNo":"ELIEF107004",
"receiptLineNo":20000,
"vendorItemNo":"",
"type":"Item",
"no":"90000",
"description":"Y-Phone Ultra Pro 23",
"qty":5.0,
"uom":"STÜCK",
"unitPrice":399.0,
"lineDisc":0.0,
"netAmount":1995.0,
"totalAmount":2374.05,
"taxRate":19.0,
"vatBusPostingGroup":"INLAND",
"vatProdPostingGroup":"MWST.19",
"dimensions":{
"ABTEILUNG":"PROD",
"BEREICH":"70",
"EINKÄUFER":"BF",
"KOSTENTRÄGER":"IT",
"VERKÄUFER":"JH",
"VERKAUFSKAMPAGNE":"WINTER"
},
"dimensionSetID":58,
"genProdPostingGroup":"HANDEL",
"genBusPostingGroup":"INLAND",
"deferralCode":"",
"quantityDifference":"false",
"unitPriceDifference":"false",
"discountDifference":"false",
"receiptDateDifference":"false",
"customFields":{
"docClass":"DXP Invoice / Credit Memo",
"namesAndValues":[
{
"name":"Custom_Field_1",
"value":"Text in Zeile 30000"
},
{
"name":"Custom_Field_2",
"value":"2025-01-29"
}
]
}
}
]
}
Best practice
- Fehlerbehandlung: Implementieren Sie eine ordnungsgemäße Fehlerbehandlung für JSON-Parsing und Datenbankoperationen:
local procedure CreateCustomDocument(JObject: JsonObject; var CreatedDocumentRecordId: RecordId)
var
CustomHeader: Record "Custom Document Header";
begin
if not DoesJsonHaveRequiredFields(JObject) then
Error('Required fields are missing in the JSON payload');
if not TryCreateCustomHeader(JObject, CustomHeader) then
Error('Failed to create document header');
// ... rest of the implementation
end;
- Validierung: Implementieren Sie eine ordnungsgemäße Validierung vor der Dokumenterstellung:
local procedure ValidateDocument(JObject: JsonObject): Boolean
var
Vendor: Record Vendor;
VendorNo: Code[20];
begin
VendorNo := CopyStr(JsonHelper.ValAsTxt(JObject, 'vendorNo', true), 1, MaxStrLen(VendorNo));
if not Vendor.Get(VendorNo) then
Error('Vendor %1 does not exist', VendorNo);
// Add more validation as needed
exit(true);
end;
Häufige Szenarien
Szenario 1: Verschiedene Dokumenttypen erstellen
local procedure GetDocumentType(JObject: JsonObject): Enum "Custom Document Type"
var
DocType: Text;
begin
DocType := JsonHelper.ValAsTxt(JObject, 'type', true);
case DocType of
'Invoice':
exit("Custom Document Type"::Invoice);
'CreditMemo':
exit("Custom Document Type"::"Credit Memo");
else
Error('Unknown document type: %1', DocType);
end;
end;
Szenario 2: Benutzerdefinierte Felder verarbeiten
local procedure ProcessCustomFields(JObject: JsonObject; var CustomDoc: Record "Custom Document Header")
var
CustomFieldsObj: JsonObject;
CustomFieldsArr: JsonArray;
FieldToken: JsonToken;
begin
if not JsonHelper.TokenExists(JObject, 'customFields') then
exit;
CustomFieldsObj := JsonHelper.ReadJObjectFromObj(JObject, 'customFields');
CustomFieldsArr := JsonHelper.ReadJArrayFromObj(CustomFieldsObj, 'namesAndValues');
foreach FieldToken in CustomFieldsArr do
ProcessCustomField(FieldToken.AsObject(), CustomDoc);
end;
Fehlerbehebung
- RecordId ist leer: Stellen Sie sicher, dass Sie den CreatedDocumentRecordId-Parameter setzen:
CreatedDocumentRecordId := CustomHeader.RecordId;
- JSON-Parsing-Fehler: Verwenden Sie die JsonHelper-Funktionen für sicheres Parsing:
if not JsonHelper.TokenExists(JObject, 'vendorNo') then
Error('Vendor number is missing in JSON');
- Datenvalidierung: Implementieren Sie eine ordnungsgemäße Datenvalidierung:
if JsonHelper.ValAsDec(LineJToken.AsObject(), 'qty', true) <= 0 then
Error('Quantity must be greater than 0');