Invoke Playbook

Invoke Playbook

Tipo: invoke-playbook  ·  Paquete: Core Activities v1.0.8

Ejecuta otro playbook del mismo proyecto, opcionalmente pasándole datos de entrada y recibiendo de vuelta sus resultados. Es la herramienta para dividir una automatización grande en piezas pequeñas y reutilizar lógica: en lugar de copiar y pegar el mismo grupo de actividades en varios sitios, lo pones en un sub-playbook y lo invocas.

Cómo funciona

1. Busca el playbook indicado en path dentro del proyecto (la ruta se resuelve contra la carpeta raíz del proyecto, donde está project.zoanproj).
2. Lo ejecuta de principio a fin, pasándole los valores de input, con su propio espacio de variables: no ve ni modifica las del playbook que lo llamó.
3. Al terminar, sus salidas se mapean a variables del playbook actual según outputs, y queda en el log Playbook '…' completado.
4. Si el sub-playbook falla, la invocación falla con el mismo error y su mismo tipo (capturable con Try / Catch): un error de negocio del hijo sigue siendo de negocio en el padre.

Límites que protegen la ejecución:

• Un playbook no puede invocarse a sí mismo, ni directa ni indirectamente (A → B → A): se detecta como recursión y falla.
• La cadena de invocaciones admite hasta 32 niveles de profundidad.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
path	string	—	El playbook hijo a ejecutar. Ruta relativa a la raíz del proyecto (ej. "playbooks/procesar-factura.json"); en el Designer lo eliges de la lista de playbooks del proyecto.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
input	Dictionary	—	Valores que recibe el sub-playbook, como pares nombre: valor. Los nombres son los argumentos de entrada (In o In/Out) del hijo; en el Designer el editor los lista al elegir el playbook.
outputs	Dictionary	—	Mapeo { salidaDelHijo: variableDelPadre }. Solo cruzan los argumentos de salida del hijo (Out o In/Out); los nombres que no son variables válidas o que el hijo no devuelve se ignoran.

Salida

Esta actividad no devuelve un valor propio: lo que el hijo produce llega a las variables del padre indicadas en outputs. Si una salida declarada del hijo quedó sin valor, llega como null y el hijo deja una advertencia en el log.

Ejemplo

Por cada factura, invocar un sub-playbook que la procesa y devuelve un estado:

For Each   items = facturas   itemVariable = factura
 └─ activities:
      Invoke Playbook
        path    = "procesar-factura.json"
        input   = { factura: factura, reintentos: 3 }
        outputs = { estado: estadoProcesamiento }
      Log   level = info   message = "Factura procesada: " + estadoProcesamiento

• input: el hijo recibe factura y reintentos como variables de entrada.
• outputs: la salida estado del hijo se guarda en la variable estadoProcesamiento del padre.

Cada playbook tiene sus propias variables

El sub-playbook no comparte variables con el que lo llama. La comunicación es solo por input (hacia el hijo) y outputs (de vuelta al padre). Esto mantiene cada pieza aislada y reutilizable. Ver Alcance de variables.

La variable del padre que recibe una salida (estadoProcesamiento en el ejemplo) debe estar declarada en el padre para poder recibir el valor. Si no lo está, la salida no se asigna y queda una advertencia en el log que lo indica. Cualquier nombre de variable válido sirve, incluidos los de una sola letra (x, n).

Solo rutas relativas dentro del proyecto

path debe ser una ruta relativa al proyecto; no se permiten rutas absolutas ni segmentos ... Esto evita que un playbook ejecute archivos fuera de su proyecto.

Cómo expone salidas el sub-playbook

En el sub-playbook, declara la salida en el panel de Argumentos con dirección Out (o In/Out) y dale valor con Set Variable. Ver Alcance de variables.

Errores comunes

Mensaje	Causa y solución
No se encontró el playbook '…' (se buscó en '…').	No existe ese archivo bajo la raíz del proyecto. Revisa la ruta (mayúsculas, extensión, carpeta) o elígelo de la lista del Designer.
Ruta no permitida: '…'. Las rutas deben ser relativas y no pueden contener '..'.	path es absoluta o sale del proyecto con ... Usa una ruta relativa a la raíz del proyecto.
Playbook '…': required input '…' was not provided by the parent.	El hijo tiene un argumento de entrada obligatorio sin valor por defecto y input no lo trae (o lo trae vacío). Agrégalo en input.
Recursion detected: '…' is already running in the current chain.	El playbook ya se está ejecutando más arriba en la cadena (A → B → A). Reorganiza la lógica para no invocarlo de nuevo.
Maximum invocation depth reached (32 levels). Check that there is no playbook cycle.	Demasiados playbooks invocándose en cadena. Aplana la estructura.
La salida '…' no se asignó a '…': …	Advertencia: la variable del padre no está declarada o su tipo no es compatible con la salida. Declárala con el tipo correcto.
El mensaje de error del hijo	El sub-playbook falló: la actividad falla con su mismo mensaje (o El playbook hijo falló. si no trae uno). Manéjalo con un Try / Catch alrededor de la invocación.

Actividades relacionadas

• Invoke Process — ejecutar un proceso publicado, incluso de otro proyecto.
• Variables — cómo se pasan entradas y se reciben salidas.
• Try / Catch — manejar el fallo de un sub-playbook.
• Vista general del Designer — proyectos con varios playbooks.