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

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

This page describes the Perfion “Release2ERP for D365, Finance and Operations” module (abbreviated Release2ERP, for the remainder of this document) which enables synchronization of data from Perfion into a Dynamics 365, Finance and Operations solution.

Architecture

The Release2ERP module is a piece of software which is installed directly into the Dynamics 365 solution, as an extension. The software is configured from inside Dynamics 365 and will appear as a fully integrated part of your D365 solution.

For the Release2ERP module to function, the data from Perfion must be accessible from the D365 server via the Perfion API. The API is used to retrieve data before they are stored in D365.

The overall architecture of the Release2ERP module is shown below:

Configuration of the integration is done inside Dynamics 365, as described later in this document. In this way, Dynamics owns the initiative over the integration, whereas Perfion is passive and responding to incoming requests.

Use cases

• Perfion as master system for ERP data.

  • For manufacturers: Items can be “born” in Perfion, and sent to D365 when they are ready for production/sales

  • For resellers: Product data received from suppliers can be received in Perfion, filtered/modified, and then sent to D365

• Use conversion rules to account for difference data structures between systems

• Allowing Perfion users to influence other processes without entering Dynamics 365

• Scheduled synchronization to ensure consistency across system landscape

Limitations

• There is no “push” functionality from Perfion when for example data has been changed. All sync jobs are “pull” from Dynamics 365

• Mapping is always done to D365 Enitites – so if no target Entity exists in D365 for a specific data field, it must be created before mapping is set up.

• Use of Release2ERP requires an additional license fee

D365 Commerce Compatibility

D365 Commerce is fully integrated with D365 Finance & Operations, meaning that the front-end of D365 Commerce is being supplied with data directly from D365 Finance & Operations.

Therefore, Perfion Release2ERP supports D365 Commerce, as the Release2ERP module supplies product information data to D365 Finance & Operations, which then can be visualized in D365 Commerce front-end.

We do not support the configuration of a D365 Commerce solution, this should be configured together with a Commerce partner.

Prerequisites and installation

Prerequisites

The Perfion Release2ERP, Finance and Operations module has been verified to be compatible with the following versions of Dynamics 365 Finance and Operations:

• 7.0

• Release 1611

• July 2017 update

• 7.3

• 8.0

• 8.1

• 10.0

In order for the integration to be working, the following Perfion components must be installed and running:

• Perfion Database

• Perfion API Web Service

In most typical Perfion installations these steps will already have been taken. If not, refer to the corresponding documentation and/or your implementation partner.

Installation

Download the latest Release2ERP for Dynamics 365 Finance & Operations from Perfion Download Center.

For installing the package into Dynamics 365, please consult with your Microsoft Dynamics Partner on how to proceed. Perfion guarantees compatibility and adherence to Microsoft standards for D365 extensions but does not handle the actual installation on the customer’s Dynamics server.

Configuration and setup

Menu structure

Installing Perfion Release2ERP adds a new submenu to the System Administration menu named Perfion Release2ERP. The submenu contains menu items for integration setup and execution:

Base data

Before setting up integrations, it is necessary to setup base data which is used in the import.

Configuring Perfion connections

The first part to complete during configuration is to set up one or more connections to Perfion. Connections are set up using the Setup à Connections menu item.

Create a new record using the +New button in the top ribbon. Specify a connection identifier (in the example below it has been named “test”). Fill in the description and connection string to complete the basic connection setup.

The connection string is the URL for the Perfion API. 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.

If authentication has been enabled on the Perfion web service, you need to specify user name and password in the Authentication part of the connection settings. The password is encrypted in the Dynamics 365 database.

Configuring value conversions

In some cases, it is necessary to convert values from Perfion when importing them into Dynamics 365. 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 setup later.

Configuring customer keys

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 365 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 using the +New button. 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. This value is not editable later.

The following screenshot illustrates a setup that will only import one note per document type for a specific record. The default behavior would have imported new records every time because of the default primary key being less strict.

Integration

When the base data has been set up, the integration setup can be created. This is done using the Common à Integrations menu item.

Integration header

Create a new integration using the +New button in the top ribbon.

The integration header consists of the following fields:

Advanced parameters

Parameters for batch processing and logging.

Batch

Parameters for batch threading defaults can be set up here. The module supports automatic batch thread calculation based on data set sizes or the number of system maximum batch threads.

“Batch size type” defines how you want to specify the number of calculated batch threads used when processing data import in batch. “Manual” defines that the value in “Batch size” will split the data import into X batch threads, where X is the number of items in the Perfion data set divided with the specified “Batch size”. “Automatic” batch size type specifies that the batch processing will use the maximum number of batch threads specified in the System administration server configuration.

Pagination

To import Perfion items in chunks, a functionality has been added that allows the Perfion API to page through all quired items. Pagination should be used when an API query is very large and includes a high data count, this helps Perfion API not to throttle since only a portion of data being queried at a time.

Pagination function can be found within “Import” on a Perfion integration. It has a combined functionality with Batch Processing and will only be activated when it’s toggled on.

When an integration is ready for import, go to import page and define a “Batch size” which is also the page size when “Use paging” is enabled.

In this example, the batch size is 100 products, meaning that if there are 1000 products in the API query it will page 11 times before all products are imported.

The first batch will be a simple “includeTotalCount” query to retrieve the number of items that needs to be paged, hereafter a calculation is made which in this case is that the import must page 10 times to retrieve all products.

Lastly 10 batch jobs will be created each one with 100 products to be imported.

Logging

Parameters for logging is set up in this field group.

“Log type” defines how extensive logging should be. “None” creates no log records when importing. “Simple” creates logs for all errors/warnings, including default value data. “Full” logs all errors/warnings, default value data and mapping values for all data imported. “Full” is only intended for use when importing small data sets or for debugging import mappings.

“Log ID” refers to an XPath expression you can use to log custom data to the integration log. The expression specified in the “Log ID” will be evaluated runtime and logged to the corresponding “Log ID” on the integration log table.

“Log text” refers to an XPath expression you can use to log custom data to the integration log. The expression specified in the “Log text” will be evaluated runtime and logged to the corresponding “Log text” on the integration log table.

View Perfion data

When the integration header has been created and filled in a Perfion query, it is possible to see the data retrieved from Perfion using the “Show data” button in the ribbon. This will show the live data which would be fetched during the import.

Integration lines

The integration lines consist of the following fields:

Default values

Several default values are available in queries and default values on integration lines. Values must be specified including the brackets [ and ] as defined below.

Example setup

An example setup for importing new products could look as below (feature names may vary).

This will create a new record in EcoResProductV2Entity (Products table) and EcoResProductTranslationEntity (Product translations) for each “record” in the Perfion data set.

It can be noticed that the Value feature is imported into the EcoResProductTranslationEntiity.ProductNumber field which is a numeric field holding a reference to the unique product record identifier. The import function translates this value into the correct record identifier using relations on the table in the development environment. The same logic can be applied to similar tables (Document references, Unit conversions, Storage dimensions etc.).

Be careful when creating setups for importing data and make sure that the setup is verified by someone who has knowledge of the data structure within Dynamics 365.

Import setup / Export setup

The import/export setups let you export your Release2ERP mappings as a json file and then import them back into the Release2ERP module. A use case for this could be having the integration setup and run in a test environment and then when implementing in a production environment, you can easily import the mappings you had from your test environment instead of reentering everything one more time.

Binary Data Import / Mapping

A new field has been added to the connection configuration, allowing one to add the Perfion Image Server URL for the integration, allowing the Release2ERP to retrieve binary data directly from Perfion.

The Image server URL should be defined as: http://localhost:8081/Perfion/Image.aspx  

Once the connection is configured, go to the integration and define your entities for where the binary data should be imported to.

In this example a mapping is made for ‘EcoResProductDocumentAttachmentEntity’, now select the XPath for a Binary feature in Perfion, in this case ‘Image’.

It is also possible to choose the desired Image Height & Image Width these values are defined in pixels.

Once these steps are done, a product with binary data (image) will look like this:

When importing products with images a query should be used to exclude products that has no image value in Perfion, if this is not done an error will occur which terminates the import of all the other products.

A query that excludes products with no images could be defined like so:

<Query>
   <Select languages='EN'>
      <Feature id='**' view='Item' />
   </Select>
   <From id='100' />
   <Where>
      <Clause id='Category' operator='=' value='Coffee Machines' />
      <Clause id='Image' operator='LIKE' value='' />
   </Where>
</Query>

As seen on the above screenshot product ‘13689’ is not part of the API result since it has no image value.

Import

When the integration setup has been completed, it is possible to import data using the Import button in the Integrations ribbon or via the menu item Periodic -> Import.

In the import dialog it is possible to import data immediately, or via batch processing using the “Run in the background” feature:

After the import, an Infolog will display a list of information regarding records imported and updated. The “Latest import” field on the integration is updated as well:

Log

In the top ribbon you have the option to see the log of all the imports that have been done in the module.

The import log gives you an extensive overview of the different steps through each import and who has done it and date/time. In the top ribbon of the log function, you have the option Clean up integration log which lets you clear the log if wanted.