Variables & Data Commands

Variables and data commands let you store, calculate, and manipulate data during your automation. These commands are the “glue” that connects different parts of your automation together, allowing you to pass data from one step to the next, perform calculations, transform text, and manage lists of items.

Without these commands, your automation would be limited to static, hard-coded actions. With them, you can create dynamic, data-driven workflows that respond to what they find on each page.

---

set_variable

Creates or updates a state variable with a specific value. Variables created with this command are available to all subsequent commands in your automation.

Description

The set_variable command stores a value under a named key in your automation’s state. You can then reference this value in any later command using the ${variable_name} syntax. This is the most fundamental way to pass data between commands.

The variable is also injected as a <meta> tag in the page’s DOM, making it accessible to dataset selectors that use the variable= selector type.

Parameters

Parameter	Type	Required	Default	Description
name	string	✅ Yes	—	The name of the variable. Must be unique within your automation. Use this name to reference the variable later with ${name}.
value	any	✅ Yes	—	The value to store. Can be a string, number, boolean, object, or array. Supports ${variable} substitution.

Examples

Store a simple string:

{
  "command": "set_variable",
  "params": {
    "name": "search_term",
    "value": "wireless headphones"
  }
}

Store a value from another variable:

{
  "command": "set_variable",
  "params": {
    "name": "full_url",
    "value": "https://example.com/search?q=${search_term}"
  }
}

Store a calculated value:

{
  "command": "set_variable",
  "params": {
    "name": "discount_multiplier",
    "value": 0.85
  }
}

Store a list of items:

{
  "command": "set_variable",
  "params": {
    "name": "keywords",
    "value": ["laptop", "tablet", "phone"]
  }
}

Behavior Notes

• If a variable with the same name already exists, its value is overwritten.
• The variable is saved to the checkpoint immediately, so it survives crashes.
• The variable is injected into the page as a <meta> tag, enabling variable= selectors in datasets.
• Variables created with set_variable are available in all subsequent commands, including nested commands inside loops and conditionals.
• Variables are scoped to the current automation run. They do not persist between separate runs.

Tips

• Use descriptive variable names like product_price instead of x or temp.
• Variable names are case-sensitive: myVar and myvar are different variables.
• Avoid using special characters in variable names. Stick to letters, numbers, and underscores.
• You can overwrite a variable as many times as needed during a run.

---

math_operation

Performs a mathematical operation on two values and optionally stores the result in a variable.

Description

The math_operation command performs basic arithmetic on two operands. This is useful for calculating prices, computing percentages, counting items, or any other numerical calculation your automation needs.

The result is returned by the command and can be stored in a variable using the output_variable parameter.

Parameters

Parameter	Type	Required	Default	Description
left_operand	number/string	✅ Yes	—	The left operand. Can be a number or a ${variable} reference.
operator	string	✅ Yes	+	The mathematical operator. Options: +, -, *, /, %.
right_operand	number/string	✅ Yes	—	The right operand. Can be a number or a ${variable} reference.
output_variable	string	No	—	The name of the variable to store the result in.

Available Operators

Operator	Name	Example	Result
+	Addition	10 + 5	15
-	Subtraction	10 - 5	5
*	Multiplication	10 * 5	50
/	Division	10 / 5	2
%	Modulo (remainder)	10 % 3	1

Examples

Add two values:

{
  "command": "math_operation",
  "params": {
    "left_operand": "${item_price}",
    "operator": "+",
    "right_operand": "${shipping_cost}",
    "output_variable": "total_price"
  }
}

Calculate a discount:

{
  "command": "math_operation",
  "params": {
    "left_operand": "${original_price}",
    "operator": "*",
    "right_operand": 0.85,
    "output_variable": "discounted_price"
  }
}

Calculate a percentage:

{
  "command": "math_operation",
  "params": {
    "left_operand": "${items_found}",
    "operator": "/",
    "right_operand": "${total_items}",
    "output_variable": "percentage_found"
  }
}

Check if a number is even (modulo):

{
  "command": "math_operation",
  "params": {
    "left_operand": "${page_number}",
    "operator": "%",
    "right_operand": 2,
    "output_variable": "is_odd_check"
  }
}

Behavior Notes

• Both operands are converted to numbers before the operation. If conversion fails, the command will error.
• Division by zero will cause an error.
• The modulo operator (%) returns the remainder of a division. Useful for checking if a number is even/odd.
• If output_variable is not specified, the result is returned but not stored. You would typically use output_variable to save the result.
• Operands can be ${variable} references, allowing you to use values from earlier commands.

Tips

• Use math_operation instead of run_script for simple calculations. It’s faster and simpler.
• For complex calculations, use run_script with JavaScript instead.
• The modulo operator is great for pagination logic (e.g., “do something every 5th page”).

---

string_operation

Performs string manipulation operations like splitting, replacing, converting case, and encoding.

Description

The string_operation command transforms text values. This is essential for cleaning up scraped data, extracting specific parts of text, formatting output, and preparing data for use in other commands.

The result is stored in the variable specified by output_variable.

Parameters

Parameter	Type	Required	Default	Description
value	string	✅ Yes	—	The input string to operate on. Supports ${variable} substitution.
operation	string	✅ Yes	to_upper	The operation to perform. See operations table below.
params	object	No	{}	Operation-specific parameters. Depends on the chosen operation.
output_variable	string	No	—	The name of the variable to store the result in.

Available Operations

Operation	Description	Required Params
concat	Concatenates (joins) a value to the end of the string	params.value
split	Splits the string into an array using a delimiter	params.delimiter
replace	Finds and replaces text using regex	params.find, params.replace_with, params.flags
to_upper	Converts the string to UPPERCASE	None
to_lower	Converts the string to lowercase	None
trim	Removes whitespace from the start and end	None
url_encode	URL-encodes the string (encodes special characters)	None

Operation Details

concat

Joins another string to the end of the input string.

Param	Type	Description
params.value	string	The string to append to the end.

{
  "command": "string_operation",
  "params": {
    "value": "Product: ",
    "operation": "concat",
    "params": { "value": "${product_name}" },
    "output_variable": "full_product_label"
  }
}

split

Splits a string into an array using a delimiter character.

Param	Type	Description
params.delimiter	string	The character(s) to split on (e.g., ,, ;, ).

{
  "command": "string_operation",
  "params": {
    "value": "red,blue,green",
    "operation": "split",
    "params": { "delimiter": "," },
    "output_variable": "color_list"
  }
}

Result: color_list = ["red", "blue", "green"]

replace

Finds text matching a pattern and replaces it with new text. Uses JavaScript regular expressions.

Param	Type	Description
params.find	string	The regex pattern to find.
params.replace_with	string	The text to replace matches with.
params.flags	string	Regex flags (e.g., g for global, i for case-insensitive).

{
  "command": "string_operation",
  "params": {
    "value": "$29.99 USD",
    "operation": "replace",
    "params": {
      "find": "[$]",
      "replace_with": "",
      "flags": "g"
    },
    "output_variable": "clean_price"
  }
}

Result: clean_price = "29.99 USD"

to_upper

Converts the entire string to UPPERCASE.

{
  "command": "string_operation",
  "params": {
    "value": "${product_name}",
    "operation": "to_upper",
    "output_variable": "upper_name"
  }
}

to_lower

Converts the entire string to lowercase.

{
  "command": "string_operation",
  "params": {
    "value": "${product_name}",
    "operation": "to_lower",
    "output_variable": "lower_name"
  }
}

trim

Removes whitespace (spaces, tabs, newlines) from the beginning and end of the string.

{
  "command": "string_operation",
  "params": {
    "value": "  ${scraped_text}  ",
    "operation": "trim",
    "output_variable": "clean_text"
  }
}

url_encode

URL-encodes the string, replacing special characters with their percent-encoded equivalents. Essential for building URLs with user input.

{
  "command": "string_operation",
  "params": {
    "value": "wireless headphones & speakers",
    "operation": "url_encode",
    "output_variable": "encoded_search"
  }
}

Result: encoded_search = "wireless%20headphones%20%26%20speakers"

Behavior Notes

• The value parameter supports ${variable} substitution, so you can operate on values from earlier commands.
• If output_variable is not specified, the result is returned but not stored.
• The replace operation uses JavaScript regex syntax. Special regex characters in the find pattern must be escaped.
• The split operation returns an array. You can use this array in a for_each loop.
• Operations are case-sensitive unless you use the i flag with replace.

Tips

• Chain multiple string_operation commands to perform complex text transformations.
• Use trim after scraping text to remove unwanted whitespace.
• Use url_encode before inserting user input into URLs to prevent broken URLs.
• Use split to break apart comma-separated values, then loop through them with for_each.

---

list_operation

Performs operations on list (array) variables, including creating, adding to, removing from, and splitting strings into lists.

Description

The list_operation command manages list variables. Lists are ordered collections of items that you can loop through with for_each commands. This command lets you build lists dynamically during your automation.

Parameters

Parameter	Type	Required	Default	Description
variable	string	✅ Yes	—	The name of the list variable to operate on.
operation	string	✅ Yes	create	The operation to perform. Options: create, push, pop, split_string.
value	any	No	—	The value to push (for push) or the string to split (for split_string).
delimiter	string	No	,	The delimiter to use when splitting a string (for split_string).

Available Operations

Operation	Description	Requires value?	Requires delimiter?
create	Creates a new empty list	No	No
push	Adds a value to the end of the list	✅ Yes	No
pop	Removes the last item from the list	No	No
split_string	Splits a string into a list using a delimiter	✅ Yes	✅ Yes

Operation Details

create

Creates a new empty list variable.

{
  "command": "list_operation",
  "params": {
    "variable": "collected_urls",
    "operation": "create"
  }
}

push

Adds a value to the end of an existing list.

{
  "command": "list_operation",
  "params": {
    "variable": "collected_urls",
    "operation": "push",
    "value": "${current_page_url}"
  }
}

pop

Removes the last item from the list.

{
  "command": "list_operation",
  "params": {
    "variable": "collected_urls",
    "operation": "pop"
  }
}

split_string

Splits a string into a list using a delimiter. The result replaces the variable’s value.

{
  "command": "list_operation",
  "params": {
    "variable": "tag_list",
    "operation": "split_string",
    "value": "electronics,computers,laptops",
    "delimiter": ","
  }
}

Result: tag_list = ["electronics", "computers", "laptops"]

Behavior Notes

• create initializes an empty list. If the variable already exists, it is overwritten with an empty list.
• push appends to the end of the list. If the variable doesn’t exist, it is created as a new list with the pushed value.
• pop removes the last item. If the list is empty, nothing happens.
• split_string replaces the variable’s value with the resulting array. The original string value is lost.
• Lists created with list_operation can be used in for_each loops.
• The value parameter for push supports ${variable} substitution.

Tips

• Use create at the start of your automation to initialize lists you’ll build up during the run.
• Use push inside loops to collect data from multiple pages.
• Use split_string to convert comma-separated or semicolon-separated data into a loopable list.
• Combine list_operation with for_each to process each item in a list.
• Lists are stored in the automation state and survive checkpoint saves.

---

Combining Variables & Data Commands

Here’s a practical example showing how these commands work together in a real automation:

[
  {
    "command": "set_variable",
    "params": { "name": "base_price", "value": 29.99 }
  },
  {
    "command": "set_variable",
    "params": { "name": "tax_rate", "value": 0.08 }
  },
  {
    "command": "math_operation",
    "params": {
      "left_operand": "${base_price}",
      "operator": "*",
      "right_operand": "${tax_rate}",
      "output_variable": "tax_amount"
    }
  },
  {
    "command": "math_operation",
    "params": {
      "left_operand": "${base_price}",
      "operator": "+",
      "right_operand": "${tax_amount}",
      "output_variable": "total_price"
    }
  },
  {
    "command": "string_operation",
    "params": {
      "value": "Total: $${total_price}",
      "operation": "concat",
      "params": { "value": " (tax included)" },
      "output_variable": "price_label"
    }
  },
  {
    "command": "list_operation",
    "params": {
      "variable": "price_history",
      "operation": "create"
    }
  },
  {
    "command": "list_operation",
    "params": {
      "variable": "price_history",
      "operation": "push",
      "value": "${total_price}"
    }
  }
]

This example calculates a price with tax, formats a label, and stores the price in a history list.