Variables

A variable is a named container where you store a piece of data to use later. Variables are how information travels between activities: one activity stores its result in a variable, and another activity reads it from there.

Without variables, each activity would be isolated. With variables, you can read an email, extract its subject, transform it and write it to an Excel file, passing the data from one step to the next.

The variables panel

Variables are managed in the Variables tab of the bottom panel. Each variable has:

• Name: how you refer to it in expressions.
• Type: what kind of data it holds (text, number, table…). See Data types.
• Initial value (optional): an expression with the value it starts with, for example 0, "pending" or newList().
• Description (optional): what it is for, for whoever reads the playbook later.

Everything is edited right in the table, cell by cell.

Declare a variable

1. In the Variables tab, click + Add variable. A new row appears (variable1, of type string) with the cursor in the name.
2. Type the name (see the rules below) and press Enter.
3. Pick the type in the selector. It has a search box, and Composite type… builds types such as List<string> or Dictionary<string,object>.
4. Optionally, type an initial value and a description.

To delete a variable, use the trash icon at the end of its row or Delete. Right-click the row → Find references shows where it is used in the playbook.

Declare it without leaving the field

If you are typing an expression and use a variable that doesn’t exist yet, press Ctrl+Shift+V: it is declared in the playbook with the type that field expects.

Naming rules

Rule	Good	Bad
No spaces	invoiceNumber	invoice number
No symbols	customerId	customerId#
Starts with a letter or _	total, _temp	1total
Not a C# reserved word	kind	class
Unique in the playbook (across variables and arguments)	total	two total
Case-sensitive	total ≠ Total	—

If the name is not valid, the Designer tells you and keeps the previous one.

Recommended convention

Use camelCase: first word in lowercase and the following ones with an initial capital: invoiceNumber, totalWithTax, emailList. Descriptive names make the playbook readable: pendingEmails is clearer than x or list2.

Capture an activity’s result

Activities that produce data have, at the end of the Properties panel, the Output section with the Save result in field. There you type the name of the variable where you want to store the result; on the right you see the type the activity returns. The field suggests the variables that already exist.

If the name you type is not declared yet, the field marks it as a new variable: press Ctrl+Shift+V to declare it with the output type.

Example: an HTTP GET activity that stores its result in response. In the following activities you can read:

response.StatusCode      // 200
response.Ok              // true
response.Body            // response body

Note

The type of the output is set by the activity. HTTP GET returns a ZoanHttpResponse, Open Browser returns a ZoanPageSession, Get Text returns a string. Knowing that type tells you which properties you can read afterwards: see Data types or the activity’s page.

After a run, the Preview (last run) section in Properties shows the value the activity produced, without leaving the Designer.

Use a variable

In any field with ƒx, type an expression that uses the variable:

email.Subject
"Hello " + customerName
total > 1000

Remember: fixed text goes in quotes ("Hello"); without quotes, the Designer reads it as a variable name.

Iteration variables (For Each)

Some activities declare variables for you. The most common one is For Each: it goes through a collection (items) and, on each pass, puts the current element in the variable you name in itemVariable. Optionally, indexVariable holds the position (starting at 0).

For Each   items = emails   itemVariable = email
   └─ Body:
        Log   message = "Processing: " + email.Subject

Here email exists only inside the loop and changes on each pass. You don’t need to declare it in the panel: the For Each declares it.

Scope

• The variables you declare belong to the playbook where you created them.
• If you invoke another playbook with Invoke Playbook, they do not share variables. Instead:
  • You pass data to its inputs.
  • You receive data from its outputs.

This keeps each playbook isolated and reusable: an invoked playbook can’t accidentally “dirty” the caller’s variables.

When you pick the playbook in Invoke Playbook, the Properties panel shows one field per input it declares (with its default value, if any) and one field per output, where you type the variable that will receive the value.

The Arguments tab

A playbook’s inputs and outputs are declared in the Arguments tab of the bottom panel, with + Add input and + Add output. The Direction column shows in (input) or out (output). Inputs can have an initial value, used when the caller doesn’t give them one. Each row’s actions (find references, delete) are in the context menu (right-click).

Common patterns

I need…	How
A counter	An int variable with initial value 0; on each pass, Set Variable with counter + 1
Accumulate in a list	A List<string> variable with initial value new List<string>(); on each pass, the Add to List activity
A flag (yes/no)	A boolean variable with initial value false; set it to true when something happens
Build a text	A string variable; append text + "line" + nl()

System variables

Besides your own variables, every run exposes a set of read-only system variables with information about the current process. You don’t declare them (they are already available) and you read them in any expression with a $ prefix. Autocomplete lists them.

Variable	Contains
$system_playbook_name	The name of the playbook currently running (it changes inside an invoked playbook).
$system_invoke_depth	The invocation depth: 0 in the main playbook, 1 in the first invoked one…
$system_playbook_started_at	When this playbook started.
$system_run_started_at	When the whole run started (the same across the invocation chain).
$system_host_name	The name of the computer where it runs.
$system_os_user	The Windows user running the robot.
$system_execution_id	The identifier of this run (the same one you see in Zoan Cloud).
$system_process_name	The name of the process being run.
$system_process_version	The version of the published process.
$system_process_id	The process identifier.
$system_environment_id	The identifier of the environment where it runs.
$system_entry	The entry playbook (the one that starts the run).
$system_instance_id	The flow case that launched this run.
$system_step_id	The flow step that launched this run.
$system_idempotency_key	The step’s idempotency key: the same across its automatic retries. Use it so an external system doesn’t repeat work; see Robots inside a flow.
$system_business_key	The business key of the flow case (for example, the invoice number).

The last four only have a value when a flow step launches the run; otherwise they are empty.

For example, to log which process and run produced some data, or how long the run has taken:

Log   message = "Processed by " + $system_process_name + " v" + $system_process_version + " (exec " + $system_execution_id + ")"
Log   message = "Seconds elapsed: " + (now() - $system_run_started_at).TotalSeconds

They are read-only

If you try to assign a system variable (for example, as the target of Set Variable), the Problems panel marks it as an error. Treat them as information, not as storage.

Common mistakes

Symptom	Cause	Solution
”The name ‘x’ does not exist in the current context”	You used a variable that is not declared, or the name doesn’t match	Declare it (Ctrl+Shift+V from the field) or fix the name: Total and total are different
”Invalid variable to write”	The output points to an undeclared variable or a system variable	Declare the variable or pick another name
The value “isn’t saved” between activities	The activity had no Save result in set	Type the variable name in the Output section
The name is saved instead of the value	You put the variable name in quotes	Remove the quotes: customer, not "customer"

Next steps

• Data types: what you can do with each type of variable.
• Expressions: read and transform variables.
• Debugging: inspect your variables’ values while running.