Perfion Release2ERP for AX2012 allows you to import and persist information from Perfion to the AX environment.

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

FAQ regarding installation of Perfion Release2ERP for AX

Perfion Release2ERP for AX 2012 allows you to import and persist information from Perfion to the AX environment.

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

Prerequisites

Supported AX Versions

The following versions of Microsoft Dynamics AX is supported by this solution:

• Microsoft Dynamics AX 2012.

Perfion Release2ERP also exists for several other Dynamics versions. Please go to Perfion Knowledge Base for the latest compatibility overview.

A Word of Caution

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

Installation

Installing Release2ERP consists of the following four steps.

Installation of web service communications assembly

Install the Perfion.WebService.dll and Perfion.WebService.XmlSerializers.dll files into the Dynamics AX server bin folder or into the Windows global assembly cache folder on the AOS. As well as to the Client itself.

Install AX customizations

Install the supplied model files into the target environment.

Add Perfion menu to main menu

The main menu modification is not included in module - to simplify the installation (no overlapping in SYS/SYP). To add the Perfion menu to the main menu, open the developer section (ctrl+d) and go to the Menus section.
Now open the MainMenu(sys,var). After this is open you should in the Menus folder structure have a folder named PF_Release2AX(var). now drag this folder into the MainMenu(sys,var) and then you should have the Perfion Release2AX in the main menu of AX2012.

Image Removed

Image Added

Synchronize + compile application

Synchronize the data dictionary and compile the application.

Configuration

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

Basic settings in Release2ERP

To set up integrations to Perfion we need to create a few base settings first.

Connections

Connections specifies the source of the data you want to import using Release2ERP. This can be a web service or a local XML file. Before creating a new connection, you need to make sure that you have the right URL for the Perfion API service.

1. Navigate to the Perfion menu > Setup > Connections

2. Click the New icon or press Ctrl + N to create a new record.

3. Assign the connection a meaningful name.

4. Select the query type (typically Web service) unless you want to test using a local file.

5. On the General tab you must specify the URL to the Perfion API service (see below for a sample screenshot).

A good way to avoid issues is always to check the URL in a browser before putting it in the connection string, just to make sure you have an open API.

Image Removed

Image Added

If Authentication has been enabled on the Perfion API end point, you will need to specify username and password on the Authentication tab.

You will need to save the password for each AOS if you have multiple AOS’es in your environment (log on to AX on every AOS). AX 2012 encryption is done using a fingerprint from the AOS Windows machine. This is also the way standard AX saves SMTP passwords.

Setting up a Release2ERP Integration

Open the Integration menu item in the root of the Perfion menu.

Click the New icon or press Ctrl + N to create a new record.

Header fields

The Overview tab of the integration contains setup elements for the integration.

Integration: This is the unique identifier for this integration.

Description: A short description of the integration.

Connection: Select from the list of connections you have created earlier.

XPath root: Root node containing data from Perfion. Defaults to //Data/Product. Change this value if it does not reflect data in your Perfion database.

Update multiple records: Allow updating multiple records when finding existing records matching criteria. This is relevant if multiple records exist in the AX database based on the field mappings and Perfion data. Choose Yes to update possible duplicates. Choose No to skip updates. Choose Error to stop the import when finding multiple records.

Latest import: Latest execution date and time. Not editable.

The Query tab contains a large text field where you can edit the Perfion query. For information about how to write a query, please see the Perfion API documentation.

Use the wildcard %d to insert date and time of latest import into the query. For example, into the where clause to filter records older than a specific time. When the query is executed, %d will be replaced with date and time.

The following 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="%d" />
      </Where>
</Query>

Field mapping

The lower part of the integration form is for the data mappings between Perfion and Microsoft Dynamics AX.

Each line in the setup represents one value mapped from Perfion to AX.

To map anything to a table in AX, you must map all mandatory fields on the table as a minimum.

It is recommended to create a section step for each destination record being inserted or modified.

Like this example:

Here is an overview of the fields:

Enabled: Enables/disables import the line in the setup.

Line number: Defines the order in which the lines are processed.

Table name: Microsoft Dynamics AX table name.

Field name: Microsoft Dynamics AX field name.

Section step: Groups table/field combinations together. If you import values into multiple records of the same type, use section steps to separate the setup into groups (1, 2, 3 etc.).

XPath expression: Mappings use XPath syntax to find data received from the Perfion API.

Default value: Default value if no Perfion value exists. Use this instead of the XPath expression when you need to fill in data that is not available in Perfion.

Conversion: Converts a value from Perfion into a value suitable for AX. See section on how to create conversions later in this document.

Custom key: Release2ERP uses primary keys for find existing data for updates. Create and use custom keys to use your own specialized column combinations to find existing data instead. See section on how to create custom keys later in this document.

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

Buttons

In the form, you will find two buttons.

Show data: Retrieves and displays XML data from Perfion based on the query.

Import: This will run the integration (or enable you to run the integration in batch).

Conversion Setup

In some cases, it is necessary to convert values from Perfion when importing them into AX.

Conversions are set up using the menu item Setup à Conversion.

Create a new record using the New button. Fill in a conversion identifier and a description. Afterwards, create conversions as needed. You will be able to specify the conversions in the integration lines setup.

Custom Keys Setup

Custom keys are only needed in those cases where you want to override the default behavior when updating records during import. Without custom keys, Dynamics AX records will be found and updated using the primary key specified on the table by the developers. Using custom keys enables you to specify which of the table fields should be used for finding and updating existing records.

The menu item for custom key setup is found in Setup à Custom keys

Create a new custom key setup. Fill in a custom key identifier and a description. When creating the custom key setup, you must enter the table which you are specifying the new custom key for.

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 Dynamics 365 BC 13.0

• Microsoft Dynamics 365 BC 14.0

• Microsoft Dynamics 365 BC 15.0

• Microsoft Dynamics 365 BC 16.0

• Microsoft Dynamics 365 BC 17.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

Image Removed

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:

Image Removed

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

Image Removed

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:

Image Removed

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.

Image Removed

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

Image Removed

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:

Image Removed

• 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:

Image Removed

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:

Image Removed

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.

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:

Image Removed

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:

Image Removed

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.

The Query Section

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

Image Removed

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' operation='=' value=="Normal" />
      <Clause id='ModifiedDate' operation='>' 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.

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

Image Removed

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:

Image Removed

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.

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:

Image Removed

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 50104

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

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:

Image Removed

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:

Image Removed

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:

Image Removed

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.