Queue

Version: 1.0.0  ·  ID: zoan-packages-queue  ·  Author: Zoan Software

The Queue package allows bots to work with Zoan Cloud work queues: lists of pending tasks that are processed one by one, with atomic locking, retries and priorities. It is the RPA pattern for processing large batches robustly and in parallel.

Antes de empezar

Read first Work Queues: explains what a queue is, how to create it in Zoan Cloud and the life cycle of an item. Here we document the activities that read and write it. The queue must exist in the environment where the execution runs, and its name must match the queueName that you put in the activities.

The two halves: producer and consumer

• The producer (dispatcher) fills the queue with Add Queue Item.
• The consumer (performer) empties the queue: it takes items with Get Queue Item, processes them and reports the result with Set Transaction Status.

Activities

Activity	Type	Output	What it does
Add Queue Item	queue-add-item	ZoanQueueItem	Enqueue a new item with its payload
Add Transaction Item	queue-add-transaction-item	ZoanQueueItem	Create an item and return it already in_progress locked (create + process in the same run)
Get Queue Item	queue-get-item	ZoanQueueItem	Take (and block) the next item; null if queue is empty
Process Queue	queue-process	—	Drains the whole queue: takes each item, runs your logic and reports the result (the performer in a single activity)
Set Transaction Status	queue-set-transaction-status	—	Mark an item as successful or failed
Postpone Transaction	queue-postpone-transaction	—	Returns the item to the queue and defers it (without counting the attempt)

The item: ZoanQueueItem

The Add Queue Item and Get Queue Item activities return ZoanQueueItem. Your most used fields, accessible from expressions:

Field	Type	Purpose
item.Id	text	Unique identifier — you need it to report the status.
item.Reference	text	The reference given by the producer (if there was one).
item.Status	text	Estado actual (new, in_progress, successful…).
item.SpecificContent["campo"]	objeto	The payload: the data that the bot must process.
item.Priority	text	high, normal o low.
item.Attempts	number	How many attempts have been made on this item.
item.Output	objeto	The saved result (if it finished successfully).
item.Exception	objeto	The detail of the error (if it failed).

For example, if you queued the payload with a facturaId field, inside the performer you read it like this: = item.SpecificContent["facturaId"].

The producer/consumer pattern

The normal thing is two playbooks (which you publish as two processes).

1. Dispatcher — fills the queue

It goes through the data source and queues an item for each work unit. It is usually launched with a programmed trigger.

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"]
         }

The reference (optional) makes the enqueue idempotent: if you enqueue the same reference again, Zoan Cloud returns the existing item instead of creating a duplicate. Useful if the dispatcher runs twice.

2. Performer — clears the queue

In a loop, it takes items until the queue is empty, processes each one and reports the result within a Try / Catch.

The short form: Process Queue

Process Queue encapsulates this whole loop (take + Try/Catch + report status) in a single activity: you only define the processing body. Use it by default; the manual loop below is for fine control.

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 }

Multiple bots at once

Since Get Queue Item locks each item upon delivery, you can launch the same performer on several agents on the same queue: the items are distributed without processing any of them twice. It’s the way to speed up large batches.

Next steps

• Work Queues (Zoan Cloud) — create and manage queues, states, and retries.
• Try / Catch — to report bugs correctly.
• Core — While, If, For Each, Break for the performer loop.