Documentation Experience Platform Destinations Guide

Microsoft Dynamics 365 connection

Last update: Wed Jul 31 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Destinations

CREATED FOR:

Admin
User

Overview overview

Microsoft Dynamics 365 is a cloud-based business application platform that combines Enterprise Resource Planning (ERP) and Customer Relationship Management (CRM) along with productivity applications and AI tools, to bring end-to-end smoother and more controlled operations, better growth potential and reduced costs.

This Adobe Experience Platform destination leverages the Contact Entity Reference API, which allows you to update identities within an audience into Dynamics 365.

Dynamics 365 uses OAuth 2 with Authorization Grant as the authentication mechanism to communicate with the Contact Entity Reference API. Instructions to authenticate to your Dynamics 365 instance are further below, in the Authenticate to destination section.

Use cases use-cases

As a marketer, you can deliver personalized experiences to your users, based on attributes from their Adobe Experience Platform profiles. You can build audiences from your offline data and send these audiences to Dynamics 365, to display in the users’ feeds as soon as audiences and profiles are updated in Adobe Experience Platform.

Prerequisites prerequisites

Experience Platform prerequisites prerequisites-in-experience-platform

Before activating data to the Dynamics 365 destination, you must have a schema, a dataset, and audiences created in Experience Platform.

Refer to Adobe’s documentation for Audience Membership Details schema field group if you need guidance on audience statuses.

Microsoft Dynamics 365 prerequisites prerequisites-destination

Note the following prerequisites in Dynamics 365, in order to export data from Platform to your Dynamics 365 account:

You need to have a Microsoft Dynamics 365 account prerequisites-account

Go to the Dynamics 365 trial page to register and create an account, if you do not have one already.

Create field within Dynamics 365 prerequisites-custom-field

Create the custom field of type Simple with field data type as Single Line of Text which Experience Platform will use to update the audience status within Dynamics 365.

Refer to the Dynamics 365 Create or edit a field (attribute) documentation if you need additional guidance.

Write down the Customization prefix of the custom field that you create in Dynamics 365. You will need this prefix during the Fill in destination details step. Refer to the Create and edit fields section of the Dynamics 365 documentation for further details.
Dynamics 365 UI screenshot showing the customization prefix.

An example setup within Dynamics 365 is shown below:
Dynamics 365 UI screenshot showing the custom fields.

Register an application and application user within Azure Active Directory prerequisites-app-user

To enable Dynamics 365 to access resources you will need to log in with your Azure Account to Azure Active Directory and create the following:

An Azure Active Directory application
A Service principal
An application secret

You will also need to create an application user in Azure Active Directory and associate it with the newly created application.

Gather Dynamics 365 credentials gather-credentials

Note down the items below before you authenticate to the Dynamics 365 CRM destination:

Credential

Description

Example

Client ID

The Dynamics 365 Client ID for your Azure Active Directory application. Refer to the Dynamics 365 documentation for guidance.

ababbaba-abab-baba-acac-acacacacacac

Client Secret

The Dynamics 365 Client Secret for your Azure Active Directory application. You would be using option #2 within the Dynamics 365 documentation.

abcde~abcdefghijklmnopqrstuvwxyz12345678 for guidance.

Tenant ID

The Dynamics 365 Tenant ID for your Azure Active Directory application. Refer to the Dynamics 365 documentation for guidance.

1234567-aaaa-12ab-ba21-1234567890

Region

The Microsoft region associated with environment URL.
Refer to the Dynamics 365 documentation for guidance.

If your domain is as below, you need to provide the highlighted value for the CRM field in the dropdown selector when authenticating to the destination.
org57771b33.crm.dynamics.com
As an example: If your company is provisioned in the North America (NAM) region, your URL would be crm.dynamics.com and you need to select crm. If your company is provisioned in the Canada (CAN) region, your URL would be crm3.dynamics.com and you need to select crm3.

Environment URL

Refer to the Dynamics 365 documentation for guidance.

If your Dynamics 365 domain is as below, you need the highlighted value.
org57771b33.crm.dynamics.com

Guardrails guardrails

The Requests limits and allocations page details the Dynamics 365 API limits associated with your Dynamics 365 license. You need to ensure that your data and payload are within these constraints.

Supported identities supported-identities

Dynamics 365 supports update of identities described in the table below. Learn more about identities.

Target Identity

Example

Description

Considerations

contactid

7eb682f1-ca75-e511-80d4-00155d2a68d1

Unique identifier for a contact.

Mandatory. Refer to the Dynamics 365 documentation for further details.

Supported audiences supported-audiences

This section describes all the audiences that you can export to this destination.

This destination supports the activation of all audiences generated through the Experience Platform Segmentation Service.

Export type and frequency export-type-frequency

Refer to the table below for information about the destination export type and frequency.

Item

Type

Notes

Export type

Profile-based

You are exporting all members of an audience, together with the desired schema fields (for example: email address, phone number, last name), according to your field mapping.
Each audience status in Dynamics 365 gets updated with the corresponding audience status from Platform, based on the Mapping ID value provided during the audience scheduling step.

Export frequency

Streaming

Streaming destinations are “always on” API-based connections. As soon as a profile is updated in Experience Platform based on audience evaluation, the connector sends the update downstream to the destination platform. Read more about streaming destinations.

Connect to the destination connect

IMPORTANT

To connect to the destination, you need the View Destinations and Manage Destinations access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.

To connect to this destination, follow the steps described in the destination configuration tutorial. In the configure destination workflow, fill in the fields listed in the two sections below.

Within Destinations > Catalog search for Dynamics 365. Alternatively you can locate it under the CRM category.

Authenticate to destination authenticate

To authenticate to the destination, select Connect to destination.
Platform UI screenshot showing how to authenticate.

Fill in the required fields below. Refer to the Gather Dynamics 365 credentials section for any guidance.

Client ID: The Dynamics 365 Client ID for your Azure Active Directory application.
Tenant ID: The Dynamics 365 Tenant ID for your Azure Active Directory application.
Client Secret: The Dynamics 365 Client Secret for your Azure Active Directory application.
Region: Your Dynamics 365 Region. As an example: If your company is provisioned in the North America (NAM) region, your URL would be crm.dynamics.com and you need to select crm. If your company is provisioned in the Canada (CAN) region, your URL would be crm3.dynamics.com and you need to select crm3.
Environment URL: Your Dynamics 365 Environment URL.

If the details provided are valid, the UI displays a Connected status with a green check mark. You can then proceed to the next step.

Fill in destination details destination-details

To configure details for the destination, fill in the required and optional fields below. An asterisk next to a field in the UI indicates that the field is required.
Platform UI screenshot showing the destination details.

Name: A name by which you will recognize this destination in the future.
Description: A description that will help you identify this destination in the future.
Customization Prefix: The Customization prefix of the custom field that you created in Dynamics 365. Refer to the Create and edit fields section of the Dynamics 365 documentation for further details.

Enable alerts enable-alerts

You can enable alerts to receive notifications on the status of the dataflow to your destination. Select an alert from the list to subscribe to receive notifications on the status of your dataflow. For more information on alerts, see the guide on subscribing to destinations alerts using the UI.

When you are finished providing details for your destination connection, select Next.

Activate audiences to this destination activate

IMPORTANT

To activate data, you need the View Destinations, Activate Destinations, View Profiles, and View Segments access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.
To export identities, you need the View Identity Graph access control permission.

{width="100" modal="regular"}

Read Activate profiles and audiences to streaming audience export destinations for instructions on activating audiences to this destination.

Mapping considerations and example mapping-considerations-example

To correctly send your audience data from Adobe Experience Platform to the Dynamics 365 destination, you need to go through the field mapping step. Mapping consists of creating a link between your Experience Data Model (XDM) schema fields in your Platform account and their corresponding equivalents from the target destination. To correctly map your XDM fields to the Dynamics 365 destination fields, follow these steps:

In the Mapping step, select Add new mapping. You will see a new mapping row on the screen.
In the Select source field window, choose the Select identity namespace category and select contactid.

In the Select target field window, select the type of target field that you want to map your source field to.

Select identity namespace: select this option to map your source field to an identity namespace from the list.

Add the following mapping between your XDM profile schema and your Dynamics 365 instance:

table 0-row-3 1-row-3
XDM Profile Schema	Dynamics 365 Instance	Mandatory
`contactid`	`contactid`	Yes

Select custom attributes: select this option to map your source field to a custom attribute that you define in the Attribute name field. Refer to Dynamics 365 documentation for a comprehensive list of supported attributes.
Platform UI screenshot showing Target mapping for email.

note important

note important
IMPORTANT
Target field names should be in `lowercase`. Additionally, if you have a date or timestamp source field which is mapped to a Dynamics 365 date or timestamp target field, ensure that the mapped value is not empty. If the exported field value is empty you will encounter a `Bad request reported while pushing events to the destination. Please contact the administrator and try again.` error message and the data will not be updated. This is a Dynamics 365 limitation.

IMPORTANT

Target field names should be in lowercase.
Additionally, if you have a date or timestamp source field which is mapped to a Dynamics 365 date or timestamp target field, ensure that the mapped value is not empty. If the exported field value is empty you will encounter a Bad request reported while pushing events to the destination. Please contact the administrator and try again. error message and the data will not be updated. This is a Dynamics 365 limitation.

For instance, depending on the values you want to update, add the following mapping between your XDM profile schema and your Dynamics 365 instance:

table 0-row-2 1-row-2 2-row-2 3-row-2
XDM Profile Schema	Dynamics 365 Instance
`person.name.firstName`	`firstname`
`person.name.lastName`	`lastname`
`personalEmail.address`	`emailaddress1`

An example using these mappings is shown below:

Platform UI screenshot example showing Target mappings.

Schedule audience export and example schedule-audience-export-example

In the Schedule audience export step of the activation workflow, you must manually map Platform audiences to the custom field attribute in Dynamics 365.

To do this, select each audience, then enter the corresponding custom field attribute from Dynamics 365 in the Mapping ID field.

IMPORTANT

The value used for the Mapping ID should exactly match the name of the custom field attribute created within Dynamics 365. See Dynamics 365 documentation if you need guidance on finding your custom field attributes.

An example is shown below:
Platform UI screenshot example showing Schedule audience export.

Validate data export exported-data

To validate that you have correctly set up the destination, follow the steps below:

Select Destinations > Browse to navigate to the list of destinations.
Select the destination and validate that the status is enabled.
Switch to the Activation data tab, then select an audience name.
Monitor the audience summary and ensure that the count of profiles corresponds to the count created within the audience.
Log in to the Dynamics 365 website, then navigate to the Customers > Contacts page and check if the profiles from the audience have been added. You can see that each audience status in Dynamics 365 was updated with the corresponding audience status from Platform, based on the Mapping ID value provided during the audience scheduling step.

Data usage and governance data-usage-governance

All Adobe Experience Platform destinations are compliant with data usage policies when handling your data. For detailed information on how Adobe Experience Platform enforces data governance, see the Data Governance overview.

Errors and troubleshooting errors-and-troubleshooting

Unknown errors encountered while pushing events to destination unknown-errors

When checking a dataflow run, if you obtain the following error message: Bad request reported while pushing events to the destination. Please contact the administrator and try again.

Platform UI screenshot showing Bad request error.

To fix this error, verify that the Mapping ID you provided in Dynamics 365 for your Platform audience is valid and exists within Dynamics 365.

Additional resources additional-resources

Additional useful information from the Dynamics 365 documentation is below:

Changelog

This section captures the functionality and significant documentation updates made to this destination connector.

View changelog

table 0-row-3 1-row-3 2-row-3 3-row-3 layout-auto
Release month	Update type	Description
October 2023	Documentation update	Updated guidance to indicate all target attribute names should be in lowercase, in the Mapping considerations and example step.
August 2023	Functionality and documentation update	Added support for Dynamics 365 custom field prefixes for custom fields which were not created within the default solution in Dynamics 365. A new input field, Customization Prefix, has been added in the Fill in destination details step. (PLATIR-31602).
Nov 2022	Initial release	Initial destination release and documentation publish.

recommendation-more-help

7f4d1967-bf93-4dba-9789-bb6b505339d6