Anyone who has spent a considerable length of time working with virtual entities in Dynamics 365 Online / the Common Data Service will have their collection of war stories to share. A great concept on paper - namely, to allow you to surface read-only versions of external system as fully-fledged entities within the Common Data Service database - they are, regrettably, a finicky feature to start getting any mileage out of. As well as requiring a compliant OData V4 endpoint that surfaces your underlying data source (other methods are supported, but can be a nightmare to code and deploy), the actual setup process for your virtual entities can lead to hours of fruitless diagnosing. Additional frustration then surfaces, as we find ourselves contending with error messages like the one below:

There is nothing within this message to help us determine whether this is a virtual entity configuration issue or a problem with our OData Service itself. You can discount any issues falling into the latter by checking the following:

• The endpoint is using v4 of the OData Standard within its implementation. Also, the endpoint should support the various system query options, such as select, filter etc. You may find that things “work” without these specified (i.e. data starts surfacing), but you will run into issues fairly quickly whenever you start filtering or returning subsections of the data needed.
• For each record returned from the endpoint, each row must contain a Globally Unique Identifier (GUID) field, that uniquely identifies the row in the dataset.
• Records must return a supported data type that the platform can translate into the appropriate Common Data Service data type. At the time of writing this post, the following data types are unsupported:
  • Edm.Binary
  • Edm.Time
  • Edm.Float
  • Edm.Single
  • Edm.Int16
  • Edm.Byte
  • Edm.SByte

After eliminating all of these potential issues from the equation, you can then turn to the configuration settings of the virtual entity. The exact problem will typically vary per situation but, more often than not, can come down to a simple misconfiguration issue. In a recent example I dealt with, the problem turned out to be frustratingly obvious to resolve. To understand this further, we can take a look at the OData metadata properties of the collection I was attempting to surface as a virtual entity in the application:

Note here that our Value field is a non-nullable type, thereby meaning it must always contain a value.

Now, let’s compare this with what I had set up within the virtual entity for this corresponding field:

All critical aspects of this configuration - the External Name and Data Type, specifically - are correct. The issue here lies in the Field Requirement property. This setting must match against the nullability properties of the underlying OData column; which, as we have witnessed, should always contain a value - as such, attempting to execute queries against this entity will fail with the error message above, up until you change this property to Business Required. This blunder is genuinely one of those things that you kick yourself over after the fact, as it seems so obvious when you think about it logically!

So, to summarise, if you are pulling your hair out over why a virtual entity is just not working, there’s an excellent chance that its a simple mistake within its configuration. I’d, therefore, recommend you check the above and the following details within your setup, to get things working:

• You are using the correct endpoint destination as part of your Virtual Entity Data Source record. This value should always be the base URL, without any collection name appended to it.
• The External Name and External Collection Name values should match against the OData entity collection name.
• The External Name values for each field defined on the virtual entity must match precisely against what has been recorded within the metadata.
• All fields must map to the correct Dynamics 365 data type, as described in this article.
• The base Name and Primary Key field created with your virtual entity must map across to an appropriate Edm.String and Edm.Guid field respectively. And, as mentioned earlier, the Primary Key value must always be unique within the collection dataset.

Either one or several of these things will be the cause of your connectivity issue to your virtual entity. Unfortunately, because of how lacking the error messages are within the system, this is ultimately something that you have to spend time combing through manually to resolve. Microsoft does advise that errors should get written out to the plug-in trace log for inspection. I have so far been unable to get this to produce any meaningful output throughout my time working with virtual entities. Answers on a postcard if you’ve had any more joy in this area. All that it leaves me to say is good luck in your journey with virtual entities, and I hope that you find this post useful in diagnosing any potential issues you have with them 🙂