Process Queue

Process Queue

Tipo: queue-process  ·  Paquete: Queue Activities v1.2.9

Actividad contenedora (como For Each) que vacía una cola por ti: en cada vuelta toma el siguiente item con bloqueo atómico, ejecuta el cuerpo que definas con el item en el ámbito, y marca el resultado automáticamente (successful si el cuerpo termina, failed si lanza una excepción). Repite hasta que la cola queda vacía.

Es el patrón del consumidor (performer) en una sola actividad: encapsula el bucle While + Get Queue Item + Try/Catch + Set Transaction Status para que no tengas que cablearlo a mano cada vez.

¿Por qué no un For Each sobre la cola?

Una cola no es una lista: los items se agregan en paralelo, se procesan con bloqueo (varios bots a la vez) y tienen un ciclo transaccional con reintentos. Por eso se toman uno a uno, no de un tirón. Process Queue te da la comodidad de un For Each conservando esa semántica.

Cómo funciona

En cada iteración:

1. Toma el siguiente item de la cola (atómico, lo bloquea para esta ejecución). Si la cola está vacía, el bucle termina. Si alguien pidió Detener la ejecución, tampoco toma otro: el item anterior ya terminó y el resto queda en la cola (ver Should Stop).
2. Expone el item en la variable que indiques (itemVariable, tipo ZoanQueueItem).
3. Ejecuta el cuerpo (activities).
4. Reporta el estado automáticamente:
   • el cuerpo termina sin error → successful. Un Continue cuenta como fin normal del item; un Break marca el item como successful y termina el bucle;
   • el cuerpo lanza un error de negocio (Throw con la excepción de negocio, BusinessRuleException) → failed sin reintento: el item queda como excepción de negocio (desde la versión 1.2.3);
   • el cuerpo lanza cualquier otro error → failed, y la cola lo reintenta según su configuración de reintentos.
5. Vuelve al paso 1, hasta vaciar la cola, llegar a maxItems o, con onError = stop, al primer item fallido.

Al terminar deja en el log un resumen: “N elemento(s) procesado(s): X correctos, Y fallidos.”.

Estado manual cuando lo necesites

Si dentro del cuerpo marcas el estado a mano con Set Transaction Status (por ejemplo, para guardar un output), Process Queue lo respeta: el auto-marcado posterior se omite sin error (queda una línea de depuración en el log).

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
queueName	string	—	Nombre de la cola. Debe existir y estar activa en el ambiente de la ejecución.
itemVariable	string	—	Nombre de la variable que recibe el item actual (ZoanQueueItem). Es un identificador, no una expresión.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
maxItems	int	—	Máximo de items a procesar en esta ejecución. Vacío o 0 = hasta vaciar la cola.
onError	string	"continue"	Ante un item que falla: continue (lo marca failed y sigue con el siguiente) o stop (lo marca failed y detiene el bucle).

Sub-flujos

activities

Las actividades que se ejecutan por cada item (obligatorio). Dentro del cuerpo, el item actual está en la variable de itemVariable: item.SpecificContent["campo"], item.Reference, item.Decision.Value…

Salida

Esta actividad no devuelve ningún valor. El resultado de cada item queda en la cola (estado, Output, Exception).

Errores comunes

Un error dentro del cuerpo no hace fallar la actividad: marca el item como fallido y sigue (o se detiene, con onError = stop). La actividad falla cuando no puede tomar items:

Mensaje	Causa y solución
'queueName' es obligatorio. / 'itemVariable' es obligatorio. / 'activities' es obligatorio.	Falta un parámetro requerido o el cuerpo.
… HTTP 404: …Queue '…' not found or inactive in this environment	La cola no existe en el ambiente o está inactiva.
… HTTP 409: …La cola '…' la procesa un flujo: sus ítems no se entregan a robots.	La cola pertenece a un flujo.
Las actividades de colas necesitan el contexto de ejecución de Zoan Automation. Falta: …	El proceso no corre desde Zoan Cloud ni desde el Designer con sesión iniciada.

Ejemplo

El performer completo, en un solo bloque:

Process Queue
  queueName    = "facturas-por-validar"
  itemVariable = item
  onError      = continue
  └─ activities:
       (… procesa = item.SpecificContent["facturaId"] …)
       If   condition = toNumber(item.SpecificContent["monto"]) <= 0
         └─ then:
              Throw   message = "Monto inválido"   errorType = BusinessRuleException
       Log   level = info   message = "Factura " + item.Reference + " validada"

No necesitas While, ni comprobar null, ni Try/Catch, ni cerrar la transacción: si el cuerpo termina, el item queda successful; si algo dentro lanza un error, queda failed y el bucle continúa con el siguiente. La factura con monto inválido queda como excepción de negocio y no se reintenta.

Equivalente manual

Process Queue hace esto por ti:

While   condition = true
  └─ body:
       Get Queue Item   queueName = "facturas-por-validar"   → output: item
       If   condition = item == null
         └─ then:  Break
       Try
         └─ body:   (… procesa …)   ·   Set Transaction Status   item = item   status = successful
         └─ catch:  Set Transaction Status   item = item   status = failed

Usa la forma manual solo si necesitas control fino (lotes, reintentos personalizados, aplazar con Postpone Transaction).

Varios bots a la vez

Como cada item se bloquea al entregarse, puedes lanzar el mismo playbook con Process Queue en varios agentes sobre la misma cola: se reparten los items sin procesar ninguno dos veces.

Actividades relacionadas

• Get Queue Item — tomar items uno a uno (la primitiva que usa por dentro).
• Set Transaction Status — reportar éxito o fallo manualmente.
• Postpone Transaction — aplazar un item para más tarde.
• Add Queue Item — encolar trabajo (el lado productor).