> 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/accounts/defining-workflow-variables.md).

# Defining workflow variables

You can define your own variables in a workflow. Use them to save an Action's result, calculate a value once and reuse it, or keep a value that different branches can update.

## Define a variable

1. Open the workflow for editing.
2. Click **Variables**, then **Declare a variable**. If variables already exist, use a row's **Insert** controls to add another.
3. Enter a key, such as `points`, and choose its type. Use Number for a points total, String for an email address, or Object for several related fields. Enable Array if the variable holds a list.
4. Click **Save**.

Keys must start with a letter and contain only letters, numbers, and underscores. Each key must be unique in the workflow and cannot duplicate a Begin input field. If a workflow variable has the same key as a module variable, the workflow variable takes its place inside that workflow.

The variable is now available throughout the workflow, but its value starts as null. Defining a variable does not give it an initial value.

## Assign a value

Add a **Set variable** step and click **Add assignment**. Choose the variable, then use the [parameter editor](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters.md) to build its value. You can also choose **Create...** in the variable dropdown to declare a new variable while adding an assignment.

Assignments are also available in the Begin, Action, and File Export steps. Begin assignments can use the full `ROOT_INPUT`; Action output assignments can use `ACTION_OUTPUT`; File Export output assignments can use `FILE_OUTPUT`. Save any output you need later into a workflow variable.

Each assignment must produce the variable's declared type. Assignments run in order, so a later assignment in the same step can use a value assigned just above it. A new assignment replaces the variable's previous value.

## Use the variable

In any later parameter, choose **Variable Selector**, then select the variable by its key. For an Object or a reference to a synced record, you can select individual fields.

The value belongs to this workflow execution. It is not shared with other executions, and updating it does not update a synced record or a module setting. If a branch skips the assignment, the variable keeps its previous value, or null if nothing has assigned it yet.

## Example: points per check-in

This complete copied workflow accepts a `check_ins` number, assigns `check_ins * 10` to a declared `points` variable, and returns an object containing `points`. With input `{"check_ins": 3}`, the output is `{"points": 30}`.

The top-level `variables` array declares the variables and their types. A step's `variable_assignments` list identifies the target by `key` and supplies its value using `node_parameter`. A `global_var_selector` reads the value by the same key.

```json
{
  "name": "Calculate check-in points",
  "description": "Award ten points per check-in.",
  "variables": [
    {
      "key": "points",
      "attribute": {"type": "number", "is_array": false}
    }
  ],
  "steps": [
    {
      "step_number": 0,
      "description": "Accept the check-in count",
      "node_type": "root_node",
      "root": {
        "next_step_number": 1,
        "input_attribute": {
          "type": "object",
          "is_array": false,
          "children": [
            {"key": "check_ins", "type": "number", "is_array": false}
          ]
        },
        "variable_assignments": []
      }
    },
    {
      "step_number": 1,
      "description": "Calculate points",
      "node_type": "set_variable_node",
      "setvariable": {
        "next_step_number": 2,
        "variable_assignments": [
          {
            "key": "points",
            "node_parameter": {
              "type": "math_expression",
              "expression": "{} * 10",
              "params": [
                {"type": "global_var_selector", "expression": "check_ins"}
              ]
            }
          }
        ]
      }
    },
    {
      "step_number": 2,
      "description": "Return the points total",
      "node_type": "return_node",
      "returnnode": {
        "output_type": {
          "type": "object",
          "is_array": false,
          "children": [
            {"key": "points", "type": "number", "is_array": false}
          ]
        },
        "output_np": {
          "type": "construct_object",
          "params": [
            {"key": "points", "type": "global_var_selector", "expression": "points"}
          ]
        }
      }
    }
  ]
}
```

For variable keys available in triggers, current-step outputs, and array operations, see [Variables](https://docs.middle.app/middle-docs/product/accounts/workflow-parameters/variables.md).


---

# 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/accounts/defining-workflow-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.
