Custom Variables

Overview

Custom Variables allow you to create, manage, and manipulate data throughout your workflows. They support different scopes (global, workflow, step), types, and transformations for flexible data handling.

📦 Purpose

Use Custom Variables to:

• Store intermediate values

• Pass data between steps

• Manage configuration

• Create reusable data structures

• Track state across workflow

---

When to Use Custom Variables

✅ Good Use Cases

Scenario	Reason
Data Transformation	Convert/format data between steps
State Management	Track values through workflow
Configuration	Centralize settings and parameters
Computed Values	Calculate derived data
Reusable Data	Share across multiple steps
Conditional Logic	Use values in conditions
Output Generation	Compose final results

❌ Anti-Patterns (Don't Do)

• ❌ Store sensitive data (use Secrets instead)

• ❌ Use as temporary scratch (defeats purpose)

• ❌ Overly complex transformations (use helper steps)

• ❌ Mutable shared state (causes race conditions)

• ❌ Unclear naming (makes code unreadable)

---

Variable Scopes

Global Scope

Available across all workflows and executions:

Scope: Global
Lifecycle: Persists across multiple workflow runs
Visibility: All workflows in project
Use Case: Shared configuration, constants

Example:
global.api_base_url = "https://api.example.com"
global.max_retries = 3
global.timeout_seconds = 30

When to use:

• Project-level constants

• Shared configuration

• Frequently changing values

• Environment settings

Workflow Scope

Available throughout a single workflow execution:

Scope: Workflow
Lifecycle: Exists during workflow execution
Visibility: All steps in workflow
Use Case: Workflow-specific data, intermediate values

Example:
workflow.user_id = "usr_123"
workflow.session_token = "token_abc"
workflow.test_start_time = "2024-01-15 14:30"

When to use:

• IDs from API responses

• Temporary calculations

• Workflow-specific settings

• Run-time state

Step Scope

Local to individual step:

Scope: Step
Lifecycle: Exists during step execution
Visibility: Only within step
Use Case: Temporary processing, step outputs

Example:
step.response_data = {...}
step.parsed_json = {...}
step.error_message = "..."

When to use:

• Step-specific processing

• Temporary values

• Step outputs

• Error handling

---

Variable Types

Primitive Types

Basic data types:

String:
  variable = "Hello World"
  variable = "[email protected]"

Number:
  variable = 42
  variable = 3.14
  variable = -1

Boolean:
  variable = true
  variable = false

Null:
  variable = null

Complex Types

Structured data:

Object/Dictionary:
  variable = {
    "id": "123",
    "name": "John",
    "email": "[email protected]"
  }

Array/List:
  variable = ["item1", "item2", "item3"]
  variable = [1, 2, 3, 4, 5]

Nested Structure:
  variable = {
    "user": {
      "id": "123",
      "profile": {
        "name": "John",
        "age": 30
      }
    },
    "permissions": ["read", "write"]
  }

---

Creating and Using Variables

Creating Variables

Step 1: API - Get User
  Output: 
    user_data = {
      "id": "usr_123",
      "email": "[email protected]",
      "role": "admin"
    }

Step 2: Create Custom Variables
  workflow.user_id = user_data.id
  workflow.user_email = user_data.email
  workflow.is_admin = (user_data.role == "admin")

Step 3: Use Variables
  [API Call: /users/{workflow.user_id}]
  [Email: To {workflow.user_email}]
  [If {workflow.is_admin}...]

Modifying Variables

Step 1: Initialize
  workflow.counter = 0
  workflow.names = []

Step 2: Update/Append
  workflow.counter = workflow.counter + 1
  workflow.names.append("new_item")
  workflow.status = "processing"

Accessing Nested Values

Object access:
  user.name
  user.profile.email
  user.settings.notifications.email

Array access:
  items[0]
  items[items.length - 1]

Safe access (null-safe):
  user?.profile?.email
  items?.[0]

---

Practical Examples

Example 1: Processing User Registration

Workflow: User Registration

Step 1: Web - Fill Registration Form
  Output: form_data

Step 2: Create Variables
  workflow.email = form_data.email
  workflow.password = form_data.password
  workflow.first_name = form_data.first_name
  workflow.last_name = form_data.last_name
  workflow.full_name = first_name + " " + last_name

Step 3: API - Create User
  Email: {workflow.email}
  Name: {workflow.full_name}
  Output: api_response

Step 4: Store User Data
  workflow.user_id = api_response.user_id
  workflow.account_created = true
  workflow.created_timestamp = current_time

Step 5: Send Welcome Email
  To: {workflow.email}
  Name: {workflow.first_name}

Step 6: Data Hub - Store
  Key: workflow.user_id
  Value: {
    email: workflow.email,
    full_name: workflow.full_name,
    created: workflow.created_timestamp
  }

Example 2: Data Aggregation

Workflow: Collect Test Metrics

Step 1: Initialize Aggregation
  workflow.metrics = {
    total_tests: 0,
    passed: 0,
    failed: 0,
    duration_ms: 0
  }

Step 2: Loop Through Tests
  FOR each_test:
    [Run Test]
    
    workflow.metrics.total_tests += 1
    
    IF test_passed THEN
      workflow.metrics.passed += 1
    ELSE
      workflow.metrics.failed += 1
    
    workflow.metrics.duration_ms += test_duration

Step 3: Calculate Percentages
  workflow.pass_rate = 
    (workflow.metrics.passed / workflow.metrics.total_tests) * 100
  
  workflow.fail_rate = 100 - workflow.pass_rate

Step 4: Send Report
  [Send Email with metrics]
  Pass Rate: {workflow.pass_rate}%

Example 3: Multi-Step Data Transformation

Workflow: Transform API Response

Step 1: API - Get Orders
  Output: api_response with orders list

Step 2: Transform to Internal Format
  workflow.orders = []
  
  FOR each api_response.orders:
    workflow.order_item = {
      id: order.order_id,
      customer: order.customer_name,
      amount: order.total_price,
      status: order.order_status,
      items_count: order.items.length
    }
    
    workflow.orders.append(workflow.order_item)

Step 3: Filter Orders
  workflow.high_value_orders = []
  
  FOR each workflow.orders:
    IF order.amount > 1000 THEN
      workflow.high_value_orders.append(order)

Step 4: Generate Report
  workflow.report = {
    total_orders: workflow.orders.length,
    high_value_count: workflow.high_value_orders.length,
    average_amount: calculate_average(workflow.orders),
    top_order: workflow.orders[0]
  }

Step 5: Store Report
  [Send to Data Hub or file]

Example 4: Configuration Management

Workflow: Environment-Aware Configuration

Step 1: Get Environment
  Output: environment

Step 2: Set Configuration Variables
  IF environment == "production" THEN
    global.api_timeout = 30
    global.retry_attempts = 5
    global.log_level = "error"
    
  ELSE IF environment == "staging" THEN
    global.api_timeout = 15
    global.retry_attempts = 3
    global.log_level = "warning"
    
  ELSE
    global.api_timeout = 5
    global.retry_attempts = 1
    global.log_level = "debug"

Step 3: Use Configuration
  [API Call with timeout: {global.api_timeout}]
  [Retry with attempts: {global.retry_attempts}]
  [Log at level: {global.log_level}]

Example 5: State Tracking

Workflow: Track Workflow State

Step 1: Initialize State
  workflow.state = "initialized"
  workflow.step_counter = 0
  workflow.errors = []

Step 2: Setup
  workflow.state = "setting_up"
  workflow.step_counter = 1

Step 3: Execute Test
  workflow.state = "executing"
  workflow.step_counter = 2
  
  [Run test]
  
  IF test_failed THEN
    workflow.errors.append({
      step: workflow.step_counter,
      error: error_message,
      timestamp: current_time
    })

Step 4: Cleanup
  workflow.state = "cleaning_up"
  workflow.step_counter = 3
  
  [Cleanup operations]

Step 5: Complete
  workflow.state = "completed"
  workflow.final_status = IF workflow.errors.empty THEN "pass" ELSE "fail"

Step 6: Report
  [Send report with workflow.state and workflow.errors]

---

Variable Operations

String Operations

Concatenation:
  full_name = first_name + " " + last_name
  message = "User: " + user.name + " created at " + timestamp

Case Conversion:
  upper_name = name.toUpperCase()
  lower_name = name.toLowerCase()

Substring:
  domain = email.substring(email.indexOf("@") + 1)
  code = reference.substring(0, 3)

Replace:
  clean_phone = phone.replace("-", "").replace(" ", "")

Numeric Operations

Arithmetic:
  total = price * quantity
  discount_amount = total * 0.1
  final_price = total - discount_amount
  average = sum / count

Comparison:
  is_expensive = price > 1000
  within_budget = cost <= budget_limit
  at_capacity = current_load >= max_capacity

Rounding:
  rounded = round(value, 2)
  ceiling = ceil(value)
  floor = floor(value)

Array Operations

Addition:
  all_items.append(new_item)
  combined = array1 + array2

Filtering:
  active_users = users.filter(u => u.status == "active")
  expensive_items = items.filter(i => i.price > 1000)

Mapping:
  user_names = users.map(u => u.name)
  prices = products.map(p => p.price)

Sorting:
  sorted_by_price = items.sort((a, b) => a.price - b.price)
  sorted_descending = items.sort((a, b) => b.created - a.created)

Object Operations

Merge:
  complete_user = {...user_from_api, ...user_profile}

Extract Fields:
  name_only = {name: user.name}
  summary = {id: user.id, email: user.email}

Modification:
  user.status = "updated"
  user.last_updated = current_time

---

Best Practices

✅ Do

• Use clear names - user_email not ue or temp

• Choose right scope - Global for constants, workflow for runtime

• Document complex variables - Add comments for non-obvious data

• Initialize before use - Set defaults to avoid null errors

• Keep simple - Don't over-nest structures

• Use type checking - Validate before use

• Clean up - Delete no-longer-needed variables

• Name by purpose - Reflect what data represents

❌ Don't

• Use global for temporary - Workflow scope for short-lived data

• Store secrets - Use proper secret management

• Over-nest - More than 3 levels gets confusing

• Reuse for different purposes - Create new variables instead

• Skip validation - Check null and type before use

• Use single letters - x, temp, data are unclear

• Mutate shared state - Can cause race conditions

• Store large objects unnecessarily - Memory impact

---

Variable Naming Conventions

Recommended Patterns

Scope prefix:
  global.* = global variables
  workflow.* = workflow variables
  step.* = step variables

Type indicator:
  *_list = arrays/lists
  *_count = numeric counts
  *_map = dictionaries/objects
  *_flag = boolean values
  is_* = boolean properties
  has_* = boolean checkers

Example names:
  workflow.user_email ✅
  global.max_retries ✅
  step.api_response ✅
  workflow.error_messages_list ✅
  workflow.is_authenticated ✅
  workflow.user_count ✅

---

Troubleshooting

Issue: Variable is undefined/null

Symptoms:

• Getting null reference error

• Variable not found

Causes:

• Variable not initialized

• Scope mismatch

• Conditional logic skipped initialization

Solutions:

1. Initialize variables before use

2. Check scope (global vs workflow)

3. Add null checks

4. Set default values

Issue: Variable type mismatch

Symptoms:

• Cannot convert string to number

• Type error when using variable

Causes:

• Expected different type

• API response format changed

• Missing type conversion

Solutions:

1. Convert explicitly: parseInt(), toString()

2. Check API response structure

3. Add type validation

Issue: Performance degradation

Symptoms:

• Workflow slowing down

• Memory usage increasing

Causes:

• Large variables accumulating

• Global scope pollution

• Inefficient data structures

Solutions:

1. Use appropriate scope (not global for temporary)

2. Clean up large variables

3. Use more efficient data structures

4. Consider moving to Data Hub for large data

---

Variable Lifecycle

Creation

Step 1: Variable created
  workflow.user_id = api_response.id

State: Variable exists, ready to use

Usage

Step 2-N: Variable used in multiple steps
  [API: /users/{workflow.user_id}]
  [Email: Send to user {workflow.user_id}]
  [If {workflow.user_id} exists...]

State: Variable used across workflow

Modification

Step N: Variable modified
  workflow.user_id = new_id

State: Updated value persists for remaining steps

Scope End

End of workflow (for workflow scope):
  workflow.* variables deleted

End of step (for step scope):
  step.* variables deleted

Never (for global scope):
  global.* persists across runs

---

Real-World Scenarios

E-Commerce: Order Processing

Workflow: Complete Order

[Get Cart Data]
  workflow.items = cart.items
  workflow.subtotal = calculate_sum(items.prices)
  workflow.tax = workflow.subtotal * 0.08
  workflow.total = workflow.subtotal + workflow.tax

[Apply Coupon if Available]
  IF workflow.coupon_code exists THEN
    workflow.discount = get_discount(workflow.coupon_code)
    workflow.total = workflow.total - workflow.discount

[Create Order]
  workflow.order_data = {
    items: workflow.items,
    total: workflow.total,
    customer: workflow.customer_id
  }

[Send Confirmation]
  Order Total: {workflow.total}

API Testing: Response Processing

Workflow: Process and Validate Response

[API Call]
  Output: response

[Extract and Transform]
  workflow.users = response.data.users
  workflow.user_count = workflow.users.length
  workflow.active_users = 
    workflow.users.filter(u => u.status == "active")

[Validate]
  IF workflow.user_count > 100 THEN
    [Pass: Large dataset]
  ELSE
    [Fail: Expected more users]

[Report]
  Total Users: {workflow.user_count}
  Active: {workflow.active_users.length}

---

Related Topics

• Data Propagation - Data flow overview

• Conditional Execution - Using variables in conditions

• Data Hub Action - Storing variables

• Workflow Patterns - Common variable patterns

• Execution Flow - Variable lifecycle

---

Summary

• Custom Variables manage data throughout workflows

• Use different scopes - Global, workflow, or step

• Choose clear names - Reflect purpose, not role

• Initialize before use - Prevent null errors

• Keep simple - Complex nesting reduces readability

• Validate types - Check before using variables

---

Next: Learn about Error Handling for robust workflows.