Using variables in Plans

Variables are used throughout plans to pass information from one node to another, or to store the result of a dynamic computation.

Variable types

Similar to any programming language, Step supports the use of variables in Plans. The variables declared and used in a Plan are called Plan variables. A Plan variable is a container that stores a data value under a specific name.

Like in classical programming languages, Step supports the following types of variables:

  • String: stores text (Default type of variables in Step)
  • Number: can be integer, long, float, or double
  • Boolean: stores values with two states: true or false
  • Complex Java objects: lets you define expressions for performing advanced data handling

When passing or setting a variable into the value field of a control or Keyword input, Groovy execution will be required for numbers, booleans, and complex Java objects. The Groovy toggle is a powerful feature in Step that lets you add dynamic behavior to a plan without modifying your Keywords.

Declaring variables in Plan

In Step, you have different ways to declare Plan variables:

  • Using Set control: the most common way to declare a Plan Variable is to use the dedicated Set control in your Plan
  • Using Parameters: Parameters declared in the web interface under Parameters are made available to the Plan as Variables
  • Using Execution Parameters: Execution Parameters selected at the start of execution (Environment, etc) are also made available to the Plan as Variable. See Executing a Plan

Variables in Set control

    Using the Visual Plan editor, you can use the Set control as follow to declare a variable:

    This would declare a variable called “myVar” as String and set its value to “This is a string value”.

    To declare a variable as an integer, toggle the dynamic field button as follow:

    Using the plain text editor, you can use the Set control as follows to declare a variable:

    Set city="Basel"
MyKeyword Parameter1="Welcome to ${city}"
Set City="Bern"
MyKeyword Parameter1="Welcome to ${city}"
    In this case the variable "city" will be declared as String.

    Similar to the Visual Plan Editor, you can also use Groovy expressions in the declaration of variables .

    Set birthyear=2006
Set age=2019-birthday

    In this case, the variable “birthyear” will be declared as integer. The variable “age” will also be declared a integer as the result of the operation “2019-birthday”

    Find out about all possibilities in our Javadocs

    See also Controls


    Variables in Parameters

    Parameters declared in the web interface through the Parameters page are automatically declared by Step as variables at the beginning of the execution and can thus be accessed in the Plan like any other Plan variable.

    Variables in Execution parameters

    The parameters selected for the execution of a Plan (like “Environment”) are called Execution parameters. These Execution Parameters are also declared by Step as Plan variables at the beginning of the execution and can be accessed in the Plan like any other Plan variable.

    Accessing variables

    Variables can be accessed practically everywhere in Plans and can also be passed to Keywords.

      Using the Visual Plan Editor, you can access previously defined variables in every field that has the dynamic field button as shown in the following screenshot. The variables are available as binding in Groovy expressions.

      In this example, we pass the content of the variable “myVar” to the first parameter of the Keyword “My Keyword”.

      Using the plain text syntax you can use the following syntax to access the content of previously declared variables:

      Set birthyear=2013
Set age=2019-birthyear
Set city="Lucerne"

MyKeyword Parameter1="I was born in ${city} in ${birthyear} and I am now ${age} years old"

      This would call the Keyword “MyKeyword” and set the value of variable “Parameter1” to “I was born in Lucerne in 2013 and I am now 6 years old”

      Find out about all possibilities in our Javadocs

      Embedding variables in text values

      Activating the dynamic field button turns the whole field into a Groovy expression. When you only want to inject a variable into a piece of text, you can instead leave the field as a plain value and embed the variable using the ${...} placeholder syntax. Both forms below produce the same result:

      Field mode What you type Result
      Dynamic (Groovy expression) "http://" + host + ":8080/api" http://myhost:8080/api
      Plain value http://${host}:8080/api http://myhost:8080/api

      In the UI, this works in every field that offers the dynamic field button, for instance in Keyword inputs, in Controls and in Parameters.

      In Automation Packages (YAML), this works in the plain values of all fields that also accept dynamic expressions, provided the package declares schema version 1.3.0 or later. See String interpolation for YAML examples.

      Syntax

      The text between the braces is a Groovy expression, evaluated against the same variables as the dynamic field mode. Its result is converted to text and inserted in place:

      Hello ${firstName} ${lastName}          ->  Hello Jane Doe
${user.email}                           ->  jane@example.com
Total: ${items.size()} item(s)          ->  Total: 3 item(s)
${items[0].name}                        ->  Keyboard

      The placeholder ends at the first closing brace, so an expression cannot itself contain a brace. Closures and map literals therefore belong in the dynamic field mode, which stays available for anything the placeholder syntax cannot express:

      ${items.collect{ it.id }.join(',')}     ->  error: use the dynamic field instead

      Everything outside the placeholders is used exactly as typed. Backslashes, quotes and line breaks need no escaping, which makes it safe to embed variables in file paths, regular expressions and JSON payloads:

      C:\logs\${date}.txt                     ->  C:\logs\2026-08-28.txt
\d+ occurrences of ${word}              ->  \d+ occurrences of error
{"user":"${name}","id":${id}}           ->  {"user":"Jane","id":42}

      Writing a literal ${

      Write $${ for a literal ${, the same convention as Apache Commons Text and docker compose. This is needed when the value is a template meant to be interpreted by another tool:

      $${name}                                ->  ${name}
name: $${JOB_NAME}                      ->  name: ${JOB_NAME}

      Nothing else is an escape. A value that does not contain ${ is never altered, so none of these need any care:

      Price: $5                               ->  Price: $5
pid $$                                  ->  pid $$
Hello $name                             ->  Hello $name      (not interpolated, use ${name})

      The one thing the syntax cannot express directly is a literal $ immediately in front of a placeholder — write it with the expression itself:

      Total: ${'$'}${price}                   ->  Total: $42

      Protected parameters

      Placeholders may reference protected parameters wherever the field is allowed to access them. The value is resolved for the execution but stays obfuscated in the reports:

      value:      Authorization: Bearer ${apiToken}
executed:   Authorization: Bearer <the real token>
reported:   Authorization: Bearer ***apiToken***