Queue

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

The Queue package lets bots work with Zoan Cloud work queues: lists of pending work processed one by one, with atomic locking, retries and priorities. It’s the RPA pattern for processing large batches robustly and in parallel.

Before you start

Read Work queues first: it explains what a queue is, how to create one 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 process runs, and its name must match the queueName you set in the activities.

Requirements

• The process must run from Zoan Cloud or from the Designer signed in to Zoan Cloud. Without that context, the activities fail with “Queue activities require a Zoan Automation runtime context. Missing: …”.
• The activities use the execution identity: they only see the queues of the environment where the robot runs, and they need no credentials.
• A queue processed by a flow doesn’t hand its items to robots: you can feed it with Add Queue Item, but not take from it with Get Queue Item or Process Queue.

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. Or all of it in a single activity with Process Queue.

Activities

Activity	Type	Output	What it does
Add Queue Item	queue-add-item	ZoanQueueItem	Enqueues a new item with its payload; optionally with a human task that must be decided before processing it
Add Transaction Item	queue-add-transaction-item	ZoanQueueItem	Creates an item and returns it already in_progress and locked (create + process in the same run)
Get Queue Item	queue-get-item	ZoanQueueItem	Takes (and locks) the next item; null if the queue is empty
Process Queue	queue-process	—	Empties 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	—	Marks 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

Add Queue Item, Add Transaction Item and Get Queue Item return a ZoanQueueItem, and Process Queue puts it in the item variable. Its fields, accessible from expressions:

Field	Type	What for
item.Id	string	Unique identifier (UUID): you need it to report the status.
item.QueueId	string	Queue id.
item.Reference	string	The reference the producer gave it (null if none).
item.Status	string	Current status: new, in_progress, successful, failed, business_exception, abandoned, retried, review or waiting_decision (waiting for its human task’s decision).
item.SpecificContent["field"]	Dictionary	The payload: the data the bot must process.
item.Priority	string	high, normal or low.
item.Attempts	int	How many attempts have been made on this item (including the current one).
item.Output	Dictionary	The stored result (if it finished successfully); null if none.
item.Exception	Dictionary	The error detail (if it failed); null if none.
item.Progress	string	Last progress message reported.
item.DeferUntil	string	Date (ISO 8601, UTC) before which it isn’t handed out; null if not deferred.
item.ProcessingStartedAt / item.ProcessedAt / item.CreatedAt	string	When processing started, when it finished and when it was enqueued (ISO 8601, UTC).
item.HumanTaskId	string	Id of the linked human task, if any.
item.HasDecision	bool	true if the item had a linked human task that has been decided, expired or cancelled.
item.Decision.Value	string	The chosen option ("Aprobar", "Rechazar"…); empty if it expired or was cancelled. Also Decision.Status (completed, expired, cancelled), Decision.Comment, Decision.Fields["field"], Decision.DecidedBy, Decision.DecidedAt and Decision.TaskId.

For example, if you enqueued the payload with an invoiceId field, inside the performer you read it like this: item.SpecificContent["invoiceId"].

The producer / consumer pattern

Normally there are two playbooks (published as two processes).

1. Dispatcher — fills the queue

It goes through the data source and enqueues one item per unit of work. It’s usually launched with a scheduled trigger.

Read Range   file = "invoices.xlsx"   → output: invoices

For Each   item in = invoices.Rows
  └─ body:
       Add Queue Item
         queueName = "invoices-to-validate"
         reference = item["number"]
         specificContent = {
           "invoiceId": item["number"],
           "amount":    = item["amount"]
         }

The reference (optional) makes enqueuing 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 — empties the queue

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

The short way: Process Queue

Process Queue wraps 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-grained control.

While   condition = true
  └─ body:
       Get Queue Item   queueName = "invoices-to-validate"   → output: item

       If   condition = item == null
         └─ then:  Break          (the queue is empty → leave the loop)

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

Several bots at once

Since Get Queue Item locks each item when handing it out, you can launch the same performer on several agents over the same queue: they share the items without processing any of them twice. That’s how you speed up large batches.

Next steps

• Work queues (Zoan Cloud) — create and manage queues, statuses and retries.
• Human decisions in batches — items that wait for a person’s decision.
• Try / Catch — to report failures properly.
• Core — While, If, For Each, Break for the performer loop.