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.6.2 or greater
• Install the service from the command prompt using installUtil.exe, with the following command: 

• Go to Control Panel > Administrative tools > Services and start the service called DynamicwebService

This exposes the web service to the Dynamicweb solution.

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:

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

ConnectorType full names:

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:

A configured AxConnector could look like this:

The D365Connector is used to connect to a D365 F&O installation - the settings are:

A configured D365Connector could look like this:

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

A configured NavConnector section could look like this:

With version 2.1.0 of the DynamicwebConnectorService it is possible to authorize access to the plug-in unit of a cloud hosted Business Central instance via the OAuth 2.0 protocol.

To set up OAuth 2.0 in the ConnectorService you must go through the following steps:

• Downloading version 2.1.0 or a newer version of the DynamicwebConnectorService
• Downloading version 2.4.0 or a newer version of the DynamicwebConnectorTestTool
• Installing the TestTool and using it to obtain an access token
• Installing the ConnectorService and inserting the TenantID, CientID og ClientSecret from your Microsoft Azure Portal
• Copying the obtained access token from the TestTool to the ConnectorService directory

OAuth 2.0 access tokens are encrypted to be client and server specific, which means that a working access token can only be shared across multiple applications on the same server with the same client. This means that if your ConnectorService and Dynamicweb solution is hosted on the same server, you can use the endpoint management tool in Dynamicweb to obtain an access token also usable in the ConnectorService, but as this is not necessartily the case, it is also possible to use the DynamicwebConnectorTestTool for the purpose.

To obtain an access token through the TestTool, run the application and follow these steps:

• Choose connection type OAuth 2.0 (A)
• Paste the URL of the plug in unit web service (B)
• Check the "Connects to standard Dynamicweb codeunit service" box (C) 
• Enter the TenantId, ClientID and Client Secret from your Microsoft Azure portal (D). Our guide to setting up OAuth 2.0 for Business Central might be helpful, if you are not yet familiar with that process
• Make sure you have http://localhost configured as a redicret URI in your Azure portal app registration
• Enter a request - you can choose a simple request from the code examples in the dropdown in the top left corner (E)
• Run test (F)
• Use your credentials to log in to the prompted Microsoft log in pop-up. Please beware that your browser may block the pop-up initially
• Upon succesful log in, a message in the TestTool should appear, stating that the Access Token was recieved. 

After an access token has been successfully recieved, open the .exe config file of you ConnectorService application and set the ClientCredentialType property to "OAuth" as shown in the example below. Then enter the same values from Azure portal as was used in the TestTool in the corresponding properties. 

To copy the access token from the TestTool to the ConnectorService, locate the folder entitled EndpointManagement in the directory of your TestTool and copy the entire folder to the ConnectorService directory. If your access token was successfully recieved earlier on, it should be located as a BIN3 file in this exact folder.

Afterwards, you might need to stop and start the Connector service application for it to use the OAuth 2.0 token.

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:

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.