> For the complete documentation index, see [llms.txt](https://docs.middle.app/middle-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.middle.app/middle-docs/product/apps/assisted-variables.md).

# Assisted variables

Define choice lists once in an app and reuse them in modules

Assisted variables use an [Action](https://docs.middle.app/middle-docs/product/apps/actions.md) to populate a list of choices. You can define the action and its input and output mappings once in an app, then reuse that definition in [Modules](https://docs.middle.app/middle-docs/product/modules.md#assisted-variables).

For example, a rewards app could provide a list of rewards. Each module can ask an account to choose a reward, while the app handles fetching the list and turning reward IDs and names into choices.

## Create an assisted variable

First, configure an action in the app's live version that returns the available choices. The action needs an executable script and an output schema describing its response.

1. Open **Apps**, select the app, then open **Assisted Variables**.
2. Click **Add assisted variable**.
3. Enter a **Title**, such as "Rewards", and **Help text** describing the choices.
4. Select the **Assisted action**. The list contains actions from the app's live version.
5. Under **Required variables**, add any module variables the action's input needs.
6. Click **Create assisted variable**.

Each required variable has a **Key**, **Type**, and **Description**. Keys must be lowercase and unique within this assisted variable. Supported types are String, Number, Boolean, Date, and Datetime, plus an Array version of each.

For the rewards example, add `business_id` with type **Number** and the description "Business whose rewards should be listed". Modules using this assisted variable must provide a module-wide Number variable with that exact key.

## Configure the input and output

After creating the assisted variable, configure **Input to assisted action** and **Map output to choices**. These mappings save as you edit. Changes to the title, help text, action, or required variables use the **Save** button.

### Input to assisted action

Construct the input expected by the selected action, using the required variables and any constant values it needs. In the rewards example, map the required `business_id` variable into the action's `business_id` field. An account's value of `42` would produce:

```json
{
  "business_id": 42
}
```

The required variables come from the account's module connection when the choices are loaded. See [Workflow parameters](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters.md) for help constructing objects and selecting variables.

### Map output to choices

Use the action output to produce an array of choice objects. Each object needs:

* `value`: the string stored in the module variable when the account selects this choice.
* `label`: the string shown to the account.
* `description`: optional text with extra information about the choice.

For example, if the action returns a `rewards` array with `id` and `name` fields, use [Map Array](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/array-manipulation.md#map-array) to construct one choice object for each reward. Map `id` to `value` and `name` to `label`:

```json
[
  {
    "value": "reward-1",
    "label": "Free smoothie",
    "description": "Redeem for one smoothie."
  },
  {
    "value": "reward-2",
    "label": "Guest pass"
  }
]
```

## Use the assisted variable in a module

1. Add a required app connection for this app to the module.
2. Create or edit a module variable. In **Type**, select the app and assisted variable, such as **Rewards app / Rewards**. Choose the **(Array)** version to allow multiple selections.
3. Define the required variables as module-wide variables with matching keys and types. Middle identifies missing variables and offers **Create this variable for me**. A variable inside a module feature or variable group does not satisfy this requirement.
4. If the module has more than one required connection to this app, select the **Required app connection** on the assisted variable's settings page.

When an account connects to the module, it supplies the required variable values and maps the required app connection to its own app connection. Middle uses that connection to call the action and load the choices.

## Updating and exporting

The definition is shared wherever it is used. Updating its action, mappings, or required variables affects modules using it, including existing module connections. If you add or change a required variable, update those modules to provide the matching key and type. Accounts may also need to fill in newly required values.

Assisted variable definitions, required variables, and mappings are included in app exports, so they travel with the app when it is imported into another installation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.middle.app/middle-docs/product/apps/assisted-variables.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
