Microsoft Dynamics 365

Sync data into Dynamics 365 by writing to Dataverse tables.

Setup

Navigate to destinations in Hightouch app and find Microsoft Dynamics 365.
Follow the oauth flow.
Once successfully authenticated, you will be asked to enter your service URL.
To get your service URL, sign in to your Microsoft Power Apps. Then, click on the settings icon on the top right corner to open the settings sidebar. Click on Developer resources
Copy the Web API endpoint then go back to Hightouch and paste the URL where it is required.
Finish creating your destination by pressing continue.

Access Level Recommendations

We recommend that you authenticate with a user that has the correct access to the environment that you will be working on.

Syncing

Microsoft Dynamics 365 destination allows you to snyc rows into tables on Dataverse which can be used by your Dynamics 365 applications.

Prerequisites

Before you set up a sync, we recommend you to skim through these concepts to gain an insight on how to effectively sync your data into Microsoft Dynamics 365.

Dataverse is the source of truth for your Dynamics 365 applications. Microsoft Dynamics 365 destination will sync your data into the Dataverse which will then allows you to use the data directly in your Dynamics 365 applications. For more information about Dataverse see Microsoft's documentation.

Record Matching

Record matching allows you to match queried data in Hightouch to rows in Dataverse. GUID and alternate keys are the two ways to match your query results to rows in your Dataverse tables.

What is a GUID?

GUID is the auto-generated primary key in your Dataverse tables. You are allowed to use GUID to match query results in Hightouch with rows in your Dataverse tables by default.

Although GUID's are available by default, we recommend the use of alternate keys for record matching in your Hightouch syncs.

What are alternate keys?

Alternate keys are custom unique identifiers that can be derived from one or more columns in your Dataverse table. It is a flexible way to set up a unique identifier in your Dataverse table to be use for record matching between your query results in Hightouch and your rows in Dataverse. In most case, you won't have access to Dataverse GUID in your external data warehouse for record matching so alternate keys are convenient solution.

Steps to setup an alternate key and use it in Hightouch for record matching

Sign in to your Microsoft Power Apps.
In the Power Apps, navigate to tables in Dataverse.
Select the table you want to sync to. In this walk through, we will use the Account table.

Please make sure that you are always working on the correct environment in Power Apps. If you haven't set up your environment yet, go to this link for more information. Here is an article from Microsoft on environment strategy.
Once you are in the table view, select keys to open the alternate keys view.
In the keys page: (1) Click New Key then in the pop-up on the right, enter the configuration for the key you are about to create. (2) Enter a label for this key. This label is the label that will be displayed in Hightouch's id mapping section. (3) Select a column that you want to use as an alternate key. Note that alternate keys must be unique and must meet the requirements here. If you do not have a column that meets these requirements, you can manually add a column and use it. In our example below, we are using a column that we created called Custom External ID.

If you are creating a new column to be used as external id, you may have to backfill the new column first before they can be used to avoid accidental duplicates.

While you can use multiple columns to make a unique key in Dynamics 365, Hightouch does not support multi-column alternate keys. These keys will not appear as option in Hightouch.

(4) Once configured, hit save button to create the alternate key.
The created alternate keys will appear as options in the id mapping section of your Hightouch sync configuration. They're ready to use.

Field Mappings

Field mappings tells us how to map columns from your query results to columns in your tables in Dataverse.

Required Fields

You may have noticed that First Name and Last Name appear to be read-only in the destination side while Description is editable. These read-only fields are fields that are marked as Business required in Dataverse. This means that whenever you create a sync, you must send data for these fields.

Field Types

The Microsoft Dynamics 365 destination will not automatically cast your data to the data types they are expected to be in your table in Dataverse. This means that you are responsible for casting them to the valid type they need to be in. The image below shows an example of fields we pulled from Dataverse along with their types. The icons on the left indicate the type of the column. As you may notice, there are icons with ?. This indicates that the type is either complex or unexplored by Hightouch. See here for more details on types.

Sync Modes

There are three different possible sync modes for this destination:

Insert — Insert mode inserts new rows into your table and does not update the objects as they change in your warehouse.
Upsert — Upsert mode inserts new rows into your table and updates fields that change in your warehouse.
Update — Update mode update fields on existing rows in your table.

Insert

This mode is good for the following scenarios:

You want to insert rows into table, but don't care if the data within each row remains up to date
Static data where each row is never updated, such as emails, events, etc.

Insert has two configuration parameters:

Name	Description
Object	The table (Account, Contact, etc..) where the rows will be inserted into Dataverse.
Hightouch to Dataverse field mappings	Tells us how fields in your query results will be mapped to columns in your Dataverse table.

Upsert

In this mode, new rows will be inserted into Dataverse and all designated columns will be kept up-to-date within Dataverse.

This mode is good for the following scenarios:

You want to push objects into Dataverse and want to keep the data up-to-date

Upsert has three configuration parameters:

Name	Description
Object	The table (Account, Contact, etc..) where the rows will be upserted into Dataverse.
Hightouch to Dataverse record matching	Tells us how to match queried records to rows in your Dataverse table.
Hightouch to Dataverse table field mappings	Tells us how fields in your query results will be mapped to columns in your Dataverse table.

Update

In this mode, selected columns from query results in Hightouch will update the columns of matching rows in your Dataverse table. For example, you could add an LTV column to an account. This mode does not create new rows for that account in your Dataverse. Instead, it updates the columns on existing matched rows.

See ID matching section in the prerequisites to learn how to match Hightouch query results to rows in your Dataverse.

This mode is good for the following scenarios:

You have rows in Dataverse that you want to enrich.
You want to continuously sync data from your warehouse but do not want to insert new rows to your table in Dataverse.

Update has three configuration parameters:

Name	Description
Object	The table (Account, Contact, etc..) where the rows will be updated into Dataverse.
Hightouch to Dataverse record matching	Tells us how to match queried records to rows in your Dataverse table.
Hightouch to Dataverse table field mappings	Tells us how fields in your query results will be mapped to columns in your Dataverse table.

Best practices

Click on Test button to open the test pop-up.

Click on the Sync as added row to make the request.

The result on the right will indicate if the request to Dataverse is successful.

Be aware that requests made through here will persist data into your destination as if you ran an actual sync. When working on a production environment, please make sure that you fully understand the risks.