Installation

To install EASY Invoice integration, the following prerequisites must be met:

  • EASY Invoice 4.2.1 has been installed

  • EASY ECM2Design DataTools 1.3.6 have been installed

  • EASY for Dynamics 365 Invoice Connector has been installed in Microsoft Dynamics 365 Business Central

  • In Microsoft Dynamics 365 Business Central on-premises environments, the authentication method NavUserPassword (https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/users-credential-types) must be enabled

  • The user to be used for communication has been created in Microsoft Dynamics 365 Business Central and a Web service access key has been created for that user

  • The name of the EASY Invoice accounting entity must be identical to the company name in Business Central (incl. spaces)

For installation, perform the following procedures :

Changes to the shadow database "InvoiceControlDb"

New installation

Use the database scripts from EASY Invoice version 4.2.0 or later.

Existing EASY Invoice installation

To integrate Microsoft Dynamics 365 Business Central Connector with existing EASY Invoice installations, you have to use the database structure updates from the Patch folder of the EASY Invoice installation media version 4.2.1 (or later).

Provision Gentable definition files

Provision the Gentable definition files from the gentable folder of the installation media in the config folder of the folder for external Tomcat content.

  • Linux: /usr/share/documents5/current/ext/config

  • Windows: usually, <DR:>\documents5\documents5-ext\config

Import the "bcc_install.xml" file via the Documents 5 Manager

Log in to the Documents 5 Manager and import the bcc_install.xml file using the XML import function.

Upload DataTools

Log in to the Documents 5 Web client using an administrative user, navigate to the Public folder Data Tools and import all files located in the datatools folder of the installation media using the import function for the Public folder.

Link Gentable definition files with the "epiFiles" file type

By default, the epiFiles file type uses the Gentable definition file that comes with EASY Invoice: epiFiles_Def.xml. The file type property hasInvoicePlugin with the value true enables the Gentable function (see https://otris.software/documents/api/properties/#hasinvoiceplugin_dlcfile). Unless other properties have been set, Documents independently looks for the definition file using the file type's technical name, retrieves epiFiles_Def.xml, and enables the Gentable functions contained therein if the name of the table definition configured in the file (<table_def name="epiFiles">) also matches the name of the file type.

Two new Gentable definition files are provided with this integration:

  • epiFiles_bc_with_po_Def.xml
    Gentable for purchase invoice with reference to a purchase order (EASY Invoice document type RMB, also Invoice with order reference) and for purchase credit memos with reference to a return order (EASY Invoice document type CWO), also Credit memo with order reference)

  • epiFiles_bc_without_po_Def.xml
    Gentable for purchase invoices without reference to a purchase order (EASY Invoice document type (IW/OOR, invoice without order reference) and for purchase credit memos without reference to a purchase return order (EASY Invoice document type CWO, Credit memo without order reference)

You now have to ensure that, according to the value in the DocType field of a process/file, the Gentable for order reference or that for processes without order reference is loaded.

Suggested solution

Only a possible solution is demonstrated below. You can use this, or find your own solution.

  • In the i_ItemDefinition field, enter the name of the Gentable definition file to be used. You can do this using a callback for the workflow start. To do this, evaluate the DocType field.

  • Add a new property named gentableDefField with the value i_ItemDefinition to the epiFiles file type (see also https://otris.software/documents/api/properties/#gentabledeffield_dlcfile)

Customizing the imported DataTools

Connectivity information

The DataTools created in the Upload DataTools step must be customized to your environment. For this purpose, we have additionally provided two maintenance DataTools, which we will explain now.

Data Tools Microsoft Business Central Connector - Customize DataTools - Imports

This DataTool modifies all DataTools that synchronize the master and transaction data from Microsoft Dynamics 365 Business Central to the shadow database InvoiceControlDb. Get the following information first:

  • API version via which your Microsoft Dynamics 365 Business Central instance provides the Web services (as of March 2021: v2.0)

  • Name of your Microsoft Dynamics 365 Business Central tenant (a UUID)

  • Name of the Microsoft Dynamics 365 Business Central system you are working with (e.g. Production or DEV-Sandbox)

  • Name of user in Microsoft Dynamics 365 Business Central used to address the Web services

  • API key of the above user

  • Type of the database system used for the InvoiceControlDb (e.g. MSSQL)

  • DSN/ODBC name for the InvoiceControlDb database (e.g. invoicecontroldb@mysql)

  • Database user with read and write permissions in the InvoiceControlDb database (e.g. invoicecontroldbuser)

  • Password of above user

On the Mapping tab, customize the parameters using the determined information. Special attention should be paid to the ehrmEnvironmentVariables target - these are the environment variables of the DataTools. Herein you have to specify a JSON that has previously been stringified. To do this, perform the following steps:

  • Prepare a JSON in an editor where you use the previously determined data: {"apiversion":"YOUR_API_VERSION","tenant":"YOUR_TENANT_ID","system":"YOUR_SYSTEM"}

  • Use an Online JSON Stringifier service such as https://onlinetexttools.com/json-stringify-text to transform the JSON to String

  • Copy the JSON transformed to String, enclosed in quotation marks, to the Parameter field

Then execute the DataTool to transfer the settings to the DataTools.

Based on one of the Import DataTools, check whether the changes have been successfully transferred to the DataTools.

Data Tools Microsoft Business Central Connector - Customize DataTools - UserExits

The UserExits configured in the Gentable definition files launch UserExit DataTools that bring up data from the shadow database for selection. This maintenance DataTool now ensures that all UserExit DataTools combined are customized. Get the following information first:

  • Type of the database system used for the InvoiceControlDb (e.g. MSSQL)

  • DSN/ODBC name for the InvoiceControlDb database (e.g. invoicecontroldb@mysql)

  • Database user with read and write permissions in the InvoiceControlDb database (e.g. invoicecontroldbuser)

  • Password of above user

On the Mapping tab, customized the parameters using the determined information. Next, execute the DataTool to transfer the settings to the DataTools.

Finally, based on one of the UserExit DataTools, check that the changes have been successfully transferred to the DataTools.

Number formats

Regardless of your own language selection, Microsoft Dynamics 365 Business Central internally works with the point as the decimal separator.

Import

Synchronizing number values (e.g. quantities, amounts) using the Import DataTools is performed without transformation - i.e., 1:1, as in Microsoft Dynamics 365 Business Central.

Use in EASY Invoice

First, it is recommended that you change the decimal separator globally used for new installations in EASY invoice in combination with "EASY for Dynamics 365 Invoice Connector" to the point (Documents5 Manager / Documents / Settings / Locale/Format / Format settings / Decimal separator: ".". The format for numbers will then be set tot he point as a decimal separator, even in the file field for Gentable data ("InvoiceItems"). When you login for the German version, amounts will continue to be displayed with the comma as the decimal separator.

Customizing data deployment for IRIS xTRACT or EASY Capture Plus is not necessary.

If the UserExit DataTools, e.g. "Purchase invoice - Line items - Purchase order line number", transfer incorrect numbers into the Gentable when applying an entry, then check which parameters are used for transforming numbers, and customize the parameters to your needs. In doing so, you need to make sure that this setting also applies globally - both for all accounting entities and for all differing language logins (English/German) in the EASY workflow.

Export to Microsoft Dynamics 365 Business Central

Transforming the numbers has previously not been necessary until they could be passed to Microsoft Dynamics 365 Business Central. Should performing a transformation prior to export become necessary, you can use the parseFloat helper.

Date formats

Regardless of your own selected language, Microsoft Dynamics 365 Business Central internally works with the advanced version of ISO 8601 - YYYY-MM-DD.

Import

Synchronizing dates (e.g. document date) using the Import DataTools is performed without transformation (e.g. orderheaderdate in the DB table orderheader).

Use in workflow

In UserExits, the dates are displayed without transformation. If you want a transformation, please customize the mapping in the corresponding UserExit DataTool.

Export to Microsoft Dynamics 365 Business Central

When exporting from EASY Invoice, you need to make sure that transformation supply the format expected by Microsoft Dynamics 365 Business Central for date values. For transforming dates, use the formatDate helper. In the case of Document Date, this already happens, see. Transformation callbackscript cb.ehrmDataTools.transform.invoice2businesscentral.

Customize EASY Invoice

Hide fields from the "epiFiles" file type

Since both Microsoft Dynamics 365 Business Central and "EASY for Dynamics 365 Invoice Connector" work line item related, some fields that exist in file view must be preferably hidden using an extension in the PortalScript epiFiles_decreaseFieldRights. This applies to:

  • Allocation (de: Belegkontierung")

  • ImpersonalAccount (de: GL account)

  • ImpersonalAccountName (de: Name)

  • CostCenter (de: Cost center)

  • CostCenterName (de: Name)

  • CostUnit (de: Cost unit)

  • CostUnitName (de: Name)

Please save the PortalScript.

Customize mapping

In EASY Invoice, the purchase invoices are enriched with data from the shadow database InvoiceControlDb when starting the workflow. For this purpose, mappings are used which can be customized in the PortalScript epiMappingConfig.

Name

Customization

epiMappingConfig.arOrderItemUpdateDataMapping

Add the following entries to the array:

["ItemType", "orderitemcustom1"], // Type
["ItemNumber", "orderitemarticlenumber"], // Number
["ItemGenBusPostingGroup", "orderitemvatcode1"], // Business posting group
["ItemGenProdPostingGroup", "orderitemvatcode2"], // Product posting group
["ItemVatBusPostingGroup", "orderitemcustom3"], // Sales tax/VAT business posting group
["ItemVatProdPostingGroup", "orderitemcustom4"], // Sales tax/VAT product posting group

Please save the PortalScript.

Change accounting entry configuration

So that the data synchronized by Microsoft Dynamics 365 Business Central to the shadow database InvoiceControlDb is loaded to the new purchase invoices or purchase credit memos, you have to make the following changes to all participating accounting entries:

"Checking orders / order source" field on file cover, "General options" section

"Use order data from shadow database"

"Check goods receipts" field, ibid.

"Use goods receipt from shadow database"

"Check order quantity deviations" field, "Order/goods receipt" tab, "Order configuration" section

"Yes"

"Type of goods receipt checking" field, "Order/goods receipt" tab, "Goods receipt configuration" section

"Check goods receipt with each invoice"

Integrate export with workflow

The purchase invoice and purchase credit memo data must be transferred at the end of the EASY Invoice workflow, using EASY Invoice Connector, to Dynamics 365 Business Central - i.e. exported.

Exporting invoice data to EASY Invoice Connector is not available as an export option for the accounting entity because EASY Invoice does not match a specific ERP system. The process for exporting the data is therefore to be developed in the respective project, and to be usefully integrated with the existing process.

See Export Integration for how to realize implementation of the export and what to take into account.

(Optional) Configure blacklist for Synchronizing the master and transaction data

The Import DataTools are automatically executed every day or hour for each EASY Invoice accounting entity configured in the principal.

If you want to exclude one or more accounting entities from auto-synchronization, please create the bccRecipientBlacklist property for the Documents principal, and enter an array including all the appropriate accounting entry names enclosed in single quotation marks as a value.

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

(Optional) Integrate other fields

For an example of how to include other fields in the Business Central Connector integration, see this page: Project-Specific Customizations.