Contents

Develop custom Data Entities for Dual-write

Contents

Dual-write has been around for almost two years now. It’s one of the ways of integrating Dynamics 365 Finance and Operations and Dataverse along with Virtual Entities.

The standard solution comes with many out-of-the-box entities available to synchronize. This has been one of the great improvements since Dual-write was made available in preview, when Juanan and I demoed it in the 2019 Dynamics Saturday in Madrid.

https://static.ariste.info/wp-content/uploads/2021/03/DW-1024x1024.png
Develop custom Data Entities for Dual-write 1

This is how Dual write really works

But what if we need to develop a new custom Data Entity in MSDyn365FO and use it in Dual-write? It’s easy but there’s some things we need to remember when doing it.

Dual-write

Dual-write is a bidirectional integration that will synchronously write in Dataverse when data is created, updated or deleted in MSDyn365FO in near-real-time. On the Finance and Operations side it uses data entities to export data to Dataverse.

Right now there’s a set of several OOB entities that come ready to be synchronized, and thanks to Initial Sync we can populate data in Dataverse choosing FnO as the source when starting the sync, or also choose Dataverse as the source.

If you want to learn more about Dual-write you can:

Create the Data-entity

In Visual Studio we need to create the entity from our table. I’ve created a new table called AASBookTable with just four fields: BookId, Author, Name and ISBN. Its primary key is the BookId field which is also its alternate key and will be used as natural key in the entity.

Next, we create the data entity and make sure we’re marking the “Enable data management capabilities” checkbox:

https://static.ariste.info/wp-content/uploads/2021/03/DW1.png
Develop custom Data Entities for Dual-write 2

Enable data management capabilities must be checked

If the entity doesn’t have data management enabled it won’t be displayed in the list in the Dual-write tables setup.

Create a table in Dataverse

Now we need to create a table in our Dataverse environment. This table must have at least some of the fields we want to synchronize to Dataverse AND a company field. The company concept doesn’t exist in Dataverse/CRM but thanks to the OOB mappings and Initial Sync we can solve this with just a few clicks and will have a company table in Dataverse with all our FnO legal entities.

https://static.ariste.info/wp-content/uploads/2021/03/DW2.png
Develop custom Data Entities for Dual-write 3

Company field related to table company

Following my example I’ve created a table with the same four fields and a company field with the data type Lookup and its related table Company, where the FnO legal entities are synchronized.

As I said, if we don’t create this field we won-t be able to setup Dual-write for this table.

Create table map

Our table and data entity are ready, and now we need to create a mapping between them in the Dual-write workspace in FnO. Click the “Add table map” button:

https://static.ariste.info/wp-content/uploads/2021/03/DW3.png
Develop custom Data Entities for Dual-write 4

Dynamics 365 Dual-write add table map

A new dialog will open and we need to select the FnO entity and the Dataverse table:

https://static.ariste.info/wp-content/uploads/2021/03/DW4-edited.png
Develop custom Data Entities for Dual-write 5

Entity map

Select the entity and table we’ve created and click save. Then we can define the field mapping:

https://static.ariste.info/wp-content/uploads/2021/03/DW13-1024x629.png
Develop custom Data Entities for Dual-write 6

Dynamics 365 Dual-write field maps

Because I’ve created both it’s clear what to map. And after doing this we can click save and it’s done, right? No! WRONG! If we do just this we’ll get an error, this error:

Project validation failed. SourceEntitySchema: Books has a primaryCompanyField set to DataAreaId and DestinationEntitySchema: cr008_bookses doesn’t have primary company field set. Dual-write only supports mapping between cross-company entities or company-specific entities from both sides..keys are missing for either AX or CRM.keys are missing for either CRM or AX

Or we can also get an error regarding a missing integration key for the company field. In the end both are caused because we’ve missed defining the integration key for this new Dataverse table:

Integration key

Go back to the main Dual-write form and click on the “Integration key” button:

https://static.ariste.info/wp-content/uploads/2021/03/DW7.png
Develop custom Data Entities for Dual-write 7

Dual-write integration key

The integration key will be the same as the FnO data entity key, plus the company if your data entity has a company context. Remember that when we create indexes in FnO the DataAreaId field isn’t included in the field, but it is in the SQL Server index along the partition field.

The integration key for our custom Dual-write mapping will look like this:

https://static.ariste.info/wp-content/uploads/2021/03/DW11.png
Develop custom Data Entities for Dual-write 8

Dual/write integration key

Remember we’ve added the company field to our Dataverse table? You can see in the image above that the field includes the relation to the Company table in Dataverse. We won’t be able to save the field mapping if we create the key using our Dataverse table’s company field instead of its Company table relation, like this:

https://static.ariste.info/wp-content/uploads/2021/03/DW9.png
Develop custom Data Entities for Dual-write 9

Dual/write integration key

See the difference? In the first image the field reads c008_company.cdm_companycode while in the second one it’s c008_company. If we set the integration key using the field in our table instead of the related table and save the fields’ mapping we’ll get an error saying the company is missing in the key because it’s expecting the relation!

Action!

The table and field mappings are ready, just click run and go create a new book in the FnO form:

https://static.ariste.info/wp-content/uploads/2021/03/DW14.png
Develop custom Data Entities for Dual-write 10

Finance and Operations form

Then we go to our Dataverse table and check its data…

https://static.ariste.info/wp-content/uploads/2021/03/DW15.png
Develop custom Data Entities for Dual-write 11

Dataverse table data

It’s there! And of course it’s working in both directions. If I create a record in Dataverse it’ll be created in FnO too. I’ll use the Excel add-in to add a new book:

https://static.ariste.info/wp-content/uploads/2021/03/DW16.png
Develop custom Data Entities for Dual-write 12

Dataverse Excel add-in

And after refreshing the form in FnO we can see it there too:

https://static.ariste.info/wp-content/uploads/2021/03/DW17.png
Develop custom Data Entities for Dual-write 13

This is a really simple example of how we can create a custom table, use it in a data entity and then use this entity in our dual-write setup. It’s something that can be easily done but we need to remember the “company thing”, otherwise this will never work!

Dual-write is even easier to configure nowadays thanks to LCS allowing us to create and link a new Dataverse environment when we deploy a new Finance and Operations environment.