Installation

Zur Installation der easy invoice-Integration müssen folgende Voraussetzungen erfüllt sein:

• easy invoice ist installiert
• EASY ECM2Design DataTools 1.3.20 sind installiert
• EASY for Dynamics 365 Invoice-Connector ist in Microsoft Dynamics 365 Business Central installiert
• In OnPremises-Umgebungen von Microsoft Dynamics 365 Business Central muss die Authentifizierungsmethode NavUserPassword (https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/users-credential-types) aktiviert sein
• In Microsoft Dynamics 365 Business Central ist der für die Kommunikation zu verwendende Benutzer angelegt und für ihn ist ein Webdienst Zugriffsschlüssel erstellt
• Die Bezeichnung des easy invoice-Rechnungskreises muss gleich dem company-Namen in Business Central sein (inkl. Leerzeichen)
  
  

Zur Installation führen Sie die folgenden Arbeitsschritte aus:

Schattendatenbank

Neue Installation

Nutzen Sie die Datenbank-Skripte aus easy invoice-Version 4.3.0 oder neuer.

Bestehende Installation von easy invoice

Damit die Integration des Microsoft Dynamics 365 Business Central-Connectors in bestehende easy invoice-Installationen erfolgen kann, sind die Datenbankstruktur-Updates aus dem Patch-Ordner des easy invoice-Installationsmediums anzuwenden.

Gentable Definitions-Dateien bereitstellen

Stellen Sie die Gentable-Definitionsdateien aus dem Ordner gentables des Installationsmediums im Ordner config des Ordners für externe Tomcat-Inhalte bereit.

• Linux: /usr/share/documents5/current/ext/config
• Windows: i.d.R. <LW:>\documents5\documents5-ext\config

Datei "bcc_install.xml" über den Documents 5-Manager importieren

Melden Sie sich am Documents 5-Manager an und importieren Sie die Datei bcc_install.xml mittels der XML-Import-Funktion.

DataTools hochladen

Melden Sie sich mit einem administrativen Benutzer am Documents 5-Webclient an, navigieren Sie zum Öffentlichen Ordner Data Tools und importieren Sie alle im Ordner datatools des Installationsmediums befindlichen Dateien mittels der Importieren-Funktion am Öffentlichen Ordner.

Gentable Definitions-Dateien mit dem Mappentypen "epiFiles" verknüpfen

Standardmäßig nutzt der Mappentyp epiFiles die durch easy invoice ausgelieferte Gentable-Definitionsdatei epiFiles_Def.xml. Die Mappentyp-Eigenschaft hasInvoicePlugin mit dem Wert true aktiviert die Gentable-Funktion (siehe https://otris.software/documents/api/properties/#hasinvoiceplugin_dlcfile). Wenn keine weiteren Eigenschaften gesetzt wurden, sucht Documents selbständig mit dem technischen Namen des Mappentypen nach der Definitionsdatei, findet epiFiles_Def.xml und aktiviert die darin enthaltenen Gentable-Funktionen, wenn der in der Datei konfigurierte Name der Table-Definition (<table_def name="epiFiles">) ebenfalls mit dem Namen des Mappentypen übereinstimmt.

Mit dieser Integration werden zwei neue Gentable-Definitionsdateien bereitgestellt:

• epiFiles_bc_with_po_Def.xml
  Gentable für Einkaufsrechnung mit Bezug zu einer Einkaufsbestellung (easy invoice-Dokumenttyp RMB, auch Rechnung mit Bestellbezug) und für Einkaufsgutschriften mit Bezug zu einer Reklamation (easy invoice-Dokumenttyp GMB, auch Gutschrift mit Bestellbezug)
• epiFiles_bc_without_po_Def.xml
  Gentable für Einkaufsrechnungen ohne Bezug zu einer Einkaufsbestellung (easy invoice-Dokumenttyp ROB, Rechnung ohne Bestellbezug) und für Einkaufsgutschriften ohne Bezug zu einer Einkaufsreklamation (easy invoice-Dokumenttyp GOB, Gutschrift ohne Bestellbezug)

Sie müssen nun sicherstellen, dass, entsprechend dem Wert im Feld DocType eines Vorgangs/Mappe, der Gentable für Bestellbezug oder derjenige für Vorgänge ohne Bestellbezug geladen wird.

Lösungsvorschlag

Im Folgenden wird nur eine mögliche Lösung vorgestellt, es sind auch andere Konfigurationen möglich.

• Tragen Sie im Feld i_ItemDefinition den Namen der zu verwendenden Gentable-Definitionsdatei ein. Das können Sie mittels eines Callbacks am Workflowstart bewerkstelligen. Werten Sie dazu das Feld DocType aus.
• Fügen Sie dem Mappentypen epiFiles eine neue Eigenschaft gentableDefField mit dem Wert i_ItemDefinition hinzu (siehe auch https://otris.software/documents/api/properties/#gentabledeffield_dlcfile)

Anpassen der importierten DataTools

Verbindungsinformationen

Die im Schritt DataTools hochladen angelegten DataTools müssen an Ihre Umgebung angepasst werden. Dazu werden zwei Pflege-DataTools zusätzlich bereitgestellt, die nun erläutert werden sollen.

Data Tools Microsoft Business Central Connector - DataTools anpassen - Importe

Dieses DataTool verändert alle DataTools, welche die Stamm- und Bewegungsdaten aus Microsoft Dynamics 365 Business Central in die Schattendatenbank synchronisieren. Beschaffen Sie sich zunächst folgende Informationen:

• API-Version, über die Ihre Microsoft Dynamics 365 Business Central Instanz die Webservices bereitstellt (Stand 03/2021: v2.0)
• Bezeichnung Ihres Microsoft Dynamics 365 Business Central Tenants (eine UUID)
• Name des Microsoft Dynamics 365 Business Central-Systems, mit dem Sie arbeiten (z. B. Production oder DEV-Sandbox)
• Name des Benutzers in Microsoft Dynamics 365 Business Central, mit dem die Webdienste angesprochen werden sollen
• API-Key des vorgenannten Benutzers
• Art des für die Schattendatenbank verwendeten Datenbanksystems (z. B. MSSQL)
• DSN/ODBC-Name für die Schattendatenbank (z. B. invoicecontroldb@mysql)
• Datenbankbenutzer mit Schreib- und Leserechten in der Schattendatenbank (z. B. invoicecontroldbuser)
• Passwort des vorgenannten Benutzers
  
  

Passen Sie nun auf dem Register Mapping die Parameter mit den ermittelten Informationen an. Beachten Sie insbesondere das Ziel ehrmEnvironmentVariables - das sind die Umgebungsvariablen der DataTools. Hierin muss ein JSON angegeben werden, das vorab stringified wurde. Führen Sie dazu folgende Schritte durch:

• Bereiten Sie ein JSON in einem Editor vor, wobei Sie die vorab ermittelten Daten einsetzen: {"apiversion":"IHRE_API_VERSION","tenant":"IHRE_TENANT_ID","system":"IHR_SYSTEM"}
• Nutzen Sie einen Online JSON Stringifier Dienst wie https://onlinetexttools.com/json-stringify-text, um das JSON in String zu wandeln
• Kopieren Sie das in String gewandelte JSON in Hochkomma eingeschlossen in das Feld Parameter
  
  

Führen Sie dann das DataTool aus, um die Einstellungen an die DataTools zu übertragen.

Überprüfen Sie anhand eines der Import DataTools, ob die Änderungen erfolgreich an die DataTools übertragen wurden.

Data Tools Microsoft Business Central Connector - DataTools anpassen - UserExits

Die in den Gentable-Definitionsdateien konfigurierten UserExits rufen UserExit-DataTools auf, die Daten aus der Schattendatenbank zur Auswahl bringen. Dieses Pflege-DataTool sorgt nun dafür, dass alle UserExit-DataTools gesammelt angepasst werden. Beschaffen Sie sich zunächst folgende Informationen:

• Art des für die Schattendatenbank verwendeten Datenbanksystems (z.B. MSSQL)
• DSN/ODBC-Name für die Schattendatenbank (z. B. invoicecontroldb@mysql)
• Datenbankbenutzer mit Schreib- und Leserechten in der Schattendatenbank (z. B. invoicecontroldbuser)
• Passwort des vorgenannten Benutzers
  
  

Passen Sie nun auf dem Register Mapping die Parameter mit den ermittelten Informationen an. Führen Sie anschließend das DataTool aus, um die Einstellungen an die DataTools zu übertragen.

Überprüfen Sie abschließend anhand eines der UserExit-DataTools, ob die Änderungen erfolgreich an die DataTools übertragen wurden.

Zahlenformate

Unabhängig von der eigenen Sprachwahl arbeitet Microsoft Dynamics 365 Business Central intern mit dem Punkt als Dezimaltrennzeichen.

Import

Die Synchronisation von Zahlenwerten (z. B. Mengen, Beträge) mittels der Import-DataTools erfolgt ohne Transformation - also 1:1 wie in Microsoft Dynamics 365 Business Central.

Verwendung in easy invoice

Zunächst empfiehlt es sich, für Neuinstallationen von easy invoice i. V. m. "EASY for Dynamics 365 Invoice-Connector" den in Documents global verwendeten Dezimaltrenner auf den Punkt zu ändern (Documents5 Manager / Documents / Einstellungen /  Locale/Format / Format-Einstellungen / Dezimaltrennzeichen: ".". Damit ist das Format für Zahlen auch im Mappenfeld für Gentable-Daten ("InvoiceItems") auf den Punkt als Dezimaltrennzeichen festgelegt. Die Anzeige der Beträge erfolgt bei Anmeldung auf Deutsch weiterhin mit dem Komma als Dezimaltrennzeichen.

Sollten die UserExit-DataTools, z. B. "Eingangsrechnung - Positionen - Tabelle Bestellpositionsnummer", bei der Übernahme eines Eintrags unkorrekte Zahlen in den Gentable übernehmen, dann prüfen Sie, mit welchen Parametern die Transformation von Zahlen ausgeführt wird und passen Sie die Parameter nach Ihren Bedürfnissen an. Dabei ist zu beachten, dass auch diese Einstellung global gilt - sowohl für alle Rechnungskreise als auch für alle sprachlich abweichenden Anmeldungen (Deutsch/Englisch) im entsprechenden Workflow.

Export nach Microsoft Dynamics 365 Business Central

Bislang war keine Transformation der Zahlen nötig, bevor sie an Microsoft Dynamics 365 Business Central übergeben werden konnten. Sollte es doch einmal erforderlich sein, vor dem Export eine Transformation durchführen zu müssen, können Sie den parseFloat-Helper nutzen.

Datumsformate

Unabhängig von der eigenen Sprachwahl arbeitet Microsoft Dynamics 365 Business Central intern mit der erweiterten Version von ISO 8601 - JJJJ-MM-DD.

Import

Die Synchronisation von Datumsangaben (z. B. Dokumentdatum) mittels der Import-DataTools erfolgt ohne Transformation (z. B. orderheaderdate in der DB-Tabelle orderheader).

Verwendung im Workflow

In UserExits werden die Datumsangaben ohne Transformation dargestellt. Sollte eine Transformation gewünscht sein, so passen Sie das Mapping im entsprechenden UserExit-DataTool an.

Export nach Microsoft Dynamics 365 Business Central

Beim Export aus easy invoice ist darauf zu achten, dass das von Microsoft Dynamics 365 Business Central erwartete Format für Datumswerte von der Transformation geliefert wird. Nutzen Sie für die Transformation von Datumsangaben den formatDate-Helper. Im Fall von Document Date passiert dies bereits, siehe Transformations-Callbackscript cb.ehrmDataTools.transform.invoice2businesscentral.

easy invoice anpassen

Felder im Mappentyp "epiFiles" ausblenden

Da Microsoft Dynamics 365 Business Central als auch "EASY for Dynamics 365 Invoice-Connector" positionsbezogen arbeiten, sind einige, in der Mappenansicht vorhandene Felder wenn möglich mit Hilfe einer Erweiterung im PortalScript epiFiles_decreaseFieldRights auszublenden. Das betrifft:

• Allocation (de: Belegkontierung")
• ImpersonalAccount (de: Sachkonto)
• ImpersonalAccountName (de: Bezeichnung)
• CostCenter (de: Kostenstelle)
• CostCenterName (de: Bezeichnung)
• CostUnit (de: Kostenträger)
• CostUnitName (de: Bezeichnung)
  
  

Sichern Sie sich das PortalScript.

Mapping anpassen

In easy invoice werden die Eingangsrechnungen beim Workflowstart um Daten aus der Schattendatenbank angereichert. Dazu werden Mappings genutzt, die sich in dem PortalScript epiMappingConfig anpassen lassen.

Sichern Sie sich das PortalScript.

Rechnungskreis-Konfiguration ändern

Damit die von Microsoft Dynamics 365 Business Central in die Schattendatenbank synchronisierten Daten auch an die neuen Einkaufsrechnungen bzw. Einkaufsgutschriften geladen werden, sind an allen teilnehmenden Rechnungskreisen folgende Änderungen vorzunehmen:

Export in Workflow integrieren

Die Daten von Einkaufsrechnungen und Einkaufsgutschriften müssen gegen Ende des easy invoice-Workflows mittels des easy invoice-Connectors an Dynamics 365 Business Central übertragen - also exportiert - werden.

Der Export von Rechnungsdaten an den easy invoice-Connector ist nicht als Export-Option am Rechnungskreis verfügbar, da easy invoice nicht auf ein bestimmtes ERP-System abgestimmt ist. Der Ablauf zum Exportieren der Daten ist daher im jeweiligen Projekt zu entwickeln und in den bestehenden Prozess sinnvoll zu integrieren. 

Wie die Umsetzung des Exports realisiert werden kann und worauf dabei zu achten ist, wird unter Integration des Exports dargestellt.

(Optional) Blacklist für Synchronisation der Stamm- und Bewegungsdaten konfigurieren

Die Import-DataTools werden täglich bzw. stündlich für jeden im Mandanten konfigurierten easy invoice-Rechnungskreis automatisch ausgeführt.

Möchten Sie einen oder mehrere Rechnungskreis aus der automatischen Synchronisation herausnehmen, dann legen Sie bitte die Eigenschaft bccRecipientBlacklist am Documents-Mandanten an und geben Sie als Wert ein Array mit all den betreffenden Rechnungskreis-Namen in Hochkommata eingeschlossen an.

Beispiel: ["Condex AG","Condex Verpackungen GmbH"]

(Optional) Weitere Felder integrieren

Ein Beispiel, wie Sie weitere Felder in die Integration des Business Central Connector einbringen können, finden Sie auf der Seite Projektspezifische Anpassungen.