Process Queue

Process Queue

Type: queue-process  ·  Package: Queue Activities v1.2.9

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

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

Why not a For Each over the queue?

A queue isn’t a list: items are added in parallel, processed with locking (several bots at once) and have a transactional cycle with retries. That’s why they’re taken one by one, not all at once. 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 (atomically, locking it for this execution). If the queue is empty, the loop ends. If someone asked to Stop the execution, it doesn’t take another one either: the previous item has finished and the rest stays in the queue (see Should Stop).
2. Exposes the item in the variable you set (itemVariable, type ZoanQueueItem).
3. Runs the body (activities).
4. Reports the status automatically:
   • the body finishes without errors → successful. A Continue counts as a normal end of the item; a Break marks the item successful and ends the loop;
   • the body throws a business error (Throw with the business exception, BusinessRuleException) → failed without retry: the item is recorded as a business exception (since 1.2.3);
   • the body throws any other error → failed, and the queue retries it according to its retry settings.
5. Goes back to step 1, until the queue is empty, maxItems is reached or, with onError = stop, the first failed item.

When it finishes it logs a summary: “N item(s) processed: X succeeded, Y failed.”.

Manual status when you need it

If inside the body you set the status by hand with Set Transaction Status (for example, to store an output), Process Queue respects it: the later automatic marking is skipped without error (a debug line is logged).

Required parameters

Parameter	Type	Default	Description
queueName	string	—	Queue name. It must exist and be active in the execution’s environment.
itemVariable	string	—	Name of the variable that receives the current item (ZoanQueueItem). It’s an identifier, not an expression.

Optional parameters

Parameter	Type	Default	Description
maxItems	int	—	Maximum number of items to process in this execution. Empty or 0 = until the queue is empty.
onError	string	"continue"	On a failing item: continue (marks it failed and goes on with the next one) or stop (marks it failed and stops the loop).

Sub-flows

activities

The activities that run for each item (required). Inside the body, the current item is in the itemVariable variable: item.SpecificContent["field"], item.Reference, item.Decision.Value…

Output

This activity does not return a value. Each item’s result stays in the queue (status, Output, Exception).

Common errors

An error inside the body doesn’t make the activity fail: it marks the item as failed and goes on (or stops, with onError = stop). The activity fails when it can’t take items:

Message	Cause and fix
'queueName' is required. / 'itemVariable' is required. / 'activities' is required.	A required parameter or the body is missing.
… HTTP 404: …Queue '…' not found or inactive in this environment	The queue doesn’t exist in the environment or is inactive.
… HTTP 409: … (QUEUE_OWNED_BY_ORCHESTRATION)	The queue belongs to a flow.
Queue activities require a Zoan Automation runtime context. Missing: …	The process isn’t running from Zoan Cloud or from the Designer signed in.

Example

The complete performer, in a single block:

Process Queue
  queueName    = "invoices-to-validate"
  itemVariable = item
  onError      = continue
  └─ activities:
       (… process = item.SpecificContent["invoiceId"] …)
       If   condition = toNumber(item.SpecificContent["amount"]) <= 0
         └─ then:
              Throw   message = "Invalid amount"   errorType = BusinessRuleException
       Log   level = info   message = "Invoice " + item.Reference + " validated"

You don’t need While, a null check, Try/Catch or closing the transaction: if the body finishes, the item ends successful; if something inside throws an error, it ends failed and the loop continues with the next one. The invoice with an invalid amount is recorded as a business exception and isn’t retried.

Manual equivalent

Process Queue does this for you:

While   condition = true
  └─ body:
       Get Queue Item   queueName = "invoices-to-validate"   → 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-grained control (batches, custom retries, deferring with Postpone Transaction).

Several bots at once

Since each item is locked when handed out, you can launch the same playbook with Process Queue on several agents over the same queue: they share the items without processing any of them twice.

Related activities

• Get Queue Item — take items one by one (the primitive it uses inside).
• Set Transaction Status — report success or failure manually.
• Postpone Transaction — defer an item for later.
• Add Queue Item — enqueue work (the producer side).