D365 X++ OData Actions

What are OData actions and when would we use them?

D365 OData Actions are very similar to custom services in D365, as both allow for business logic to be ran via API calls.  OData Actions are built on top of data entities which can already be used to make RESTful API calls to evoke CRUD operations.  A developer might choose to use this approach over custom services for a few reasons:

1. It is quick and easy to create instance methods to process a single record in the entity. Additionally, the code interacting with an entity conceptually lives in the same places as the entity giving clarity to all available operations.
2. Services, services groups, service classes, and additional security are not required to expose custom business logic, therefore there is a reduced development load.
3. Complex objects like data entities can easily be returned in the HTTP response, this avoids having to recreate a data entity’s structure in a return contract.

Note: Commonly custom services are seen as the industry standard for exposing business logic but OData Actions are certainly useful in specific scenarios.

Example:

The following is an example OData Action method added to a custom data entity for return order headers. Note the additional ‘SysODataActionAttribute’ attribute added above the method definition. Here we are returning a boolean and simply updating a field to showcase the syntax and structure of these OData Actions.

We can call this method as follows from Postman:

Here we can see the body uses the parameterized value to send in data. The value returned is true, indicating the method was successful.

The URL to send the post request to is:

https://<D365URL>/data/<DATAENTITY>/Microsoft.Dynamics.DataEntities.<METHODNAME>

This example only uses one parameter but additional parameters can be added to both the method definition and JSON body.

List Example:

The following shows an example of an OData Action method receiving a list of values to process.

Here we can see the additional ‘SysODataCollectionAttribute’ attribute added to the method definition to indicate the parameterized value is a list of strings. Once we have the List in x++ we can enumerate through and process the data as usual.

The data sent in from Postman can be structured like so:

Complex Return Object Example:

The following shows an example of an OData Action method returning a complex object in the HTTP response.

Here we can see the additional attribute used to specify the return value List type.  The code simply creates a list of the same type, inserts records, and returns the object.

From Postman we can see the response contract returned is a list of records in this entity:

Instance Method Example:

Finally I want to show case an instance method. All of the previous methods set the second parameter to ‘false’ for the ‘SysODataActionAttribute’ attribute to specify they are not instance methods. Setting this to true allows us to use the ‘this’ keyword to reference data for a single record on the entity.

An instance method needs called slightly differently from Postman:

The URL of this POST request needs the additional unique index information used to specify a record, including the dataAreaId value. This is similar to how PATCH and DELETE CRUD operations are made against entities. For this use case, we do not need to pass in any information via the body of the request.

Now that you are familiar with OData Actions, go learn more about OData filters!

Filter D365 Entities with OData