Dynamicweb TestTool & Connector Service

The Dynamicweb Connector Service is a tool which functions as the bridge between the Dynamicweb solution and the ERP system. It is typically installed on the DMZ/Perimeter network of your environment, and handles data encryption and decryption – and functions as an extensibility point when developing custom integrations.

The connector is supplemented by the Dynamicweb Connector TestTool, which is a small but useful tool used for two things:

  • Testing the connection to the web service exposed by the remote system plugin
  • Testing requests to and responses from the remote systm, and delivering data from this process to the Dynamicweb side of an integration project

The two tools use the same Connectors – add-ins which connect to a particular remote system – so in a typical scenario you can transfer most of the settings from the TestTool to the Connector Service, once you’re ready.

If you follow the recommended project process, you will first install the TestTool on the remote environment, and use it to query the remote system for data, which you will then deliver to the Dynamicweb side of the integration. They will use this data to create import jobs and develop the solution against real data, which helps the project stay on track.

Once the data has been delivered to the Dynamicweb side, you will then install and configure the Dynamicweb Connector Service.

The Dynamicweb Connector TestTool is a small and useful tool which is used for two things:

  • Testing the responses returned by the web service for any given request
  • Testing the connection to the web service exposed by the remote system plugin

It can be downloaded from the downloads area of our documentation portal – you must be logged in to access the files. Unpack it:

  • When testing requests & responses it should be placed on the same environment as the remote system
  • When testing connectivity to the remote system, it should be placed where you want the Dynamicweb Connector Service to reside – e.g. on a perimeter network.

It does not require any installation, but must be configured before it can be used.

To configure the Connector TestTool, open the DynamicwebConnectorTestTool.exe.config file using Notepad++ or equivalent.

It contains:

  • A <configSections> element which specifies configuration sections and handler declarations.
  • A number of Connector sections – e.g. <D365Connector> or <AxConnector> – which contain setting for a particular remote system
  • A <ConnectorTestTool> section which can contain the following configuration settings:

Name

Required

Default Value

Note

TargetEnvironmentLabel

 

 

A short name that can be used to identify the current environment, e.g. “DEV”.

This is useful when you are using separate copies of the service tool for different environments (development, staging, production) or different clients.

TargetEnvironmentTextColor

 

 

A hex color code to be used for the environment label text, e.g. “fff”

TargetEnvironmentBackgroundColor

 

 

A hex color code to be used for the environment label background, e.g. “ff0000”

Edit the Connector section relevant to your remote system – the settings for each Connector are described in detail in the Connectors section if this article.

Run the DynamicwebConnectorTestTool.exe executable and then:

  • Select a Connector (1)
  • Enter a request or load a predefined request using the dropdown (2)
  • Click Run Test (3)
Figure 4.1 The Dynamicweb Connector TestTool

The response will be shown in the Response tab (Figure 4.2):

Figure 4.2 A response retrieved with the TestTool

The TestTool also contains the following useful features:

  • Use the arrows on the request tab to page back and forth between previously issued requests
  • Use the save to file button to:
    • Save a request – it will be available as a predefined request afterwards
    • Save a response as an XML file

For testing and debugging, the advanced TestTool features described below may be useful to you.

The XPath tab can be used to filter a response – this allows for basic debugging of data issues by reviewing a specific subset of data.

To use XPath filtering on a result:

  • Switch to the XPath tab
  • Enter an XPath – e.g. //item[column[@columnName='ProductNumber']='D0005'], which finds products by product number
  • Click the Test button

The XSLT tab can be used to transform the response from one XML format to a different XML format.

This can be useful in more advanced debugging scenarios, or if you’re testing against a passive remote system which is unable to process data and deliver data in the XML format required by Dynamicweb.

This example will find a product by product number:

XML
<?xml version="1.0" encoding="utf-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" exclude-result-prefixes="msxsl"> <xsl:output method="xml" indent="yes"/> <xsl:template match="/"> <XML> <xsl:apply-templates select="//item[column[@columnName='ProductNumber']='D0005']"/> </XML> </xsl:template> <xsl:template match="item"> <xsl:copy-of select="."/> </xsl:template> </xsl:stylesheet>

The transformed response is shown on the Transformed Response tab.

The DynamicwebConnectorService is a web service, which functions as the bridge between the Dynamicweb solution and the ERP system. It must be installed on the DMZ/Perimeter network of your environment. It handles data encryption and decryption, and is also an extensibility point when developing a custom integration to a system for which we don’t deliver a standard plugin.

The install process will 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 Dynamicweb Connector service:

  • Download the DynamicwebConnectorService files from our downloads area – you must be logged in to access the files
  • Right click on theZIP file, then select properties > unblock
  • 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
  • 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 Dynamicweb solution.

Once the service has been installed, you must open and edit the DynamicwebConnectorService.exe.config file, which can be found in the DynamicwebConnectorService folder.

XML
<?xml version="1.0" encoding="utf-8"?> <configuration> <configSections> <section name="D365Connector" type="System.Configuration.NameValueSectionHandler" /> <section name="NavConnector" type="System.Configuration.NameValueSectionHandler" /> <section name="AxConnector" type="System.Configuration.NameValueSectionHandler" /> <section name="CrmConnector" type="System.Configuration.NameValueSectionHandler" /> <section name="PerfionConnector" type="System.Configuration.NameValueSectionHandler" /> </configSections> <D365Connector> <add key="D365Url" value="" /> <add key="ActiveDirectoryResource" value="" /> <add key="ActiveDirectoryTenant" value="" /> <add key="ActiveDirectoryClientAppId" value="" /> <add key="ActiveDirectoryClientAppSecret" value="" /> <add key="CompanyName" value="" /> </D365Connector> <NavConnector> <add key="UserName" value="" /> <add key="Password" value="" /> <add key="Domain" value="" /> <add key="NavEndpoint" value="" /> <!-- 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="AxVersion" value="2012" /> <add key="BindingType" value="BasicHttpBinding" /> <add key="CompanyName" value="" /> <add key="UserName" value="" /> <add key="Password" value="" /> <add key="Domain" value="" /> <add key="AxEndpoint" value="" /> </AxConnector> <CrmConnector> <add key="CrmEndpoint" value="" /> </CrmConnector> <PerfionConnector> <add key="PerfionEndpoint" value="" /> </PerfionConnector> <appSettings> <add key="ServiceName" value="DynamicwebService" /> <add key="TestMode" value="False" /> <add key="TestOutputFile" value="c:\Test.xml" /> <add key="TestOutputFolder" value="c:\TestFiles" /> <add key="Secret" value="" /> <add key="DebugInfo" value="True" /> <add key="WebserviceURI" value="" /> <add key="ConnectorType" value="Dynamicweb.Ecommerce.Integration.Connectors.Ax.AxConnector" /> </appSettings> </configuration>

The config-file consists of:

  • A <configSections> element which specifies configuration sections and handler declarations
  • A number of Connector sections – e.g. <D365Connector> – which contain setting for a particular remote system
  • An <appSettings> section which contains configuration settings for the service itself

The Connector appSettings are as follows:

Name

Required

Default Value

Note

ServiceName

 

DynamicwebService

A valid name for a windows service, e.g. “DynamicwebService”.

Use this to provide a unique name for the service, in case that you have multiple services running on the same machine.

TestMode

 

False

True | False

Enables test mode when set to “True”

TestOutputFile

 

 

Full path to a file, e.g. “C:\TestFolder\TestFile.xml”

This file will be returned as response when test mode is enabled.

TestOutputFolder

 

 

Full path to a directory, e.g. “C:\TestFolder\”

Files in this folder will be returned as responses when test mode is enabled.

Secret

X

 

A secret key which is used for encrypting and decrypting responses from the service.

DebugInfo

 

False

True | False

Includes exception details in responses from the service when set to “True”

WebserviceURI

X

 

A valid URL, e.g. “http://localhost:8090/DynamicwebService”

ConnectorType

X

 

Full name of a connector type, e.g. “Dynamicweb.Ecommerce.Integration.Connectors.D365.D365Connector”

In addition to any settings, you must edit the Connector section for the remote system you want to connect to. Each Connector section is described in detail below.

When TestMode is set to true in the configuration XML, the connector service can be used to mock responses from the remote system. This is very useful when you have a pretty good idea about the data you will eventually receive, but the connection between the Dynamicweb solution and the remote system is not yet open.

When TestMode is true, you can specify which testfile you want to return for a request in the request XML:

XML
<GetEcomData TestFile=”GetCurrencies.xml”> <tables> <Currencies type="all"/> </tables> </GetEcomData>

The structure and contents of the testfile should be as close to the structure and contents you eventually expect to receive from the remote system, whether it has been mocked or consists of actual sample data.

Connectors are add-ins which connect to the plugin installed on a particular remote system – e.g. AX2012 or D365. They are used by both the Dynamicweb Connector Service and the Dynamicweb Connector TestTool, as outlined above.

Each Connector contains a number of settings, which are used to e.g. authenticate the request for data or trigger a particular behavior from the remote plugin.

See more under each Connector below.

The Connector settings for the AxConnector are:

Name

Required

Default Value

Note

AxVersion

 

2009

2009 | 2012 (Version of AX).

AxEndpoint

x

 

URL to the AX webservice

BindingType

 

WSHttpBinding

BasicHttpBinding | WSHttpBinding
Specifies the binding type to use for the webservice communication

CompanyName

 

 

A company (data area id) registered in AX, e.g. “DAT”. If nothing is specified then AX will use the default area id associated with the authenticated user.

UserName

x

 

Username used for Active Directory authentication

Password

x

 

Password used for Active Directory authentication

Domain

x

 

Domain used for Active Directory authentication

A configured AxConnector could look like this:

XML
<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <section name="AxConnector" type="System.Configuration.NameValueSectionHandler"/> </configSections> <AxConnector> <add key="AxVersion" value="2012" /> <add key="AxEndpoint" value="http://server:8080/MicrosoftDynamicsAXAif60/DWServicePort/xppservice.svc"/> <add key="BindingType" value="BasicHttpBinding" /> <add key="CompanyName" value="DAT" /> <add key="UserName" value="******"/> <add key="Password" value="******" /> <add key="Domain" value="COMPANY-DOMAIN"/> </AxConnector> </configuration>

The Connector settings for the D365Connector are:

Name

Required

Default Value

Note

D365Url

x

 

URL to an installation of Dynamics 365 for Finance and Operations

ActiveDirectoryResource

x

 

A resource identifier used for Azure Active Directory authentication

ActiveDirectoryTenant

x

 

A tenant (company) identifier used for Active Directory authentication

ActiveDirectoryClientAppId

x

 

An application identifier used for Active Directory authentication

ActiveDirectoryClientAppSecret

x

 

An application secret used for Active Directory authentication

CompanyName

 

 

A company (data area id) registered in Dynamics 365, e.g. “DAT”. If nothing is specified then Dynamics 365 will use the default area id associated with the authenticated user.

A configured D365Connector could look like this:

XML
<?xml version="1.0" encoding="utf-8"?> <configuration> <configSections> <section name="D365Connector" type="System.Configuration.NameValueSectionHandler" /> </configSections> <D365Connector> <add key="D365Url" value="https://***devaos.cloudax.dynamics.com/"/> <add key="ActiveDirectoryResource" value="https://***devaos.cloudax.dynamics.com" /> <add key="ActiveDirectoryTenant" value="https://login.windows.net/***.onmicrosoft.com" /> <add key="ActiveDirectoryClientAppId" value="********-****-****-****-************" /> <add key="ActiveDirectoryClientAppSecret" value="************************" /> <add key="CompanyName" value="" /> </D365Connector> </configuration>

If you follow the recommended project process, this phase contains two deliveries:

  • For each feature in the integration, use the TestTool to construct a request which extracts the appropriate data from the remote system – then deliver the request and an XML file with the response to the Dynamicweb side of the integration

This will allow them to create the initial import jobs and consider implementation strategies against real data – a step which is crucial to a successful integration project.

Then, after installing and configuring the Dynamicweb Connector Service, deliver the following to the Dynamicweb side:

  • The secret (encryption key) from the Dynamicweb Connector service configuration file
  • The endpoint of the web service exposed by the Dynamicweb Connector service

This will allow them to set up and schedule proper import jobs with real data from the remote system - a prerequisite for moving on to the final phase of the integration project. Depending on the complexity of the integration and the quality of data, the final phase may require significant ressources on both sides of the integration.

It is critical to the quality of the final product that you establish effective workflows and communication channels early in the process to avoid downtime and endless start-stop cycles.