Integrating with Perfion

The Dynamicweb Integration Framework is a collection of components for transferring data and maintaining data consistency between a Dynamicweb solution and a remote system.

There are two main components to developing an integration with Dynamicweb (Figure 1.1):

  • batch integration is a file-based approach, which uses scheduled tasks to import and export data at intervals (hourly, daily, weekly, etc.).
  • live integration submits real-time requests from a Dynamicweb frontend to the remote system, then uses the data returned to show e.g. live prices or stock
Figure 1.1 The components when integrating with Perfion

A Perfion integration is a batch integration – and the overall data flow is as follows:

  • Dynamicweb submits XML requests for data to the DynamicwebConnectorService
  • The DynamicwebConnectorService relays the request to the Perfion API Service
  • The Perfion API Service extracts data and returns it to Dynamicweb as an XML file
  • An XSLT template transforms the Perfion XML data to a format understood by Dynamicweb
  • The transformed XML is imported to the Dynamicweb database

In this document, we will go through the process from both sides of the integration – the Perfion side and the Dynamicweb side.

In the Perfion side of the integration you must:

  • Install and configure the Perfion API Service on the Perfion environment
  • Install and configure the DynamicwebConnectorService on the DMZ/Perimeter network

Presently, Perfion have removed support for downloading and installing the Perfion API Service directly.

Please contact Perfion for information on adding the Perfion API Service to your Perfion solution.

The DynamicwebConnectorService is a web service, which functions as the bridge between the Dynamicweb solution and Perfion. It must be installed on the DMZ/Perimeter network of the Perfion environment.

The install process will likely require a user that has permission to install the service. If you are on a domain, the user should include the domain. If you are using a user on the local machine, the username should be prefixed with a period and a slash: “./Username”.

To install the DynamicwebConnectorService:

  • Download the DynamicwebConnectorService files from our downloads area – you must be logged in to access the files
  • Extract the DynamicwebConnectorService files to an appropriate location  – e.g. C:\Program Files\DynamicwebConnectorService
  • Locate the installUtil.exe file – it is usually found in the c:\Windows\Microsoft.NET\Framework\vX.X.XXXXX folder, where vX.X.XXXX is the latest version of .NET you have installed. This should be .NET 4.5 or greater
  • Right click on the DynamicwebConnectorService.exe file, then select properties > unblock
  • Install the service from the command prompt using installUtil.exe, with the following command: 
c:\Windows\Microsoft.NET\Framework\vx.x.xxxx\installUtil.exe DynamicwebConnectorService.exe
  • Go to Control Panel > Administrative tools > Services and start the service called DynamicwebService

This exposes the web service to the internet.

Once the service has been installed, you must open and edit the DynamicwebConnectorService.exe.config file located inside the DynamicwebConnectorService folder:

<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <section name="NavConnector" type="System.Configuration.NameValueSectionHandler"/> <section name="AxConnector" type="System.Configuration.NameValueSectionHandler"/> <section name="PerfionConnector" type="System.Configuration.NameValueSectionHandler"/> </configSections> <NavConnector> <add key="UserName" value="Navconnector" /> <add key="Password" value="Navconnect1.2" /> <add key="Domain" value="dynamic-systems.lan" /> <add key="NavEndpoint" value="http://YourNAvServer:7047/DynamicsNAV/WS/CRONUS%20Danmark%20A/S/Codeunit/DWWebService" /> <!-- Set IgnoreCertificateWarnings to true for https endpoints using self-signed or untrusted certificates. Useful for testing. Should be avoided in production. --> <add key="IgnoreCertificateWarnings" value="True" /> <!-- Valid options for ClientCredentialType are: Default, Ntlm, Windows, Basic --> <add key="ClientCredentialType" value="Default"/> </NavConnector> <AxConnector> <add key="UserName" value="Navconnector" /> <add key="Password" value="Navconnect1.2" /> <add key="Domain" value="dynamic-systems.lan" /> <add key="AxEndpoint" value="http://YourAxServer:8090/MicrosoftDynamicsAXAif50/dwservice.svc" /> </AxConnector> <PerfionConnector> <add key="PerfionEndpoint" value="http:/YourPerfionServer/Perfion/getdata.asmx" /> </PerfionConnector> <appSettings> <add key="ServiceName" value="DynamicwebService" /> <add key="testMode" value="False" /> <add key="TestOutputFile" value="c:\exportContent.xml" /> <add key="Secret" value="test" /> <add key="DebugInfo" value="True"/> <add key="WebserviceURI" value="http://localhost:8090/DynamicwebService"/> <add key="ErpConnectorType" value="AXConnectorAddIn.AxConnector"/> </appSettings> <system.serviceModel> <bindings> <wsHttpBinding> <binding name="WSHttpBinding_DWService" /> </wsHttpBinding> </bindings> <client> <endpoint address="http://dw-jkd-erp.dynamic-systems.lan:8090/MicrosoftDynamicsAXAif50/dwservice.svc" binding="wsHttpBinding" bindingConfiguration="WSHttpBinding_DWService" contract="AxDynamicwebService.DWService" name="WSHttpBinding_DWService"> <identity> <userPrincipalName value="Navconnector@Dynamic-Systems.lan" /> </identity> </endpoint> </client> </system.serviceModel> </configuration>

In the <PerfionConnector> section you must:

  • Point the PerfionEndpoint value to your Perfion web service

In appSettings section you can:

  • Set testMode to True – this will make any call to the connecter service read and return the contents of the file specified in TestOutputFile. This is useful for debugging purposes.
  • Specify a secret which is used to encrypt traffic between the Dynamicweb solution and the connector service. It will be used on the Dynamicweb-side of the integration as well.

If your Perfion is on different server/network than your Dynamicweb installation – and it usually is – you must make sure that the network and firewall settings allow connections from the Dynamicweb server to the web service exposed by the Dynamicweb Connector.

At this point in time, the people working on the Dynamicweb side of an integration expect two things from you:

  • The secret (encryption key) from the DynamicwebConnectorService configuration file
  • The endpoint of the DynamicwebConnectorService web service

This will allow them to query the API service, receive data, and import it to the Dynamicweb database.

Once the Perfion API Service and the DynamicwebConnectorService have been installed on the remote environment, the Dynamicweb side can query the Perfion API Service and get data back.

In contrast to an integration with an ERP system like NAV or AX, Dynamicweb does not install an active component in the Perfion environment. The Perfion API Service can be queried, but the data being returned is returned as is – in the standard Perfion XML format.

This means that the Dynamicweb side of the integration must use XSLT to transform the Perfion data into a format understood by Dynamicweb.

The data flow is as follows:

  • The Dynamicweb solution requests data from the Perfion API Service
  • The Perfion API Service extracts data and returns it in XML format to Dynamicweb
  • The XML file is transformed into an XML format understood by Dynamicweb using an XSLT template
  • The transformed XML is imported to the Dynamicweb database

All pretty straight forward.

On the Dynamicweb side, you must do the following:

  • Create a Data Integration activity for parsing Perfion data and adding it to the Dynamicweb database
  • Create a Batch Integration task for requesting data at scheduled intervals

Perfion exports data in an XML format which is not compatible with Dynamicweb – so you must create a data integration activity which transforms the data to Dynamicweb-compatible XML before adding it to the database.

This activity depends on two things; an xml file containing data and an XSLT template transforming the data from Perfion XML to Dynamicweb XML.

Of course, at this point we have neither – so create a simple XML file with the following content:

<?xml version="1.0" encoding="utf-8"?><Data></Data>

Place it in Files/Integration/Perfion or an equivalent folder, then download the PerfionExemple.xslt file – which is based on a Perfion demo database –and place it in the same folder, then edit it to fit your data.

You can now create the data integration activity:

  • Go to Apps  > Data Integration and click New activity
  • Select the XML Provider as your source provider
  • Select the xml file you just created as the source file
  • Select the PerfionExample.xslt as the XSL file
  • Set Source decimal separator to Detect automatically

You should end up with a source provider configured as in Figure 7.2)

Figure 7.2 Configuring an XML provider for perfion integration

Next you must select and configure the destination provider – in this case the Ecom provider:

  • Click Next and select the Ecom provider
  • Configure it to your liking –read more about your configuration options
  • Click Next – you will be asked to map source tables to target tables – ignore the request, you want to map automatically every time the activity is run
  • Click Finish and Name the activity
  • Check the Perform mapping automatically on run checkbox
  • Click OK

This creates the data integration activity which is used to transform and import the data extracted from Perfion.

We still don’t have any data, though, so let’s get on that.

To retrieve data from Perfion, you must create a batch integration task which queries the Perfion solution using a Perfion-specific query language.

Please contact Perfion for documentation on the query language.

To create the batch integration task:

  • Go to Settings > >Integration > Integration Framework Batch
  • Click Add
  • Provide a name, a start date/time, an end date/time, and a repetition interval as appropriate
  • Select the Import data with custom request add-in (Figure 8.1) and configure it
Figure 8.1 Importing data from Perfion

To configure the Import data with custom request add-in:

  • Provide the web service URL exposed by the DynamicwebConnectorService - by default this is http://YourServerNameOrIP:8090/DynamicwebService
  • Provide the security key which is used to encrypt and decrypt data flowing between Dynamicweb and the remote environment. It is defined in the DynamicwebConnectorService configuration file.
  • Enter the request XML used to query the Perfion solution
  • Select the import activity  you just created – it will be executed when this job is run

The request XML is of course dependent on your scenario, but in general looks something like: 

<Query><Select languages='EN, DE, DK' view='Normal, Virtual'><Feature id='*' /></Select><From id ='Product, Category' /></Query>

You can also set up notifications on successful/failed executions, as you see fit.

Once the batch integration activity is set up, test it to verify that the XML is transformed correctly. If not, edit the XSLT file and try again.

Images from Perfion are imported using a particular batch task add-in called Import Perfion Images Add-in.

It can be run once or periodically – if run more than once, the new images will overwrite the existing images if they were updated or changed in Perfion.

To create an image import job:

  • Go to Settings > Integration > Integration Framework Batch
  • Click Add
  • Provide a name, a start date/time, an end date/time, and a repetition interval as appropriate
  • Select the Import Perfion Images Add-in and configure it (Figure 9.1)
Figure 9.1 Importing images from Perfion

To configure the Import Perfion Images Add-in:

  • Provide the web service URL exposed by the DynamicwebConnectorService - by default this is http://YourServerNameOrIP:8090/DynamicwebService
  • Provide the security key which is used to encrypt and decrypt data flowing between Dynamicweb and the remote environment. It is defined in the DynamicwebConnectorService configuration file.
  • Point the add-in to the Perfion image server URL – this is the image.aspx exposed by the Perfion API Service website
  • Select a destination folder for the imported images

You can also specify the file format, size or dpi, and the image fit (crop, fit, etc.) of the images returned by Perfion, and set up notification emails.

A typical query for retrieving images has the following format:

<Query> <Select languages='{Perfion Language IDs}' view='Normal, Virtual'> <Feature id='Images' /> </Select> <From id ='Product' /> </Query>

The Import Data from Multiple Requests Add-in makes it possible to execute several requests against the Perfion web service, and import the result afterwards.

It must be paired with an import activity which uses the XML Provider with a source folder instead of a source file.

You can select a separate XSLT file for each query, if necessary.

Figure 10.1 The Import Data from Multiple Requests Add-in

Since the Perfion API Service is not an active component, extending a Perfion integration happens on the Dynamicweb-side of the integration:

  • Query the Perfion API Service to return the data you want to extend the integration with
  • Modify the XSLT to place the data correctly in the Dynamicweb database

There are two possible scenarios when placing data in Dynamicweb:

  • The data is appropriate for a standard field in Dynamicweb
    If the data has a natural destination in a standard Dynamicweb field, the column name in the XSLT should follow the system name of the field in Dynamicweb. If the job uses automatic mapping at runtime, this should be sufficient. If not, the mapping must be created manually.
  • Dynamicweb does not contain an appropriate standard field
    If Dynamicweb does not contain an appropriate standard field, a custom field must be created to receive the data. The column in the XSLT should be named after the system name of the custom field. Please keep the data type in mind when deciding on the type of custom field.