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

Systemvoraussetzungen zur Nutzung von Breeze Interface for Dynamics 365 BC

Systemvoraussetzungen

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.

 

Systemvoraussetzungen

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.

Installation

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.

Installation

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.

BreezeInterface_icon_appsource.png

Konfiguration & Administration

Konfiguration & Administration

Berechtigungssätze

Um die Module nutzen zu können, muss den jeweiligen Anwendern der passende Berechtigungssatz zugewiesen werden.

Folgende werden mit ausgeliefert:

Konfiguration & Administration

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.

Konfiguration & Administration

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.

image-1677145439422.png

Nummernserie

Hier wird die Nummernserie für die Breeze Interface Belege hinterlegt.

image-1677145463110.png

Konfiguration & Administration

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

image-1646811835555.png

Feldzuordnung herunterladen

Hiermit wird die Feldstruktur der SQUEEZE Dokumentenklasse heruntergeladen. Diese werden für die Metadaten-Zuordnung benötigt.

Navigation

image-1646811861396.png

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.

image-1671447413471.png

Karte

Dokumentenklasse

Hier wird jede Dokumentenklasse individuell eingerichtet.

Allgemein

image-1677144005353.png

In diesem Fastab wird der Name der Dokumentenklasse, der nächste Prozessschritt, sowie die automatische Anreicherung der Positionen eingerichtet.

Breeze Interface

image-1677144339201.png

Hier legt man die Standard Zielvorlage für diese Dokumentenklasse fest.

Folgende gibt es im Standard:

image-1687943322241.png

Konfiguration & Administration

Zielvorlagen Einrichtung

Hier werden Zielvorlagen für das Breeze Interface verwaltet. Im Standard sind diese Vorlagen verfügbar:

image-1687943221943.png

image-1677145077646.png

Allgemein

Hier sehen Sie welche Zielvorlage gerade bearbeitet wird.

Plausibilitätsprüfung

Hier können bestimmte Plausibilitätsprüfungen pro Zielvorlage deaktiviert werden.

Konfiguration & Administration

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.

image-1707821087292.png

Zu jedem technischen JSON Feldnamen wird das entsprechende BC Feld zugewiesen.

Konfiguration & Administration

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

image-1703164621193.png

Unter App registrations eine neue App anlegen

image-1666695222272.png

image-1666695353025.png

API permissions (Berechtigungen) anlegen

Die Application (client) ID kann an dieser Stelle bereits kopiert und abgelegt werden (wird später benötigt)

image-1666698096645.png

image-1666696539153.png

image-1666696558451.png

image-1666696591385.png

Client secret anlegen und sicher ablegen

image-1666697533453.png

image-1666697558892.png

Business Central

Microsoft Entra-Anwendungen öffnen und einen neuen Eintrag anlegen

image-1739971845282.png

image-1739971890925.png

Microsoft Entra-Anwendungen einrichten
  1.  Client ID eintragen
  2. Beschreibung eintragen (Beschreibung ist etwas irreführend. Es handelt sich hier eher um einen Benutzernamen)
  3.  Benutzerberechtigungssätze individuell vergeben
  4. (Optional)
  5. Anwendung aktivieren

image-1739972012317.png

 

 

 

 

 

 

 

 

 

 

 

 

 

Konfiguration & Administration

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.

Anwendung / Nutzung

Breeze Interface Belege

Hier werden alle Belege welche sich im Breeze Prozess befinden aufgelistet.

image-1677146997274.png

Statuswerte
Anwendung / Nutzung

Ü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.

image-1677150630849.png

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.

image-1677149521926.png

Anwendung / Nutzung

Breeze Interface API

Hier finden Sie die Dokumentationen zu folgenden Produkten:

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.

Extension Entwicklung

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:

image-1737634153644.png

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.

image-1737637141572.png

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

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

  1. 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;
  1. 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

  1. RecordId ist leer: Stellen Sie sicher, dass Sie den CreatedDocumentRecordId-Parameter setzen:
CreatedDocumentRecordId := CustomHeader.RecordId;
  1. 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');
  1. Datenvalidierung: Implementieren Sie eine ordnungsgemäße Datenvalidierung:
if JsonHelper.ValAsDec(LineJToken.AsObject(), 'qty', true) <= 0 then
    Error('Quantity must be greater than 0');