Add Transaction Item

Add Transaction Item

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

Adds an item to a work queue and returns it already in_progress, locked for the current execution — add + start in a single step. It’s for flows where the same bot creates the work and processes it in the same execution, keeping the queue’s traceability and retries.

How it works

Unlike Add Queue Item —which leaves the item in new for another performer to take later—, this activity creates the item directly in in_progress and reserves it for you: it doesn’t go through new or review. You get it ready to process, with Attempts = 1.

With reference, if the queue already has a live item with that reference:

• if it’s yours (this same execution holds the lock), it returns it as is;
• if it’s new, or in_progress with an expired lock, it takes it for this execution and adds an attempt;
• in any other status (already processed, or in progress in another execution), the activity fails.

Like any transaction, you must close it: when you’re done, mark the result with Set Transaction Status (successful or failed). If you don’t, the item stays in_progress until its lock expires (15 minutes) and Zoan Cloud returns it to the queue or abandons it according to its retries.

When to use this one and not Add Queue Item?

• Add Transaction Item (this one): the bot creates and processes the item in the same run. Useful to record a unit of work “on the fly” without separating dispatcher and performer.
• Add Queue Item: the producer enqueues work that another bot (or the same one, later) will take with Get Queue Item or Process Queue.

Required parameters

Parameter	Type	Default	Description
queueName	string	—	Queue name. It must exist and be active in the execution’s environment.
specificContent	Dictionary	—	The payload: data mapped as key → value (literals or expressions). You read it with item.SpecificContent["my_field"].

Optional parameters

Parameter	Type	Default	Description
reference	string	—	Reference for traceability (up to 200 characters). If an item with it already exists, the rules above apply.
priority	string	"normal"	high, normal or low.

Output

Returns a ZoanQueueItem in in_progress status and locked for this execution, ready to process and close.

Common errors

Message	Cause and fix
'queueName' is required. / 'specificContent' must be an object.	The queue is missing or the payload isn’t a dictionary.
… HTTP 404: …Queue '…' not found or inactive in this environment	The queue doesn’t exist in the environment or is inactive.
… HTTP 409: … (QUEUE_REFERENCE_EXISTS)	The reference is on an item that’s already processed or being processed by another execution. Use another reference.
… HTTP 409: … (QUEUE_OWNED_BY_ORCHESTRATION)	The queue belongs to a flow: its items aren’t processed by robots. Feed it with Add Queue Item.
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 add the transaction item: ”.

Example

Create a transaction, process it and close it in the same flow:

Add Transaction Item
  queueName       = "reprocessing"
  specificContent = {
    "invoiceId": invoice.number,
    "reason":    "manual revalidation"
  }
  → output: item

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

Related activities

• Set Transaction Status — close the transaction (required).
• Add Queue Item — enqueue work for another performer to take.
• Get Queue Item — take the next item in the queue.
• Process Queue — process the whole queue in a loop.