Scope and context

This is the official documentation of the agent_ruby Ruby agent.

Actions can have 3 different scopes: Single, Bulk, and Global.

The scope of an action defines how it can be triggered and which records it will target.

-	Single	Bulk	Global
Targeted records	One at a time	All selected and matching the current segment / search	Your choice among all matching the current segment / search
Can be triggered from the List View	When a single record is selected	When one or more records are selected	✅
Can be triggered from the Details View or Summary View	✅	✅	🚫

The context object

The context object is central to writing Actions controllers in Forest Admin.

There are two different object context. The first ForestAdminDatasourceCustomizer::Decorators::Action::Context::ActionContext is used for the actions of type Bulk or Global. And the second ForestAdminDatasourceCustomizer::Decorators::Action::Context::ActionContextSingle is only used with the actions of type Single

It is the bridge between all the data that your agent has access to and the action's execution. It is passed to the execute function as the first argument and provides access to the following properties:

• get_record(field_names) (or get_records(field_names) for Bulk and Global Actions)

• get_record_id() (or get_record_ids() for Bulk and Global Actions)

• collection the collection on which the action is declared, which can be queried using the Forest Admin Query Interface.

• datasource the composite data source who contains all your collections, which can be queried using the Forest Admin Query Interface

• filter a filter that can be used to query the collection, and which is based on action scope and the list of selected records.

• caller an object containing information about the user who is performing the action (see details below)

• field_changed?(field_name) the name of the field who has changed in the UI. See an example of usage

Ruby DSL: Simplified helper methods

When using the Ruby DSL syntax with collection.action, the execute block provides simplified helper methods that make your code more concise:

Helper Method	Traditional Equivalent	Description
record(fields)	context.get_record(fields)	Get a single record (for Single actions)
records(fields)	context.get_records(fields)	Get multiple records (for Bulk/Global actions)
form_value(key)	context.get_form_value(key)	Access form field values
datasource	context.datasource	Access the datasource
caller	context.caller	Access caller information
success(message)	result_builder.success(message: message)	Return success result
error(message)	result_builder.error(message: message)	Return error result
file(content:, name:)	result_builder.file(...)	Return file download

These helper methods are only available when using the DSL syntax with execute do ... end blocks. For traditional syntax using BaseAction.new, continue using the full context.get_record style methods.

Example:

Traditional Syntax

Using full context methods with customize_collection:

@create_agent.customize_collection('orders') do |collection|
  collection.add_action(
    'Mark as shipped',
    BaseAction.new(scope: ActionScope::SINGLE, form: [...])
  ) do |context, result_builder|
    order = context.get_record(['reference'])
    tracking = context.get_form_value('tracking_number')

    result_builder.success(message: "Order #{order['reference']} shipped!")
  end
end

DSL Syntax

Using simplified helper methods with collection.action:

@create_agent.collection :orders do |collection|
  collection.action 'Mark as shipped', scope: :single do
    form do
      field :tracking_number, type: :string
    end

    execute do
      order = record(['reference'])           # Simplified
      tracking = form_value(:tracking_number) # Simplified

      success "Order #{order['reference']} shipped! Tracking: #{tracking}"
    end
  end
end

The caller object

The caller object contains information about the current user performing the action:

Property	Description
id	User ID
email	User email
firstName	First name
lastName	Last name
team	Team name
role	Role name
tags	Custom tags (key-value pairs)
timezone	User timezone

Error methods

The context also provides methods to throw errors that will be displayed in the Forest Admin UI:

Method	Description
throw_validation_error(message)	Display a validation error
throw_forbidden_error(message)	Display a forbidden error
throw_error(message)	Display a generic error

Example 1: Getting data from the selected records

We can simply use the get_record(field_names) method to get any column from the selected record or a relation.

# Traditional syntax
include ForestAdmin::Types

@create_agent.customize_collection('user') do |collection|
  collection.add_action(
    'Mark as live',
    BaseAction.new(scope: ActionScope::SINGLE) do |context|
      record = context.get_record(['name'])
        if record['name'] === 'John'
          # log with your favorite logger => 'hi John'
        else
          # log with your favorite logger => 'You are not John!'
        end
    end
  )
end

# DSL syntax (simplified)
@create_agent.collection :user do |collection|
  collection.action 'Call me John in the server logs', scope: :single do
    execute do
      # Use simplified helper methods in the DSL
      user = record(['name'])  # Instead of context.get_record(['name'])

      if user['name'] == 'John'
        # log with your favorite logger => 'hi John'
      else
        # log with your favorite logger => 'You are not John!'
      end
    end
  end
end

Example 2: Updating a field of the selected record

For simple queries, use context.collection and context.filter to query the collection.

Those are instances of objects from the Forest Admin Query Interface.

include ForestAdmin::Types

@create_agent.customize_collection('user') do |collection|
  collection.add_action(
    'Mark as live',
    BaseAction.new(scope: ActionScope::SINGLE) do |context|
      context.collection.update(context.filter, { name: 'foo' })
    end
  )
end

Example 3: Coding any business logic

Forest Admin does not impose any restriction on the handler: you are free to write the execute handler to fit your use case.

You are free to call external APIs, query your database, or perform any work in action handlers.

include ForestAdmin::Types

@create_agent.customize_collection('user') do |collection|
  collection.add_action(
    'Mark as live',
    BaseAction.new(scope: ActionScope::SINGLE) do |_context|
      res = HTTParty.get('http://my-api.com/mark-as-live')
    end
  )
end