Scripting API

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.globals

Overview

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.

ScopeReadsWrites
relay.variablesValues 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.environmentThe workspace's active environment.The active environment.
relay.collectionVariablesThe request's collection.The request's collection.
relay.workspaceVariablesThe workspace's default variables.The workspace's default variables.
relay.globalsGlobal 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 | undefined

Returns the variable's value, or undefined if it isn't set.

has(key)

scope.has(key: string): boolean

Returns whether the variable is set.

toObject()

scope.toObject(): object

Returns the variables as an object of names and values.

Writing values

set(key, value)

scope.set(key: string, value: any): void

Sets the variable's value.

unset(key)

scope.unset(key: string): void

Removes the variable.

clear()

scope.clear(): void

Removes every variable.

Expanding tokens

replaceIn(text)

scope.replaceIn(text: string | object): string | object

Replaces {{name}} tokens in text with their variables' values.

Environment

name

relay.environment.name: string | undefined

The 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