OData v4 Data Provider configuration, requirements, and best practices
Applies to Dynamics 365 for Customer Engagement apps version 9.x (on-premises)
This topic describes how to configure the OData v4 data provider as well as the requirements and recommended best practices for using the OData v4 data provider to connect with an OData v4 web service.
OData v4 data provider best practices
Your instance requires that all entities have an ID attribute. This ID is known as a unique identifier and the value must be a guid. You can only map ID fields to external fields with the EDM.Guid data type. You can’t map an EDM.Int32 data type to a uniqueidentifer data type field.
OData entities with nullable properties must be set to match the mapped field in the virtual entity. For example, an OData entity property with Nullable=False must have the mapped field with the Field Requirement attribute set to Business Required.
For retrieve multiple queries, such as when you load data in to a grid, control the size of the dataset returned from the external data source by using the select and filter query parameters.
If not already enabled, system administrators should enable plug-in tracing. Once enabled, all errors from the OData endpoint are captured in the plug-in trace log. More information: System Settings dialog box - Customization tab
Data type mapping
The following table lists the OData Entity Data Model (EDM) data type mappings with the appropriate data type.
|OData Data Type||Data Type|
|Edm.DateTime||Date and Time|
|Edm.DateTimeOffset||Date and Time|
|Edm.Decimal||Decimal Number or Currency|
|Edm.Double||Floating Point Number|
|Edm.String||Single Line of Text or Multiple Lines of Text|
OData EDM data types that are not supported for mapping with virtual entities
Add a data source using the OData v4 Data Provider
This procedure shows you how to use the out-of-box OData Data Provider to use as the virtual entity data source.
Go to Settings > Administration > Virtual Entity Data Sources.
On the actions toolbar, select New.
On the Select Data Provider dialog box, select from the following data sources, and then select OK.
OData v4 Data Provider. Your environment includes an Odata v4 data provider that can be used to connect to data sources that support the OData v4 open standard.
Custom data provider. If you've imported a data provider plug-in, the data provider will appear here. More information: Get started with virtual entities
On the New Data Source properties page, complete the following fields, and then save the record.
Name. Type a name that describes the data source.
Uri. If you are using the OData Data Provider, enter the uri for the OData web service. For example, if you are using the OData provider to connect to a web service hosted in Azure, the URI can look similar to http://contosodataservice.azurewebsites.net/odata/.
Timeout in seconds. Enter the number of seconds to wait for a response from the web service before a data request time-out. For example, enter 30 to wait a maximum of thirty seconds before a time-out occurs.
Pagination mode. Select whether to use client-side or server-side paging to control how query results are paged. The default value is client-side paging. With server-side paging, the server controls how results are paged by using the $skiptoken parameter, which is added to the query string. More information: Skip Token System Query Option ($skiptoken)
- Return inline count. Returns the total number records in the result set. This setting is used to enable next page functionality when you return data to a grid. Use a value of false if your OData endpoint doesn't support the OData $inclinecount parameter. The default value is false.
Request Parameters. Optionally, you can add custom header or query string parameters used to connect to the OData web service, such as authentication parameters to the external service. Select Query String to toggle between header and query string parameter and value. Up to 10 header or query strings can be added.