---
title: Using Variables in Playbooks
slug: using-variables-in-playbooks
docTags: 
createdAt: 2025-08-11T11:13:48.000Z
---

The **Variables** feature in Swimlane Turbine allows orchestrators to collect, store, and use data across various actions within playbooks. By leveraging the **Create Variables** and **Update Variables** native actions, orchestrators can define and modify variables without writing any code. This enables greater flexibility and ease of use in complex workflows.

## Overview

Variables in Swimlane Turbine serve as temporary data storage that can be dynamically manipulated throughout the execution of a playbook. This allows playbooks to make decisions, manage data, and pass information between actions seamlessly.

## Key Benefits

- **Dynamic Data Handling:** Easily collect, modify, and utilize data throughout the workflow.
- **Code-Free Configuration:** Create and update variables without the need for scripting.
- **Improved Flexibility:** Enable complex logic and decision-making capabilities by dynamically adjusting the flow of actions.
- **Seamless Integration:** Variables can be used across different actions, ensuring smooth data flow and continuity within playbooks.
- **Promotable Variables:** Promote variables for accessibility across multiple playbooks, enhancing reusability and reducing redundancy.

## Creating Variables

The **Create Variables** native action enables orchestrators to generate new variables that can be applied across downstream actions. **Important:** You cannot create a variable that already exists. If you attempt to create a variable with a name that already exists, the action will fail. Use the **Update Variables** action to modify existing variables instead.

Here is how to use it:

1. Start by adding a trigger or existing playbook action to ensure upstream data is available for the variables.
2. From the Add Panel, drag and drop the **Create Variables** action onto the playbook canvas.
3. Click **Configure**, then select **Add variable**. A list of available property types will appear. The following types are currently supported: *String, Number, Boolean, Object, Array, or Attachment*.

:::hint{type="info"}
**Attachment** variables can be created and used in downstream actions, but they **cannot** be evaluated in the playbook **Conditions** native action until attachment support is added to the Condition Builder. See [Conditions Native Action](docId\:BIFYlYtGGAlx6WhIPxvaY) → **Limitations**.
:::

4. If you want to add more than one variable, click **Add variable** again and select another property type.
5. In the variable box, enter a value directly or click **Select a property** to open the property drawer.
6. The property drawer displays all available inputs from upstream playbooks, actions, or event inputs. You can also select **Expression** and use dot notation for advanced variable manipulation. Variables can be accessed in expressions using the `$variables.` prefix (for example, `$variables.myVariable`).

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/zeYXXC1OZYloE_LKJ3iwd_variable-playbook-property-drawer.png" size="56" width="1185" height="616" darkWidth="1185" darkHeight="616" position="center" alt="Property Drawer" indent="2" showCaption="false"}

7. If you want the variable accessible outside of the current playbook, click **+Promote**. Promoted variables can be accessed in other playbooks through the playbook's published outputs using the `$published.variables_` prefix followed by the variable name.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/-Kz2HtrNHw1Kqzy17SD4r_variable-action.png" size="70" width="1185" height="744" position="center" alt="Promote Variable" indent="2" darkWidth="1185" darkHeight="744" showCaption="false"}

8. You can mark the data as sensitive while creating a variable. Click the ellipsis button next to the **select a property** and click **Mark Sensitive**.
9. Now that the variable is created, you can reference it in subsequent actions.
10. In the next action's configuration, under **Inputs**, click **Select a property** to access the variable from the playbook property drawer.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/UcE1cA_5ZKUcx3QAGKJib_variable-available.png" size="60" width="1190" height="741" position="center" alt="Variable Available in Playbook" indent="2" darkWidth="1190" darkHeight="741" showCaption="false"}

11. Congratulations! You now have a variable to use in your playbook workflow.

### Example: Creating an Object Variable

Here’s an example of creating an object variable to store a URL:

1. Drag and drop the **Create Variables** action.
2. Add a new variable, select **Object** as the type, and name it *object\_test2*.
3. Under *object\_test2*, add a property named *string\_akbds* and set its value to `$event.data.url`.
4. Promote the variable if you want to use it across multiple playbooks.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/zeYXXC1OZYloE_LKJ3iwd_variable-playbook-property-drawer.png" size="60" width="1185" height="616" darkWidth="1185" darkHeight="616" position="center" alt="Property Drawer Example" showCaption="false"}

## Updating Variables

If you need to modify an existing variable, use the **Update Variables** action. The **Update Variables** action replaces the variable's value with a new value.

**Note:** If a variable does not exist when updating, it will be created automatically using the operation's value (effectively behaving like a **Set** operation). Below is an example where a string and object variable are updated:

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/owdlJlcz81yCyPvfifVp7_variable-existing-action.png" size="64" width="978" height="734" position="center" alt="Configured Variable Action" darkWidth="978" darkHeight="734" showCaption="false"}

### How to Update Variables

1. Add the **Update Variables** action to the playbook canvas, then click **Configure**.
2. Click **Select variable to update** to open the playbook property drawer. From here, select the variable you want to modify.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/GH16qTCVK1u6P3bC_13eK_variable-select-to-update.png" size="62" width="976" height="735" position="center" alt="Select Variable to Update" indent="2" darkWidth="976" darkHeight="735" showCaption="false"}

3. Once selected, choose an update operation type and enter new data, choose a playbook property, or use an expression to update the variable.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/KGxoSaEUCLWDD4sglArYf_variable-updated.png" size="66" width="976" height="729" position="center" alt="Updated Variable" indent="2" darkWidth="976" darkHeight="729" showCaption="false"}

4. The variable is now updated and can be used in subsequent actions.

## Accessing Variables

Variables created in a playbook are accessible to all downstream actions in the same execution path. You can reference variables in expressions using the `$variables.` prefix followed by the variable name. For example:

- `$variables.myStringVariable` - Accesses a string variable
- `$variables.myObjectVariable.propertyName` - Accesses a property within an object variable
- `$variables.myArrayVariable[0]` - Accesses an element in an array variable

Variables are scoped to the execution path, meaning variables created on separate branches of conditional logic are not accessible to actions on other branches.

## Advanced Use Cases

### Handling Arrays

Use arrays to store lists of values and iterate over them with loop actions.

1. Create an **Array** variable named *email\_list* using the **Create Variables** action.
2. Add email addresses as elements within the array.
3. Use the **Update Variables** action with the **Append** operation to add more items to the array.
4. Use a **Loop** action to iterate through each email and perform actions like sending notifications or logging details.

### Performing Arithmetic Operations

Use the **Update Variables** action with arithmetic operations to perform calculations:

1. Create a **Number** variable named *counter* and set its initial value.
2. Use **Update Variables** with the **Arithmetic** operation to increment, decrement, multiply, or divide the counter.
3. Reference the updated counter value in subsequent actions.

### Merging Objects

Use the **Merge** operation to combine object properties:

1. Create an **Object** variable with initial properties.
2. Use **Update Variables** with the **Merge** operation to add or update properties from another object.
3. The merge operation combines properties, with new values overwriting existing ones for matching keys.

### Error Handling with Variables

Use variables to capture and log error messages dynamically:

1. Create a **String** variable named *error\_message*.
2. In your error handling action, use **Update Variables** to set the variable to the error output using an expression or property selection.
3. Log or display the variable in subsequent actions to track errors efficiently.

## Troubleshooting

- **Variable Creation Fails:** If you receive an error that a variable already exists, use the **Update Variables** action instead of **Create Variables** to modify the existing variable.
- **Variable Not Updating:** Ensure the variable is correctly referenced and updated in the action. Check for spelling errors or incorrect property paths. Verify that you are using the correct operation type for the variable's data type (for example, **Append** only works with arrays, **Arithmetic** only works with numbers).
- **Merge Operation Fails:** The **Merge** operation only works with Object or Array variable types. Ensure both the variable and the input value are objects or arrays.
- **Arithmetic Operation Fails:** The **Arithmetic** operation only works with Number variable types. Ensure the variable contains a valid number value.
- **Append Operation Fails:** The **Append** operation only works with Array variable types. Ensure the variable is an array.
- **Unexpected Variable Values:** Review upstream actions to ensure data is being passed correctly. Use logs or debugging actions to trace variable changes. Remember that variables are scoped to execution paths, so variables from separate branches may not be accessible.
- **Missing Variables in Property Drawer:** Confirm that variables are promoted if needed for accessibility in other playbooks. Variables must be created upstream in the execution path to be accessible to downstream actions.

## Best Practices

- **Keep Variables Organized:** Use descriptive names and add clear descriptions to your variables to make your playbooks easier to understand.
- **Choose the Right Action:** Use **Create Variables** for new variables and **Update Variables** for modifying existing ones. Remember that **Create Variables** will fail if the variable already exists.
- **Select Appropriate Operations:** Choose the correct update operation type for your use case:
  - Use **Set** for simple value replacement
  - Use **Merge** for combining objects or arrays
  - Use **Append** for adding items to arrays
  - Use **Arithmetic** for numeric calculations
- **Understand Variable Scoping:** Variables are scoped to execution paths. Variables created on one branch of conditional logic are not accessible to actions on other branches.
- **Promote When Necessary:** Only promote variables that need to be accessible across multiple playbooks to avoid cluttering the global variable space.
- **Test Variable Logic:** Regularly test your playbooks to ensure variables are set and updated correctly, especially when using different operation types.
- **Use Expressions Wisely:** Leverage expressions with the `$variables.` prefix for complex variable logic, but keep them as simple as possible for maintainability.