Variables

A variable is a named container where you store data for later use. They are the mechanism with which information travels between activities: one activity saves 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 into Excel — chaining the data from one step to the next.

The Variables Panel

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

• Name — how it is referenced in expressions.
• Type — what kind of data it contains (text, number, table…). See Data Types.
• Initial value (optional) — what value it starts with before any activity modifies it.

Declare a variable

1. In the variables panel, click + New variable.
2. Enter a name (see rules below).
3. Choose the type of data.
4. Optionally, assign an initial value.

Rules for names

Regla	Bien	Mal
No spaces	numeroFactura	numero factura
No accents or symbols	clienteId	clienteId#
Starts with letter o _	total, _temp	1total
Capital sensitive	total ≠ Total	—

Recommended convention

Use camelCase: lowercase first word and uppercase initial words — numeroFactura, totalConIva, listCorreos. Descriptive names make the playbook readable: prefer correosPendientes over x or list2.

Capture the result of an activity

Most activities that produce data have an Output field in the properties panel. There you write the name of the variable where you want to save the result. If the variable does not exist, it is created with the correct type.

Example: an HTTP GET activity with Output = respuesta saves its result in respuesta. In the following activities you can read:

= respuesta.StatusCode      // 200
= respuesta.Ok              // true
= respuesta.Body            // cuerpo de la respuesta

Note

The type of the output variable is determined by the activity. HTTP GET returns a ZoanHttpResponse, Excel Read Range returns a DataTable, Page Get Text returns a string. Knowing that type tells you what properties you can read next — see Data Types or the activity page.

Use a variable

In any parameter field, type an expression (starting with =) that references the variable:

= correo.Subject
= "Hola " + nombreCliente
= total > 1000

Remember: a field that does not begin with = is treated as literal text. To read a variable, you always need the =.

Iteration variables (For Each)

Some activities create variables automatically. The most common is For Each: it loops through a collection and, on each return, puts the current element into a variable you name (the iterator).

For Each   collection = correos   iterator = correo
   └─ body:
        Log   message = = "Procesando: " + correo.Subject

Here correo exists only within the loop, and changes on each loop. You don’t need to declare it in the panel: For Each creates it.

Alcance (scope)

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

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

main:
   Invoke Playbook   playbook = procesar-factura
                     inputs   = { factura: = facturaActual }
                     output   = resultado

The Arguments panel

A playbook’s inputs and outputs are declared in the Arguments panel, in a single list with a Direction selector per argument: In, Out, or In/Out (it comes in and its final value also flows back to the caller). By default inputs are isolated (changing them inside the playbook does not affect the caller). Each row shows a type chip; the actions (find references, rename, delete) live in the context menu (right-click on the row).

Patrones comunes

Necesito…	How
an accountant	Variable int with initial value 0; on each turn, Set Variable = contador + 1
Accumulate in a list	Variable List; use List Add or = listAdd(items, valor)
A flag (yes/no)	Variable boolean with initial value false; you put it in true when something happens
Build a text	Variable string; concatenate it with = texto + "linea\n" (or concatenate parts)

Variables del sistema

In addition to your variables, each run exposes a set of read-only system variables with information about the current process. You do not declare them —they are already available— and you read them in any expression prefixing $:

Variable	Contiene
$system_execution_id	The ID of this run (the same one you see in Zoan Cloud).
$system_process_name	The name of the process that is running.
$system_process_version	The version of the published process/package.
$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 execution).

For example, to record in a log which process and execution generated a data:

Log   message = = "Procesado por " + $system_process_name + " v" + $system_process_version + " (exec " + $system_execution_id + ")"

They are read-only

If you declare a variable with one of these names and try to reassign it, the engine resets it to the system value at the start of each invocation. Treat them as information, not storage. For activities (packages), the same data is available as environment variables ZOAN_NEXUS_PROCESS_NAME, ZOAN_NEXUS_PROCESS_VERSION, ZOAN_NEXUS_PROCESS_ID, and ZOAN_NEXUS_EXECUTION_ID.

Common errors

Symptom	Causa	Solution
Variable no declarada	You used a variable that does not exist in the panel	Declare it, or check that the name matches exactly
An expression returns null	Typing error in name (upper/lowercase)	Total and total are different — check the exact name
The value “is not saved” between activities	You expected it to be saved but the activity did not have an Output field configured	Make sure you put a name in the Output field
Field saves the literal name instead of the value	You forgot = at the beginning	Prepend = to read the variable

Next steps

• Data types — what you can do with each variable type.
• Expressions — read and transform variables.
• Debug — inspect the values ​​of your variables when running.