Queue

Versión: 1.2.9  ·  ID: zoan-packages-queue  ·  Autor: Zoan Software

El paquete Queue permite que los bots trabajen con las colas de trabajo de Zoan Cloud: listas de tareas pendientes que se procesan una a una, con bloqueo atómico, reintentos y prioridades. Es el patrón de RPA para procesar lotes grandes de forma robusta y en paralelo.

Antes de empezar

Lee primero Colas de trabajo: explica qué es una cola, cómo crearla en Zoan Cloud y el ciclo de vida de un item. Aquí documentamos las actividades que la leen y escriben. La cola debe existir en el ambiente donde se ejecuta, y su nombre debe coincidir con el queueName que pongas en las actividades.

Requisitos

• El proceso debe ejecutarse desde Zoan Cloud o desde el Designer con la sesión de Zoan Cloud iniciada. Sin ese contexto, las actividades fallan con “Las actividades de colas necesitan el contexto de ejecución de Zoan Automation. Falta: …”.
• Las actividades usan la identidad de la ejecución: solo ven las colas del ambiente donde corre el robot y no necesitan credenciales.
• Una cola que procesa un flujo no entrega sus items a robots: se puede alimentar con Add Queue Item, pero no tomar con Get Queue Item ni Process Queue.

Las dos mitades: productor y consumidor

• El productor (dispatcher) llena la cola con Add Queue Item.
• El consumidor (performer) vacía la cola: toma items con Get Queue Item, los procesa y reporta el resultado con Set Transaction Status. O todo en una sola actividad con Process Queue.

Actividades

Actividad	Tipo	Salida	Qué hace
Add Queue Item	queue-add-item	ZoanQueueItem	Encola un item nuevo con su payload; opcionalmente con una tarea humana que debe decidirse antes de procesarlo
Add Transaction Item	queue-add-transaction-item	ZoanQueueItem	Crea un item y lo devuelve ya in_progress bloqueado (crear + procesar en el mismo run)
Get Queue Item	queue-get-item	ZoanQueueItem	Toma (y bloquea) el siguiente item; null si la cola está vacía
Process Queue	queue-process	—	Vacía la cola entera: toma cada item, corre tu lógica y reporta el resultado (el performer en una sola actividad)
Set Transaction Status	queue-set-transaction-status	—	Marca un item como successful o failed
Postpone Transaction	queue-postpone-transaction	—	Devuelve el item a la cola y lo aplaza (sin contar el intento)

El item: ZoanQueueItem

Las actividades Add Queue Item, Add Transaction Item y Get Queue Item devuelven un ZoanQueueItem, y Process Queue lo pone en la variable del item. Sus campos, accesibles desde expresiones:

Campo	Tipo	Para qué
item.Id	string	Identificador único (UUID): lo necesitas para reportar el estado.
item.QueueId	string	Id de la cola.
item.Reference	string	La referencia que le dio el productor (null si no hubo).
item.Status	string	Estado actual: new, in_progress, successful, failed, business_exception, abandoned, retried, review o waiting_decision (esperando la decisión de su tarea humana).
item.SpecificContent["campo"]	Dictionary	El payload: los datos que el bot debe procesar.
item.Priority	string	high, normal o low.
item.Attempts	int	Cuántos intentos se han hecho sobre este item (incluido el actual).
item.Output	Dictionary	El resultado guardado (si terminó con éxito); null si no hay.
item.Exception	Dictionary	El detalle del error (si falló); null si no hay.
item.Progress	string	Último mensaje de progreso reportado.
item.DeferUntil	string	Fecha (ISO 8601, UTC) antes de la cual no se entrega; null si no está aplazado.
item.ProcessingStartedAt / item.ProcessedAt / item.CreatedAt	string	Cuándo se empezó a procesar, cuándo terminó y cuándo se encoló (ISO 8601, UTC).
item.HumanTaskId	string	Id de la tarea humana enlazada, si la tiene.
item.HasDecision	bool	true si el item tenía una tarea humana enlazada y ya se decidió, venció o se canceló.
item.Decision.Value	string	La opción elegida ("Aprobar", "Rechazar"…); vacía si venció o se canceló. También Decision.Status (completed, expired, cancelled), Decision.Comment, Decision.Fields["campo"], Decision.DecidedBy, Decision.DecidedAt y Decision.TaskId.

Por ejemplo, si encolaste el payload con un campo facturaId, dentro del performer lo lees así: item.SpecificContent["facturaId"].

El patrón productor / consumidor

Lo normal son dos playbooks (que publicas como dos procesos).

1. Dispatcher — llena la cola

Recorre el origen de los datos y encola un item por cada unidad de trabajo. Suele lanzarse con un trigger programado.

Read Range   archivo = "facturas.xlsx"   → output: facturas

For Each   item en = facturas.Rows
  └─ body:
       Add Queue Item
         queueName = "facturas-por-validar"
         reference = item["numero"]
         specificContent = {
           "facturaId": item["numero"],
           "monto":     = item["monto"]
         }

La reference (opcional) hace el encolado idempotente: si vuelves a encolar la misma referencia, Zoan Cloud devuelve el item existente en vez de crear un duplicado. Útil si el dispatcher se ejecuta dos veces.

2. Performer — vacía la cola

En un bucle, toma items hasta que la cola se vacía, procesa cada uno y reporta el resultado dentro de un Try / Catch.

La forma corta: Process Queue

Process Queue encapsula todo este bucle (tomar + Try/Catch + reportar estado) en una sola actividad: defines solo el cuerpo del procesamiento. Úsalo por defecto; el bucle manual de abajo es para control fino.

While   condition = true
  └─ body:
       Get Queue Item   queueName = "facturas-por-validar"   → output: item

       If   condition = item == null
         └─ then:  Break          (la cola está vacía → salir del bucle)

       Try
         └─ body:
              (… procesa = item.SpecificContent["facturaId"] …)
              Set Transaction Status   item = item   status = successful
                output = { "validada": true }
         └─ catch (err):
              Set Transaction Status   item = item   status = failed
                exception = { "message": err.Message }

Varios bots a la vez

Como Get Queue Item bloquea cada item al entregarlo, puedes lanzar el mismo performer en varios agentes sobre la misma cola: se reparten los items sin procesar ninguno dos veces. Es la forma de acelerar lotes grandes.

Siguientes pasos

• Colas de trabajo (Zoan Cloud) — crear y administrar colas, estados y reintentos.
• Decisiones humanas en lotes — items que esperan la decisión de una persona.
• Try / Catch — para reportar fallos correctamente.
• Core — While, If, For Each, Break para el bucle del performer.