Actions

This is the official documentation of Forest Admin Cloud.

Actions allow users to trigger custom HTTP API calls, encapsulating custom business logic or initiating workflows on third-party tools. These actions are shown as buttons on the admin panel and are connected to specific collections to make sure they are related to the data being handled.

Before proceeding with this section to learn how to create an action using Code customization, it is recommended to first create your action using UI Customization, which is quicker and easier. This section aims to provide you with the most flexibility in creating actions, including advanced customization options.

The following sections assume that you have correctly followed all the steps in the Code Customization Getting Started guide.

TL;DR

Ensure you update the collection and action names as needed.

src/index.ts

import type { Agent } from '@forestadmin/forest-cloud';
import { Schema } from '../typings';

export default function customizeAgent(agent: Agent<Schema>) {
  agent.customizeCollection('users', collection =>
    collection.addAction('Ban user', {
      scope: 'Single',
      execute: async context => {
        // Your business logic here.
      },
    }),
  );
}

---

To make the code easier to read, all the code snippets below should be wrapped in the following code.

import type { Agent } from '@forestadmin/forest-cloud';
import { Schema } from '../typings';

export default function customizeAgent(agent: Agent<Schema>) {
  // Insert the code snippet here.
}

Creating an Action

First, you need to call the customizeCollection() method on the agent.

agent.customizeCollection('users', collection =>
  // ...
);

Arguments:

• name* String: The name of the collection to customize.

• handle* Function: A function that has the collection instance as an argument to start customizing it.

Next, you can invoke the addAction() method on the collection instance to create an action in Forest Admin:

agent.customizeCollection('users', collection =>
  collection.addAction('Ban a user', {
    scope: 'Single',
    execute: async context => {
      // Your business logic here.
    },
  }),
);

Arguments:

• name* String: The name of the action.

• definition* Object: A JavaScript object that contains the definition of the action:

  • scope* String: See Scope.
  • execute* Function: An async function that contains your business logic, which is executed when your action is triggered.

    • context Object: See Context.
    • resultBuilder Object: See Response.

Configuring the scope

The scope of an action refers to the targeted range of records when triggering an action. There are 3 types of scopes:

1. Single: Enables you to execute an action on a single, specifically chosen record.

2. Bulk: Empowers you to trigger the action on multiple selected records simultaneously.

3. Global: Allows you to initiate the action at the collection level without the need to select individual records.