Troubleshoot your connector setup

 

Applies To: Dynamics Marketing

Important

Microsoft Dynamics Marketing has been discontinued and is no longer available. All customer data related to this product has been permanently deleted from all Microsoft servers and is no longer available for extraction. This documentation is being provided for historical purposes only.

This topic provides answers to frequently asked questions and general troubleshooting advice for the Microsoft Dynamics Marketing Connector for Microsoft Dynamics 365. For more information on initiating health checks and analyzing log files for errors, see Configure the SDK and Dynamics 365 Connector.

Solutions to common problems

If your connector is not working, or if you are seeing error or warning messages related to it, then review the following list of common problems to see if one of them might be affecting you.

The connector service is out of date

The connector service must be installed on your Microsoft Dynamics 365 server and must be up to date with both your Dynamics 365 and your Dynamics Marketing installations. Often, when you update one or both of these applications, you will also need to update your connector service and/or connector Dynamics 365 solution. If you are running Microsoft Dynamics 365 (online), then your connector service should always be installed and up to date with Dynamics 365, but if you are running Dynamics 365 (on-premises), then you must maintain the connector and Dynamics 365 installations yourself locally, which means your versions may be different at some point.

Dynamics Marketing automatically detects when your connector service requires an update, and pauses the synchronization. Please note that no data will be lost. After you update your connector, synchronization will resume as usual with no data loss.

When this issue occurs, you will see the following warning message in the Administration section of the Integration Options page (note that the required versions of both the connector service and connector Dynamics 365 solution are shown here).

If you see this warning, then go to the Dynamics Marketing download page to get the latest version of the connector installer and update your connector service as described in Update the Connector Service and Dynamics 365 Solution.

For more information about the Integration Options page, see Configure the SDK and Dynamics 365 Connector.

The connector solution for Dynamics 365 is missing

Dynamics 365 supports a concept called solutions, which enables administrators to apply add-ons to Dynamics 365. The connector uses this mechanism to enable communication with Dynamics Marketing. If the solution is missing, you will see the following warning message in the Administration section of the Integration Options page (note that the required versions of both the connector service and connector Dynamics 365 solution are shown here).

If you see this warning, then go to the Dynamics Marketing download page to get and install the latest version of the connector installer, then import the connector Dynamics 365 solution as described in Install the Connector.

For more information about the Integration Options page, see Configure the SDK and Dynamics 365 Connector.

The connector solution for Dynamics 365 is out of date

Dynamics 365 supports a concept called solutions, which enables administrators to apply add-ons to Dynamics 365. The connector uses this mechanism to enable communication with Dynamics Marketing. If the solution is out of date, then any Dynamics Marketing administrator will see the following banner when signing in.

If you see this, then click the link to go to the Integration Options page to get more information about the problem. Here you will see the following notice in the Administration section.

If you see this warning, then go to the Connector download page to get the latest version of the connector installer and update your connector Dynamics 365 solution as described in Update the Connector Service and Dynamics 365 Solution. Then, return to the Integration Options page in Dynamics Marketing and click the Restart button in the Services section to start the communication.

For more information about the Integration Options page, see Configure the SDK and Dynamics 365 Connector.

The user account running the connector solution for Dynamics 365 lacks required permissions

Although it is an automated system, the connector solution for Dynamics 365 must run under a Dynamics 365 user account with a security role that provides it with all of the necessary privileges to execute its functions. When you import the connector solution into Dynamics 365, a new security role called Dynamics Marketing Connector is created for this purpose. We recommend you set up a dedicated user account that has this and no other security roles for the exclusive purpose of running the connector solution (see also Install the Connector). During a standard sync operation, Dynamics Marketing will sign in to Dynamics 365 using this account; if the account is missing or lacks required permissions, the sync will fail. In this case, any Dynamics Marketing administrator will see the following banner when signing in to Dynamics Marketing.

If you see this, then click the link to go to the Integration Options page to get more information about the problem. Here you will see one of the following notices in the Administration section.

Do one of the following, depending on which error message you see on the Integration Options page:

• If the warning message says you need to import the connector solution for Dynamics 365, then go to the Dynamics Marketing download page to get and install the latest version of the connector installer, import the connector solution for Dynamics 365, and then set up a user account to run it as described in Install the Connector. Return to the Integration Options page in Dynamics Marketing, and then click the Restart button in the Services section to start the communication.

• If the warning message only asks you assign a security role for the connector user, then you do not need to import the connector solution; you just need to update the permissions for the user account that Dynamics Marketing is using to sign in and run the solution. Sign in to Dynamics 365, set up a dedicated Dynamics 365 user to run the connector solution (if you haven’t already), and make sure it has the Dynamics Marketing Connector security role. (See the Dynamics 365 help for details about how to set up users and assign roles.) When you are done, return to the Integration Options page in Dynamics Marketing and click the Restart button in the Services section to start the communication. More information:Install the Connector

The connector can’t connect to your Dynamics 365 instance

If Dynamics Marketing can’t connect to your Dynamics 365, but the connector has otherwise been working correctly until recently, then you may see the following warning message in the Administration section of the Integration Options page.

There are two reasons why this message could appear:

• Dynamics 365 is temporarily offline.

• The password for the connector user has expired. User passwords expire every three months, and this includes the user account being used to run the connector. When the password expires, Dynamics Marketing will no longer be able to communicate with Dynamics 365.

Follow these steps to determine which issue you are having, and then fix it:

1. Try to sign in to Dynamics 365. If the system is offline, then wait until it comes back and check the Administration section of the Integration Options page in Dynamics Marketing again to see if the connector is working. If so, then you are done and can skip the next steps.

2. If your Dynamics 365 instance is working correctly, then you probably need to update the password. Sign in to Dynamics 365 using the connector user account and respond to the request to update the password.

3. Sign in to Dynamics Marketing and go to Settings > Administration > Integration Options.

4. Click the Dynamics 365 Endpoint Configuration button at the top of the Dynamics 365 / Dynamics CRM Endpoint section to open the Configure Dynamics 365 account for access by the connector service dialog box.

5. Enter the new password in the Password field.

6. Click Verify to verify that the connection works. If the connection still fails, check your password settings and try again. On success, click Submit.

The connector certificate is missing for Dynamics 365 (on-premises)

A connector certificate is only required if you are integrating with Dynamics 365 (on-premises). The certificate authenticates the solution with Azure and enables secure communication over the Azure service bus.

Important

Your certificate must use SHA2 encryption (which includes SHA256, SHA384, and SHA512). SHA1 is no longer considered secure, so new SHA1 certificates will not be issued after January 1, 2016 (except for certain legacy applications); Windows will reject SHA1 certificates issued after this date. In addition, the certificate encryption provider must be either Microsoft Strong Cryptographic Provider or Microsoft Enhanced Cryptographic Provider. Microsoft Software Key Storage Provider is not supported. For the latest information about Microsoft’s certificate policies, see this TechNet article

To check whether you have the required certificate, sign in to Dynamics 365 and go to Settings > Customizations > Developer Resources. If you see a downloadable certificate with a valid Issuer Name under "Windows Azure Service Bus Issuer Certificate", then your certificate is already in place, so this is probably not your problem. If the certificate is missing, then do one of the following:

• Request a certificate from a server within your domain that has the Certification Authority role service using the "Create Domain Certificate" option in Internet Information Services Manager.

• Purchase a domain-level validation certificate from a trusted certificate issuing authority.

When you have a certificate, install it as described in Prepare Dynamics 365 (on-premises) for Azure.

Read privileges are missing for the connector certificate in Dynamics 365 (on-premises)

As mentioned in the previous section, a connector certificate is only required if are integrating with Dynamics 365 (on-premises).

If you have already obtained and installed the required certificate, but are still having trouble with the connector, check the following:

1. Sign in to Dynamics 365.

2. Go to Dynamics 365 > Settings > System Jobs and look for jobs stuck in the waiting state.

3. If you see many jobs in this state, then check the details for one of them. If the details include the line <Message>Keyset does not exist</Message>, then your Dynamics 365 Async Service is probably missing read privileges to the certificate.

To solve this issue, do the following:

1. Sign in as an admin on the server running the Dynamics 365 Asynchronous Processing Service.

2. Find out which user account is being used to run the Dynamics 365 Asynchronous Processing Service. You can do this by opening the Services console (for example by pressing the Windows key, typing “services”, and choosing “View Local Services” from the search results). Find the Asynchronous Processing Service in this list and note the value shown for Log On As. (You will need this again later near the end of this procedure.)

3. Open a Microsoft Management Console (MMC), for example by pressing the Windows key, typing “MMC”, and choosing the found “mmc.exe” file.

4. Click File > Add/Remove Snap-in.

5. In the Add or Remove Snap-ins window, click the Certificates button in the left pane, and then click Add.

6. The Certificates snap-in window opens. Click Computer Account, and then click Next. Click Local computer, and then click Finish to close the window.

7. Click OK in the Add or Remove Snap-ins window to finish adding the snap-in.

8. You will now see a Certificates (Local Computer) button in the left pane of the console. Expand this and click Certificates (Local Computer) > Personal > Certificates. You’ll now see a set of certificates in the right pane.

9. Right-click the certificate you imported into your Dynamics 365 instance, and then select All Tasks > Manage Private Keys. This opens the Permissions window.

10. Click Add in the Permissions window to open the Select Users, Computers, Service Accounts, or Groups window, and then use those controls to add the account running the Dynamics 365 Asynchronous Processing Service that you found earlier in this procedure.

11. Click OK in each of the open console windows to apply your settings.

Multiple Dynamics 365 instances are connected to the same Dynamics Marketing instance

Dynamics Marketing supports at most one connected Dynamics 365 instance. However, situations can arise in which more than one Dynamics 365 instance attempts to connect to a single Dynamics Marketing instance (such as after moving from a test to production environment). To protect against this, the Integration Option settings in Dynamics Marketing require you to specify a single Dynamics 365 instance from which to accept connections. If a second Dynamics 365 instance attempts to connect, you will see the following warning in the Administration section of the Settings > Administration > Integration Options page in Dynamics Marketing.

The warning message remains in place for three hours after the last connection attempt, which means that after you fix this problem you might need to wait up to three hours before this warning goes away.

If you see this warning, don’t worry; your data is safe. No incoming data from the secondary system will be accepted, so no duplicate or test data will enter Dynamics Marketing or get replicated in your current Dynamics 365 instance. Still, you should fix the problem right away.

The warning message shows the domain name of the extra Dynamics 365instance that is attempting to connect. Sign in to the specified Dynamics 365 instance and disable its SDK plug-in to stop it from trying to contact your Dynamics Marketing instance.

Note

This same warning can sometimes appear because you have entered an incorrect Service URL for Dynamics 365 (rather than because you have multiple instances).

When this problem occurs, you'll notice that the Site Company Integration Settings page shows a warning about multiple instances that includes the expected URL but also shows a Service URL that contains an extra .api subdomain, which you need to remove.

The extra .api subdomain might have been included because one way to find the Service URL is to open Dynamics 365, go to Settings > Customizations > Developer Resources, and copy the value shown there. But that value typically looks something like https://contoso.api.crm.dynamics.com. Fix it by removing .api to create a URL in the form https://contoso.crm.dynamics.com.

More information: Enable and configure the connector

Unable to delete an installed connector solution for Dynamics 365

You can’t delete an installed connector solution through a Dynamics 365 instance if there are references to the fields introduced by the solution from your forms. Before you delete a solution, first remove all the dependencies to the fields that are introduced by the installed Dynamics 365. More information: View or edit default solution components

Service integration issuer certificate not found

If Dynamics Marketing is not synchronizing anything with your Dynamics 365 (on-premises) installation, then check your system jobs in Dynamics 365. If you see a large number of pending/failed jobs showing the message “Service integration issuer certificate not found,” then you may have multiple certificates with the same subject value on your Dynamics 365 (on-premises) server.

Check the certificate store on your Dynamics 365 server to see if you have any other certificates with the same subject value as the one you are using to authenticate your Dynamics 365 installation with Azure. If you do, then resolve the issue either by generating a new certificate with a unique subject value, or by removing the duplicate certificate if you are sure it is not being used for any other purpose. For more information about how to configure the solution to use a new certificate, see Prepare Dynamics 365 (on-premises) for Azure.

Records don't sync correctly when using custom Dynamics 365 workflows or plugins

Some types of custom Dynamics 365 workflows can interfere with the connector if they result in changing ownership of incoming records or make some other type of change that removes the ability of the connector to create, update, and/or delete records. As a result, some records may fail to sync to Dynamics 365, or may sync with some fields left empty (such as the name for a lead record). This issue only occurs when using certain types of custom Dynamics 365 workflows or plugins, and only affect records travelling from Dynamics Marketing to Dynamics 365 (not the other way).

The solution is to add the required access privileges to the Dynamics Marketing Connector security role in Dynamics 365.

To find out if you are having this issue, and to see which privileges you need to add, do one of the following:

• If you are using Microsoft Dynamics 365 (online)
  Open Dynamics Marketing, go to Settings > Administrator > Integration Options, and then download the connector log. Inspect the log for entries related to privilege issues. The log entries should specify which privilege is missing.

• If you are using Dynamics 365 (on-premises)
  Open the Windows Event Viewer on the server where you are hosting Dynamics 365. Inspect the log for entries related to privilege issues. The log entries should specify which privilege is missing.

When you know which privileges you need, edit the Dynamics Marketing Connector security role settings in Dynamics 365 and grant the required permissions.

Companies with large code values do not sync to Dynamics 365

In a default connector setup, the code field for companies in Dynamics Marketing maps to the Account.accountnumber field in Dynamics 365. By default, the Dynamics 365Account.accountnumber field is limited to 20 characters or fewer, while the Dynamics Marketing company code can be up to 70 characters. With these default settings, if you create a company in Dynamics Marketing and specify a code with more than 20 characters, then that company will be rejected by Dynamics 365 and will not be synced. If you need to use company codes (account numbers) with more than 20 characters, then edit your Dynamics 365 setup to allow the required number of characters (up to 70) for the Account.accountnumber field. See Create or edit entity fields in the Dynamics 365 online help for instructions. Another possible solution for this issue is to map the company code in Dynamics Marketing to a different field in Dynamics 365 that is capable of holding the required number of characters.

Frequently asked questions

Here are answers to the questions most often heard by Microsoft Support in relation to the Microsoft Dynamics Marketing Connector for Microsoft Dynamics 365.

Will multiple executions of “Run Initial Synchronization” result in data duplication in one or both systems?

No. The initial synchronization function always merges data in both systems without creating any duplicates. You can safely run and re-run this operation at any time.

The regularly scheduled incremental updates take much less time than an initial sync, but every now and then you may need to re-run an initial sync (such as after adding a new field to your mapping).

Is it possible to synchronize a single Dynamics Marketing instance with multiple Dynamics 365 instances?

No. Only one connection is supported at a time. The only Dynamics 365 system that Dynamics Marketing will accept connections from is the one configured in the Dynamics 365 / Dynamics CRM Endpoint section of the Settings > Administration > Integration Options page for your Dynamics Marketing instance. All the data coming from any other Dynamics 365 instance will be ignored.

If you install the connector on a second Dynamics 365 instance and try to configure it to connect to an already-occupied Dynamics Marketing instance, you will see a warning in the Administration section of the Settings > Administration > Integration Options page in Dynamics Marketing.

Can I customize the set of fields and/or entities that are synchronized between Dynamics Marketing and Dynamics 365?

You can customize, add, or remove field mappings between any of the entities already managed by the connector. To do so, go to Settings > Administration > Integration Options in Dynamics Marketing and work with the settings in the Mapping section as described in Configure the SDK and Dynamics 365 Connector. However, you cannot customize the set of entities themselves as these are hard coded by the connector.

Your customized field mappings can include both user defined fields (UDFs) and custom contact fields (see also Configure user defined fields and Create custom contact fields for market segmentation).

Can the connector handle very large data sets?

The connector does not have a fixed limitation on how many records it can keep synchronized. However, very large databases (for example, with around 10 million records or more) may result in increasingly long synchronization times. If this is starting to be a problem for you, then contact Microsoft Support to request an increase in your processing throughput.

Can I set up the connector to communicate with Dynamics 365 (on-premises) via a proxy?

No. The connector does not support Internet access via proxy.

How can I set up the connector to communicate with Dynamics 365 (on-premises) via a firewall?

This is possible. You just need to configure your firewall exceptions to allow it. For details, see Internet accessible URLs required for connectivity to Microsoft Dynamics Marketing, Network ports for Microsoft Dynamics CRM, and Microsoft Azure Datacenter IP Ranges.

What does the connector installation package contain?

The connector setup program installs files in the following location:
C:\Program Files (x86)\Microsoft Dynamics Marketing\

For more information about the various files and folders installed here, see Install the Connector

Do I need to use the Configure Dynamics 365 Connector option after installing the connector?

When you run the connector installer, the last page of the install wizard includes a Configure Dynamics 365 Connector check box, which is selected by default.

If you click Finish with that check box selected, then you will launch the configuration wizard for Dynamics 365 (on-premises). If you are using Dynamics 365 (on-premises), then we strongly recommend you leave this check box selected and work through the wizard. However, if you are connecting to Microsoft Dynamics 365 (online), then clear this check box; the on-premises configuration wizard has no effect on Microsoft Dynamics 365 (online).

More information: Install the Connector

Why do new contacts from Dynamics Marketing appear as inactive contacts in Dynamics 365?

This is by design and is intended to prevent new marketing contacts not yet associated with a qualified (sales-ready) lead from cluttering views in Dynamics 365. When a lead achieves a sales-ready score in Dynamics Marketing, that lead record will be synchronized and its associated contact will be promoted to active status in Dynamics 365 (and remain there, even if the lead is lost or abandoned).

Why aren't our marketing lists syncing correctly?

The connector only synchronizes those lists that are explicitly marked for sync. Also, if some of your marketing lists contain a very large number of contacts, they may require extra time to synchronize completely. The following behaviors and settings can affect marketing list synchronization:

• Static lists created in Dynamics Marketing must have their Synchronize with Dynamics 365 checkbox selected to be synced with Dynamics 365. Lists with this box cleared are not synced. More information:List management and segmentation

• All marketing lists created in Dynamics 365 must be explicitly enabled for sync with Dynamics Marketing. When you import the connector solution into Dynamics 365, a new marketing-list field called "Sync Enabled" is created in the database, but it is not added to the marketing-list form by default. To make this field visible to Dynamics 365 users, you must edit the respective form(s), add the custom “Sync Enabled” field to it/them, and then save/publish the change. You must set this field to "Yes" for each marketing list you want to synchronize. More information:Add a field to a form

• Queries (dynamic lists) in Dynamics Marketing can't be synced to Dynamics 365.

• Dynamic lists created in Dynamics 365can be synced to make them available in Dynamics Marketing, but they appear as static lists in Dynamics Marketing and won't sync in the opposite direction.

• You might sometimes notice that newly-created lists take extra time to synchronize completely between the two systems. As a result, you might see that a new list appears empty or just partially full in the opposite system until the connector has had enough time to process all of the member contacts. After that the solution should work as expected.

• By default, the connector is configured to allow 10 minutes between list synchronizations. This value works well in most cases, but if you have especially long marketing lists then your connector queues may become clogged with list updates. This will not result in data loss, but it can impact the sync performance of all types of records. Take a look at your marketing lists and, if they together comprise a large number of contacts, try to increase the list sync interval using the connector mapping settings in Dynamics Marketing. More information:Configure the SDK and Dynamics 365 Connector

Why do some marketing lists show different membership counts in Dynamics Marketing and Dynamics 365?

Dynamics Marketing shows the total number of active contacts included in all synced (and non-synced) marketing lists. There are two reasons the membership count you see for a list in Dynamics Marketing might be different from what you see in Dynamics 365:

• In Dynamics Marketing, the member count for marketing lists only includes active contacts, not inactive contacts, while Dynamics 365 counts both active and inactive contacts. Both active and inactive contacts are synchronized between systems, and inactive contacts that belong to a synced marketing list also belong to that list in both systems. You can see inactive contacts in a Dynamics Marketing list by clicking on the Show/hide inactive button while viewing the list, but the member count still includes only the active contacts.

•  Dynamics Marketing updates the membership counts for very large marketing lists less frequently than it does for shorter lists. This can mean that you'll need to wait some time before seeing the updated membership count for especially large lists.

See Also

Connect Microsoft Dynamics Marketing to Dynamics 365
Connector deployment scenarios
Prepare Dynamics 365 (on-premises) for Azure
Install the Connector
Enable and configure the connector
Configure Azure Service Bus settings
Install the seller portal for Dynamics 365
Connector entity mapping
Update the Connector Service and Dynamics 365 Solution
Configure the SDK and Dynamics 365 Connector