How To Create A D365 Data Entity

In this article, learn how to create a D365 Data Entity. Previously, you learned what a data entity is, and when they are used. In this lesson, walk through the steps of creating a data entity in Visual Studio. Then, see it within the Data Management workspace.

Review

Before learning how to create a D365 Data entity, take a minute to review what data entities are.

First, read my article on What is a D365 Data Entity?

Second, let us talk through why data entities should be used instead of just the tables directly.

Note: it is not actually possible to load data directly into D365 tables. Data entities must be used. But even if it were still possible, the following will explain how data entities are the best to use.

Tables Are Normalized

As a reminder, data within D365 is normalized. To explain, this means that for a given type of data, such as items, customers, sales orders, and many others, the data is stored across several different tables.

The benefit of this is that it allows the data to take up less space by only creating records for fields that is has data. Additionally, it increases the system performance when searching, reading, and writing this data.

However, this approach is not helpful when outside systems need to interact with this data. The outside system or user would need to understand and work with all of those related tables to read or write data in D365.

Data Entities are De-normalized

Therefore, data entities were created to address this problem. Data entities de-normalize the data. To explain, fields across multiple are added to a single data entity, that acts like a single table or view.

Whenever data is read from the data entity, the definition of the data entity understands the relationships between the tables so that the calling system does not need to understand them.

Similarly, whenever data is written using a data entity, the system will handle populating reference record ID’s needed to allow the tables to relate to each other. This saves so much time and effort!

Data Entity Examples

Before learning how to create a D365 data entity it is helpful to look at an example. This will help you see the end result.

Below are the names of some common data entities. The second name is the name used within Visual Studio.

• Items (Released products V2), EcoResProductV2Entity
• Customer (Customers V3)
• Vendors (Vendors V2)
• Sales order header (Sales order headers V2)
• Sales order lines (Sales order lines V2)
• Warehouses (Warehouses)

Every time Microsoft publishes a new version of a data entity, they create a new entity and add V# on the end. This ensures they do not break existing integrations.

Items Data Entity Example

Next, look at the items data entity in Visual Studio. After opening Visual Studio, open the ‘Application Explorer‘, by going to View>Application Explorer.

Next, expand the node AOT>Data Model>Data entities. Then, locate the node EcoResProductV2Entity. Alternatively, search for EcoResProductV2Entity in the search bar at the top of the Application Explorer.

Right click on the data entity EcoResProductV2Entity, and select ‘Open designer‘.

The designer window opens. Next, expand the ‘Fields’ node, and see all of the fields that you can read or write to in the data entity.

Remember, data entities are similar to tables in that they have fields, and allow you to interact with data. The key differences are that data entities can be interacted with from outside systems, whereas tables cannot. And, data entities show fields that often span across multiple related tables. I am repeating this concept several times as it is the most important thing to understand.

To prove this, expand the data sources node, and see all of the data sources that contribute fields to this data entity.

Lastly, click on each field in the Fields node, and look at the properties. Notice how the Data field and Data Source values come from more than one table.

Create A D365 Data Entity

Now that you have seen an example of what we will build, let us create a D365 Data Entity.

Create A New Project

For this example, we create the same example that Microsoft does in this documentation.

First, open create a D365 project in Visual Studio. Name it tutorialDataEntity, or whatever you like.

Second, right click on the project, select properties, then set the project to your custom model. Follow this article on how to create a model in D365. Or, use the Fleet Management model.

Additionally, set the Synchronize Database On Build property to True.

If you use a custom model, make sure that your custom model has a reference to the ‘Fleet Management’ model, since we will be referencing a table that exists in the Fleet Management model. See How to Update Reference Packages. Specifically, go to Extensions>Dynamics 365>Model Management>Update model parameters.

Next, set the ‘Model name‘ drop down to your custom model. Then click ‘Next‘.

Next, check the checkboxes next to the ‘Fleet Management’ model, and click ‘Next’. Finally, click ‘Finish’ on the wizard.

Add a new data entity to your project

First, right click your project, and select Add>New Item.

Second, select ‘Data Entity‘ from the list. Next, enter ‘FMLabCustomerEntity‘ as the name. Or, come up with your own name. Then, click the ‘Add‘ button. Note, it is helpful to name data entities with the suffix ‘Entity’.

The Data Entity Wizard will open.

Set the Primary Data Source and Public Entity Name

When you create a D365 Data Entity, you need to specify a primary data source.

First, set the ‘Primary datasource‘ to the main table or view you want your data entity to interact with. For this example, set the ‘primary datasource‘ property to ‘FMCustomer‘. This should be the parent table that is always present. There may be exist child tables that relate to this main table that do not always exist.

Secondly, set the public entity name to ‘FleetLabCustomer‘. And, set the Public collection name to ‘FleetLabCustomers‘. This is important to remember as these are the names that will be used by an outside system to interact with your data entity.

You should not need to change the rest. Finally, click the ‘Next‘ button.

For more information about these properties, see this Microsoft documentation.

Specify The Fields

The next step to create a D365 Data Entity is to specify what fields you want on the data entity.

Often there may be many fields on the tables your data entity is interacting with. However, a data entity should only contain the fields that an outside system needs to read or write. While you could list all the fields, this would hurt performance and make the data entity harder to work with.

Check the checkboxes next to the fields you want to include. Uncheck the checkboxes for the fields you wish to exclude. Change the values in the ‘Data entity field name’ to be what you would like the outside system to use.

For this example, first, check the ‘Convert labels to field names’.

Second, uncheck the fields LicenseImage, and Image.

Thirdly, check the ‘Is Mandatory‘ value in the row where the ‘Field name‘ is set to ‘DriverLicense‘.

Fourth, let us add some fields from a table that is related to the primary data source. Click on the carat next to the ‘Data source‘ property value. The drop down ‘PrimaryAddress‘ will show. Click on ‘PrimaryAddress‘.

Fifth, ensure that all of the checkboxes on the PrimaryAddress data source fields are checked. Also, rename the ‘Data entity field name’ fields to match the following screenshot.

Finally, click the ‘Finish‘ button.

Notice, the data entity ‘FMLabCustomerEntity‘ was added to your project. Additionally, the staging table ‘FMLabCustomerStaging‘ was added. And, two security privileges were added to your project: FMLabCustomerEntityMaintain and FMLabCustomerEntityView. All of these names were specified on the first screen of the wizard.

Build Your Project

After you create a D365 data entity you must build your project so that the views and tables are creating on the SQL server database.

Again, right click on your project, select properties, and ensure that the ‘Synchronize Database on Build‘ property is set to True.

Next, in Visual Studio, click Build>Build solution. Validate that the build was success and that there were no errors.

Make Further Changes

When you create a D365 Data Entity, it is easiest to let the wizard create the data entity, staging table, and security objects for you. However, after you have created the initial data entity you make need to make changes. Let us go through how to do that.

Validate the Public Entity Name

To change a D365 data entity, right click the data entity, and select ‘open designer‘.

Right click the data entity node, and select ‘Properties‘. Validate the properties are correct. Often, users may want to change the ‘Public Collection Name’ or ‘Public Entity Name’ to something different. Ensure the ‘Is Public‘ flag is set to Yes.

For this example, set the ‘Label’ to ‘Fleet lab customers‘.

Change Data Source Properties

Next, expand the ‘FMCustomer‘ data source, and select the ‘PrimaryAddress‘ data source. Set the ‘Is Read Only’ property to ‘No‘.

Add Fields

Optionally, you can add or remove fields from your data entity.

To add a field, drag the field from the data source Fields nodes to the Fields nodes of the data entity.

To remove a field from the data entity, right click the data field from the Fields node, and select ‘Delete‘.

Validate the Entity Key

Whenever you create a D365 data entity it is important that the data entity has a unique key. This means you must have a combination of one or more fields whose combination of values will always be unique.

For example, on an item, this is the ItemId field. Additionally, for a customer, this is the customerID field. On a sales order, this is the SalesID field.

In this example, we do not have a customer ID. And, the fields FirstName and LastName by themselves will not necessarily be unique. There could be more than one person with the same first and last name. Therefore, we must also include the field DriversLicense. That should ensure we have a unique key.

Update The Staging Table

Every D365 data entity will have a corresponding staging table. This is a table that the system uses to allow the data entity to function. The staging table must be kept in sync with the fields in the data entity.

It would be nice if the system fully kept this table in sync for us without our intervention. But that is not the case. Instead, every time you make a change to the data entity’s data sources, fields, or entity key, you need to tell the system to update the staging table.

Note, you should not try to update the staging table manually. Instead, right click on the data entity, and select ‘Update staging table‘. The system will then update the staging table to match the fields currently in the data entity. Do this anytime you make a change to the data entity. It does not hurt to do it even when you did not make a field, data source, or entity key change.

Finally, in Visual Studio, go to Build>Build Solution once more. This will cause the SQL server database to get updated as well.

Afterwards, you can open the staging table, and validate that all the fields are listed.

To see the name of the staging table, right click on the data entity, and select ‘Properties’. Next, see the value of the ‘Data Management Staging Table’ property.

Additionally, validate that there exists an index. The index will have all the fields in the data entity EntityKey plus the DefinitionGroup and ExecutionId fields.

Regenerate Staging table

In rare occasions, you might receive synchronization errors, or other strange errors relating to the staging table. If you have tried to resolve the issues but are still not successful, you can try to regenerate the staging table.

In these cases, you can go to the staging table in Visual Studio and delete the table.

Then, go to the data entity, right click, and select ‘Regenerate staging table‘. This may fix the issues.

Since the staging table acts like a temporary table and does not actually contain data when not in use, doing this will not result in loss of data.

Data Management Workspace

After you create a D365 data entity, you can see it in the Data Management Workspace.

In Microsoft Dynamics 365 for Finance and Operations, search for ‘Data management‘ in the top bar. Select ‘Data management‘ under System administration>Workspaces.

Next, once the page opens, click on the ‘Data entities‘ tile.

Scroll down or filter until you see the entity that you created. If you do not see it, ensure you have the ‘Synchronize on Build’ property on your project set to ‘True’, and build your solution again.

Testing A Data Entity

After you create a D365 Data entity, you will want to test it. You can do this in several different ways.

First, you can use the data management workspace and import or export a file.

Second, you can use a web request tool like Postman to call the data entity using OData.

Third, you can actually just write an x++ job to populate your data entity and call the ‘insert’ method. If your data entity is setup correctly, data should now exist in the destination tables. See Microsoft’s example for this here.

Conclusion

In this tutorial, you learned how to create a D365 Data Entity. You learned how you can use the wizard to help create the initial data entity. Afterwards, you can manually update the data entity using Visual Studio like you would any other object. In the next lesson you will learn how to test and use a data entity to read or write data in Microsoft Dynamics 365 for Finance and Operations. Thank you!