Virtual Entities

Interact with data from external systems using the new virtual entities

Starting with the July 2017 Update for Dynamics 365 (online), virtual entities enable the integration of data residing in external systems by seamlessly representing that data as entities in Dynamics 365, without replication of data and often without custom coding.

Virtual entities replace previous client-side and server-side approaches to integrating external data, which required customized code and suffered from numerous limitations, including imperfect integration, data duplication, or extensive commitment of development resources. In addition, for administrators and system customizers, the use of virtual entities greatly simplifies administration and configuration

A virtual entity is a definition of an entity in the Dynamics 365 platform metadata without the associated physical tables for entity instances created in the Dynamics 365 database. Instead during runtime, when an entity instance is required, its state is dynamically retrieved from the associated external system. Each virtual entity type is associated with a virtual entity data provider and (optionally) some configuration information from an associated virtual entity data source.

Records based on virtual entities are available from all Dynamics 365 (online) clients, including custom applications developed using the Dynamics 365 SDK.

Virtual entities provide these benefits:

  • End users work with the records created by the virtual entity to view the data in fields, grids, search results, and Fetch XML-based reports and dashboards.
  • System customizers can configure the data source record and create virtual entities without writing any code.
  • Developers can implement plugins to read external data using the Dynamics 365 SDK and Dynamics 365 (online) Plug-in Registration tool.


In this release, virtual entities have a couple of restrictions:

  • Data is read-only
  • Only organization-owned entities are supported
  • Field-level security is not supported
  • It must be possible to model the external data as a Dynamics 365 entity. This means:
    • All entities in the external data source must have an associated GUID primary key
    • All entity properties must be represented as Dynamics 365 attributes - you can use simple types representing text, numbers, optionsets, dates, images, and lookups
    • You must be able to model any entity relationships in Dynamics 365


In this blog post I'll walk you through a simple way of creating a virtual entity.

What you need to test this out:

  1. Access to a service exposing data in OData v4
  2. An entity in this external data source with an associated GUID primary key
  3. Access to the latest preview of Dynamics 365

On the site you will find a service you can use for testing. Just type$metadata in your browser to see a list of entities

Fig. 1

If you expand a given entity branch, eg Product, you will need to check if the entity has an associated key of type GUID (requirement #2 above). Please note that this is NOT the fact for the Product entity (ref picture below). So this entity is not one we can bring in.

Fig. 2

However expanding the entity Advertisement branch, we see that this entity HAS got an associated key of type GUID, so we will use that. Note the ID is spelled "ID" (all capital letters), and also note the Name and AirDate properties - we will get back to those

Fig. 3

To see which records this data set returns we will need the collection (ie plural) name of the entity - for that we type in the browser, and see the collection name is Advertisements

Fig. 4

Using this information its a matter of typing in the brower to learn that the data set holds two records (these are the two external records we will surface in Dynamics 365 using the new Virtual Entity capability).

Note: You can use this OData API Explorer for a more visual representation of the data set (in its v3 edition though)

Fig. 5


Create a Virtual Entity Data Source

With the data source identified we can proceed to the next step - creating a Virtual Entity Data Source. In Dynamics 365 click Settings -> Administration (1) and then Virtual Entity Data Sources (2) to open the Data Sources grid.

Fig. 6

In the Data Sources grid click NEW (1) to open the Select Data Provider dialog

Fig. 7

In the Select Data Provider dialog select OData v4 Data Provider (the only option) and then click OK to open the New OData v4 Data Source dialog

Fig. 8

Fig. 9

In the New OData v4 Data Source dialog fill out the three to fields in the General section

  1. In the Name text box type a name of your choice for the data source (I'll use "Public Service")
  2. In the URL text box type or paste the URL from above (fig 4)
  3. In the Timeout text box (optional) type the number of seconds to wait for a response from the web service before quitting a data operation

And then click OK (4) to return to the Data Sources grid

Fig. 10

Fig. 11


Create a Virtual Entity

Last thing is to create a Virtual Entity to bring in data from the OData source. Click Settings -> Administration -> Customize the System 

Fig. 12

Create a virtual entity like any custom entity, and then select the Virtual Entity check box (1) - see below

Selecting the check box displays additional information requirements for the data source (2), as well as the External Name and External Collection Name values (3) for the entity definition.

So in this example the

  1. name of the new Virtual Entity is called "Advertisement" (a name I typed)
  2. name of the Data Source is "Public Service" (as per fig. 10 above)
  3. External Name = "Advertisement" and External Collection Name = "Advertisements" (as per fig. 3 and 4 above)

Fig. 13

Once the new Virtual Entity is created a couple of important things to ensure/edit in order for the mapping to work.

The system automatically creates two fields, one for the id (1) and one for the name (2). You will need to map those to the external data source names.

Fig. 14

So for the ID field (the primary key) ensure that the name in the External Name text box (1) matches the property name in the data source (2) as per figure 3 above. Observe case sensitivity.

Fig. 15

For the Name field ensure that the name in the External Name text box (1) and the Data Type (2) matches the property name and type in the data source (3)  as per figure 3 above. Observe case sensitivity and Data Type.

Fig. 16

Optionally you can create a third field to bring in the AirDate field from the data source (Date type)  as per figure 3 above. Observe case sensitivity and Data Type. If the property has Nullable = "false" like seen for the AirDate property (3), then you must set Field Requirement = Business Required (4)

Fig. 17

Create a form with the desired fields

Fig. 18

Create a view with the desired columns

Fig. 19

Publish customizations

Fig. 20


You now have a list with the two records from fig. 5 above

Fig. 21

Opening a record will display the form you defined

Fig. 22

I hope you will enjoy this new elegant way of surfacing data from external data sources in Dynamics 365 without the data residing in Dynamics 365. Data are mastered outside of Dynamics 365, yet available to work with in Dynamics 365 like any other entity.


See Also

  • Virtual Entities Demo Solutions (download) - link
  • Virtual Entities - Relationships  - link