All the new services launched under OData use OAuth 2.0 for authentication. There are two approaches for the authentication: 1) a native client application that requires a user name and password for authentication and authorization, and 2) a web application confidential client where the authorization server assigns a confidential password to the client application. With native application, users will be required to change their password every time it expires, which is not the case with web application; it simply uses an app ID and client secret key which greatly reduces the overhead of maintaining password.
Whenever you enter the credentials for authentication, it goes to the Azure Active Directory server (http://login.windows.net/<tenant>). After verifying the credentials, the Active Directory server authenticates it by providing an access token which has to be passed in the header of the request, as shown below:
Using OData in D365FO
OData service uses data entities that are created in D365FO. Currently, Microsoft offers about 1900+ standard data entities; however, you can also create your own data entity based on your requirement. The important thing to take note of is that the IsPublic property of data entity should be set to ‘Yes’. Only those data entities with IsPublic property ‘Yes’ are exposed in the OData service and can be used for integration purposes.
In order to consume the OData service (web application) and use it for create-read-update-delete or (CRUD operations) in Dynamics 365FO, you will first be required to feed in some details to authenticate the request, which includes creating a new application in your Azure portal. Follow the steps mentioned below to generate an app ID and the client secret key.
Creating an application in Azure
1. Browse to the Azure portal using https://portal.azure.com
2. Login to portal using admin access.
3. Navigate to Azure Application → App registration → New application registration.
4. Enter the below mentioned details on the Create form and click the ‘Create’ button.
Name: <Your application name>
Application type: Web App / API
Sign-on URL: <Your Dynamics 365 URL>/data
5. The system will create a new application. Copy the application ID.
6. Navigate to Settings → Keys and Generate client secret key.
7. Insert the following details in the Password tab and click ‘Save’.
Key Description: OData
Duration: Never expires
8. The system will create a new key. Copy the value of client Secret as shown. Please note that you will not be able to retrieve this later.
Your application is now generated which can be used for authentication. However, since the application doesn’t have access to carry out read/write operations in D365, you need to provide privileges to the application.
Adding permissions to Azure App
1. On the application page, go to Settings and click on ‘Required permissions’.
2. On the Required Permissions form, click ‘Add new’ and then select API. In the API list, select Microsoft Dynamics ERP (Microsoft.ERP
) API and then click ‘Select’.
3. After selecting the API, you need to add permissions. For this, click on ‘Select permissions’. Add all the permissions mentioned under Delegated permissions and then click ‘Select’. After Selecting Permissions, click “Done”.
4. Next, on the Required Permissions form, click on “Grant permissions” and then “Yes” to provide consent to the application.
Registering service in D365FO
Once you have successfully created a new application using OData services, you have to then add this application in D365. This will allow the application to access data that resides within D365. Please note that if you miss this step, you may get a Forbidden error while calling the service. Follow the steps below to add the application in D365:
1. Open your D365 environment.
2. Navigate to System administration → Setup → Azure Active Directory application.
3. Enter the application ID and name for the application.
4. Assign a user with admin rights to access the data.
Creating visual studio project for consuming OData service
Now that you have created the application and its client secret key, you can start consuming OData service in .NET application.
Creating OData Utility
1. Download and install OData client code generator in your visual studio environment. Navigate to Tools → Extensions and updates and look for OData client code generator in the search tab.
The tool generates a .tt file in the Visual Studio project, a transformation file that will generate a class by reading the metadata XML file from D365 metadata schema.
2. Create a new C# project of type Class Library with the name ODataUtility. Add this project to a new solution with the name ODataServices.
3. You can delete the default class (class1) that is created.
4. Right click on project and click “New item”. In the Add New Item dialog, search for “OData Client”, which will be the class type. This will generate Proxy classes from the OData v4 service. The name of the class will be ODataClient.tt
5. When you get the following message box, click on Cancel.
6. Open ODataClient.tt file and find the code public const string MetadataDocumentUri = “”;
and replace “” by your <D365FO URL>/data/$metadata. Next, go to the code public const string TempFilePath = “”;.
Pass any temp path here (e.g. @”C:\Temp\Edmx.xml”). This path will be used to navigate to the Edmx xml file generated while processing the tt file. Please note that this will only be available in the OData Client Code Generator 7.5.1 version. It is introduced to resolve String buffer exceed error while compiling the .cs file generated using tt file. Save the file and you will get the same message box (as step #5) again. Click on OK.
7. After sometime, you will find all of the D365FO OData service endpoints appearing under the ODataClient. If you are using Update 15, you may get an ambiguity error while running the .tt file. This is because there is an Entity with name “ItemType” and also an enum with the same name. So, while generating the class, it gets confused and throws an ambiguity error.
To resolve this issue, you need to first open the URL <D365FO URL>/data/$metadata and save the XML schema generated.
Open that XML file in notepad, find <EntityType Name=”ItemType”> and replace it with find <EntityType Name=”ItemTypes”>. You need to add s as the suffix so both enum and entity can work differently.
Now in MetadataDocumentUri, you have to specify this file name instead of D365 URL. The purpose of the .tt file is to read the XML and generate a .cs file which contains classes that can be used in your code. It will create classes for all the entities and enum specified in the XML schema. So, you can either enter the XML file or D365 metadata URL as both are the same.
8. After the process is completed, verify if the .cs file generated is proper. Expand the .tt file and then the .cs file. You will see all the classes generated from the .tt file.
9. Right click on the project and click on Build.
Creating Authentication Utility
1. Create a new C# project of type Class Library with the name AuthenticationUtility. Add this project to the existing ODataServices solution.
2. Install the following NuGet Packages:
- Microsoft.OData.Client (this will automatically install a few more dependent packages)
3. You can delete the default class (class1) that is created.
4. Right click on the project and click on New Item. In the Add New Item dialog, select Code → Class and create a new class with the name ClientConfiguration.cs.
5. Right click on the project and click on New Item. In the Add New Item dialog, select Code → Class and create a new class with the name OAuthHelper.cs.
6. Right click on the project and click on Build. This is the authentication utility that will get the parameters and provide you with a bearer access token that you can pass in header.
Creating the console application
1. Create a new C# project of type Console Application with the name ODataConsoleApplication. Add this project to the existing ODataServices solution.
2. Install the following NuGet Packages
- Microsoft.OData.Client (this will automatically install few more dependent packages)
3. Install the following reference from the solution:
4. Open the program.cs class generated in the console application.
5. Right click on the project and click on “Build”.
6. Right click on “ODataConsoleApplication” and click on “Set as StartUp Project”.
7. Build the project and click on “Execute”.
This will create a new customer with address and contact information.
Please note that whenever you add an entity in the DataServiceCollection object, it will start change tracking your entity. That means it will try to update only those properties which are changed.
Please note that you are passing the SaveChangesOptions.PostOnlySetProperties in the save changes context. It will actually post only those objects which have been defined. If you don’t pass this property, it may throw an error because some fields in the entity cannot be set, and so your request will pass a null value in this field. Therefore, it is a good practice to set SaveChangesOptions.PostOnlySetProperties while calling the saved changes.
Enable seamless integration
For higher productivity, every ERP system requires integration with one or many third-party integrations – either desktop or web-based – including integration for inventory, purchase orders, sales orders, transfer orders, etc. Since D365FO has many data entities exposed to third-party applications, OData helps create a robust solution for businesses by enabling data access between them. For example, a franchise management portal can call the Dynamics 365FO data entity SalesOrdersHeader and SalesOrderLines, respectively. No matter what the requirement, with OData, you can drive seamless integration between various products and carry out all your business processes with higher efficiency.
About the Author - Angna Thakkar
Angna Thakkar is a competent Senior Project Manager, Microsoft Dynamics AX Technical at Indusa with over 10 years of experience in managing multi-disciplinary teams of varying sizes and complex programs of work. She is always committed to professionalism, highly organized, able to see the big picture while paying attention to small details.
Contributing Author: Malavika Nityanandam