Add Queue Item

Add Queue Item

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

Adds a new item to a Zoan Cloud work queue. It’s the activity the producer (dispatcher) uses to fill the queue: for each unit of work (an invoice, a payment, an email) it enqueues an item with its data. Returns the created ZoanQueueItem.

How it works

1. Looks up the queueName queue in the execution’s environment (it must exist and be active).
2. If you set reference and the queue already has an item with that reference (not deleted), it returns that item instead of creating another one, and logs “Item already existed in the queue; the existing item was returned.”. That makes enqueuing idempotent.
3. Creates the item with status new (ready to process) or review (a person must approve it first), according to the queue’s policy or what you set in needsReview.
4. With deferUntil, the item isn’t handed to any performer before that date.

With a human decision

With taskTitle the item is born waiting for a decision (waiting_decision): a linked task is created in the Tasks inbox and the item isn’t handed to any bot until someone decides it, it expires or it’s cancelled. Then it returns to the queue with item.Decision for a performer to process. Like every task, it needs a recipient: assignUserEmail or assignRole. With taskForm the person fills in a form from the library: the activity checks it with Zoan Cloud before creating the item or the task, just like Create Human Task.

Required parameters

Parameter	Type	Default	Description
queueName	string	—	Queue name (up to 120 characters). It must exist in the environment where the process runs.
specificContent	Dictionary	—	The item payload: key → value (literals or expressions). Inside the consumer it’s read with item.SpecificContent["field"].

Optional parameters

Parameter	Type	Default	Description
reference	string	—	Reference unique per queue (up to 200 characters). If you enqueue the same reference again, Zoan Cloud returns the existing item instead of duplicating it (idempotency).
priority	string	"normal"	high, normal or low. Higher-priority items are handed out first.
deferUntil	string	—	ISO 8601 date and time in UTC (with Z), e.g. 2026-10-20T13:00:00Z or utcNow().AddHours(2).ToString("o"). The item won’t be handed out before that moment. Empty = can be processed right away.
needsReview	bool	—	Initial status of the item: true → review (a person approves it before a performer takes it), false → new. Empty = the queue’s acceptance policy. Doesn’t apply with taskTitle. Since 1.1.0.

Human decision

All of these parameters exist since 1.2.0, except the form ones (since 1.2.6).

Parameter	Type	Default	Description
taskTitle	string	—	What must be decided, in one line (up to 200 characters). Enables the linked task.
taskDescription	string	—	Context for the reviewer. Multi-line text editor.
taskOptions	string	"Aprobar, Rechazar"	Options separated by commas (or ; / |), between 2 and 6.
taskFields	Dictionary	—	Fields the reviewer must fill in, key → Label:type[*] (text, number, date, select:A|B; * = required). They come back in item.Decision.Fields.
taskForm	string	—	Name of a form published in the library, instead of taskFields (not both). The answers come back in item.Decision.Fields: tables as lists of rows and files as { id, name, … } for Download Human Task File. Since 1.2.6.
taskFormVersion	int	—	Pins a published version of the form (positive integer). Empty = the current one when the task is created. Since 1.2.6.
taskFormInputs	Dictionary	—	Values for the form’s inputs (input → value), or an expression that returns a dictionary. If a required one is missing, the activity fails without creating the item or the task. Since 1.2.6.
assignRole	string	—	Code of the role the task is addressed to. Required if you don’t set assignUserEmail.
assignUserEmail	string	—	Email of an active person in the tenant. Takes precedence over assignRole. Required if you don’t set assignRole.
dueInHours	int	—	Hours until it expires (business hours if the organization defined a schedule), between 1 and 8760. Empty = never. On expiry, the item returns with Decision.Status = "expired" or is abandoned, depending on the queue.
escalateToRole	string	—	If the deadline passes, reassign the task once to this role.
escalateToUserEmail	string	—	If the deadline passes, reassign the task once to this person. Takes precedence over escalateToRole.
catalog	string	—	Business catalog of the task (invoices, refunds…) to filter and see metrics in the inbox.
labels	string	—	Task labels separated by commas.
taskWebhookUrl	string	—	Public URL that receives a signed event when the task is decided, cancelled or expires.

Output

Returns the enqueued ZoanQueueItem, with its Id, Reference, SpecificContent, Priority and Status:

• new or review for a regular item (according to needsReview or the queue’s policy);
• waiting_decision if it carries a human task (its id in HumanTaskId);
• if the reference already existed, the existing item as it is (it may be in any status, even already processed).

Common errors

Message	Cause and fix
'queueName' is required.	queueName is missing.
'specificContent' must be an object.	specificContent isn’t a dictionary. Use the key → value editor or an expression that returns a Dictionary.
… HTTP 404: …Queue '…' not found (or the Spanish La cola ’…’ no existe en este ambiente.)	There’s no queue with that name in the environment (the name is case-sensitive). Create it in Zoan Cloud or fix queueName.
… HTTP 400: …Queue is inactive (or La cola ’…’ está inactiva.)	The queue is disabled. Enable it in Zoan Cloud.
… HTTP 422: …	A value doesn’t have the expected format: typically deferUntil with a time-zone offset (-05:00) or not in ISO format, or a priority other than high, normal, low.
… HTTP 400: … (the task needs a recipient)	You set taskTitle without assignUserEmail or assignRole.
… HTTP 400: … (ASSIGNEE_INVALID)	The email isn’t an active person, or the role doesn’t exist or has no active people.
… HTTP 409: … (QUEUE_REFERENCE_EXISTS)	With a human task: the reference is already on an item that has no linked task. Use another reference.
taskForm, taskFormVersion and taskFormInputs only apply with a task: set 'taskTitle'.	You set form options without taskTitle.
taskFormVersion and taskFormInputs only apply with a form: set 'taskForm'.	You set taskFormVersion or taskFormInputs without taskForm.
Use loose fields (taskFields) or a form (taskForm), not both.	You set taskFields and taskForm together.
taskFormVersion must be a positive integer (got: «…»).	taskFormVersion isn’t an integer greater than 0.
Form «…» needs the input «…» (taskFormInputs).	A required form input is missing.
There is already an item with reference «…» whose task was created without form «…»: use another reference.	The reference matches an item whose task doesn’t use that form.
The server does not support forms: update Zoan Cloud.	Your Zoan Cloud doesn’t support tasks with a form yet.
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 queue item: ”.

Example

Enqueue an invoice to validate, using its number as an idempotent reference:

Add Queue Item
  queueName = "invoices-to-validate"
  reference = invoice["number"]
  priority  = normal
  specificContent = {
    "invoiceId": invoice["number"],
    "amount":    = invoice["amount"],
    "customer":  = invoice["customer"]
  }
  → output: item
Log   level = info   message = "Enqueued " + item.Reference + " (status " + item.Status + ")"

With a human decision

Each high-amount invoice waits for a supervisor’s approval before it’s paid:

Add Queue Item
  queueName = "payments"   reference = invoice["number"]
  specificContent = { "invoiceId": invoice["number"], "amount": invoice["amount"] }
  taskTitle = "Approve payment of invoice " + invoice["number"]
  taskOptions = "Approve, Reject"
  assignRole = "supervisors"   dueInHours = 48
  → output: item

The performer reads item.Decision.Value when processing it (see Human decisions in batches).

Idempotency with reference

If your dispatcher can run twice over the same source (because of retries or overlapping schedules), always set a unique reference (the invoice number, the record id). That way you’ll never enqueue the same work twice.

Related activities

• Get Queue Item — take items to process them.
• Process Queue — process the whole queue.
• Create Human Task — the same task from the task side (with queueName).
• Work queues — create the queue and understand the statuses.