Install the Connector

Article
05/15/2018
13 minutes to read

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 guides you through downloading the Microsoft Dynamics Marketing Connector for Microsoft Dynamics 365 and importing the connector solution into Dynamics 365.

Important

This topic describes how to download and import the connector solution for the first time. If you are updating from an older version of the connector, go to Update the Connector Service and Dynamics 365 Solution instead.

In this topic

On-page link button Prerequisites

On-page link button ** **Download and run the connector setup program

On-page link button What gets installed where

On-page link button ** **Import the connector solution into Dynamics 365 and prepare it for use

On-page link button Finish setting up Dynamics 365 (on-premises)

Spacing image On-page link button ** **Run the Dynamics 365 (on-premises) configuration wizard and start the service

Spacing image On-page link button Enable Internet access for the asynchronous service

On-page link button ** **Next steps

Prerequisites

The Microsoft Dynamics Marketing Connector requires, at a minimum, that Microsoft Dynamics CRM 2011 Update Rollup 12 be installed for an on-premises deployment or that you have Microsoft Dynamics CRM December 2012 Service Update or later for an online deployment.
You must be able to sign in to Microsoft Dynamics 365 with an account that has the System Administrator security role.
If you are integrating with Dynamics 365 (on-premises), then you must sign in to the Dynamics 365 server as a Windows user with administrator privileges. The connector service will also run under this user account after you install it.
If you are integrating with Dynamics 365 (on-premises), then you must prepare your Dynamics 365 instance an collect some information about it as described in Prepare Dynamics 365 (on-premises) for Azure before you install the connector.

Download and run the connector setup program

The connector setup program is an MSI file that installs and registers the software on the computer where you run it. The setup program gets you started, but it's just the first step; after you run it you must work with the files it installs and configure the solution as described in this and the other referenced topics of this online help.

To download and install the connector setup program:

Sign in on the computer where you want to download and install the connector. This may depend on which version of Dynamics 365 you are integrating with.
- If you are integrating with Dynamics 365 (on-premises), then you must sign in to Windows on the computer where Dynamics 365 is installed using an account with administrator privileges. This account will also be the one where the connector service will be running after you install it.
- If you are integrating with Dynamics 365 (online), then run the setup program on any computer where you can access your Dynamics Marketing and Dynamics 365 applications. For Dynamics 365 (online), all you will need is the connector solution for Dynamics 365, which is included with the setup program.
Go to the Dynamics Marketing download page to get the latest version of the connector and other add-on software. Several versions may be available on the download page. Be sure to pick the version that matches your version of Dynamics Marketing.
When the download is complete, run the setup program for your version of Dynamics Marketing to launch the setup wizard.
The setup wizard is very simple. It provides just a few pages that ask you to confirm the license agreement, choose which components to install, and choose a destination folder. You should choose to install all of the components. The last page of the wizard includes a check box labeled Configure Dynamics 365 Connector (Dynamics 365 On Premise Only).

Do one of the following:
- If you are integrating with Dynamics 365 (on-premises), and are working on your Dynamics 365 server as recommended at the start of this procedure, then select the Configure Dynamics 365 Connector check box and click Finish. A new setup wizard launches to help you configure Dynamics 365 (on-premises) for the connector. However, before you continue with that wizard, you should import the connector solution into your Dynamics 365 instance. Instructions for importing the solution and for working through the configuration wizard afterwards are given later in this topic.
- If you are integrating with Dynamics 365 (online), then clear the check box and click Finish.
Import the connector solution into your Dynamics 365 instance as described in Import the connector solution into Dynamics 365 and prepare it for use, later in this topic. (Applies for both Dynamics 365 (on-premises) and Dynamics 365 (online).)

What gets installed where

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

This folder might also include add-ons and other software for Dynamics Marketing that are not part of the connector. The following table describes each folder that is created here by the connector setup program. For more information about the role of each component listed in the table, see Connector deployment scenarios.

Subfolder	Description
CRMConnectorService	Contains registered files that create a Windows service for the connector on the system where it is installed. These are only used by Dynamics 365 (on-premises). Dynamics 365 (online) does not need them.
CRMConnectorService\ DataIntegrationConfigurationWizard	Contains the configuration wizard for Dynamics 365 (on-premises) and its support files. The configuration wizard is only used by Dynamics 365 (on-premises). Dynamics 365 (online) does not need it.
LicensingTerms	Contains licensing terms for the connector and other Dynamics Marketing products in each of several languages.
Solutions\ CRMConnector	Contains one or more versions of the solution that must be imported into Dynamics 365 to enable the connector. Each of these is a ZIP file named to indicate the Dynamics 365 version(s) supported. Both Dynamics 365 (on-premises) and Dynamics 365 (online) require this component.
Solutions\ SellerPortal	Contains one or more versions of the solution that must be imported into Dynamics 365 to enable the seller portal. Each of these is a ZIP file named to indicate the Dynamics 365 version(s) supported This component is optional, but is recommended for both Dynamics 365 (on-premises) and Dynamics 365 (online).

Import the connector solution into Dynamics 365 and prepare it for use

A connector Dynamics 365 solution is required for both Dynamics 365 (online) and Dynamics 365 (on-premises), and the procedure for importing it is the same for both types of systems.

To import the connector solution into Microsoft Dynamics 365:

Sign in to Microsoft Dynamics 365 as a system administrator.
Go to Home > Settings > Administration > Solutions.
Temporarily turn off the pop-up blocker in your web browser if it is currently turned on. You can turn it back on after this procedure is completed.
Click Import to open the Import Solution dialog, and then click Browse to open a file browser.

Go to the Dynamics 365 solutions folder created by the connector setup program (mentioned previously). This folder may contain several ZIP files, each named for a specific verison (or versions) of Dynamics 365. Choose the file named for the version of Dynamics 365 that you are running.
After choosing a file, you return to the Select Solution Package page. Click Next to load you selected file.
The Solution Information page of the Import Solution dialog opens. Click Import.
The solution is now imported. When it is done, the Import Solution dialog shows the result of the import operation. This summary will almost always include a few notices and minor warnings, but you can safely ignore these.

Click Close. The connector solution is now installed and can be seen in the Solutions list.
Create a new Dynamics 365 user and give it the new Dynamics Marketing Connector security role, which came with the solution. Dynamics Marketing will use this account when connecting to Dynamics 365. Make a note of the user name and password that you create for this purpose, as you will need these later when setting up the connector in Dynamics Marketing.
Though your connector setup is not yet complete, now might be a good time to consider which marketing lists you want to sync between the two systems (you could also do this later and change them at any time).
- Static lists created in Dynamics Marketing must have their Synchronize with Dynamics 365 check box 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 marketinglist 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

Note

Re-enable document management settings for entities after importing the connector solution.

Finish setting up Dynamics 365 (on-premises)

If you are connecting with Dynamics 365 (on-premises), you need to finish setting up the connector Windows service and a few other settings. (If you are connecting with Dynamics 365 (online), then you can skip this section.)

Run the Dynamics 365 (on-premises) configuration wizard and start the service

Usually you run the Dynamics 365 (on-premises) configuration wizard automatically, right after you run the connector installer as described in the previous section. However, you can also run the configuration wizard by itself at any time by launching it from its install folder. See What gets installed where, earlier in this topic, for details about how to find it.

Note

When running this wizard, you must be signed in to Windows on the computer where Dynamics 365 is installed using an account with administrator privileges. The connector service will run under this account when you are done installing it .
The wizard starts with a welcome page.
Click Next to continue.

Choose one of the following:
- Add a new connector: if you are installing the connector for the first time, then choose this option. (You could also create an additional connector instance using this option.) Specify an Instance Name for the new instance in the field provided; choose a name that will be easy to identify later.
- Reconfigure an existing connector: Select this option if you want to update or reconfigure an existing connector. The Instance Name drop-down lists shows the name of each instance currently installed (typically, you'll have just one); choose the instance you want to update.
Click Next to continue.

Provide the User Name and Password for the Windows account that the connector Windows service should run under. Usually this should be the account you are already using to install and configure the connector.
Click Next to continue.

Enter the Service URL where your Dynamics 365 instance is running (this is the address you normally use to sign into Dynamics 365). Then enter the Connector Account (user name) and Password for the Dynamics 365 account that the connector should run as. This is the account that you should have created and assigned the Dynamics Marketing Connector security role to during the solution-import procedure described earlier in this topic.

Important

Be careful how you specify the Service URL. One way to find this value 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, which includes an extra subdomain (.api) that will be accepted by the configuration wizard but won't work with the connector. Fix it by removing the ".api" part to create a URL that looks like: https://contoso.crm.dynamics.com
Click Next to continue.

Make the following settings:
- Azure Authentication Mode: If this is shown, then leave it set to SAS. Other authentication modes (such as ACS) are no longer supported.
- Connector Service Path: Specify the path where you installed the connector executable. By default, it's located at: C:\Program Files (x86)\Microsoft Dynamics Marketing\CrmConnectorService\Microsoft.Dynamics.Marketing.DataIntegrationService.exe
Click Next to continue.

Make the following settings here:
- Service Bus Namespace: Enter the Azure Service Bus namespace that you set up to run the connector.
- Policy Name and Key: Enter these values from the connection string used by your Azure Service Bus namespace. More information: Prepare Dynamics 365 (on-premises) for Azure
- Queue from Dynamics 365 / Dynamics CRM and Queue from Dynamics Marketing: Enter a unique name for each of these two required queues. Each of these queues must be unique and not shared or used for any other purpose. Usually, you should invent two new queue names that don't already exist in your specified Azure Service Bus namespace; Dynamics Marketing will create the new queues later when you configure the connector. The names that you specify here must match the names that you will create later using Dynamics Marketing, so be sure to take a note of them.
  Important
  
  If you want to use existing queues rather than let Dynamics Marketing create them for you later (not recommended), then keep the following important points in mind:
  - Don't use queues that are also used by the SDK service because that will produce many errors, both during sync and SDK operations, and can result in data loss.
  - Your queues must be configured as follows: Recommended max size = 5GB; duplicate detection disabled; sessions disabled; partitioning disabled.
  - Don't set up authentication on the individual queues. Dynamics Marketing authenticates against the Azure Service Bus namespace and expects those credentials to be inherited by the queues it uses.
Click Next to continue.

Verify the details you provided, and then click Next to start configuring your system.
If the service is configured successfully, you’ll get a confirmation screen as shown here.

Click Close to close the wizard.
The connector service is installed but has not yet started. To start the service, go to Windows Services, right-click the connector service, and then click Start.

Enable Internet access for the asynchronous service

For Dynamics 365 (on-premises) to work with Microsoft Azure Service Bus, the Dynamics 365 asynchronous service must have access to the Internet through the server’s firewall.

The server where you installed the asynchronous service must be exposed to the Internet, and the account that the service runs under must have Internet access. Only outbound connections on ports 80 and 443 are required. Inbound connection access isn’t required. Use the Windows Firewall control panel to enable outbound connections for:

CrmAsyncService.exe application located on the server in the %PROGRAMFILES%\Microsoft Dynamics CRM\Server\bin folder.
Microsoft.Dynamics.Marketing.DataIntegrationService.exe application located on the server in the %ProgramFiles(x86)%\Microsoft Dynamics Marketing\CRMConnectorServicefolder.

The URLs shown in the following table must be exposed to the Internet for high ports and TCP, http, and https protocols to enable a connection between Dynamics 365 asynchronous and data integration services.

URLs	Comment
.accesscontrol.windows.net/ and .servicebus.windows.net/	The connection is used to provide a communication tunnel between both system components to allow the dataflow.
.login.live.com/	The connector must be able to authenticate using a Microsoft account.
http://cdp1.public-trust.com/CRL/Omniroot2025.crl	Dynamics 365 needs to ensure that the connection isn’t being targeted for man-in-the middle attacks. For this security verification, a different certificate is used. The certificate originates from the Azure team, has the Microsoft CA issuer name, and must pass the Azure certificate validation. Dynamics 365 sends a request for revocation checking to the Certificate Revocation List from Baltimore Trust (Microsoft CA is a child of Baltimore Trust).

For more information on firewall configuration for Dynamics 365, see Internet accessible URLs required for connectivity to Microsoft Dynamics Marketing, Network ports for Microsoft Dynamics CRM, and Microsoft Azure Datacenter IP Ranges.

Next steps

Continue to Enable and configure the connector.