I have never had to deliberately learn what virtual entities are and what they are for. Sure, I might have come across it in blogs I have read, but that’s where the story ends. That is, until last week.
One of the elements in the design being looked at for a project with a client (which is in the retail business) is to use virtual entities to “bring in” data in Dynamics 365. I know that it has been around for some time but it has not been actually implemented in any of the projects managed by the company I work for. In the project’s analysis and design stage, we wanted to prove a few things including being able to surface the virtual data on a related physical entity (that is, by establishing a 1:N relationship between a virtual and a physical entity).
Here’s how the setup goes.
- Virtual entity enables surfacing of data from an external system in Dynamics 365
- If the use case is such that viewing of the data would be sufficient, then consider virtual entity as the solution. Among others, below are some to be taken into consideration:
- Data is read only and does not consume any storage space
- Forms, views, reports, among others can be configured
- Security privilege to read the data is just either a yes or no – there is no concept of depth of access.
- An organization has an Azure SQL database. Records from a certain table in the database are to be exposed in Dynamics 365. This is so that relevant metrics can be viewed by users including within the context of a contact record. All data calculation are done outside Dynamics 365.
At a high-level, these are the steps to be followed:
- Create Odata v4 Web API
- Create Web App
- Generate Model Class
- Deploy to Azure
- Setup the Virtual Entity in Dynamics 365
- Create Virtual Entity Data Source
- Create Virtual Entity
- Create the Virtual Entity Field
- Create Odata v4 Web API
I’ll go over them in more detail below, with images of course!
1. Create Odata v4 Web API
1.1 Create a Web App
1.1.1 Using Visual Studio, create ASP.Net Web Application (.NET Framework).
1.1.2 Select Empty and check the Web API box.
1.1.3 Install the Restier packages via NuGet Package Manager. To do this, in the Solution Explorer, right-click on the project and select Manage NuGet Packages. Browse for RESTier.
1.2 Generate Model Classes
1.2.1 Under the Models folder, add item. Select ADO.NET Entity Data Model.
1.2.2 Select EF Designer from database.
1.2.3 Create a connection to the Azure SQL database by clicking New Connection. Enter your database credentials.
1.2.4 Select the tables, views, and/or stored procedures to be included in the model.
1.2.5 WebApiConfig.cs should be modified. The WebApiConfig class should have the block of code as below. Make the necessary adjustments.
public static class WebApiConfig
public async static void Register(HttpConfiguration config)
// enable query options for all properties
1.3 Deploy the App to Azure
1.3.1 Right click on the project and select publish.
2. Set-up the virtual entity in Dynamics 365
2.1 Create a Virtual Entity Data Source
2.1.1 Navigate to Settings > Administration. Click on the Virtual Entity Data Sources.
2.1.2 Fill in the form with data. Ensure that the correct URL is entered.
2.2 Create a Virtual Entity
2.2.1 To create a virtual entity, check the box that indicates it is such. The External Name will come from the Name attribute of the EntityType element while External Collection Name corresponds to the Name attribute of the EntitySet element. Ensure that what is entered in both fields exactly matches what is in the data model, including the case of the letters (whether upper or lower case).
2.3 Create the Virtual Entity Fields
2.3.1 When creating the fields in Dynamics 365, be mindful of the following:
- The External Name exactly matches the Name attribute of the Property element, including the letter case.
- If the Property is nullable=“false”, it means the field is mandatory and so, the field requirement in Dynamics 365 should also be mandatory.
- The data type between the web service data model and Dynamics 365 are compatible. Please refer to this page to see the field data type equivalence: https://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/customize/virtual-entity-odata-provider-requirements
That’s about it! To end this, I just wanted to share that when I did this initially, I ran into a snag; I just keep getting an error that the data could not be retrieved from the data source when doing an advanced find. If I were a pro developer, let alone an API expert, I suppose it’s only gonna take a minute to resolved it but since I am on the functional/business analysis front on a journey to the more technical aspect of things, it continued on for 3 days. It turned out that I was entering the URL incorrectly (see step 2.12).
Creating the Odata Web Service
Deploying the Web Service to Azure
Setting up the Virtual Entity