Get Queue Item

Get Queue Item

Type: queue-get-item  ·  Package: Queue Activities v1.2.9  ·  Output: ZoanQueueItem

Takes the next item from a work queue and locks it for this execution. It’s the activity the consumer (performer) uses on each pass of its loop. If the queue is empty, it returns null.

How it works

The operation is atomic: Zoan Cloud hands out the item, moves it to in_progress, adds an attempt (Attempts) and reserves it for your execution, so no other bot can take it. That’s why several performers can read the same queue in parallel without processing an item twice.

• It only hands out items in new status: those in review (review) or waiting for a human decision (waiting_decision) don’t come out until they’re approved or decided.
• The order respects priority (high before normal before low) and, within the same priority, the oldest first. Deferred items (deferUntil) aren’t handed out before their time.
• The lock lasts 15 minutes. If the execution doesn’t close the item in that time (for example, because the robot crashed), Zoan Cloud returns it to new for another attempt, or marks it abandoned if it already used up the queue’s retries.
• If the machine is suspended in Zoan Cloud, it returns null as if the queue were empty, so the loop ends on its own.

Always close the transaction

When you finish processing the item, you must mark its result with Set Transaction Status (or defer it with Postpone Transaction). If you don’t, the item stays in_progress until its lock expires.

Required parameters

Parameter	Type	Default	Description
queueName	string	—	Queue name. It must exist and be active in the execution’s environment.

Optional parameters

None.

Output

Returns a ZoanQueueItem in in_progress status, or null if the queue has no items ready to hand out. Always check for null to leave the loop.

Common errors

Message	Cause and fix
'queueName' is required.	queueName 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.

Zoan Cloud errors arrive with the prefix “Could not get a queue item: ”. An empty queue is not an error.

Example

The typical performer loop: take items until the queue is empty.

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

       If   condition = item == null
         └─ then:  Break          (empty queue → finish)

       (… process = item.SpecificContent["invoiceId"] …)

       Set Transaction Status   item = item   status = successful

Related activities

• Process Queue — the same loop in a single activity.
• Set Transaction Status — report the item’s success or failure.
• Postpone Transaction — defer the item for later.
• Add Queue Item — enqueue work.