Process Queue

Process Queue

Type: queue-process  ·  Package: Queue Activities v1.0.0  ·  Output: —

A container activity (like For Each) that drains a queue for you: on each turn it takes the next item with an atomic lock, runs the body you define with the item in scope, and sets the result automatically (successful if the body finishes, failed if it throws). It repeats until the queue is empty.

It is the consumer (performer) pattern in a single activity: it encapsulates the While + Get Queue Item + Try/Catch + Set Transaction Status loop so you don’t have to wire it by hand every time.

Why not a For Each over the queue?

A queue is not a list: items are added in parallel, processed with a lock (several bots at once) and have a transactional lifecycle with retries. That’s why they are taken one at a time, not in one shot. Process Queue gives you the convenience of a For Each while keeping those semantics.

How it works

On each iteration:

1. Takes the next item from the queue (atomic, locks it for this execution). If the queue is empty, the loop ends.
2. Exposes the item in the variable you choose (itemVariable, typed ZoanQueueItem).
3. Runs the body (your sub-activities).
4. Reports the status automatically:
   • the body finishes without error → successful;
   • the body throws an exception → failed (honors the queue’s auto_retry).
5. Goes back to step 1.

Manual status when you need it

If inside the body you set the status by hand with Set Transaction Status (for example, to tell a business error from a system error), Process Queue respects it: it detects the item is no longer in_progress and skips the auto-marking.

Required parameters

Parameter	Editor	Description
queueName	expression	Queue name. It must exist in the execution environment.
itemVariable	identifier	Name of the variable that receives the current item (ZoanQueueItem).
activities	body	The activities that run for each item.

Optional parameters

Parameter	Editor	Description
maxItems	number	Maximum number of items to process. Empty = until the queue is empty.
onError	list	On a failing item: continue (mark it failed and go to the next one — default) or stop (mark it failed and stop the loop).

Example

The full performer, in a single block:

Process Queue
  queueName    = "facturas-por-validar"
  itemVariable = item
  onError      = continue
  └─ body:
       (… process = item.SpecificContent["facturaId"] …)
       Set Variable   validated = true

You don’t need While, a null check, Try/Catch, or to close the transaction: if the body finishes, the item is left successful; if something inside throws, it is left failed and the loop continues with the next one.

Manual equivalent

Process Queue does exactly this for you:

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

Use the manual form only if you need fine control (batches, custom retries, postponing with Postpone Transaction).

Several bots at once

Because each item is locked when delivered, you can run the same playbook with Process Queue on several agents over the same queue: they split the items without processing any of them twice.

Related activities

• Get Queue Item — take items one at a time (the primitive it uses internally).
• Set Transaction Status — report success or failure manually.
• Postpone Transaction — postpone an item until later.
• Add Queue Item — enqueue work (the producer side).