Using Variables in Boomerang

Variables allow you to dynamically construct your request data. You can use variables in multiple parts of your request:

• URLs: https://{{baseUrl}}/api/{{version}}/users
• Headers: Authorization: Bearer {{authToken}}
• Query Parameters: ?userId={{userId}}&timestamp={{timestamp}}
• Request Body:{ "user": "{{username}}", "token": "{{accessToken}}" }

Important

Variable names are case-sensitive. For example, {{userId}} and {{UserID}} are treated as different variables.

Variables in Boomerang can be declared at different levels:

1. Environment Variables (Lowest Priority)
2. Global Variables
3. Folder Level Variables
4. Request Level Variables
5. Collection Runner Data Variables (Highest Priority)

Environment Variables

Environment variables are managed through the environment page using a key-value form:

1. Click the Environment dropdown in the top-right corner
2. Select "Create Environment"
3. Name your environment (e.g., "Development" or "Production")
4. Add variables using the key-value form:
   • Key: baseUrl
   • Value: https://api.dev.example.com
5. Click "Add Variable" to add more variables

All changes to environment variables are automatically saved.

Global Variables

Global variables are created through scripts and accessible across all requests:

// Setting global variables in pre-request script
bg.globals.set("requestId", Date.now());
bg.globals.set("timestamp", new Date().toISOString());

// Reading response data in post-response script
const responseData = bg.response.json();
bg.globals.set("userId", responseData.id);

Variable Precedence

Precedence Order (Highest to Lowest)

1. Collection Runner Data Variables

   • Variables from data file (CSV) during collection runs
   • Highest precedence, overrides all other variables
   • Each column in CSV becomes a variable
   • Example: If CSV has a column "userId", it overrides any "userId" defined elsewhere

2. Request Level Variables

   • Defined in the request's script section
   • Overrides folder, global, and environment variables
   • Set using bg.variables.set("variableName", "value")

3. Folder Level Variables

   • Defined in folder's variables form section and through scripts
   • Overrides global and environment variables
   • Available to all requests within the folder
   • In script, set using bg.variables.set("variableName", "value")

4. Global Variables

   • Defined through scripts using bg.globals.set()
   • Overrides environment variables
   • Set using bg.globals.set("variableName", "value")

5. Environment Variables

   • Defined in environment settings
   • Lowest precedence
   • Useful for environment-specific configurations

Variable Resolution Flow

Collection Runner Data Variable ↓
(if not found) ↓
Request Level Variable ↓
(if not found) ↓
Folder Level Variable ↓
(if not found) ↓
Global Variable ↓
(if not found) ↓
Environment Variable

Collection Runner Data Example

userId,name,email
1001,John Doe,john@example.com
1002,Jane Smith,jane@example.com

When running the collection with this CSV file:

• Each row is processed sequentially
• Variables userId, name, and email are available for each iteration
• These variables override any similar named variables defined at other levels
• Useful for data-driven testing and batch processing

Practical Examples

Dynamic URL Construction

// Base URL defined in environment
Key: baseUrl
Value: https://api.example.com

// Version defined in environment
Key: version
Value: v2

// Using variables in URL
{{baseUrl}}/api/{{version}}/users/{{userId}}

Dynamic Headers

Authorization: Bearer {{authToken}}
X-Request-ID: {{requestId}}
X-API-Version: {{version}}

Dynamic Request Body

{
  "user": {
    "id": "{{userId}}",
    "token": "{{sessionToken}}",
    "lastAccess": "{{timestamp}}"
  }
}

Troubleshooting

If variables aren't resolving:

1. Check variable casing matches exactly
2. Verify environment is active for environment variables
3. Confirm global variables are set before use
4. Check console for script errors