Skip to navigation
WorkflowsCore Concepts

Configuration

View as Markdown

Most workflows lean on a handful of settings that never change from one run to the next: the office timezone, the hours you count as after hours, an account name at a partner service, the address a summary email goes to. Configuration is where those live. You define them once for your organization, and every workflow you build can read them by name.

The alternative is typing the same literal value into six different steps across three workflows. When the office hours change, you then have to remember all nine places. With configuration you change one line and everything follows.

Defining settings

Your organization has one set of named settings shared by every workflow. Each name follows the same rules as a secret name:

  • Lowercase letters, numbers, and underscores only.
  • Must start with a letter.
  • Up to 64 characters.

A value can be text, a number, true or false, a list, or a group of nested values:

timezone            "America/Phoenix"
after_hours_start   17
notify_on_weekends  false
escalation_emails   ["sarah@chenins.com", "ops@chenins.com"]
business_hours      { "open": 8, "close": 17 }

Values are fixed. A setting cannot be an expression, cannot read a step’s output, and cannot point at a secret. If you need a computed value, compute it in a step and read it from there.

You can hold up to 100 settings, and the whole set is limited to 64 KB. Saving replaces the complete set: a name you leave out is removed, and saving an empty set clears configuration entirely.

Names inside a nested group are tidied to lowercase with underscores when you save, so { "openHour": 8 } comes back as { "open_hour": 8 }. That is the name your workflows use. Two names in the same group that would tidy to the same thing (openHour and open_hour, say) are rejected rather than quietly merged, so pick one.

Using a setting in a workflow

Reference a setting by its group and name, the same way you reference any other value:

config.timezone

Nested values keep going with a dot:

config.business_hours.open

As with any value, you normally pick it from the builder’s value picker rather than typing it. Settings are available everywhere in a workflow, including inside a For Each or Sub Graph body, and they are ready from the very first step because they do not depend on anything having run.

A setting can be combined with other text, exactly like any other value:

"https://" + config.partner_account + ".example.com/quotes"

Because settings are shared and can change at any time, a workflow that points at a name you later remove keeps publishing fine and then fails when it runs, at the step that reads it. The error names the setting it could not find. If you rename or remove a setting, check the workflows that used it.

When a change takes effect

A run reads configuration once, when it starts, and keeps those values for its whole life. Runs already in progress are never disturbed by a change.

  • Manually started, webhook-triggered, and debug runs pick up a change immediately.
  • Scheduled workflows are the exception. A schedule captures configuration when the workflow is published, so after changing a setting, republish any scheduled workflow that should use the new value. This works the same way as secrets.

Configuration is stored in plain text. Anyone who can open your workflows can read it, and its values are shown unmasked in the debugger and in run history. Never put an API key, password, or token in configuration - use a secret instead. Fields that ask for a credential will not accept a setting.

Configuration or a Data Transform node

Before configuration existed, a common trick was to put a Data Transform node at the top of a workflow purely to hold fixed settings, then read them as node.settings.timezone. Configuration is the better home for those: it costs nothing to run, it reads as config.timezone, it is available before the first step, and every workflow shares one copy.

Keep a Data Transform node for what it is good at: reshaping data that a step actually produced, or snapshotting values into run history.

Choosing where a value belongs

UseWhen the value is
ConfigurationThe same for every run, shared across workflows, and not sensitive.
SecretA credential: an API key, password, or token.
Start inputDifferent on every run, supplied by whoever or whatever starts it.
Variables & Data Flow

See how configuration fits alongside the other groups of values.

Secrets

Store API keys and passwords safely instead of in configuration.