Data actions

Note

The Retail Interest Group by Dynamics 365 Commerce has moved from Yammer to Viva Engage. If you don't have access to the new Viva Engage community, fill out this form (https://aka.ms/JoinD365commerceVivaEngageCommunity) to be added and stay engaged in the latest discussions.

This article describes data actions in Microsoft Dynamics 365 Commerce.

Data actions are JavaScript functions in the Dynamics 365 Commerce architecture that you use to help fetch and map data required by modules across applications.

Data actions improve performance through the following features:

• Integrated application-level and request-level caches enable state sharing scenarios.
• Built-in utilities support batching to minimize the number of external requests that your application requires.
• Automatic deduplication helps guarantee that multiple data action calls aren't duplicated.

The Dynamics 365 Commerce platform includes a set of core data actions that modules can call to perform typical data retrieval. For example, core data actions can return product details. You can also create custom data actions to fetch and process data that modules require.

Anatomy of a data action

The following example shows a template TypeScript file created for a new data action.

import * as Msdyn365 from '@msdyn365-commerce/core';

/**
 * GetProductReviews Input Action
 */

export class GetProductReviewsInput extends Msdyn365.CommerceEntityInput implements Msdyn365.IActionInput {

    // TODO: Determine if the results of this get action should cache the results and if so provide
    // a cache object type and an appropriate cache key
    constructor() {
        super({shouldCacheOutput: true, cacheObjectType: 'TODO', cacheKey: 'TODO'});
    }

    public getCacheKey = () => `TODO`;
    public getCacheObjectType = () => 'TODO';
    public dataCacheType = (): Msdyn365.CacheType => 'application';
}

// TODO: Create a data model here or import one to capture the response of the action
export interface IGetProductReviewsData {
    text: string;
}

/**
 * TODO: Use this function to create the input required to make the action call
 */
const createInput = (args: Msdyn365.ICreateActionContext): Msdyn365.IActionInput => {
    return new GetProductReviewsInput();
};

/**
 * TODO: Use this function to call your action and process the results as needed
 */
async function action(input:GetProductReviewsInput, ctx: Msdyn365.IActionContext):Promise<IGetProductReviewsData> {
    // const apiSettings = Msdyn365.msdyn365Commerce.apiSettings;

    // TODO: Uncomment the below line to get the value from a service
    // const response = await Msdyn365.sendRequest<IGetProductReviewsData[]>('/get/example/id/1', 'get');
    return {text: 'Static data from action'};
}

export const IGetProductReviewsAction =  Msdyn365.createObservableDataAction({
    action: <Msdyn365.IAction<IGetProductReviewsData>>action,
    input: createInput
});

Key parts of a data action

• Action function – The main function that contains the logic that runs when the action is called. This function might involve making application programming interface (API) calls, reading cookies, or transforming data that the function receives.

  async function action(input:GetProductReviewsInput, ctx: Msdyn365.IActionContext):Promise<IGetProductReviewsData> {
      // const apiSettings = Msdyn365.msdyn365Commerce.apiSettings;
  
      // TODO: Uncomment the below line to get the value from a service
      // const response = await Msdyn365.sendRequest<IGetProductReviewsData[]>('/get/example/id/1', 'get');
      return {text: 'Static data from action'};
  }
  
  // TODO: Create a data model here or import one to capture the response of the action
  export interface IGetProductReviewsData {
      text: string;
  }
  

• Action input class – The class that you use to pass data into the action function. The "cacheObjectType" and "cacheKey" values indicate where in the cache the class should put the result of the action.

  export class GetProductReviewsInput extends Msdyn365.CommerceEntityInput implements Msdyn365.IActionInput {
  
      // TODO: Determine if the results of this get action should cache the results and if so provide
      // a cache object type and an appropriate cache key
     constructor() {
          super({shouldCacheOutput: true, cacheObjectType: 'TODO', cacheKey: 'TODO'});
      }
  
      public getCacheKey = () => `TODO`;
      public getCacheObjectType = () => 'TODO';
      public dataCacheType = (): Msdyn365.CacheType => 'application';
  }
  

• createInput method – This optional method builds an instance of an action input class that loads data when a page is first populated.

  const createInput = (args: Msdyn365.ICreateActionContext): Msdyn365.IActionInput => {
      return new GetProductReviewsInput();
  };
  

Create a new custom data action

To create a new custom data action, follow these steps.

• At a command prompt, go to your root software development kit (SDK) folder, and run the yarn msdyn365 add-data-action DATA_ACTION_NAME command-line interface (CLI) command to create a data action, as shown in the following example.

  c:\repos\Msdyn365.Commerce.Online>yarn msdyn365 add-data-action get-product-reviews
  

TypeScript files for new custom data actions are created under the \src\actions\ directory. The name of each file uses the name of the data action. For the preceding example, the path and name of the file for the new custom data action are \src\actions\getProductReviews.ts.

Additional resources

Data action cache options

Test data actions with mocks

Page load data actions

Event-based data actions

Core data actions

Call Retail Server APIs