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) How to test D365 Finance DMF OData APIs using Postman - Part 1

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) Microsoft D365 FO - Test OData API/Web Services by using POSTMAN

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 is OData in D365? ›

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.

What is OData used for? ›

OData helps applications to focus on business logic without worrying about the various API approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc.

What are the multiple paths to integration in Dynamics 365 for operations? ›

Integrations Utilizing Data Management Framework

These are the file-based integration scenarios; file import and file export. There are two out of the box APIs available in Dynamics 365 Finance and Operations to support these scenarios; Data management framework's API and Recurring integrations API.

How do I create an API in D365 F&O? ›

This is done in three parts: Create an application registration (identity), assign access rights, and register in D365.
  1. Create an application registration. ...
  2. Assign Access Rights. ...
  3. Register in D365. ...
  4. Preparing Postman. ...
  5. Setting the URL. ...
  6. Create the body. ...
  7. Create a Test. ...
  8. Test your call.
Jun 14, 2022

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.

What is OData in layman's terms? ›

1. What is OData? The simplest definition of OData would be that it is a standardized protocol built over existing HTTP and REST protocols supporting CRUD (Create, Read, Update, Delete) operations for creating and consuming data APIs.

What is OData with example? ›

The Open Data Protocol (OData) is a data access protocol built on core protocols like HTTP and commonly accepted methodologies like REST for the web. There are various kinds of libraries and tools can be used to consume OData services.

What protocol does OData use? ›

OData is a REST-based protocol for querying and updating data. It is built on technologies like HTTP, ATOM/XML and JSON.

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.

Can we pass data between two plugins in Dynamics 365? ›

If you want to share some information between multiple plugin, you can create entity to hold such information and read in different plugins (plugins not running in same transaction).

Which two types of workflows are available in Dynamics 365 CE? ›

Workflow in Dynamics 365 are two types : Asynchronous workflows and Real-time (synchronous) workflows.

How to create OData service in D365? ›

OData service uses data entities that are created in D365FO.
...
Registering service in D365FO
  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.
Nov 20, 2018

Does Dynamics 365 have an open API? ›

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

Does Dynamics 365 have a REST API? ›

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.

How to use Postman to access d365fo OData endpoint? ›

  1. Start Postman -> manage environments. Select Manage environments to create or update an environment. ...
  2. Bulk edit. Enter key-value pairs as shown in the below image. ...
  3. Go to Tests Tab.

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.

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.

Is OData same as REST API? ›

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.

How do I connect to OData in Excel? ›

To import data into Excel by using an OData data feed

Open Microsoft Excel. Choose Blank workbook to create a workbook. On the Data tab, choose Get External Data group, choose From Other Sources, and then choose From OData Data Feed. The Data Connection Wizard opens.

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.

How to get data from OData? ›

OData services support requests for data via HTTP GET requests.
  1. Requesting Entity Collections. The request below returns the the collection of Person People. ...
  2. Requesting an Individual Entity by ID. ...
  3. Requesting an Individual Property. ...
  4. Requesting an Individual Property Raw Value.
Dec 8, 2022

How do I access OData service? ›

Go to transaction code /IWFND/MAINT_SERVICE . Click on push button Add services . Next screen will appear, give the alias name and execute , Search you for your project . Now click back and go to main screen of transaction /IWFND/MAINT_SERVICE and find your service.

What are the 2 actions allowed in an OData Entity? ›

These OData actions are available for each entity:
  • Get Entities.
  • Get Entity By Key.

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.

What port does OData use? ›

OData access uses TCP/IP port 8086 by default.

Why OData is used in SAP? ›

What Is OData and Why Do We Use It? 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 are the various types of OData services? ›

OData Service Examples w.r.t. Business cases:
  • Odata Service to get one table records via RFC. ...
  • Odata Service to post multiple table as a request in a single call. ...
  • Odata Service to get multiple table response in a single call. ...
  • Odata Service to consume a REST-Services.
Apr 10, 2018

What are the two components of the OData runtime? ›

OData Runtime Runs instances of MPC (Model Provider Class) and DPC (Data Provider Class) that provide meta data information, acquire data and perform requested operations on the data.

How to use OData in Web API? ›

Additional resources
  1. Software versions used in the tutorial.
  2. Tutorial versions.
  3. Create the Visual Studio Project.
  4. Install the OData packages.
  5. Add a model class.
  6. Enable Entity Framework.
  7. Configure the OData endpoint.
  8. Add the OData controller.
May 11, 2022

What are the limitations of plugins Dynamics 365? ›

One of the main limitations that you will be exposed to in any dynamics CRM online project is the two-minute time limit for the Plugin to finish execution, which will be a problem if you have huge data and huge number of records. Plugins that needs more than 2 minutes to execute will throw a timeout exceptions.

What is the difference between Dataverse and Dynamics 365? ›

In short, Dataverse is a ready-to-use server that offers a security layer, a business layer, a data access layer and so on. Dynamics CRM solutions store their data on a Dynamics server, the business logic is implemented via plugins on Dataverse.

How many plugins is too many? ›

Too many plugins can lead to security breaches on your site, site crashes, bad performance, slow loading speeds, and more. A good rule of thumb is to never exceed 20 plugins. If your site is hosted on shared or budget cloud hosting, try not to use more than 5 plugins.

What are the 3 basic components of workflow? ›

The three basic components of a workflow diagram are input, transformation, output. Every step within a workflow is assigned one of these statuses.

What are the four types of workflow actions? ›

There are four different Rule Actions allowed in Workflow Rules:
  • Create a Task.
  • Send an Email Alert.
  • Send an Outbound Message.
  • Update a Record.
Jan 2, 2020

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.

How many ways we can create OData service? ›

Creating an OData service you can use: (1) “Classical” ABAP (needed for ABAP platform <= 7.4), which comes with significant higher efforts. (2) “SAP Fiori programing model” (ABAP platform = 7.5. 4) or SAP BTP, Steampunk/RAP and CAP (SAP BTP) both using CDS views.

How to perform CRUD operations in OData? ›

So correct steps are,
  1. Execute GET to read single entity /sap/opu/odata/sap/ZUSERINFO_SRV/UserCollection('Test')
  2. Click Use as Request button.
  3. Update your request properties.
  4. Select HTTP method as POST.
  5. Query as /sap/opu/odata/sap/ZUSERINFO_SRV/UserCollection and execute.
Mar 6, 2014

Is OData a webservice? ›

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.

Is OData SQL? ›

OData is a widely accepted open standard for data access over the Internet. OData protocol provides powerful features for querying data via URLs, similar to SQL. This article helps to quickly understand how to query data via OData and shows how OData features correspond to the most commonly used SQL features.

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.

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.

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. Integration Frameworks within Dynamics 365 Finance & Operations
(Microsoft Dynamics 365)
4. Dynamics 365 Finance & Operations - Module 11: Introduction to Advanced Development Topics
(Microsoft Dynamics 365)
5. Integrating with Dynamics 365 F&O: how & what to do
(India Dynamics 365 & Power Community)
6. Office Integration with Dynamics 365 Finance & Operations
(Microsoft Dynamics 365)
Top Articles
Latest Posts
Article information

Author: Rev. Leonie Wyman

Last Updated: 11/20/2022

Views: 5700

Rating: 4.9 / 5 (79 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Rev. Leonie Wyman

Birthday: 1993-07-01

Address: Suite 763 6272 Lang Bypass, New Xochitlport, VT 72704-3308

Phone: +22014484519944

Job: Banking Officer

Hobby: Sailing, Gaming, Basketball, Calligraphy, Mycology, Astronomy, Juggling

Introduction: My name is Rev. Leonie Wyman, I am a colorful, tasty, splendid, fair, witty, gorgeous, splendid person who loves writing and wants to share my knowledge and understanding with you.