Flow Variables

Before a flow is executed by the server, it’s variable store is populated according to it’s flow variable configuration. Flow variables are typically used to configure which server variables are used in flows. Flow variables may also be used to:

1. Specify which server variables are required by the flow
2. Specify default values for optional server variables which are not available
3. Create internal-only variables in flows

Note

Flow variables were introduced in Sirveo 0.2.9, which changed the way in which [server variables] are made available to flows. See the 0.2.9 changelog for details.

Configuration

To add a variable in a flow, open it in the flow editor, and select the variables tab. Then use the green add button to create a new flow variable. The following options are available to control how a flow variable behaves:

Key

The key determines the name of the variable in the flow’s variable store. Keys may contain between 1 and 80 alphanumeric characters, underscores and dashes (hyphens).

A key of username will be accessible in the flow’s variable store as ${vars:username}, or via Javascript as $vars.username.

If the key matches a server variable key, that server variable’s value will be available as username within the flow.

External key

An external key can be used to make a server variable available in a flow with a different key.

For example, a flow variable with key token and external key api-token will attempt to make a server variable with key api-token available in the flow as token. Note that if an external key is configured, only the external key is used to match server variables.

This feature is useful when importing flows. When an imported flow is configured with server variables that conflict with existing server variables, there are two options:

1. Change the flow’s variable keys
2. Configure external keys, and keep the internal keys

The latter is often more convenient, especially for more complex flows.

Name

A name is optional, and used for informational purposes.

Description

A description is optional, but useful to describe what a variable is for in a flow.

Internal only

If a flow variable is configured as internal, it’s value will not be replaced by a matching server variable. Internal variables must have a default value, and may not have an external key.

Required

This option is used to instruct the server to abort flow execution when any of it’s required flow variables is not available in the configured server variables.

When a flow variable is optional, and has no default value, it may be missing from the flow’s variable store when no associated server variable is found.

Default value

Default values are useful in two cases:

1. To configure a value for optional flow variables when no matching server variable is available
2. To provide values for internal-only variables

An optional flow variable with a default value will always be available in the flow’s variable store. A required flow variables may not have a default value; it’s value either comes from a server variable, or flow execution is aborted if a matching server variable is not

Note that default values are specified as JSON values. So use the following syntax to create default values with the appropriate type:

Type	Syntax
string	"some value"
number	123.4
boolean	true
object	{"a": "b"}
array	[1,2,3]
null	null

Accessing server variables

To access a server variable in a flow, the flow requires a variable configuration with a corresponding key or external key.

As an example, suppose that a flow requires an API token to authenticate an HTTP request.

To make that API token available in a flow via a server variable, follow these steps:

The API token is configured as a server variable, which should then be accessible in one or more flows.

1. In the UI, open server/variables

2. Create a new server variable with key api_token and the token value. It’s optional, but recommended, to enable the “Is Secret” setting on sensitive values.

3. Open the flow that should use this server variable in the flow editor (or create a new flow)

4. In the flow editor, select the “variables” tab, and create a new variable with key api_token

5. Do not enable the “internal only” setting of the flow variable

The API token may now be used in the flow. Typically, an HTTP node would be configured with an Authorization header, and a value of Bearer ${vars:api_token}.

For secrets like this, and other variables which are essential in a flow, it makes sense to configure those variables as required variables. When a flow variable is required, the flow will fail to execute if the target server variable is not available.

There are multiple ways to access a flow variable within a flow.

Using variable expressions

Typically used within node configuration, the value can be accessed with:

${vars:api_token}

Or to provide a default value if the server variable does not exist, or if it’s flow variable does not have a configured default:

${vars:api_token||someDefault}

Via Javascript

const token = $vars.api_token;

Or to provide a default value:

const token = $vars.api_token || "someDefault";

If variable keys contain dashes, or characters not allowed in property names:

const token = $vars["api-token"];

Note

It is technically possible (but not necessary) to use variable expressions within the configuration of JS nodes.

This will work as expected:

const token = "${vars:api_token}";

But this causes a syntax error, since replacements are exact:

const token = ${vars:api_token}