rq.collectionVariables (Collection variables)

Complete reference for the rq.collectionVariables object in Requestly scripts to manage collection-scoped variables dynamically.

The rq.collectionVariables object provides methods to manage collection variables during script execution. Collection variables are scoped to a specific collection and are only accessible within the requests that belong to that collection. Unlike environment variables (scoped to a specific environment), collection variables persist across all environments within the same collection.

Methods

rq.collectionVariables.set(key, value)

Creates or updates a collection variable with the given key and value. If the variable already exists, it will be updated with the new value.

Parameters:

• key (string): The name of the collection variable
• value (any): The value to store. Scalar values are stored as strings; passing an array stores a real array, so a later get returns the array unchanged. Passing null or undefined clears the variable, which is equivalent to unset(key), so a later get returns undefined (not the string "null").

Example:

rq.collectionVariables.set("basePath", "/v1/users");

Passing an array to set stores a real array, and get returns it as a real array with .first() and .last() helpers. See rq.environment for examples.

rq.collectionVariables.get(key)

Retrieves the value of the specified collection variable.

Parameters:

• key (string): The name of the collection variable to retrieve

Returns: The value of the collection variable, or undefined if it doesn’t exist.

Example:

const path = rq.collectionVariables.get("basePath");
console.log("Collection Variable basePath:", path);

rq.collectionVariables.unset(key)

Removes the specified collection variable.

Parameters:

• key (string): The name of the collection variable to remove

Example:

rq.collectionVariables.unset("basePath");

rq.collectionVariables.clear()

Removes all variables from the current collection.

Parameters: none.

Example:

rq.collectionVariables.clear();
console.log("All collection variables cleared");

rq.collectionVariables.clear() works only when the request belongs to a collection. Calling it from a request that is not in a collection throws an error, the same as set() and unset().

Common Use Cases

Store API Base Path

Set a base path that all requests in the collection can use:

// In pre-request script
rq.collectionVariables.set("basePath", "/api/v2");
rq.collectionVariables.set("apiVersion", "v2");

Then use it in your request URL:

{{baseUrl}}{{basePath}}/users

Share Data Between Collection Requests

Pass data from one request to another within the same collection:

// In the first request's post-response script
const data = rq.response.json();
rq.collectionVariables.set("createdResourceId", data.id);
rq.collectionVariables.set("resourceName", data.name);

// In the next request's pre-request script
const resourceId = rq.collectionVariables.get("createdResourceId");
console.log("Using resource ID:", resourceId);

Store Default Values

Set default values that can be overridden by environment variables:

// In pre-request script
const pageSize = rq.environment.get("pageSize") || 
                 rq.collectionVariables.get("defaultPageSize") || 
                 "20";
console.log("Using page size:", pageSize);

Track Collection State

Maintain state across requests in a collection:

// Track if authentication has been completed
const isAuthenticated = rq.collectionVariables.get("isAuthenticated");
if (!isAuthenticated) {
    console.log("Need to authenticate first");
    rq.collectionVariables.set("isAuthenticated", "true");
}

Store Computed Values

Calculate and store values that multiple requests will use:

// In pre-request script
const timestamp = Date.now();
const signature = generateSignature(timestamp); // Your custom function

rq.collectionVariables.set("requestTimestamp", timestamp);
rq.collectionVariables.set("requestSignature", signature);

Best Practices

1. Naming Convention: Use clear, descriptive names that indicate the variable’s purpose

   rq.collectionVariables.set("authBaseEndpoint", "/auth");
   rq.collectionVariables.set("apiVersion", "v2");
   

2. Initialize in Setup Requests: Create a setup or initialization request that sets default collection variables

3. Validate Before Use: Check if a variable exists before using it

   const value = rq.collectionVariables.get("myVar");
   if (!value) {
       console.error("Collection variable 'myVar' not found");
   }
   

4. Clean Up: Remove variables that are no longer needed

   rq.collectionVariables.unset("temporaryData");
   

5. Document Variables: Add comments in your scripts explaining what each variable is for

   // Store the created user ID for use in subsequent requests
   rq.collectionVariables.set("userId", data.id);
   

Related Documentation

• Pre-request & Post-response Scripts
• rq.sendRequest Object
• rq.execution Object
• rq.request Object
• rq.response Object
• rq.environment Object
• rq.globals Object
• rq.vault Object
• rq.test Object
• rq.expect Object