Global variables

Beta feature

Global variables are in beta and may be subject to change. Please contact us to provide feedback.

Global variables are values you define once for an environment and use in any Action Flow, in card content or step configuration. Change a global variable in one place and every Action Flow that uses it picks up the new value the next time it runs, so you no longer need to edit and republish each Action Flow to update a shared value.

Global variables sit alongside the variables you define inside an Action Flow. An Action Flow variable belongs to that one Action Flow, while a global variable is shared by every Action Flow in the environment.

Example use-cases

• Seasonal campaigns: keep the current sale name and discount, such as Spring sale and 20%, in global variables, and switch every card that mentions them when the next campaign starts.
• Contact details: store your support phone number or help center URL once, so a change reaches every Action Flow that links to it.
• Rates and thresholds: hold an interest rate, a free shipping threshold, or a fee in a number variable, and update it when it changes.
• Per-request overrides: let an API request or integration send a different value for a single run, while every other run uses the environment's value.
• Endpoint of a third party integration: define the endpoint to use for Send Request steps to a third-party integration you use often.

How to manage global variables

Navigate to Configuration > Action Flows > Global variables. Alternatively, open the command palette and type Global variables.

The list shows each global variable's name and description, type, current value, which Action Flows use it, and when it was last updated. Use the search box to find a variable by name, value or description, and the filters to narrow the list by type or by whether any Action Flow uses it.

Permissions

Anyone who can view Action Flows can view global variables. Adding, editing, restoring and removing them needs Admin access to the Action Flow resource, because a change reaches every Action Flow in the environment.

Add a global variable

1. Click Add global variable.
2. Enter a Name. Names can contain letters, numbers and underscores, must start with a letter or underscore, and must be unique in the environment.
3. Optionally, add a Description that explains what the variable is for. Descriptions appear in the list and when you hover over the variable in the Action Flow editor.
4. Choose a Type: String, Number, Date, Boolean, List, Checkbox List or Script.
5. Set its value.
6. Choose whether to Allow request payload to overwrite the value. This is off by default. See Supplying a value when an Action Flow starts.
7. Click Save.

A name can't be changed

Action Flows refer to a global variable by its name, so a name is fixed once the variable is created. To rename one, add a new global variable, update your Action Flows to use it, then remove the old one.

Edit a global variable

1. Click the variable's name, or open its menu (the three dots) and choose Edit.
2. Make your changes on the Settings tab.
3. Click Review and save. The review shows what you changed and how many published and draft Action Flows use the variable.
4. Optionally, add a Change note describing why you made the change. The note is shown in the variable's history.
5. Click Save.

The new value applies to Action Flow runs that start after you save. Runs that are already in progress keep the value they started with. See How global variables are resolved.

See which Action Flows use a global variable

Open a global variable and select the Used by tab, or click the entry in the Used by column. Each Action Flow is listed with whether its published version or only its draft uses the variable, along with the steps that reference it. Click an Action Flow to open it.

View history and restore a previous value

Every change to a global variable is recorded. Open a global variable and select the History tab to see each previous value, who changed it, when, and the change note they left. Atomic keeps the last 20 versions.

To go back to an earlier value, click Restore next to that version. Restoring saves the earlier value as a new change, so it also appears in the history.

Remove a global variable

Open the variable's menu (the three dots) and choose Remove. If any Action Flows use the variable, the confirmation lists them and warns you if any are published.

Once a global variable is removed:

• Runs that have already started keep the value they started with.
• New runs of Action Flows that still use it get no value for it, which could cause failures or unexpected behaviour.
• An Action Flow that uses it can't be published again until you add a global variable with the same name back, or remove the reference from the Action Flow.

Use a global variable in an Action Flow

The global variables an Action Flow uses are listed in the Variables panel of the Action Flow editor, below the Action Flow's own variables, marked with a globe icon. Clicking one shows its settings, read-only, with a link to manage it in Configuration.

To insert a global variable into card content or a step's configuration, open the context placeholder picker (or type +) and choose it from the Global variables section. See Personalize content and configuration with context data.

A global variable can use the same name as an Action Flow's own variables. They are treated as separate variables, so you can choose which one to use.

If an Action Flow refers to a global variable that doesn't exist in the environment, for example because it was removed or because the Action Flow was copied from another environment, the editor shows a warning, and the Action Flow can't be published until you add the global variable or remove the reference.

How global variables are resolved

When an Action Flow run starts, Atomic takes a copy of every global variable the Action Flow uses, and that run uses those values from start to finish. This means:

• A change only reaches new runs. If you edit a global variable while a run is waiting, for example on a wait step or for a customer to respond to a card, that run keeps the value it started with. Runs that start after you save use the new value.
• Every step in a run sees the same value. A card sent at the start of a run and a card sent days later in the same run show the same value.
• Scripts run once per run. A Script global variable is calculated when the run starts, using the target customer's profile, and is not re-run while the run is in progress.
• Values are the same on every platform. A global variable resolves to a single value that is used on web, iOS and Android alike.

Options that only apply to an Action Flow's own variables, such as runtime variables and markdown, aren't available on global variables. Date formatting and the non-wrapping string option do apply.

Supplying a value when an Action Flow starts

By default, a global variable always uses the value set in Configuration. To let the request that starts an Action Flow supply its own value for one run, turn on Allow request payload to overwrite for that variable. Script variables can't be overwritten.

A request supplies values for global variables in a globalVariables object, beside variables:

{
  "payload": {
    "variables": {
      "first_name": "Jane"
    },
    "globalVariables": {
      "discount": "25%"
    }
  }
}

Different triggers handle values they can't use (such as one for a global variable that doesn't exist, or that doesn't allow overwriting, or of the wrong type) differently:

• Action Flow API, connector triggers and CSV bulk sends reject the request (or, for a CSV, the row).
• Event and segment triggers don't start the Action Flow, and record an action-flow-not-started event with the error code VARIABLE_VALIDATION_FAILED.

FAQs

I changed a global variable, but a customer still sees the old value. Why?

Their run started before you saved the change. Each run keeps the values it started with, so the new value appears in runs that start after you save. Cards that were already sent also keep the value they were sent with. Cancel the Action Flow or card for that customer and re-send it to apply the latest value.

Can I use a global variable in more than one environment?

No. Global variables belong to a single environment. If you copy an Action Flow to another environment, add the global variables it uses to that environment too, or the Action Flow can't be published there.

Why can't I edit a global variable?

Changing global variables needs Admin access to the Action Flow resource. With view access, you can still see each variable's settings, usage and history. Ask your workbench administrator if you need to make changes.