ClickDimensions requires that data be synchronized in two directions between the customer’s on-premises Dynamics system and the ClickDimensions application which runs on Microsoft’s Azure cloud platform. For organizations whose security requirements prevent them from permitting connections to be initiated from external sources to their on-premises Dynamics deployments, ClickDimensions has developed the Service Bus Relay Connector (SBRC).
Goals
- Learn how to troubleshoot the SBRC
- Learn what information ClickDimensions support requires in order to assist with troubleshooting the SBRC
Table of Contents
- What is the SBRC?
- How do I get the SBRC?
- Troubleshooting the SBRC
- Requesting support
- Outbound Calls to ClickDimensions from Dynamics 365
What is the SBRC?
The SBRC is a small application that must be installed on a server within the customer’s network. It runs as a Windows service which serves as a proxy relay, calling out to Microsoft’s Azure Service Bus and accepting responses back to carry requests and data for processing in Dynamics.
How do I get the SBRC?
Inquiries regarding the SBRC should be directed to your organization's ClickDimensions Partner Account Manager.
Troubleshooting the SBRC
If the SBRC service is not running, users will encounter error messages indicating that a relay has not been established. In many cases, restarting the ClickDimensions Azure Proxy service should re-enable the SBRC to establish the relay after 2-5 minutes.
The vast majority of issues encountered when using the SBRC are due to the firewall, proxy or other network issues that block the SBRC from communicating out to Microsoft's Azure Service Bus and therefore preventing the relay from being established.
NOTE: SBRC Services are restarting. The SBRC services will restart about every 12 hours in order to obtain a new token from Azure Service Bus. If a user accesses a feature during this time, they will receive an error. If this is the case the error should clear on its own within 10 minutes.
NOTE: Before contacting ClickDimensions support, follow each of the steps outlined below to troubleshoot the installation and operation of the SBRC. Remember to re-start the ClickDimensions Azure Proxy Windows service in the services control panel after any change you make during troubleshooting.
NOTE: For customers using the SBRC, If you encounter an error in a ClickDimensions iFrame or window containing the message ClickDimensions cannot connect to your CRM, be sure to click View Full Error to see more information about the cause of the error.
Ensure that all prerequisites are met
- WIF and .NET 4.6.1 are installed on the SBRC server
- Ports 443, 5671, 5672 and 9350-9354 are permitted out to the internet from the SBRC server
- The Dynamics CRM URL and unique organization name that were registered with
ClickDimensions are correct and have not changed - The username and password for the Dynamics user provided to ClickDimensions works. Please ensure that you can log into Dynamics at the same URL and with the same credentials provided to ClickDimensions from the SBRC server.
Check the relevant logs
- Check the logs in C:\Logs for details on the installation attempt or service execution
- If an error is encountered during installation, make sure Antivirus software is temporarily
disabled during the installation and try again. - Check the Application Log in Event Viewer on the server where the SBRC is installed. Resolve any errors listed there.
NOTE: SBRC logs are only kept for the past 3 days.
Communication errors (the SBRC is blocked from reaching out to the Azure Service Bus)
Common communication errors are:
- There was no endpoint listening at <ClickDimensions relay address at servicebus.windows.net>
that could accept the message. This is often caused by an incorrect address or SOAP action - 50200: Bad Gateway, Resource:sb://<ClickDimensions relay address at servicebus.windows.net>...
- 50200: None of the connected listeners accepted the connection within the allowed timeout.
Communication errors are often caused by one or more of the following:
- Firewall does not permit communication outbound on ports 9350-9354 or ports 5671 and 5672. Check the local firewall on the server where the SBRC is installed as well as the corporate firewall on the network to ensure they permit outbound calls to the internet on these ports. Use TCPView from Microsoft to see if the ClickDimensions Azure Relay is communicating on ports 9350-9354 and 5671/5672. If it is not shown in TCPView, then the firewall or something else on the network is blocking communication.
- Proxy is not permitting the SBRC through to the internet. If your network requires internet connections to go through a proxy, the SBRC must be permitted to communicate through the proxy as well. By default, the SBRC's Windows service is installed under a local system account. Your proxy may require that you run the service under a domain account, or that the machine be permitted to pass through the proxy. There is no proxy configuration setting in the SBRC config. Depending on your environment and the proxy applications being used, this may mean installing a proxy client application or configuring the server via Internet Explorer’s connection settings to use the proxy. Consult with your network administrator for details on how applications can be permitted to use your proxy.
- Certificate errors: You may find the errors below in the C:\Logs file or similar certificate errors in the Windows Server CAPI2 logging (if enabled). Certificate errors are often due to missing certificate validation chains on the Windows Server being used for the SBRC, or if the server is not current on Windows Updates, or if you maintain an internal certificate server or certificate revocation list.
NOTE: The SBRC communicates with Microsoft, so the certificates involved are Microsoft’s certificates which your environment should be configured to trust.
Examples of certificate errors:
- SecurityNegotiationException: The X.509 certificate CN=servicebus.windows.net is not in
the trusted people store. The X.509 certificate CN=servicebus.windows.net chain
buildfailed. The certificate that was used has a trust chain that cannot be verified.
Replace the certificate or change the certificateValidationMode. A certificate chain
could not be built to a trusted root authority. - The token provider was unable to provide a security token while accessing '[access URL]'. Token provider
returned message: 'The request was aborted: The request was canceled.'.
You can get additional information on certificate errors by enabling CAPI2 logging on the SBRC
server:
- From the Start menu, type “MMC” to open an MMC snap-in.
- From the MMC “File” menu, select “Add/Remove Snap In”.
- Add the “Event Viewer” snap in for “Local Computer”
- In the Event Viewer, navigate to Event Viewer (Local)\Applications and ServiceLogs\Microsoft\Windows\CAPI2\Operational
- Enable the logging
Accessing the Azure Service Bus endpoint
Make sure you can browse in Internet Explorer from the SBRC server to the Azure Service Bus (there should be no errors or certificate warnings in Internet Explorer) for the appropriate URL:
- US: https://clickdimensionsrelay.servicebus.windows.net
- EU: https://clickdimensionsrelayeu.servicebus.windows.net
- AU: https://clickdimensionsrelayau.servicebus.windows.net
- CAN: https://clickdimensionsrelayca.servicebus.windows.net
The result should appear in your browser similar to an RSS feed:
Service User credentials or Dynamics 365 security role issues
The error “Object Reference not set to an instance of an object” can result if the wrong Dynamics user was provided to ClickDimensions when requesting the SBRC. This user must be an enabled Dynamics user with the ClickDimensions Service security role. Be certain that you can log into Dynamics from the SBRC server using the service user credentials that were configured for the account.
Miscellaneous
If a relay listener seems to be established and verified by ClickDimensions, but the communication is still showing errors, you can test whether the correct TCP ports and communication are being permitted on your network by temporarily adding a config key that forces traffic over HTTPS instead of TCP. This should just be used for testing and to reveal if TCP is still being blocked on your network. In the ClickDimensions.Proxy.WindowsService.exe.config file, add the following key in the <appSettings> node:
<appSettings>
<add key="Microsoft.ServiceBus.OverrideAutoDetectMode" value="Https" />
</appSettings>
NOTE: Always re-start the ClickDimensions Azure Proxy service on the SBRC server after any configuration changes.
Requesting Support from ClickDimensions
If the above steps do not resolve the errors, collect the following prior to opening a support ticket:
- Copy the error text (or capture a screenshot)
- Screenshot of TCPView showing that the correct ports are established
- Contents of C:\Logs-Copies of relevant errors from the application log and/or CAPI2 logs on the SBRC server
- Screenshot showing ability to log into Dynamics from SBRC server
- Screenshot showing ability to browse to Azure Service Bus endpoint from SBRC server
Provide the above information in a support ticket by opening a request at http://support.clickdimensions.com. Include the keyword “SBRC” in the subject line and attach any relevant log files, screenshots and/or error messages.
Outbound Calls to ClickDimensions from Dynamics 365
Users can take actions within Dynamics that will request a web page from the ClickDimensions cloud service, for example, and this request does not pass through the proxy relay service. In this scenario, the user would need to be able to access the internet from his or her browser. When an outbound request such as this is made, the SBRC does play a role in that it handles authenticating the user’s request in order to provide access to the requested page.
Another example of an outbound call from Dynamics would be a plugin firing on the Dynamics platform server, which would post data to the ClickDimensions web service. Since this would be initiated from within Dynamics, the Dynamics server would need to be able to call out directly to the ClickDimensions web services.
Communication from the Dynamics server or client machines(NOT the SBRC Server), out to ClickDimensions, can be restricted to the IP addresses for the ClickDimensions application that are listed here:
https://support.clickdimensions.com/hc/en-us/articles/115001155093/
NOTE: The SBRC server should not be limited to the IP addresses listed above. It will need to communicate with the internet across ports 443, 9350-9354, 5671 and 5672. These ports carry encrypted traffic between the SBRC and Microsoft’s Azure Service Bus. Microsoft’s Azure Service Bus uses dynamic, changing IP addresses for load balancing, and this is not within the control of ClickDimensions.