Perfion Release2ERP for D365 BC allows you to import and persist information from Perfion to the D365 BC environment.
This document will describe the installation and configuration of Perfion Release2ERP for the typical D365 BC environment.

If you have special use cases or need custom setup tailored to your needs, please contact your Perfion partner for more information.

Introduction

Perfion Release2ERP for D365-BC allows you to import and persist information from Perfion to the BC environment.

This document will describe the installation and configuration of Perfion Release2D365BC for the typical BC environment. If you have special use cases or need custom setup tailored to your needs, please contact your Perfion representative for more information.

General Considerations

A word of caution

Any changes made to your ERP system should be tested in a proper test environment before being deployed to the live ERP system. Please consult with your Microsoft Dynamics 365 partner about the changes required to implement this software, before continuing further.

Supported BC Version

The following versions of Microsoft Dynamics365 BC are supported:

• Microsoft Dynamics365 BC 13.0 to BC 24.0

Perfion will continually strive to offer support for any new releases of Dynamics 365 BC that Microsoft publish.

Object scope for Perfion Release2ERP for D365BC

Supported BC Clients

The online client is supported.

The On-Premise client is supported.

Prerequisites

The Service Layer server needs Microsoft .Net 4.5 installed.

The Perfion Web Client needs to be available and set up correctly. 
One specific requirement is that a secure https must be used (web client accessed via https:// and not just http://). This is necessary because the cloud version of Business Central will not accept the web client as a secure site without a certificate.

Installation

There are two types of installations, one is for the cloud-based Business Central and the other one is for Business Central On-premise. So follow the installation instructions fitting for the type of Business Central on your machine.

On-premise Business Central Installation

Release2D365BC will be installed through the Powershell from Business Central.

You must make sure the NAVAdminTool Powershell Module is installed. If it is not present, please contact your ERP partner to have it installed.

Open the search feature in windows and type in: Business Central Administration Shell, right click the app and open it as PowerShell Administrator.
Below is an example:

After opening the Powershell, write cd \ and the folder directory for your Business Central as in this example below:

When you start typing the directory you can press the TAB button to make Powershell guess the folder name.

You should end up in the service folder like this:

Press Enter.

Now to the installation. To install the Release2 module you must run the app provided by Perfion. The following is an example:

Publish-NAVApp -ServerInstance "BC130" -Path "C:\PerfionR2ERP\Perfion_Release2D365BC_1.1.0.0.app" -SkipVerification

ServerInstance: The name of your BC Server, standard is “BCXXX”
Path: The exact location of your Perfion Release2D365BC.app file.

Press Enter, and your Release2 module should now be published in Business Central.

Now open your Business Central and search for Extension Management. Your Release2 should now be available inside here. Click it and click Install.

That’s it. The Perfion Add-in has now been installed.

Cloud-based Business Central Installation

Release2D365BC can be imported by uploading the .app-file as an Extension in Business Central.

Go to Setup & Extensions/Extensions and choose Manage/Upload Extension. You should see a page like this:

• Select .app file: This is where you must choose the Perfion_Release2D365BC_1.1.0.0.app file to deploy it to BC.
• Deploy to: Here you can select when to deploy the extension. The current version of BC, or the next minor or major version.
• Language: This chooses between the languages you have in BC.
• Accept: Push the dot to the right, to accept the Disclaimer that Microsoft is not the creator of this extension.

After the installation you should be able to see the Release2D365BC in your extensions menu like this:

Install via Extension Marketplace (Cloud)

Perfion now offers the option for ones who are running on a cloud hosted D365 Business Central, to directly download and install our Release2ERP module through D365 Business Central ‘Extension Marketplace’.

Search for ‘Extension Marketplace’ in Business Central:

In the ‘Extension Marketplace’ search for ‘Perfion Release2ERP’ and press ‘Get it now’

Enter the required information and accept the terms of use click ‘Continue’. The Add-in will now proceed to download and should be visible under ‘Extension Management’ once it has downloaded and installed.

Configuration

Release2D365BC is a very versatile tool that can be configured to fit many different use cases. In this document, we will show simple examples that illustrate what is possible and discuss the options available. All settings have to be made in Business Central, and it is at this moment only possible to gain access to each page by using the search function. Throughout this document the keywords to search for, will be listed in the beginning of each section.

Basic settings in Release2D365BC

Start by searching for Release2BC Setup Card and then open that page.

You should see a page like this:

Log Cleaning run from Job Queue Entries is a new option added in Release2BC v. 3.1.0.9

For most, the default values will be perfectly fine.

• Log: The log field is where you choose what type of events to log. The options are: Error, Success, All
• Log Period: this field is where you set how far back in time the log entries will be kept. It is expressed as a date formula https://docs.microsoft.com/en-us/dynamics-nav/dateformula-property
• Chunk Size: This value sets the number of records retrieved from the Perfion API at a time, when dealing with large amounts of records.
• Log Cleaning run from Job Queue Entries: Allows user to setup a Job Queue Entry to automatically delete obsolete log entries run by the integration, configuration of this can be found at section “Configure Automatic Log Cleanup”

Setting up a Perfion Connection for Release2D365BC

Start by searching for Release2BC Connection List and then open that page. You should see a page like this:

Click the New button to add a new line. Fill in the fields to match your setup.

• Code: This is the code for this connection. It should be filled with a meaningful string of max 10 characters.
• Description: Enter a description of this connection.
• Perfion API URL: Enter the full URL of the API service. Example: http://url.com:8081/Perfion/GetData.asmx
• Perfion API Image URL: Enter the full URL of the API Image service. Example: http://url.com:8081/Perfion/Image.aspx
• Perfion API User Name: If authentication is enabled on the API service then enter the username here.
• Perfion API Password: If authentication is enabled on the API service then enter the password here. 

Setting up a Release2D365BC Integration

Start by searching for Release2BC Integration List and then open that page. Click the New button to open the Integration Card. You should see a page like this:

However, the page does not yet have any values entered. Let’s go through them section by section.

The General Section

This section contains the general setup elements for the integration.

• Code: This is the code for this integration. It should be filled out with a meaningful string of max 10 characters.
• Connection Code: Here you select which connection the integration will use to import data.
• Description: Enter a description of this integration.
• Last Run Date: This field is not editable; it will automatically be updated whenever the integration is run successfully.
• Record Root Node: This is the XPATH that contains product information in the XML returned from Perfion. Typically, the value should be //Data/Product. If you are releasing other data than products the value has to be changed.

The Query Section

This section contains the settings that are related to the query of the API service.

First click the Process button to open the query options.

Here is an overview of the fields in the query section:

• Upload Api Query: This lets you upload the API query file that will be used for the Release2 module.
• Download Api Query: This will download the current API query file that is used for the Release2 module.
• Preview Query: Will download a preview in .txt format of what the query will get from Perfion.
• Execute Query: Let’s you Execute the query inside Business Central.
• For information about how to write a query, please see the Perfion API documentation.

Here is an example query:

<Query>
      <Select languages='EN, DE' view='Normal'>
            <Feature id='ItemNumber' />
            <Feature id='ShortText' />
            <Feature id='Description' />
            <Feature id='Image' />
      </Select>
      <From id ='Product'/>
      <Where>
            <Clause id='brand' operator='=' value="Normal" />
            <Clause id='ModifiedDate' operator='>' value="%LASTRUN%" />
      </Where>
</Query>

The Field Mapping Section

This is what we are here for: Mapping data fields from Perfion to data fields in BC. It is simple, but there are a few things you must keep in mind.

• Each line represents one value mapped from Perfion to BC.
• To map anything into a table in BC, you must map all primary key fields of the destination table as a minimum. 
• It is recommended to make a section step for each destination record being inserted or modified.
• If you make changes to a line that affects the order of execution, it is not shown in the window until it is either refreshed or closed and reopened.

Here is an overview of the fields:

Section Step: This is the logical top level container of lines. Section steps lets you group the steps together in columns, table wise.

Table No.: This is the number of the table in BC that the line is pointing to.

Table Caption: This is the caption of the table that the line is pointing to. When Table No. is changed this is automatically filled in.

Field No.: This is the number of the field in BC that the line is pointing to.

Field Caption: This is the caption of the field that the line is pointing to. When Field No is changed this is automatically filled in.

XPath: This is the Xml XPath to the value that is being imported from Perfion. This is a relative path from the root node that was declared in the Record Root Node field, in the Query section.

Import: Defines when data is imported into the mapped field. Import is skipped for existing records (records which are updated) when the value is set to “Inserting”.

Validate Data: This has 3 settings: Blank means no validation. When Different means that the data will be validated if the new value is different from the old value. Always means that the value will be validated every time the integration is run.

Accept Max. Length: When enabled, the value from Perfion will be truncated to the length of the destination field if necessary.

Allow Empty String In Key Field: Default behavior is to skip creation of records if they have blank values in any key field. Enabling this option will allow an empty string in the specific key field, and still create a new record if none exist in BC.

Default Value: This is a constant value that will be inserted in the destination field if no value is found in the XPath of the data from the API service. Default Value is used twice in the example integration shown above. First one is Section Step 1, Table No. 30 Field No. 2 where the Language Code is set to the constant DEU. Here no XPath value is defined because only the constant value is ever wanted in the destination field. The second one is Section Step 1, Table No. 30, Field No. 5400 where there are blank values in both XPath and Default Value. This means that a blank value will be inserted in the destination field. The reason for this last line is to fulfill the requirement to map all primary key fields of a record.

Conversion Code: If this is set to a valid Code, then the selected conversion will be applied to the value being imported. See next page for details about setting up a conversion.

Buttons

In the action pane, there is also a Report button.

• Log Entries: This will open the Log Entries Page with a filter set for this integration.

Setting up Release2D365BC image parameters

Adding the new parameters

Open the Release2BC Integration Card and click on the small gears icon (Settings) in the top right corner. Select Personalized and then select the mapping area and click the + Field option as shown in the screenshot below.

Now you have the option to add different image parameters to the mapping.

Field overview:

Image DPI: This parameter wills cale the image exactly to the specified resolution. This parameter cannot be combined with the fit or size parameters. For precision, the parameter value can include a decimal separator.

Image Fit: This parameter controls how to interpret the size parameter. 
Fit is the default behavior (equivalent to omitting the parameter). Scale the image to fit within the specified size by keeping the aspect ratio. 
Exact will stretch the image in one or the other dimension of the specified size does not have the same proportions as the original image.
Crop will crop the image in either the sides or at the top/bottom, thereby leaving the contents of the image undistorted if the specified size does not have the same proportions as the original image.
Smart will adjust the image via a 50% combination of the before mentioned exact and crop fitting methods if the specified size does not have the same proportions as the original image.

Image Format: This parameter will let you choose the format of the image import. The supported image formats are what is supported by the Microsoft .NET framework.

Image Height: Lets you decide the height of the image in pixels. The pixels must be expressed in whole integer numbers.

Image Width: Lets you decide the width of the image in pixels. The pixels must be expressed in whole integer numbers.

Setting up a Conversion

Start by searching Release2BC Conversion List and then open that page. Click the New button to open the Integration Card. You should see a page like this:

The General Section

This section contains the general setup elements for the conversion.

• Code: This is the code for this conversion.
• Description: Enter a description of this conversion.

The Values Section

Here you will find the Conversion Lines. Each line describes one value conversion. The lines have two columns:

• Perfion Value: This value is what Perfion will return. Values are case sensitive and only exact matches are considered.
• Business Central Value: If a match has been made in the Perfion Value column, then this value is used in BC. 

NOTE: when setting up the Perfion Value in the conversion card the text value must be in UPPERCASE in order for BC to accept the value. The Business Central value can be user defined to fit the needs for the conversion.

Example:

In this example we want create a conversion that takes the Perfion value “CHAMBORD” to be “chambord testing”, even if the Perfion value within Perfion is not CHAMBORD with all uppercase letters the user must still define this value as all uppercase.

After importing the product the description is now updated to what the conversion BC value is set to:

Setting up the NAV Job Queue to run a Release2D365BC Integration

Start by searching Job Queue Entries and then open that page. Click the New button to open the Job Queue Entry Card. You should see a page like this:

The values in the screenshot above is a good starting point but should obviously be adapted to your needs.

• Object Type to Run: this should be set to Codeunit
• Object ID to Run: this should be set to 81004 (PFNRel2BCIntegrationMgt)
• Parameter String: this should be filled in with the Code of the Release2D365BC Integration that you wish to run.

The remaining settings will need to be set according to your wishes.

When you are satisfied with everything, go to Process and press the button Set Status to Ready. Your scheduled job is now activated, and you can close the window.

Configure Automatic Log Cleanup

Users can now create a Job Queue Entry allowing automatic cleanup of old log entries accumulated by the integration executions.

To configure the Job Queue Entry go to the Release2BC Setup Card and select the field outside of the caption Log Cleaning run from Job Queue Entries.

The Log Period on this page defines for how long the logs are kept and the Job Queue Entry job will remove them accordingly in this case all logs that are older than 1 Day will be removed next time the cleanup job has been executed.

This will open a new job queue entry creation window:

Configuration:

Object type to Run: Codeunit

Object ID to Run: 81004 or 71057702

• On-premise: 81004
• Cloud hosted: 71057702

Object Caption to Run: PFNRel2BCIntegrationMgt

Description: Optional

Parameter String: HOUSECLEANING (this is case sensitive and should always be in caps and one word)

Once these are configured go ahead and setup up how often these integration runs, it is advised to run it more frequently if the log level is set to high.

Appendix A: Advanced mapping example

Importing from Perfion to BC requires knowledge in both systems, and the use cases range from simple and straightforward mapping to more advanced usage.

We here provide an example of a mapping to the Sales Price Table, since this will demonstrate some of the more advanced topics and should give you an idea of how to map to further tables in BC after going through each step in this example.

The Sales Price table consists of multiple primary keys that we need to define in the mapping to be able to import to it, so to find these go to Sales Prices and press Ctrl+Alt+F1. This will give you a page overview of the Sales Price table like on the screenshot below:

On the right side you have the Page Inspection, and this shows all the fields on the Sales Price table. If you look closely on each field, you can see what kind of field it is as well. So in this case Item No, Sales Code, Currency Code, Starting Date, Minimum Quantity, Unit of Measure Code and Variant Code all have PK after their main information, which means that these 7 fields are Primary Keys and have to be mapped to import any data into the Sales Price table.

This was the first step. So now that we have found all the primary keys needed for the importing, we can start mapping in the Release2ERP module.

As you can see on the screenshot below, we have mapped all primary keys and some additional fields in the example:

Now the next step is mapping all the Primary Keys and fields from BC to Perfion, to connect it all together. Let’s go through all 7 Primary Keys

Item No: Is Mapped to Perfion as Value.
Sales Code: Since we don’t have the field in Perfion we put a check in the Allow Empty Value In Keyfield. This will let us import even though we don’t have a real value for that Primary Key.
Currency Code: Since we don’t have the field in Perfion we put a check in the Allow Empty Value In Keyfield. This will let us import even though we don’t have a real value for that Primary Key.
Starting Date: Is Mapped to Perfion as StartDate.
Minimum Quantity: Is set up to have a Default Value, in this case 0.
Unit of Measure Code: Is set up to have a Default Value in this case PCS. 
Variant Code: Since we don’t have the field in Perfion we put a check in the Allow Empty Value In Keyfield. This will let us import though we do not have a real value for that Primary Key.

After having everything mapped, we can now execute our Import and as you can see from the screenshot below from the Log, we now have imported data into the Sales Price Table:

This should give you a basic idea of how more advanced mapping is done inside BC. We always recommend working together with your ERP Partner to help with the overall business logic since this can vary from customer to customer.