Open Data Protocol (OData) - Finance & Operations | Dynamics 365 (2023)

  • Article
  • 8 minutes to read

This article provides information about Open Data Protocol (OData) and explains how you can use OData V4 to expose updatable views.

What is OData?

OData is a standard protocol for creating and consuming data. The purpose of OData is to provide a protocol that is based on Representational State Transfer (REST) for create, read, update, and delete (CRUD) operations. OData applies web technologies such as HTTP and JavaScript Object Notation (JSON) to provide access to information from various programs. OData provides the following benefits:

  • It lets developers interact with data by using RESTful web services.
  • It provides a simple and uniform way to share data in a discoverable manner.
  • It enables broad integration across products.
  • It enables integration by using the HTTP protocol stack.

For more information about OData, see the following webpages.

TopicWebpage
OData standardsOData Version 4.01 documentation
OData: Data access for the web, the cloud, mobile devices, and moreOData in ASP.NET Web API

The public OData service endpoint enables access to data in a consistent manner across a broad range of clients. To see a list of all the entities that are exposed, open the OData service root URL. The URL for the service root on your system has the following format: [Your organization's root URL]/data

Note

OData actions added via extensions are currently not supported.

Addressing

The following table describes the resources and the corresponding URLs in the Fleet Management sample.

ResourceURLDescription
Service endpoint[Your organization's root URL]/data/The root service endpoint for OData entities
Entity collection[Your organization's root URL]/data/CustomersThe collection of all customers
Entity[Your organization's root URL]/data/Customers("[key]")A single entity from the entity collection
Navigation property[Your organization's root URL]/data/Customers("[key]")/ReservationsThe navigation from a customer to that customer's reservations
Property[Your organization's root URL]/data/Customers("[key]")/FirstNameThe customer's first name

OData services

We provide an OData REST endpoint. This endpoint exposes all the data entities that are marked as IsPublic in the Application Object Tree (AOT). It supports complete CRUD (create, retrieve, update, and delete)functionality that users can use to insert and retrieve data from the system. Detailed labs for this feature are on the LCS methodology.

(Video) OData and Dynamics 365 - Detailed Analysis and Usage

Code examples for consuming ODataservices are available in the Microsoft Dynamics AX Integration GitHub repository.

Supported features from the OData specification

The following are the high-level features that are enabled for the OData service, per the OData specification.

  • CRUD support is handled through HTTP verb support for POST, PATCH, PUT, and DELETE.

  • Available query options are:

    • $filter
    • $count
    • $orderby
    • $skip
    • $top
    • $expand (only first-level expansion is supported)
    • $select
  • The OData service supports serving driven paging with a maximum page size of 10,000.

For more information, see: OData actions that are bound to entities.

Filter details

There are built-in operators for $filter:

  • Equals (eq)
  • Not equals (ne)
  • Greater than (gt)
  • Greater than or equal (ge)
  • Less than (lt)
  • Less than or equal (le)
  • And
  • Or
  • Not
  • Addition (add)
  • Subtraction (sub)
  • Multiplication (mul)
  • Division (div)
  • Decimal division (divby)
  • Modulo (mod)
  • Precedence grouping ({ })

You can also use the Contains option with $filter requests. It has been implemented as a wildcard character. For example: http://host/service/EntitySet?$filter=StringField eq '*retail*'

(Video) EP06 ODATA and REST APIs for D365 FinOps

The operators 'has' and 'in' are not supported.

For more information, see OData operators.

Batch requests

Batch requests are supported in the OData service. For more information, see OData batch requests.

Metadata annotations

/data/$metadata provides annotations. EnumType is support in $metadata.

Open Data Protocol (OData) - Finance & Operations | Dynamics 365 (1)

Cross-company behavior

By default, OData returns onlydata that belongs to the user's default company. To see data from outside the user's default company, specify the ?cross-company=true query option. This option will return data from all companies that the user has access to.

Example: http://[baseURI\]/data/FleetCustomers?cross-company=true

To filter by a particular company that isn't your default company, use the following syntax:

http://[baseURI\]/data/FleetCustomers?$filter=dataAreaId eq 'usrt'&cross-company=true

Validate methods

The following table summarizes the validate methods that the OData stack calls implicitly on the corresponding data entity.

ODataMethods (listed in the order in which they are called)
Create
  1. Clear()
  2. Initvalue()
  3. PropertyInfo.SetValue() for all specified fields in the request
  4. Validatefield()
  5. Defaultrow
  6. Validatewrite()
  7. Write()
Update
  1. Forupdate()
  2. Reread()
  3. Clear()
  4. Initvalue()
  5. PropertyInfo.SetValue() for all specified fields in the request
  6. Validatefield()
  7. Defaultrow()
  8. Validatewrite()
  9. Write()
Delete
  1. Forupdate()
  2. Reread()
  3. checkRestrictedDeleteActions()
  4. Validatedelete()
  5. Delete()

Exposing OData entities

OData entities are based on the concept of an updatable view. When the IsPublic property for an updatable view is set to TRUE, that view is exposed as a top-level OData entity.

(Video) Microsoft D365 FO - Test OData API/Web Services by using POSTMAN

Setting navigation properties between OData entities

Links between OData entities are described by a navigation property. Navigation properties describe the navigation from one end of an association to the other end.

Adding actions on OData entities

Actions let you inject behaviors into the data model. To add actions, add a method to the updatable view, and decorate that method with specific attributes. Here is an example.

[SysODataActionAttribute("CalcMaintenanceDuration", true)]public int CalculateMaintenanceDuration(){ //do something return 0;}

In this example, the SysODataActionAttribute class decorates the CalculateMaintenanceDuration method that is exposed as an action. The first argument of the attribute is the publicly exposed name of the action, and the second argument indicates whether this action is always available. Methods that are exposed as actions can return any primitive type or another public updatable view. After this method is exposed, it appears in the OData $metadata. Here is an example.

<Action Name="CalcMaintenanceDuration" IsBound="true"> <Parameter Name="ViewMaintenance" Type="Microsoft.Dynamics.AX.Resources.ViewMaintenance"/> <ReturnType Type="Edm.String" /></Action>

The following example of an OData action takes in a parameter and returns a list.

[SysODataActionAttribute("GetColors", true), SysODataCollectionAttribute("return", Types::Record, "CarColor")]public List GetColorsByAvailability(boolean onlyAvailableVehicles){ List returnList = new List(Types::Record); // do something return returnList;}

In this example, the SysODataCollectionAttribute class enables OData to expose strongly typed collections from X++. This class takes in three parameters:

  • The name of the parameter that is a list (Use return for the return value of the method.)
  • The X++ type of the members of this list
  • The public name of the OData resource that is contained in the collection

After these actions are exposed, they can be invoked from the service root URL.

You can find actions that are defined on data entities by searching for the SysODataActionAttribute attribute in the source code.

Querying or browsing an OData endpoint

OData enables an SQL-like language that lets you create rich queries against the database, so that the results include only the data items that you want. To create a query, append criteria to the resource path. For example, you can query the Customers entity collection by appending the following query options in your browser.

URLDescription
[Your organization's root URL]/data/CustomersList all the customers.
[Your organization's root URL]/data/Customers?$top=3List the first three records.
[Your organization's root URL]/data/Customers?$select=FirstName,LastNameList all the customers, but show only the first name and last name properties.
[Your organization's root URL]/data/Customers?$format=jsonList all the customers in a JSON format that can be used to interact with JavaScript clients.

The OData protocol supports many similar filtering and querying options on entities. For the full set of query options, see Windows Communication Foundation.

Using Enums

Enums are under namespaceMicrosoft.Dynamics.DataEntities. Enums can be included in an OData query is by using the following syntax.

Microsoft.Dynamics.DataEntities.Gender'Unknown'

(Video) How to test D365 Finance DMF OData APIs using Postman - Part 1

Microsoft.Dynamics.DataEntities.NoYes'Yes'

An example query for using the above enum values is shown below.

https://environment.cloud.onebox.dynamics.com/data/CustomersV3?\$filter=PersonGender eq Microsoft.Dynamics.DataEntities.Gender'Unknown'

https://environment.cloud.onebox.dynamics.com/data/Currencies?\$filter=ReferenceCurrencyForTriangulation eq Microsoft.Dynamics.DataEntities.NoYes'No'

The operations supported for enums are eq and ne.

Authentication

OData sits on the same authentication stack as the server. For more information about the authentication, see Service endpoints overview.

Tips and tricks

Run multiple requests in a single transaction

The OData batch framework uses changesets. Each changeset contains a list of requests that should be treated as single atomic unit. In other words, either all the requests are run successfully or, if any request fails, none of the requests are run successfully. The following example shows how to send a batch request that has a list of requests in a single changeset.

The SaveChangesOptions.BatchWithSingleChangeset option in SaveChanges() helps guarantee that all requests are bundled into a single changeset.

public static void CreateProductColors(Resources context){ var productColorsCollection = new DataServiceCollection<ProductColor>(context); var color1 = new ProductColor(); productColorsCollection.Add(color); color1.ColorId = "New Color1"; // set any other properties needed var color2 = new ProductColor(); productColorsCollection.Add(color1); color2.ColorId = "New Color2"; // set any other properties needed context.SaveChanges(SaveChangesOptions.BatchWithSingleChangeset);}

Prevent unset records from being posted when you use an OData client

When you create a new record by using an OData client, as shown in example 1, properties that aren't set are included in the body of the request, and default values are assigned to them. To prevent this behavior and post only properties that are set explicitly, use the SaveChangesOptions.PostOnlySetProperties option in SaveChanges(), as shown in example 2.

Example 1

public static void CreateVendor(Resources context){ var vendorCollection = new DataServiceCollection<Vendor>(context); var vendor = new Vendor(); vendorCollection.Add(vendor); // set properties context.SaveChanges();}

Example 2

(Video) D365FO, OData and Custom Apps: High Performance Integration Scenarios - FinOps 2021

public static void CreateVendor(Resources context){ var vendorCollection = new DataServiceCollection<Vendor>(context); var vendor = new Vendor(); vendorCollection.Add(vendor); // set properties // Save specifying PostOnlySetProperties flag context.SaveChanges(SaveChangesOptions.PostOnlySetProperties);}

Handling duplicate names between enums and entities in metadata

There are instances where enums and entities share the same name. This name duplication results in OData client code generation errors. To recover from this error, the helper code in GitHub can be used to identify duplicate name instances that must be removed. The generated metadata document can be used for further processing of the OData logic on the client side.

Array fields

OData does not support array fields in entities. This must be taken into consideration when designing entities that will be used with OData.

After restarting AOS, the first OData call may take a long time to process

The first OData call processed by an AOS that was restarted may take a long time to process because the metadata is not being cached. This latency can be avoided by warming up OData on AOS startup. For more details, see Build OData metadata cache when the AOS starts.

FAQs

What does open data protocol OData do? ›

The OData Protocol is an application-level protocol for interacting with data via RESTful interfaces. It supports the description of data models, editing and querying of data according to those models.

What is REST API in D365? ›

Dynamics 365 REST APIs

Dynamics 365 unifies the capabilities of CRM business software and ERP systems by providing intelligent applications that seamlessly work together in the cloud. For more information, see Microsoft Dynamics 365 documentation.

What is the point of OData? ›

The purpose of OData is to provide a protocol that is based on Representational State Transfer (REST) for create, read, update, and delete (CRUD) operations. OData applies web technologies such as HTTP and JavaScript Object Notation (JSON) to provide access to information from various programs.

What is the purpose of OData service? ›

OData is used to define best practices that are required to build and consume RESTful APIs. It helps you to find out changes, defining functions for reusable procedures and sending batch requests etc. OData provides facility for extension to fulfill any custom needs of your RESTful APIs.

Does Dynamics 365 have an open API? ›

Standard APIs for Business Central are available as an OpenAPI Specification (OAS).

Is Dynamics 365 being discontinued? ›

The Microsoft Dynamics 365 (Preview) app for Windows was deprecated on June 20, 2022. The app is no longer supported.

What is the difference between REST API and Restfull API? ›

Put simply, there are no differences between REST and RESTful as far as APIs are concerned. REST is the set of constraints. RESTful refers to an API adhering to those constraints. It can be used in web services, applications, and software.

What is D365 F&O called now? ›

What is Microsoft Dynamics 365 Finance and Operations? Formally known as Dynamics AX, Dynamics 365 Finance and Operations (now, they are called as Finance and Supply Chain Management) is a robust Microsoft Dynamics ERP well suited for large enterprise organizations (more than 500 employees).

What are the modules in D365 F&O? ›

Microsoft Dynamics 365 Finance and Operations Modules

Commerce. Finance. Supply Chain Management. Human Resources.

What are the 3 types of APIs? ›

Today, there are three categories of API protocols or architectures: REST, RPC and SOAP. These might be dubbed "formats," each with unique characteristics and tradeoffs and employed for different purposes. REST.

What are the 4 most common REST API operations? ›

For REST APIs built on HTTP, the uniform interface includes using standard HTTP verbs to perform operations on resources. The most common operations are GET, POST, PUT, PATCH, and DELETE.

Is OData outdated? ›

It was deprecated with Dynamics 365 Customer Engagement v8. 0. Also known as the OData endpoint or REST endpoint when it was released, this endpoint only provides the ability to perform create, retrieve, update, and delete operations on tables.

What is better than OData? ›

GraphQL is a self-contained and powerful query language, including all the things for querying and implementing the Rest API. So it is more powerful in comparison to OData.

Is OData a REST service? ›

OData is a web based protocol that defines a set of best practices for building and consuming RESTful web services. OData is a way to create RESTful web services thus an implementation of REST.

What is the difference between API and OData? ›

The REST standard defines principles that must be adhered to by any REST API. OData builds on top of the REST framework to define best practices for building REST APIs—including the HTTP message format, how to query the API, and more.

How does OData work internally? ›

OData fetches the data from one or many database and tables with the help of select, insert, delete or modify statements. It is based on the HTTP framework. In other words in the application layer, we have an internal table and that internal table data is passed out through OData to HTTP.

What is the difference between OData and JSON? ›

JSON is just a data-interchange format based on JavaScript. REST is an architecture style whereas OData is a specific implemenation of REST designed to generate and consume data, which supports two formats, AtomPub and JSON.

What is the difference between API and open API? ›

An open API has access restrictions because they are openly accessible to the public and can be invoked from anywhere on the open internet. On the other hand, a closed API, also known as a private API, is not accessible openly on the internet.

Is open API widely used? ›

There are several specifications available that describe RESTful APIs. OpenAPI is among the most well-known and widely used. The other two formats used for REST APIs are RAML and API Blueprint.

What database is behind Dynamics 365? ›

Dynamics 365 CRM - SQL server is the database used for Dynamics 365 system and it is one of the pre-requisites to install Dynamics 365.

Does Dynamics 365 have future? ›

The future projects of Microsoft Dynamics 365 will include more intelligence and cognitive services, using companies' data proactively to digitally transform businesses. Microsoft Dynamics 365 continues to evolve — the pace of change is increasing, and projects will be bigger, more complex and more fun.

Is Dynamics 365 better than SAP? ›

They help users operating in retail and provide them with product development functions to order processing and quality control functionalities. However, Microsoft Dynamics 365 has proved to be much more efficient than SAP in multiple attributes, some of which are listed below.

Is Dynamics 365 better than Salesforce? ›

We recommend Salesforce for younger companies and smaller businesses because of its lower starting price and its extensive integrations with third-party applications. Microsoft Dynamics 365 is better for larger and more established businesses, especially ones that already use the Microsoft Office suite extensively.

Is RESTful API frontend or backend? ›

REST and GraphQL are both standard ways to develop backend APIs. But over the past decade REST APIs have dominated as a choice for developing backend API's. And many companies and developers use it actively in their projects. But REST has some limitations, and there's another alternative available – GraphQL.

Is REST API always JSON? ›

REST APIs should accept JSON for request payload and also send responses to JSON. JSON is the standard for transferring data. Almost every networked technology can use it: JavaScript has built-in methods to encode and decode JSON either through the Fetch API or another HTTP client.

Why is it called REST? ›

REST stands for Representational State Transfer. This means that when a client requests a resource using a REST API, the server transfers back the current state of the resource in a standardized representation.

Does OData service need to be activated? ›

Log on to the SAP Fiori server backend using SAP GUI. Enter transaction Activate and Maintain Services (/N/IWFND/MAINT_SERVICE). Choose Add Service. For the System Alias field, use the value help to select the correct service.

What are the methods in OData? ›

The OData service interface has a fixed number of operations that have uniform meaning across all the resources it can act on. These operations are retrieve, create, update and delete and they map to the GET, POST, PUT/MERGE and DELETE HTTP methods. Each of them acts on a resource that is indicated using a URI.

Is Dynamics 365 a CRM or ERP? ›

Microsoft Dynamics 365 is a cloud-based business applications platform that combines components of customer relationship management (CRM) and enterprise resource planning (ERP), along with productivity applications and artificial intelligence tools.

What is the difference between Dynamics 365 F&O and Business Central? ›

Business Central Vs Dynamics 365 For Finance and Operations

Dynamics Business Central is an all-in-one solution that offers integration with the wider modules although it is primary purpose is to act as a stand alone solution whilst Dynamics 365 is a modular solution where you can pick functions that you want to add.

What is main method in D365FO? ›

A main method is a class method that is run directly from a menu option. The method should only create an instance of the object and then call the required member methods. The _args parameter lets you transfer data to the method. static void main (Args _args) { // Your code here. }

How many types of forms does Dynamics 365 have? ›

In Microsoft Dynamics 365, we can create 4 types of Forms: 1. Main Form: When you create a new form for an entity, its form type is Main.

What is the difference between OData and OpenAPI? ›

OData is based on a powerful set of concepts and conventions which allow rich interaction with OData services. OpenAPI on the other hand does not assume or rely on any conventions and requires explicit and – from an OData perspective – relatively low-level and repetitive description of each service feature.

How is OData different from REST? ›

OData differs from REST and gains its focus on business logic in its feature set. Whereas REST is an architectural style solely concerned with data transfer via web service APIs, OData builds upon that architecture with a set of metadata that can be easily integrated into most programming and scripting languages.

What is OData Protocol in SAP? ›

OData is a Web protocol for querying and updating data, applying and building on Web technologies such as HTTP, Atom Publishing Protocol (AtomPub), and RSS (Really Simple Syndication) to provide access to information from a variety of applications.

What is the use of OData in Web API? ›

The Open Data Protocol (OData) is a data access protocol for the web. OData provides a uniform way to query and manipulate data sets through CRUD operations (create, read, update, and delete). ASP.NET Web API supports both v3 and v4 of the protocol.

What language is OpenAPI? ›

Features. The OpenAPI Specification is language-agnostic. With OpenAPI's declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code.

Is OData an API? ›

OData RESTful APIs are easy to consume. The OData metadata, a machine-readable description of the data model of the APIs, enables the creation of powerful generic client proxies and tools. Some of them can help you interact with OData even without knowing anything about the protocol.

Is OData a web service? ›

The Open Data Protocol (OData) is a web protocol that is designed for querying tabular data and provides you with an alternative to SOAP-based web services.

Videos

1. Power BI Odata connection to Dynamics 365 Finance and Operations data entities
(Andrew Karasev)
2. Dynamics 365 | Virtual Entity | External Data Sources | OData
(JourneyTEAM)
3. How to use Dynamics 365 Portal OData feed?
(oakley2500)
4. Integrating with Dynamics 365 F&O: how & what to do
(India Dynamics 365 & Power Community)
5. A demo on using Power Automate apps to Extend Dynamics 365 FinOps - Scheduled Flow with OData Action
(Michael Cobbin - Dynamics 365)
6. Nathan Clouse - Integrating with OData Deep Dive
(DynamicsCon hosted by Dynamics User Group)
Top Articles
Latest Posts
Article information

Author: Kareem Mueller DO

Last Updated: 10/28/2022

Views: 6437

Rating: 4.6 / 5 (46 voted)

Reviews: 85% of readers found this page helpful

Author information

Name: Kareem Mueller DO

Birthday: 1997-01-04

Address: Apt. 156 12935 Runolfsdottir Mission, Greenfort, MN 74384-6749

Phone: +16704982844747

Job: Corporate Administration Planner

Hobby: Mountain biking, Jewelry making, Stone skipping, Lacemaking, Knife making, Scrapbooking, Letterboxing

Introduction: My name is Kareem Mueller DO, I am a vivacious, super, thoughtful, excited, handsome, beautiful, combative person who loves writing and wants to share my knowledge and understanding with you.