# Action Variables

An *action variable* is a variable defined on an action. It can hold a primitive value, an [enumerated type](https://docs.appfarm.io/reference/data-model/enumerated-types), a [schema](https://docs.appfarm.io/reference/platform-concepts/schemas), or a reference to an [object class](https://docs.appfarm.io/reference/data-model/object-classes).

An action variable exists only for the duration of the action run that declares it. [Action nodes](https://docs.appfarm.io/library/action-nodes) in the same run can read and write the variable, and it is discarded when the action completes.

Action variables are useful for holding intermediate values that flow between action nodes, for exposing results from an action to its caller, and for referencing existing object-class records without loading their data into an action data source.

### What an action variable can hold

An action variable's data type determines what it holds:

* **Primitive values** — strings, numbers, booleans, and other basic value types available on the platform.
* **Enumerated types** — values from an enumerated type defined in the solution. An enumerated-type variable can have cardinality one (a single value) or many (a list of values).
* **Schemas** — structured data, with the schema defined inline on the variable. See [schemas](https://docs.appfarm.io/reference/platform-concepts/schemas).
* **References to object classes** — a pointer to a single record (cardinality one) or a set of records (cardinality many) from an object class. The variable holds the reference, not the records: records cannot be created, modified, or persisted through an action variable. Use an [action data source](https://docs.appfarm.io/reference/actions/action-data-sources) when records need to be created, modified or persisted.

### Creating an action variable

Action variables are defined on their parent action, alongside action data sources and action params. The authoring surface is the same as for other action data:

* **In a flow action,** action data is configured on the **Action data** tab in the flow action editor.
* **In an app action,** action data is configured under **Action settings** in the right-side panel.

When adding an action variable, choose its name and its data type. Some data types need additional configuration — for example, selecting an object class and cardinality for an object-class reference, or defining properties for a schema.

### Using an action variable

**As intermediate state.** An action variable holds values that are computed in one action node and consumed by later nodes in the same action.

**As a reference to existing object-class records.** A variable of type object-class reference points at records retrieved from elsewhere — a query result, another variable, or a caller's input. The reference is read-only: records can be read through the variable but not created or persisted through it.

### Returning an action variable from an action

An action variable can be marked **return from action**, which makes it available to the caller as an output. When the caller — for example, a **Run Flow** or **Run Action** node — invokes the action, the returned variable can be mapped into a variable in the calling context, either another action variable or an app variable. The mapping UI and its options are documented on the reference pages for [Run Flow](https://docs.appfarm.io/library/action-nodes/run-flow) and [Run Action](https://docs.appfarm.io/library/action-nodes/run-action).

### Properties

| Property               | Description                                                                                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**               | A descriptive name.                                                                                                                                             |
| **Node Name**          | The internal identifier used to reference the variable in code, such as in [functions](https://docs.appfarm.io/reference/platform-concepts/functions).          |
| **Data Type**          | The type of data the variable holds. See [What an action variable can hold](#what-an-action-variable-can-hold).                                                 |
| **Cardinality**        | *Available if Data Type is an object class or an enumerated type.* Whether the variable holds a single value (**One**) or a list of values (**Many**).          |
| **Schema**             | *Available if Data Type is Schema.* The inline schema definition. Click to open the **Edit schema** dialog and define the schema's properties.                  |
| **Value on Create**    | *Available if Data Type is a simple type or an enumerated type.* Set a default value for the variable when the action starts.                                   |
| **Description**        | A longer description of the action variable. For your own reference.                                                                                            |
| **Return from Action** | Make the action variable available to the caller as an output. See [Returning an action variable from an action](#returning-an-action-variable-from-an-action). |


---

# 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.appfarm.io/reference/actions/action-variables.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.