Skip to main content

Variables

Variables are tenant-level key-value pairs that a Code step can read at runtime. Their main use is keeping secrets out of your code: store the secret as a secure variable and read it in the Code step, instead of typing it into the script. Anyone who can open the workflow can read a hard-coded secret; a secure variable can't be read back from the platform once saved.

Variables are also useful for other values shared across workflows, such as account identifiers or configuration flags, so they're managed in one place instead of duplicated inside each workflow.

Credentials for another system belong on a Connection

To log in to another system, don't store its API key, bearer token, password or client secret in a variable. Put the credentials on a Connection instead. In a Code step, pass the Connection to authorizedAxios and it authenticates every request for you, with no variable needed and no credentials in your script. The REST API step uses the same Connections.

Use secure variables for secrets that aren't a login to a system, such as a key for signing or encrypting data.

The variables list​

ColumnDescription
NameThe key used to reference this variable in workflows
ValueThe stored value — shown as •••••••• for secure variables
SecureWhether this variable is treated as a secret

Referencing a variable in a workflow​

Variables can only be read in a Code step, with getContext:

const getContext = require('getContext');

const pageSize = await getContext('globals.variable', 'M3_PAGE_SIZE');
const limit = Number(pageSize?.value ?? 100);

Pass the exact name of the variable as it appears in the list. getContext returns the variable object; the value is in .value, and is always a string. See Example: read a Variable.

note

There is no {{ }} placeholder for these variables, so they can't be used directly in fields such as a REST API step's URL or headers. To use one there, read it in a Code step and return it, so a later step can pick it up.

These tenant-level variables are not the same as the environment-specific runtime variables under $context.runtime.variables. See the $context Reference.

Creating a variable​

  1. Go to Administration → Workflow Management → Variables.
  2. Click + New Variable.
  3. Fill in the required fields:
FieldDescription
NameThe key you pass to getContext('globals.variable', 'NAME') in a Code step
ValueThe value that will be substituted at runtime
SecureToggle on to store the value as a secret — see below
  1. Click Save.

Secure variables​

Enabling the Secure toggle stores the value encrypted. Secure variables behave differently from regular variables in one important way:

warning

Secure values cannot be read again after saving. Make sure you store the original somewhere safe.

After saving a secure variable, the value field displays •••••••• and cannot be retrieved through the UI. If the value is lost, you must create a new variable — there is no way to recover it from the platform.

Use secure variables for:

  • Keys for signing or encrypting data, such as a shared secret for HMAC signatures
  • Any other secret your code needs that must not be visible in the administration interface

For API keys, bearer tokens, passwords and client secrets used to log in to another system, use a Connection instead (see the tip at the top of this page).

Using a secret in a Code step​

Read the secret with getContext instead of hard-coding it in the script. For example, to sign a payload with a shared secret:

const getContext = require('getContext');
const crypto = require('crypto');

// Don't: the secret is visible to anyone who opens the workflow
// const secret = 'whsec_4f9a…';

// Do: read it from a secure variable
const secret = (await getContext('globals.variable', 'PARTNER_SIGNING_SECRET')).value;

const signature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

getContext returns secure values decrypted, so the script can use them. Don't include them in what the step returns, or they'll be visible in the step's output.

Editing and deleting variables​

Use the ⋮ menu on a variable row to Edit its value or Delete it.

Editing a secure variable requires entering a new value — the existing value cannot be pre-filled.

Deleting a variable that a workflow still reads means the Code step that reads it no longer gets a value, so the workflow may fail or behave unexpectedly. Check the Code steps of your workflows before deleting a variable.

Further reading​

Last updated on