Virtual Entities in Dynamics 365

Roshan Mehta, 25 February 2021

Virtual Entities allow you to display and interact with data from other systems inside Dynamics 365. This article provides a step-by-step guide on how to read data from a RESTful API and present the information within a Virtual Entity.

In this example, I am going to create a Virtual Entity called “Policy”. The data shown in this entity will come from a custom API.

I have noted some useful links at the end of this article for you to get familiar with Virtual Entities.

Create a new Solution

Create a new solution to store the components required for our Virtual Entity. I have called my solution “Virtual Entities”.

Create a plugin to call the API

Plugins are used to call an API through C# code and return data as an output parameter. The two plugin triggers used are Retrieve (a single record is retrieved – e.g. viewing a record through a form) and RetrieveMultiple (multiple records are retrieved – e.g. viewing records in a view).

The plugin performs the following actions:

1. In the Execute method, it checks the MessageName as either “Retrieve” or “RetrieveMultiple”.

2. For “RetrieveMultiple”, calls the API using an HttpClient to retrieve multiple Policies.

3. For each record returned, an Entity object is instantiated and is added to an EntityCollection.

4. The EntityCollection is returned as an output parameter in the “RetrieveMultiple” message and can be rendered in a view.

5. Optionally, you can write logic on the “Retrieve” message to call the API to return a single record, or you can skip this entirely. This is explained below.

Register the plugin with Dynamics 365 using the Plugin Registration Tool against the Retrieve and RetrieveMultiple messages.

Register a new Data Provider

The next step is to create a new Virtual Entity Data Provider. To do this, you need to use the Plugin Registration Tool. Connect to your Dynamics 365 organisation and perform the following steps:

1. Click on Register > Register New Data Provider

2. Fill out the details on the Register New Data Provider screen:

Data Provider Name: This name is used when creating a new Virtual Entity Data Source.

Solution: Select the solution that you previously created. My solution is called “Virtual Entities”.

Data Source Entity: Select the drop-down and choose Create new Data Source. This will create a new entity in the selected Solution, so choose a meaningful name. I have chosen the name “REST API Data Source”. You can customize the Data Source Entity to store configuration information that your plugin can read, such as API URLs, timeouts, API keys/credentials etc.

Assembly: Select the plugin assembly which contains the logic to call your API.

Retrieve: Select the plugin assembly which contains the logic for the “Retrieve” message.

RetrieveMultiple: Select the plugin assembly which contains the logic for the “RetrieveMultiple” message.

3. Click on Register to create the new Data Provider.

Create a new Virtual Entity Data Source

To create a new Virtual Entity Data Source:

1. Go to Settings > Administration > Virtual Entity Data Sources and click on New.

2. Select the Data Provider you created and click on OK.

This will open the form for your Data Provider, which will only have a Name field. As previously mentioned, you can add additional fields to store configuration details for the plugin to use in its API calls.

Create a Virtual Entity

In your solution, create a new Virtual Entity.

Virtual Entity: Ticked

External Name: Policy

External Collection Name: Policys

Data Source: Choose the Data Source you created in a previous step.

Create fields, forms, and views for the Virtual Entity

Here is an XML representation of what the API returns.

When creating fields for your Virtual Entity, you need to map the field to a property from the API. This is done through the External Name option on the field editor. I have mapped the out of the box Name field to the PolicyNumber field and then created new fields as follows:

· Policy Details (mapped to the PolicyDetails property from the API)

· End Date (mapped to the PolicyEndDate property from the API)

I have added the Name and Policy Details fields to the view – the End Date field is NOT on the view. All fields have been added to the form.

Test the Virtual Entity

If I navigate to my Virtual Entity, I can see the Policy Number and Policy Details displayed. My plugin only implements the RetrieveMultiple message, NOT the Retrieve message.

If I open one of the records, I can see that the Name and Policy Details are displayed, but the End Date shows as empty. This is because Dynamics 365 caches what is displayed in the view and can quickly display the information on the form. Remember that the End Date is NOT on the view.

If there are fields that you have excluded from the view but want to show on the form (e.g. End Date), you will need to implement the Retrieve message in your plugin to do an API call to retrieve that specific record. The concept is similar to the RetrieveMultiple message; however you will need additional filtering in your API call to get the right record, and then return a BusinessEntity as your Output Parameter.

Summing it up

Virtual Entities is a nice way to display information from other systems in Dynamics 365. You need to develop a custom plugin to retrieve data from an API, which can read information from a custom Virtual Entity Data Source entity if required.

You can extend on my example by writing additional logic in your plugin to filter the data based on the context of where it is being viewed from. For example, if you are viewing Policies for a single Contact, you can examine the Query input parameter in your plugin to find the Contact Id, and then pass that information to the API to get only the Policies for that Contact.

There are a few limitations to Virtual Entities which are described in the following resources.

https://docs.microsoft.com/en-us/powerapps/developer/data-platform/virtual-entities/get-started-ve

https://docs.microsoft.com/en-us/powerapps/maker/data-platform/create-edit-virtual-entities

More information on custom providers can be found here:

https://docs.microsoft.com/en-us/powerapps/developer/data-platform/virtual-entities/custom-ve-data-providers