Variables

Una variable es un recipiente con nombre donde guardas un dato para usarlo más adelante. Son el mecanismo con el que la información viaja entre actividades: una actividad guarda su resultado en una variable, y otra actividad lo lee desde ahí.

Sin variables, cada actividad estaría aislada. Con variables, puedes leer un correo, extraer su asunto, transformarlo y escribirlo en un Excel — encadenando el dato de un paso al siguiente.

El panel de variables

Las variables se gestionan en el panel inferior del Designer. Cada variable tiene:

• Nombre — cómo la referencias en las expresiones.
• Tipo — qué clase de dato contiene (texto, número, tabla…). Ver Tipos de datos.
• Valor inicial (opcional) — con qué valor arranca antes de que cualquier actividad la modifique.

Declarar una variable

1. En el panel de variables, haz clic en + Nueva variable.
2. Escribe un nombre (ver reglas abajo).
3. Elige el tipo de dato.
4. Opcionalmente, asigna un valor inicial.

Reglas para los nombres

Regla	Bien	Mal
Sin espacios	numeroFactura	numero factura
Sin acentos ni símbolos	clienteId	clienteId#
Empieza con letra o _	total, _temp	1total
Distingue mayúsculas	total ≠ Total	—

Convención recomendada

Usa camelCase: primera palabra en minúscula y las siguientes con inicial mayúscula — numeroFactura, totalConIva, listaCorreos. Nombres descriptivos hacen el playbook legible: prefiere correosPendientes sobre x o lista2.

Capturar el resultado de una actividad

La mayoría de las actividades que producen un dato tienen un campo Salida (output) en el panel de propiedades. Ahí escribes el nombre de la variable donde quieres guardar el resultado. Si la variable no existe, se crea con el tipo correcto.

Ejemplo: una actividad HTTP GET con Output = respuesta guarda su resultado en respuesta. En las actividades siguientes puedes leer:

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

Nota

El tipo de la variable de salida lo determina la actividad. HTTP GET devuelve un ZoanHttpResponse, Excel Read Range devuelve un DataTable, Page Get Text devuelve un string. Conocer ese tipo te dice qué propiedades puedes leer después — consulta Tipos de datos o la página de la actividad.

Usar una variable

En cualquier campo de parámetro, escribe una expresión (empezando con =) que referencie la variable:

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

Recuerda: un campo que no empieza con = se trata como texto literal. Para leer una variable, siempre necesitas el =.

Variables de iteración (For Each)

Algunas actividades crean variables automáticamente. La más común es For Each: recorre una colección y, en cada vuelta, pone el elemento actual en una variable que tú nombras (el iterador).

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

Aquí correo existe solo dentro del bucle, y cambia en cada vuelta. No necesitas declararlo en el panel: lo crea el For Each.

Alcance (scope)

• Las variables que declaras pertenecen al playbook donde las creaste.
• Si invocas otro playbook con Invoke Playbook, no comparten variables automáticamente. En su lugar:
  • Le pasas datos como inputs (entradas).
  • Recibes datos como outputs (salidas).

Esto mantiene cada playbook aislado y reutilizable: un sub-playbook no puede “ensuciar” por accidente las variables del que lo llamó.

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

El panel de Argumentos

Los inputs y outputs de un playbook se declaran en el panel de Argumentos, en una sola lista con un selector de Dirección por argumento: In (entrada), Out (salida) o In/Out (entra y, además, su valor final vuelve al que lo llamó). Por defecto los inputs están aislados (modificarlos dentro del playbook no afecta al que lo llamó). Cada fila muestra un chip de tipo; las acciones (buscar referencias, renombrar, eliminar) están en el menú contextual (clic derecho sobre la fila).

Patrones comunes

Necesito…	Cómo
Un contador	Variable int con valor inicial 0; en cada vuelta, Set Variable = contador + 1
Acumular en una lista	Variable List; usa List Add o = listAdd(items, valor)
Una bandera (sí/no)	Variable boolean con valor inicial false; la pones en true cuando ocurre algo
Construir un texto	Variable string; concaténale con = texto + "linea\n" (o concatenando partes)

Variables del sistema

Además de tus variables, cada ejecución expone un conjunto de variables del sistema de solo lectura con información del proceso en curso. No las declaras —ya están disponibles— y las lees en cualquier expresión anteponiendo $:

Variable	Contiene
$system_execution_id	El identificador de esta ejecución (el mismo que ves en Nexus).
$system_process_name	El nombre del proceso que se está ejecutando.
$system_process_version	La versión del proceso/paquete publicado.
$system_process_id	El identificador del proceso.
$system_environment_id	El identificador del entorno donde se ejecuta.
$system_entry	El playbook de entrada (el que arranca la ejecución).

Por ejemplo, para registrar en un log qué proceso y ejecución generaron un dato:

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

Son de solo lectura

Si declaras una variable con uno de estos nombres e intentas reasignarla, el motor la vuelve a poner al valor del sistema al inicio de cada invocación. Trátalas como información, no como almacenamiento. Para las actividades (paquetes), los mismos datos están disponibles como variables de entorno ZOAN_NEXUS_PROCESS_NAME, ZOAN_NEXUS_PROCESS_VERSION, ZOAN_NEXUS_PROCESS_ID y ZOAN_NEXUS_EXECUTION_ID.

Errores comunes

Síntoma	Causa	Solución
Variable no declarada	Usaste una variable que no existe en el panel	Decláralo, o revisa que el nombre coincida exactamente
Una expresión devuelve nulo	Error de tipeo en el nombre (mayúsculas/minúsculas)	Total y total son distintas — verifica el nombre exacto
El valor “no se guarda” entre actividades	Esperabas que se guardara pero la actividad no tenía campo Output configurado	Asegúrate de poner un nombre en el campo Salida
Campo guarda el nombre literal en vez del valor	Olvidaste el = al inicio	Antepón = para leer la variable

Siguientes pasos

• Tipos de datos — qué puedes hacer con cada tipo de variable.
• Expresiones — leer y transformar variables.
• Depuración — inspeccionar los valores de tus variables al ejecutar.