Queue

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

El paquete Queue permite que los bots trabajen con las colas de trabajo de Nexus: 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 Nexus y el ciclo de vida de un item. Aquí documentamos las actividades que la leen y escriben. La cola debe existir en el entorno donde se ejecuta, y su nombre debe coincidir con el queueName que pongas en las actividades.

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.

Actividades

Actividad	Tipo	Salida	Qué hace
Add Queue Item	queue-add-item	ZoanQueueItem	Encola un item nuevo con su payload
Add Transaction Item	queue-add-transaction-item	ZoanQueueItem	Crea un item y lo devuelve ya in_progress lockeado (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 y Get Queue Item devuelven un ZoanQueueItem. Sus campos más usados, accesibles desde expresiones:

Campo	Tipo	Para qué
item.Id	texto	Identificador único — lo necesitas para reportar el estado.
item.Reference	texto	La referencia que le dio el productor (si la hubo).
item.Status	texto	Estado actual (new, in_progress, successful…).
item.SpecificContent["campo"]	objeto	El payload: los datos que el bot debe procesar.
item.Priority	texto	high, normal o low.
item.Attempts	número	Cuántos intentos se han hecho sobre este item.
item.Output	objeto	El resultado guardado (si terminó con éxito).
item.Exception	objeto	El detalle del error (si falló).

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, Nexus 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 (Nexus) — crear y administrar colas, estados y reintentos.
• Try / Catch — para reportar fallos correctamente.
• Core — While, If, For Each, Break para el bucle del performer.