Working with the OData Endpoint in Dynamics 365 for Operations

 

The OData endpoint is a new REST-based service that allows for integrating with Dynamics 365 for Operations. Below are some tips to help with using an OData client to authenticate and use methods to read and write data in the system.

Data Entities

Data Entities that are marked ‘Yes’ for the ‘Is Public’ property will be available as an OData endpoint. You can consume this OData endpoint in your external application such as a .Net application for integration scenarios.

In the screenshot below, I have created a custom data entity called CPRCustCreditRatingEntity. Note the Is Public, Public Collection Name and Public Entity Name properties:

When viewed using the Chrome browser, I can see my custom Data entity is available:

Tip: If using IE to view the OData endpoint, you might have to open the JSON results in a separate file download. Chrome will automatically show the JSON results in the browser.

Creating a OData Client Application

Use the OData v4 Client Code Generator in your Visual Studio application to build the OData entity proxy classes. This can be downloaded and installed from with Visual Studio. Once it is installed, you can add the OData client to the application. In the following screenshots, I downloaded it and then added it to my C# Console application project:

This will create a file with an extension of tt which stands for Text Template. Update the MetadataDocumentUri string value in the tt file so it contains your OData metadata endpoint. For example, mine is:

public const string MetadataDocumentUri = “https://usnconeboxax1aos.cloud.onebox.dynamics.com/data/$metadata”;

Lastly, right click on the tt file and choose to ‘Run custom tool’. This will read the metadata and build a large class file (45+ MB). It may take several minutes to complete. You can explore the CS file when it completes.

Using the generated proxy classes

The generated proxy classes let you instantiate the data entity objects, set properties, and call methods to interact with the OData endpoint. The following is an example of reading a CustCreditRating record using a LINQ (System.Linq) query pattern:

 

 

 

 

 

 

C#

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91

//Get Single CustCreditRating Console.WriteLine("Get a single CustCreditRating instance..."); CustCreditRating existCustCreditRating = GetCustCreditRating("USMF", "US-010"); Console.WriteLine("Credit Rating for {0} is {1}. Press Enter.", existCustCreditRating.CustomerAccount, existCustCreditRating.CreditRating); Console.ReadLine();   The GetCustCreditRating method: #region Get Single CustCreditRating         private static CustCreditRating GetCustCreditRating(string targetAXLegalEntity, string customerAccount)         {             context.SendingRequest2 += new EventHandler<SendingRequest2EventArgs>(delegate (object sender, SendingRequest2EventArgs e)             {                 var authenticationHeader = OAuthHelper.GetAuthenticationHeader();                 e.RequestMessage.SetHeader(OAuthHelper.OAuthHeader, authenticationHeader);             });               var custCreditRatingQuery = from entity in context.CustCreditRatings                                         where entity.DataAreaId == targetAXLegalEntity                               && entity.CustomerAccount == customerAccount                               select entity;               return (custCreditRatingQuery.Count() > 0) ? custCreditRatingQuery.First() : null;         } #endregion   The following code is a complete example of creating multiple Customer records using the OData endpoint: using System; using AuthenticationUtility; using Microsoft.OData.Client; using CustomerOdataClient.Microsoft.Dynamics.DataEntities;   namespace CustomerOdataClient {     class Program     {         private static string ODataEntityPath = ClientConfiguration.Default.ODataEndpointUri;         private static Uri oDataUri = new Uri(ODataEntityPath, UriKind.Absolute);         private static Resources context = new Resources(oDataUri);             static void Main(string[] args)         {             Console.WriteLine("Set HTTP header...");             context.SendingRequest2 += new EventHandler<SendingRequest2EventArgs>(delegate (object sender, SendingRequest2EventArgs e)             {                 var authenticationHeader = OAuthHelper.GetAuthenticationHeader();                 e.RequestMessage.SetHeader(OAuthHelper.OAuthHeader, authenticationHeader);             });               Console.WriteLine("Creating new customer using Data Entity OData...");             Customer myCustomer = new Customer();             DataServiceCollection<Customer> customersCollection = new DataServiceCollection<Customer>(context);               customersCollection.Add(myCustomer);                          myCustomer.CustomerAccount = "US-X11111";             myCustomer.Name = "ABC Trees  111";             myCustomer.CustomerGroupId = "10";             myCustomer.SalesCurrencyCode = "USD";             myCustomer.CreditRating = "Excellent";             myCustomer.AddressCountryRegionId = "USA";               #region Create multiple customers                          Customer myCustomer2 = new Customer();                          customersCollection.Add(myCustomer2);               myCustomer2.CustomerAccount = "US-X22222";             myCustomer2.Name = "ABC Rains vb";             myCustomer2.CustomerGroupId = "10";             //myCustomer2.SalesCurrencyCode = "USD";             myCustomer2.CreditRating = "Excellent";             myCustomer2.AddressCountryRegionId = "USA";                          #endregion               DataServiceResponse response = null;             try             {                 response = context.SaveChanges(SaveChangesOptions.PostOnlySetProperties | SaveChangesOptions.BatchWithSingleChangeset);                 Console.WriteLine("created ok");             }             catch (Exception ex)             {                 Console.WriteLine(ex.Message + ex.InnerException);             }             Console.ReadLine();         }     } }

In the code above, two Customer objects are being created and passed into a DataServiceCollection named customersCollection. I am using the optional SaveChangesOptions.BatchWithSingleChangeset enum in the SaveChanges method. This means if one of the Customer objects fails validation then neither of the Customer objects are created. Since both Customers run under one batch in the HTTP call to the OData endpoint if one fails then they both do.

Lastly, the Resources object that has been instantiated as ‘context’, is using objects from the AuthenticationUtility project to help with authentication. This is a C# library project made of two classes to help in setting up the authentication to the OData endpoint and retrieving the authorization token. This AuthenticationUtility project can be found in Microsoft’s Dynamics AX Github repository at https://github.com/Microsoft/Dynamics-AX-Integration/tree/master/ServiceSamples/AuthenticationUtility.

Hopefully, this post can steer you in the right direction on how to successfully interact with the OData entities in Microsoft Dynamics 365 for Operations.