Configure the SDK and Dynamics 365 Connector

Click the Edit button at the top of the Mapping section to open the Interoperation Mappings page. Use this page to map fields between the two systems and to fine-tune a few other aspects of the integration. The settings provided here are described in the following table.

Setting	Description
MDM Entity drop-down list	Use this drop-down list to choose the Dynamics Marketing entity you want to map. You can think of each entity as a simple database table that supports a given feature area, but the underlying data structure is actually more complex. The Interoperation Mappings page reloads to show the mappings and other settings for your selected entity (all of the other settings on this page apply to the entity you select here).
Remote Entity value	This read-only field shows the Dynamics 365 entity that maps to the currently selected MDM Entity. This is selected automatically and can’t be changed.
Threshold Field drop-down list and Threshold Value field	Use these settings to establish a condition that must be met for a record to be synced from Dynamics Marketing to Dynamics 365. For example, the default mapping uses this feature to ensure that only sales-ready leads are synced back to Dynamics 365. To accomplish this, the LeadManagement entity from Dynamics Marketing is configured with a Threshold Field of “SALESREADY” and a Threshold Value of “1”. This means that leads with a sales-ready value other than one will not be synced. The Threshold Field drop-down list is hard-coded to include only those Dynamics Marketing fields that make sense for use with this feature. Often, these are fields used internally by Dynamics Marketing that would not make sense to sync to Dynamics 365, which is why the fields available in the Threshold Field drop-down list are often different from those available for mapping. Warning Misconfiguring these fields can cause some or all records to fail to sync. Only use these settings selectively and with purpose. In most cases, you should leave them blank.
Sync Interval (minutes)	This setting is only provided when you have chosen ListEntity from the Microsoft Dynamics Marketing Entity drop-down list. It establishes the schedule by which the connector synchronizes your marketing lists, and must be set to allow enough time for non-list data to synchronize between list syncs. The default setting is 10 minutes, which works best in most cases. However, if you are synchronizing very large marketing lists, then you may need to increase this interval to keep your list data from clogging the connector queues. Using too short an interval won't cause data loss, but it could degrade synchronization performance of all types of records.
Enable Entity check box	Select this check box to enable mapping to the currently selected Microsoft Dynamics Marketing Entity. Clear this check box to disable the mapping. Entities for which this check box is cleared will not be synced between systems.
Status value	Displays a short status message related to the mapping, including the success/failure/result of any recent operations (such as file upload)
Dynamics Marketing Field column	This column lists each field that exists on the Dynamics Marketing side of the mapping. You can change any of these using the drop-down list for any row. You are most likely to need this setting when you add new rows to the table.
Dynamics 365 / Dynamics CRM Field column	This column lists each field that exists on the Dynamics 365 side of the mapping. You can change any of these using the drop-down list for any row. You are most likely to need this setting when you add new rows to the table.
New toolbar button	Click this button to add a new row to the table for the current MDM Entity. Then use the Dynamics Marketing Field and Dynamics 365 / Dynamics CRM Field drop-down lists to map the fields for the new row.
Delete toolbar button	To delete a row from the mapping, select the check box for the target row and then click this button.
Change option value mapping table-row button	This button appears for rows that map fields expecting one of just a few possible values (for example, ENUM fields, typically presented as drop-down lists for input). Click this button to open the Customize Option Mapping pop-up window, which shows a table that includes a row for each possible option name, as defined in Dynamics Marketing. Use this window to map these values between systems as follows: Option Name: shows the display name used in Dynamics Marketing. (These are typically established using Dynamics Marketing categories; see also Create custom drop-down values and folders). Map to Value: enter the analogous value used in Dynamics 365.

If you prefer to define your mappings all at once using XML rather than working on the Interoperation Mappings page, you can easily do so by downloading and examining the current mappings as an XML file, editing the download and then uploading the result.

Warning
This operation requires that you already know how to work with XML, and can easily understand how to edit an XML file based on its existing content to produce a valid result.

To edit your mapping via XML:

1. Click the Download button at the top of the Mapping section. Your browser saves the file either in your default download folder or in a folder that you choose.

2. Open the downloaded file in a text of XML editor and modify it as needed.

3. Return to the Integration Settings page in Dynamics Marketing and click the Upload button at the top of the Mapping section. Your web browser opens a file browser window; use this window to locate and select your modified XML file.

To set up Azure Service Bus queues with SAS authentication for the SDK service:

1. If you haven't already done so, use the Azure Management Portal to create the Azure Service Bus namespace where you will run message queues for communicating to and from the Dynamics Marketing SDK service. Dynamics Marketing will create the queues themselves later in this procedure.

2. Find the policy name and primary key generated for your Azure Service Bus namespace and paste them into a temporary text file so you can use them later in this procedure. You can find these by checking your Azure Service Bus configuration in the Azure Management Portal or by looking up its connection string, which shows them as values for its SharedAccessKeyName and SharedAccessKey parameters, respectively.

3. Sign into Dynamics Marketing as an administrator and go to Settings > Administration > Integration Options.

4. Check the Services section to make sure the SDK is enabled and running. If it isn't running, click on the Enable SDK service button .

5. Click the Settings button at the top of the SDK Service Settings section to open the Configure Windows Azure for Dynamics SDK Service pop-up window.

   

6. Enter the following values:

   • Authentication: If shown, choose SAS (ACS authentication is no longer supported).

   • Azure namespace: Enter the Azure Service Bus namespace where you want to run your SDK queues.

   • Key name: Paste in the Azure Service Buspolicy name (SharedAccessKeyName) that you copied at the start of this procedure.

   • Key value: Paste in the Azure Service Busprimary key (SharedAccessKey) that you copied at the start of this procedure.

   • Queue name for incoming requests and Queue name for outgoing responses: 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. As long as you choose queue names that don't already exist in your specified Azure Service Bus namespace, Dynamics Marketing will create and configure new queues with the names you specify, exactly as required. If you enter existing queue names, then Dynamics Marketing will use the existing queues instead of creating new ones (not recommended).

   Important

   If you want to use existing queues rather than letDynamics Marketingcreate them for you (not recommended), then keep the following important points in mind: Don't use queues that are also used by the connector 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 itself and expects those credentials to be inherited by the queues it uses.

7. Click Submit to save your settings and close the pop-up window.

Note
The current Azure Management Portal doesn’t allow you to view the configuration of the “Require Session” flag. To see the flag, query the QueueDescription class, or use Service Bus Explorer (or similar).

After you have successfully enabled the SDK and its Azure queues, the SDK Service Settings section will display information about your Azure connection and will also include a set of check boxes for enabling or disabling read and write permissions for each of several request groups. Each of these groups maps roughly to a feature area of Dynamics Marketing. Select the check box for each type of operation you would like to expose to the SDK. You should only grant those permissions that your custom solution actually requires.

If you use the SDK to trigger the sending of marketing emails to a specified set of email addresses, Dynamics Marketing will check to see if any contacts exist for the incoming email addresses. If a match is found, the email message is linked to the found contact for purposes of email tracking and lead scoring. For addresses where no match is found, Dynamics Marketing creates a new contact whose record includes only the email address, plus associated email tracking, lead scoring, and other records. Use the Enable Contact Reconciliation check box in the SDK Service Settings section to control how new contacts created in this way will be handled by Dynamics Marketing and synchronized to Microsoft Dynamics 365.

• When contact reconciliation is enabled: new contacts created in this way are initially invisible in Dynamics Marketing until a contact with a matching email address is synchronized from Dynamics 365, at which time the invisible contact will be merged with the newly synced contact, thus associating all emails and leads with that contact. The invisible records aren’t synced until they are matched.

• When contact reconciliation is disabled: new contacts created in this way are visible in Dynamics Marketing and will be synced back to Dynamics 365 as new contacts. This ensures that all such contacts are visible and usable in Dynamics Marketing, but may result in the creation of duplicate contacts in Dynamics 365.

Note
If your Dynamics Marketing or Dynamics 365 database includes multiple contacts that share a given email address, contact reconciliation will use the first matching contact it happens to find.