Understanding variables and their functions in ScenarioBuilder

Variables in ScenarioBuilder can store various data types: strings, numbers, dates and times. They can also get their values from external data sources, such as Excel or CSV files. Variables can change their values using the appropriate functions.

With variables, data input can be varied to emulate real world application usage. Below is detailed information on working with the variables and their functions.

For scenarios that show how to put variables to use, see the How do I use variables in scripts? article. To learn more about variable scope, please refer to the What is variable scope in ScenarioBuilder? article.

Variable Actions

Set String Variable

Add a string variable to your scenario.

Properties

  • Variable Name – provide a meaningful name to the variable.
  • Variable Value – simply type in your value/text entry or use the drop-down menu to select a pre-defined variable. The value of a variable is set when the set variable action is executed.
  • Variable Scope – specify the level at which you want to access your variable.
  • Encrypted – selecting this checkbox will encrypt the variable value for security purposes. This is useful if your variables contain passwords or other sensitive information.
  • Scenario Section – this is for Global scenarios only. Specify the section name that can be called from other scenarios.

Set Date Variable

Add a date variable to your scenario.

Properties

  • Variable Name – provide a meaningful name to the variable.
  • Variable Scope – specify a level at which you want to access your variable.
  • Date Format – select a date format. You can select a format from the drop-down, or you can enter your own format. Use the Syntax table below to assist in this effort.
date syntax
  • Variable Value – provide a value for the variable based on the date format or your own format using the syntaxes associated with it. If you leave this field blank the date will be set to the current date. The value of a variable is set when the set variable action is executed.
  • Scenario Section – this is for Global scenarios only. Specify the section name that can be called from other scenarios.

Set Time Variable

Add a time variable to your scenario.

Properties

  • Variable Name – provide a meaningful name to the variable.
  • Variable Scope – specify a level at which you want to access your variable.
  • Time Format – select a Time format. You can select a format from the drop-down, or you can enter your own format. Use the Syntax table below to assist in this effort.
time syntax
  • Variable Value – provide a value for the variable based on the Time format or your own format using the syntaxes associated with it. If you leave this field blank the time will be set to the current time. The value of a variable is set when the set variable action is executed.
  • Scenario Section – this is for Global scenarios only. Specify the section name that can be called from other scenarios.

Set Number Variable

Add a number variable to your scenario.

Properties

  • Variable Name – provide a meaningful name to the variable.
  • Variable Scope – specify a level at which you want to access your variable.
  • Variable Value – enter your variable value or use the drop-down menu to select a random number range [Low-High]. Replace the first number with the lowest number to use and the second number with the highest number to use (i.e. [1-10] Random Number). The value of a variable is set when the set variable action is executed.
  • Number of Decimals – Specify the number of decimal places that you want to use.
  • Decimals Separator – enter a character to separate the integer part from the fractional part of a number written in decimal form (comma, period, space, etc.). By default, ScenarioBuilder uses period (.) character.
  • Thousands Separator – enter a character to separate the integer part from the fractional part of a number written in decimal form. (comma, period, space, etc.)
  • Currency Symbol – enter a symbol if you want to display numbers as monetary values. The currency symbol appears right next to the first digit. ($)
  • Negative Symbol – enter a symbol you want to use for negative numbers. The number can be displayed with parentheses, braces, brackets around it.
  • Scenario Section – this is for Global scenarios only. Specify the section name that can be called from other scenarios.

Variable Functions

ScenarioBuilder offers various functions for variables to help you process information.

String Functions

ScenarioBuilder has strong text handling capabilities. Read below to understand the string functions that are available for manipulating text strings.

  • FirstCapital – returns text with the first letter of each word capitalized.
  • Split – splits text into a list of values by separating the text at specified delimiter. You can get the values out of the list by entering the following syntax: variable name[index]. The list values' indices start at 1 and increment by 1, so the first value's index is 1, the second value's index is 2, etc. For more on using this function, see the How do I use variables in scripts? article.
  • ToLowerCase – returns text converted to all lowercase (non-capital) letters.
  • ToUpperCase – return text converted to all uppercase (capital) letters.
  • Trim – removes whitespace or tab characters from the beginning and end of the source text value.

Properties

  • Variable Name – provide a meaningful name to the variable.
  • Function – select one of the above listed functions from the drop-down list.
  • Split Delimiter – when using the Split function, enter the characters that is used to separate the values (comma, period, space, pipe, etc.)
  • Reg Expression – use a regular expression to read the execution results. For example, for ping www.automai.com, expression #output# will place what the command returns in the variable output, and expression sent = #sent# will place what is between =space and comma in the SENT variable.

Date Functions

Read below to understand how to use and manipulate values representing dates.

  • AddDays – adds a number of days to a date.
  • AddMonths – adds a number of months to a date.
  • AddYears – adds a number of years to a date.
  • Format – returns a formatted value as defined by the Date format property.
  • LastDayOfTheMonth – returns the last day of a month, considering leap years too.
  • SubtractDays – subtracts a number of days from a date.
  • SubtractMonths – subtracts a number of months from a date.
  • SubtractYears – subtracts a number of years from a date.

Properties

  • Variable Name - Enter the name of the variable you wish to manipulate (the "Set Date Variable" action must precede this step, establishing the variable to be used).
  • Function – select one of the above listed functions from the drop-down list.
  • Add/Subtract Value – enter a value you want to add to or subtract from the variable value.
  • Date Format – select a Date format.
  • Scenario Section – this is for Global scenarios only. Specify the section name that can be called from other scenarios.

Time Functions

Read below to understand how to use and manipulate values representing times.

  • AddHours – adds a number of hours to a time.
  • AddMinutes – adds a number of minutes to a time.
  • AddSeconds – adds a number of seconds to a time.
  • Format – returns a formatted value as defined by Time format.
  • SubtractHours – subtracts a number of hours from a time.
  • SubtractMinutes – subtracts a number of minutes from a time.
  • SubtractSeconds – subtracts a number of seconds from a time.

Properties

  • Variable Name – enter the name of the variable you wish to manipulate (the "Set Time Variable" action must precede this step, establishing the variable to be used).
  • Function – select one of the above listed functions from the drop-down list.
  • Add/Subtract Value – enter a value you want to add to or subtract from the variable value.
  • Time Format – select a Time format from the drop-down or enter your own.
  • Scenario Section – this is for Global scenarios only. Specify the section name that can be called from other scenarios.

Increment A Variable

Use this action when you want to increase a variable value by a specified amount.

Properties

  • Variable Name – enter the name of the variable you wish to increment (the “Set A Variable” action must precede this step, establishing the variable to be incremented).
  • Increment Value – enter the value that you wish to increment the entered variable by.

Load An Image Into A Variable

If you have a changing image that needs to be used for an action, have ScenarioBuilder capture the image during execution and them pass that on as a variable value to the step that needs to use it.

Properties

  • Variable Name – this is the variable where the text is stored.
  • Use Anchor – if enabled, mouse location is relative to the parent Image or Window Action (property is only relevant if the “Mouse Move” Action is a child of either an Image or Window Action).
  • Image area – click the ellipses to use your mouse to select the area from which to capture text. Capture only the desired image. NOTE – the “Start” and “End” Text Area “X” and “Y” property fields will automatically populate after you make your selection. To remove the “Image Area” settings, click the X.
  • Start Image area X – image search area coordinates upper left corner X
  • End Image area X – image search area coordinates lower right corner X
  • Start Image area Y – image search area coordinates upper left corner Y
  • End Image area Y – image search area coordinates lower right corner Y
  • Scenario Section – this is for Global scenarios only. Specify the section name that can be called from other scenarios.

For more about the Load An Image Into A Variable action, please check out “Load Image As Variable” in our Video Tutorials series.