About data entities


Data entities were introduced in Dynamics 365.
It is an abstraction from the physical implementation of database tables. They enhance data importing/exporting services.

A data entity

  • is a de-normalized view of data that is spread across multiple normalized tables.
  • is the most common use for exporting/importing data packages.
  • helps to connect any third-party app with Dynamics and its data.
  • can be used in synchronous integrations through OData services.
  • enables public application programming interfaces (APIs) to be exposed, which are used in Office integrations and third-party apps.
  • supports asynchronous integrations by using a data management pipeline, such as interactive file-based import/export and recurring integrations.
  • usually consists of multiple connected tables, but can consist of a single table.
  • can have unmapped fields – such as computed columns and virtual fields.
Data entity structure

Data entity types

  • Parameter
    • These are the functional or behavioral parameters. They’re required to set up a deployment or a module for a specific builder customer. Usually, parameter entities are tables that contain only one record where the columns are values for settings. Examples of such tables exist for the accounts payable, general ledger, client performance options, workflows, and so on.
  • Reference
    • Reference entities store simple reference data of small quantity that is required to operate a business process. They contain data that is specific to an industry or a business process. Examples include units, dimensions, and tax codes.
  • Master
    • Master data is one of the key data assets of the business. Generally, master data entities are the nouns of the business which typically fall into categories, such as people, places, and concepts. They are complex reference data of large quantity, and examples include customers, vendors, and projects.
  • Document
    • These are worksheet data that is converted into transactions later. Document entities are the operational data of the business. Documents have complex structures, such as several line items for each header record. Examples include sales orders, purchase orders, open balances, and journals.
  • Transaction
    • These are the operational transactional data of the business. They include posted transactions, which are non-item ported items, such as the posted invoice and balances. Examples of transaction entities include pending invoices.

Creating a new data entity

Add the postfix “Entity” to the name in order to prevent conflicts with tables and classes that have the same prefix.
The Primary data source must have a natural key, otherwise the data entity can’t be created.
A data entity should provide a holistic object that encapsulates the relevant business logic in a single consumable contract. The consumer of an entity must be able to interact with the entity by using the natural key of the entity.

Data entity wizard properties
Setting up data entity fields through the wizard

If the entity is not composite, setting set-based processing to true can improve performance.

Composite data entity

  • Allows you to build a single entity by leveraging multiple entities that are related to each other.
  • Is applicable in asynchronous integration scenarios rather than synchronous OData scenarios.
  • Is only supported for data management platform that is part of XML file-based imports/exports.
  • There is no programmatic interface for composite entities in X++.
Composite data entity structure

Unmapped fields

Unmapped fields comparison

Creating a new computed field

Creating a new computed field

Computed field example

Computed field code example

The method has to be static and the server keyword is required.
Ensure that the method name matches the field’s ‘DataEntityViewMethod’ property’s value of the unmapped computed field.

Data integration


  • Uses OData.
  • Business logic immediately runs on API call.
  • Uses blocking request and response pattern
    • the caller is blocked until the callee has finished running and gives a response.


  • Uses Batch data API.
  • Used for exporting/importing high-performing data and recurring integrations.
  • Uses non-blocking pattern
    • the caller sends the request and proceeds without waiting for the response.


  • is a standard protocol for creating and consuming data.
  • is based on Representational State Transfer (REST) and lets developers interact with data by using RESTful web services.
  • applies web technologies such as HTTP and JavaScript Object Notation (JSON).
  • exposes all the data entities that are marked as ‘IsPublic’.
  • supports complete CRUD (create, retrieve, update, and delete) functionality.
  • uses OAuth 2.0 authentication.


All of this information is originated from various Microsoft e-learning documents.


Data entities play an important role in exporting/importing data packages and in connecting data related third-party apps with D365.

Have a look at our other posts related to this topic.

Leave a Reply

Your email address will not be published. Required fields are marked *