Dynamicweb Connector Service

The DynamicwebConnectorService is a web service, which functions as the bridge between the Dynamicweb solution and a remote system. It handles data encryption and decryption, and must be installed on the DMZ/Perimeter network so it can be reached by both the DW solution and the remote system. It also functions as an extensibility point if you are developing a custom integration with 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.

The ConnectorService and the TestTool

The Dynamicweb Connector Service is strongly linked to the Dynamicweb Connector TestTool, which is a tool used to test requests and responses from the web services exposed by the remote system plugins or by the Connector Service itself.

Most importantly, the configuration file used by the test tool is identical to the one used by the Connector Service, which makes it easy to test out different config section setups and deploy them from test tool to the connector service directly.

To use the connector service you must open and edit the DynamicwebConnectorService.exe.config file, which contains the settings necessary to connect to remote systems. It can be found in the DynamicwebConnectorService folder and contains:

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

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.

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 D365Connector is used to connect to a D365 FO installation - the settings 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.

ActiveDirectoryValidateTenant x true If Cloud Deployment set to true - if On-premise set to false

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="" /> <!-- If Cloud Deployment set ActiveDirectoryValidateTenant to true. If On-premise set ActiveDirectoryValidateTenant to false --> <add key="ActiveDirectoryValidateTenant" value="true" /> </D365Connector> </configuration>

The NavConnector is used to connect to older Dynamics Nav versions, as well as more recent D365 Business Central installations – the settings are:

Name

Required

Default value

Notes

UserName

X

 

 

Password

X

 

 

Domain

X

 

 

NavEndpoint

X

 

 

IgnoreCertificateWarnings

 

 

Set to true for https endpoints using self-signed or untrusted certificates. Useful for testing, but should be avoided in production.

ClientCredentialType

 

 

Valid options are; Default, Ntlm, Windows, Basic

A configured NavConnector section could look like this:

XML
<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <section name="NavConnector" type="System.Configuration.NameValueSectionHandler"/> </configSections> <NavConnector> <add key="UserName" value="navconnector"/> <add key="Password" value="xxxxx1.2"/> <add key="Domain" value="dynamic-systems"/> <add key="NavEndpoint" value="http://dwis-NAVBC.Dynamic-Systems.lan:7047/DynamicsNAV130/WS/CRONUS%20Danmark%20A%2FS/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> </configuration>

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.

If you need SSL/HTTP on the ConnectorService:

  • Please follow the steps in this guide until you reach the section called ‘The WCF Service’
  • Download these batch files for creating SSL certificates – but you should check if the paths to the commands are correct, and use your own GUID for your created SSL certificate
  • The zip also includes the httpcfg.exe utility for SSL setup which can sometimes be missing from a machine

After installing the SSL certificate you must open the DynamicwebService configuration file (DynamicwebConnectorService.exe.config) and fix the key="WebserviceURI" value to use SSL(it must start with "https") for example value="https://localhost:8090/DynamicwebService". Then restart the DynamicwebService windows service from Computer -> Management -> Services.

If you want to stop using SSL you need to change the "https" to "http" for "WebserviceURI" and restart the DynamicwebService windows service.