Integration des Exports

Über diese Links gelangen Sie zu den einzelnen Abschnitten auf dieser Seite:

Allgemein

Der easy invoice-Connector gibt nach einer erfolgreichen Belegverarbeitung im Response-Objekt die Nummer des Belegs in Microsoft Dynamics 365 Business Central zurück. 

Konnte der Export nicht erfolgreich durchgeführt werden, ist hinsichtlich der betroffenen Komponente geeignet zu reagieren.

Um ein erfolgreichen Export erreichen zu können, sind mindestens folgende Felder mit Werten zu exportieren:

Export-DataTool

Das DataTool für den Export (Microsoft Business Central Connector - Export) ist bereits Bestandteil des Standardpakets, in dem sich auch die Import- und UserExit-DataTools befinden. Es besteht aus drei Komponenten:

• dem DataTool Microsoft Business Central Connector - Export selbst,
• dem Transformation-Callbackscript cb.ehrmDataTools.transform.invoice2businesscentral und
• dem Response-Handler-Script cb.ehrmDataTools.handler.invoice2businesscentral
  
  

Das DataTool ist so konfiguriert, dass es für die Ausführung eine einzelne Mappe vom Mappentyp epiFiles erwartet. Es werden die in der Selektion Einfach konfigurierten Felder aus der Rechnungsdaten-Mappe ausgelesen, im Transformation-Callbackscript transformiert (z.B. Anpassung des Formats von Datumsangaben) und an den Webdienst des EASY Invoice-Connectors übergeben. Dazu werden die am DataTool gesetzten bzw. zur Laufzeit noch ergänzten Umgebungsvariablen in die URL eingesetzt. Das Response-Handler-Skript verarbeitet die Antwort von Microsoft Dynamics 365 Business Central bzw. vom EASY Invoice-Connector, indem es entweder die Belegnummer (Feld ERPProcessNumber) oder die Fehlermeldung (Feld ExportServerInfo) in die Rechnungsdaten-Mappe zurückschreibt.

Anpassungen am DataTool

Für eine erfolgreiche Inbetriebnahme sind mindestens die folgenden Anpassungen am Export-DataTool erforderlich:

• Feld Benutzer unter Mappendeckel, Bereich Zieldienst
• Feld Passwort unter Mappendeckel, Bereich Zieldienst
• Feld Umgebungsvariablen auf dem Register Erweitert, Abschnitt Scripting
  • apiversion: Geben Sie die zu verwendende API-Version an (Stand 03/2021: v2.0)
  • tenant: Geben Sie die GUID Ihres Business Central Tenant an
  • system: Geben Sie den Namen des zu verwendenden Systems an

Anpassungen am Transformation-Callbackscript

Es sind bereits alle mindestens erforderlichen und ein Teil der optionalen Felder integriert, sodass das Script ohne größere Anpassungen lauffähig sein sollte. Sind dennoch Anpassungen und Erweiterungen nötig, finden Sie Beispiele auf Projektspezifische Anpassungen an.

Anpassungen am Response-Handler

Sie sollten das Skript unverändert einsetzen können. Nur in Ausnahmefällen passen Sie es an Ihre Bedürfnisse an.

Hinweise zur Integration

• Organisieren Sie den Export nach der abschließenden Freigabe der Rechnung/Gutschrift. 
  
  
  • Eine Variante ist es, den Export über öffentliche Ordner zu organisieren, wie in der Beispielintegration vorgeschlagen. 

  • Es kommt aber auch ein Skriptaufruf am Ende des projektspezifischen Teils Ihres Freigabeworkflows infrage. Mögliche Serverantworten mit Fehlern sind dann im Workflow zu behandeln.

    Beispielcode für Scriptaufruf

    //#import cached [de.easy.ehrm.library.Standalone]

    try {

    const cFile = context.file;

    if (!cFile) throw new Error("no file in context.");

    const uniqueId = "de.easy.bcc.export.CHANGE_ME"; // Ändern Sie bitte die uniqueId auf die von Ihnen am Export-Data Tool eingetragene UniqueID, Register "Erweitert"

    const dt = new de.easy.ehrm.classes.DataToolsFactory.createByUniqueId(uniqueId, cFile),

    env = dt.getEnvironmentVariables();

    env.company = cFile.Recipient;

    dt.getDestinationService().addContext(env);

    dt.execute();

    } catch (ex) {

    cFile.ExportServerInfo = ex;

    cFile.sync();

    util.log("execution failed. " + ex);

    }
  • Das Export-DataTool kann auch als Aktion am epiFiles-Mappentypen konfiguriert werden (Export-DataTool, Mappendeckel, Kontrollkästchen Aktion konfigurieren im Abschnitt Quelle). Ist das die bevorzugte Option, dann sollten Sie mit einem AllowedActions-Skript sicherstellen, dass die Aktion nur unter bestimmten Bedingungen angezeigt wird.
    
    
• Zur Vermeidung von Diskrepanzen zwischen den in "Microsoft Dynamics 365 Business Central" gebuchten Einkaufsrechnungen und den archivierten EASY Invoice-Eingangsrechnungen sollte vor dem Archivieren der Rechnungsdaten-Mappe die "Microsoft Dynamics 365 Business Central"-Tabelle der gebuchten Einkaufsrechnungen mit der Mappen-ID des aktuellen Workflows abgefragt und die Documents-Mappe aktualisiert werden.

Beispielintegration

Die folgenden Komponenten und Abläufe stellen lediglich einen Vorschlag dar, wie der Export von Eingangsrechnungsdaten an den easy invoice-Connector in einen bestehenden EASY Invoice-Workflow integriert werden kann.

Funktionsweise

Der Export von EASY Invoice-Rechnungen und -Gutschriften wird über drei öffentliche Ordner gesteuert: 

• Übergabe ERP
• An ERP exportiert
• ERP-Übergabe fehlerhaft

Im Ordner Übergabe ERP werden alle zum Export bereitstehenden Eingangsrechnungen und -gutschriften aufgeführt. Hierzu werden zwei Filter genutzt (ExportServerInfo <leer> und ERPProcessNumber <leer>). Die Filter sind um mindestens ein drittes Kriterium entsprechend des Prozesses in Ihrer Umgebung zu erweitern, damit nicht unbeabsichtigt noch nicht freigegebene Vorgänge exportiert werden.

An dem Ordner Übergabe ERP ist die Aktion Export verfügbar. Es erlaubt die Auswahl eines Export-DataTools und führt für alle markierten Vorgänge das Export-DataTool einzeln aus. Als Export-DataTools werden alle DataTools aufgelistet, deren Feldwert Unique ID auf dem Register Erweitert mit de.easy.bcc.export beginnt. Ein geeignetes Export-DataTool ist mit der Installation des Installationsmediums bereits vorhanden.

Der Export eines Vorgangs kann erfolgreich oder mit Fehler abgebrochen worden sein:

• Erfolgreiche Exporte werden im Ordner An ERP exportiert dargestellt und enthalten im Mappenfeld ERPProcessNumber die von Dynamics 365 Business Central vergebene Belegnummer.
• Fehlerhafte Exporte werden im Ordner ERP-Übergabe fehlerhaft aufgelistet. Sie enthalten im Mappenfeld ExportServerInfo die Fehlermeldung; das Feld ERPProcessNumber ist leer.

Die Auswertung und Behandlung des Export-Ergebnisses unterscheidet sich je Fall und antwortender Komponente. Folgende Fälle werden berücksichtigt:

Installation und Konfiguration

Die nötigen Importe finden Sie im Ordner example des Installationsmediums. Gehen Sie wie folgt vor:

1. Importieren Sie mithilfe des Documents5-Managers die xml-Dateien für Öffentliche Ordner, die Sie im Ordner /example/folder finden
2. Definieren Sie an den soeben importierten Ordnern als Oberordner einen bestehenden Rechnungskreis-Ordner (Ordner für Rechnungskreise befinden sich unterhalb des Ordners epiData)
3. Importieren Sie die xml-Datei für die PortalSkripte
4. Beachten Sie die Minimal-Konfiguration des Export-DataTools (Kap. Export-DataTool)