# Static Forms

{% hint style="success" %}
This is the official documentation of the `agent_ruby` Ruby agent.
{% endhint %}

Very often, you will need to ask for user inputs before triggering the logic behind an action.

For example, you might want to specify a reason if you want to block a user account. Or set the amount to charge a user’s credit card.

![Action Form displayed on Forest Admin](/files/To07klSA2q7tfDjCCE9f)

## Field Configuration

### Properties

Fields are configurable using the following properties:

| Property        | Expected value                                                                                                                                                                               | Description                                                                                                               |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `type`          | `FieldType::{BOOLEAN`, `DATE`, `DATE_ONLY`, `ENUM`, `JSON`, `NUMBER`, `STRING`, `NUMBER_LIST`, `ENUM_LIST`, `STRING_LIST`, `LIST`, `FILE_LIST` and [`COLLECTION`](#references-to-records)`}` | Set the type of the field.                                                                                                |
| `label`         | string                                                                                                                                                                                       | Set the label of the field.                                                                                               |
| `id`            | string                                                                                                                                                                                       | Set the id of the field. The is used internally and to access values from the context. If not set the label will be used. |
| `description`   | string                                                                                                                                                                                       | Set the description of the field.                                                                                         |
| `is_required`   | boolean                                                                                                                                                                                      | Make the field required (default false).                                                                                  |
| `is_read_only`  | boolean                                                                                                                                                                                      | Make the field read-only (default false).                                                                                 |
| `default_value` | any                                                                                                                                                                                          | Set the default value of the field.                                                                                       |
| `enum_values`   | array of strings                                                                                                                                                                             | Change the list of possible values of the field when type is .                                                            |

#### Traditional Syntax

Using full context methods with `customize_collection`:

```ruby
include ForestAdmin::Types

@create_agent.customize_collection('customer') do |collection|
  collection.add_action(
    'Charge credit card',
    BaseAction.new(
      scope: ActionScope::SINGLE,
      form: [
        {
          type: FieldType::NUMBER,
          label: 'amount',
          description: 'The amount (USD) to charge the credit card. Example: 42.50',
          is_required: true
        }
      ]
    ) do |context, result_builder|
      record = context.get_record(['stripeId', 'address:country'])
      form_values = context.form_values

      # ... charge the credit card ...

      result_builder.success(message: 'Amount charged!')
    end
  )
end
```

#### DSL Syntax

Using simplified helper methods with `collection.action`:

```ruby
@create_agent.collection :companies do |collection|
  collection.action 'Charge credit card', scope: :single do
    form do
      field :amount, type: :number,
        description: 'The amount (USD) to charge the credit card. Example: 42.50'
    end

    execute do
      company = record(['stripeId', 'address:country'])
      amount = form_value(:amount)

      # ... charge the credit card ...

      success 'Amount charged!'
    end
  end
end
```

### References to records

![Reference widget on an action form](/files/ehP5fTvpA5zTHT0lgSvG)

When using the `Collection` type, you can create a reference to a record of any collection.

The value of the field will be the primary key of the selected record.

{% hint style="info" %}
Note that the value will be stored in an array as the target collection may be using a composite primary key. When not using a composite primary key, the array can be assumed to contain a single value.
{% endhint %}

```ruby
include ForestAdmin::Types

@create_agent.customize_collection('ticket') do |collection|
  collection.add_action(
    'Assign ticket',
    BaseAction.new(
      scope: ActionScope::SINGLE,
      form: [
        {
          label: 'Assignee',
          description: 'The user to assign the ticket to',
          type: FieldType::COLLECTION,
          collection_name: 'user',
          is_required: true
        }
      ]
    ) do |context, result_builder|
      # Retrieve user id from the form
      user_id = context.form_values['Assignee']
    end
  )
end
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestadmin.com/developer-guide-agents-ruby/agent-customization/actions/forms-static.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.