Variable scopes
The variable scopes scripts read and write, from values for this send to globals.
Declaration
relay.variables
relay.environment
relay.collectionVariables
relay.workspaceVariables
relay.globalsOverview
Each scope is an object with the same methods. relay.variables reads through every scope the request can use, in the order Relay resolves {{name}} tokens. The other scopes each read and write one table of variables.
| Scope | Reads | Writes |
|---|---|---|
relay.variables | Values set for this send, then the request's folders (innermost first), the active environment, the collection, the workspace and globals. | Values that last for this send only. |
relay.environment | The workspace's active environment. | The active environment. |
relay.collectionVariables | The request's collection. | The request's collection. |
relay.workspaceVariables | The workspace's default variables. | The workspace's default variables. |
relay.globals | Global variables. | Global variables. |
// Saved to the active environment, so later requests can use {{token}}.
relay.environment.set("token", relay.response.json().access_token);
// Lasts for this send only.
relay.variables.set("requestTime", new Date().toISOString());Drafts don't belong to a collection, so for a draft relay.collectionVariables is empty and folders don't take part in relay.variables.
Topics
Reading values
get(key)
scope.get(key: string): string | undefinedReturns the variable's value, or undefined if it isn't set.
has(key)
scope.has(key: string): booleanReturns whether the variable is set.
toObject()
scope.toObject(): objectReturns the variables as an object of names and values.
Writing values
set(key, value)
scope.set(key: string, value: any): voidSets the variable's value.
unset(key)
scope.unset(key: string): voidRemoves the variable.
clear()
scope.clear(): voidRemoves every variable.
Expanding tokens
replaceIn(text)
scope.replaceIn(text: string | object): string | objectReplaces {{name}} tokens in text with their variables' values.
Environment
name
relay.environment.name: string | undefinedThe active environment's name, or undefined when no environment is active.
Discussion
Values are strings
Variables hold text. set() stores a number or Boolean as its text and an object or array as JSON, and get() always returns a string. Parse values you stored as JSON with JSON.parse. Setting a value of undefined or null stores an empty string.
get() returns a value as it's written, without expanding the tokens in it. If baseUrl is {{host}}/v1, get("baseUrl") returns {{host}}/v1. Use replaceIn() to expand it.
Reading follows Relay's rules
Disabled rows and rows without a name are ignored. When a table has several enabled rows with the same name, the last one is the one that counts, as when Relay resolves a request. A secret that has no value on this Mac reads as undefined, though has() still returns true.
replaceIn() expands tokens the way the request will be resolved, including values set with relay.variables.set(). Each dynamic variable such as {{$guid}} gets a new value. When text is an object or array, replaceIn() returns a copy with the tokens in every string expanded.
Writing saves the change
set(), unset() and clear() on relay.environment, relay.collectionVariables, relay.workspaceVariables and relay.globals change the variables in the workspace, which Relay saves as if you'd edited them. A later read in the same script sees the change. Changes from a pre-request script are applied before Relay resolves the request's variables, so the request uses the new values.
set() changes the existing row with that name, keeping its description and whether it's secret, or adds a row when there isn't one. unset() removes the enabled rows with that name. You can't undo a script's set() or unset(); you can undo clear() with Edit > Undo.
On relay.variables, set(), unset() and clear() change only the values for this send. Those values take precedence over every scope, apply to the request's {{name}} tokens, and are still there in the post-response script.
When a scope doesn't exist for the request, a write does nothing and Relay writes a warning to the Console. For example, relay.environment.set() warns when no environment is active, and relay.collectionVariables.set() warns for a draft.
Folder variables
relay.variables reads folder variables, but there's no scope for writing them. Scripts can't set folder variables. Bruno's bru.getFolderVar() reads them; see bru.
See Also
- Reading and writing variables in scripts: Read variables and set new values from pre-request and post-response scripts.
- Using variables: Insert values into requests with
{{name}}tokens and see where each value comes from. - Dynamic variables: Dynamic variables that generate a new value each time a request is sent.