Add Queue Item

Add Queue Item

Tipo: queue-add-item  ·  Paquete: Queue Activities v1.2.9  ·  Salida: ZoanQueueItem

Agrega un item nuevo a una cola de trabajo de Zoan Cloud. Es la actividad que usa el productor (dispatcher) para llenar la cola: por cada unidad de trabajo (una factura, un pago, un correo) encola un item con sus datos. Devuelve el ZoanQueueItem creado.

Cómo funciona

1. Busca la cola queueName en el ambiente de la ejecución (debe existir y estar activa).
2. Si indicas reference y la cola ya tiene un item con esa referencia (que no esté eliminado), devuelve ese item en vez de crear otro, y deja en el log “El elemento ya existía en la cola; se devolvió el existente.”. Así el encolado es idempotente.
3. Crea el item con estado new (listo para procesar) o review (una persona debe aprobarlo antes), según la política de la cola o lo que digas en needsReview.
4. Con deferUntil, el item no se entrega a ningún performer antes de esa fecha.

Con decisión humana

Con taskTitle el item nace esperando decisión (waiting_decision): se crea una tarea enlazada en la bandeja de Tareas y el item no se entrega a ningún bot hasta que alguien la decida, venza o se cancele. Después vuelve a la cola con item.Decision para que un performer lo procese. La tarea, como toda tarea, necesita destino: assignUserEmail o assignRole. Con taskForm la persona llena un formulario de la biblioteca: la actividad lo comprueba con Zoan Cloud antes de crear el item o la tarea, igual que Create Human Task.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
queueName	string	—	Nombre de la cola (hasta 120 caracteres). Debe existir en el ambiente donde se ejecuta.
specificContent	Dictionary	—	El payload del item: clave → valor (literales o expresiones). Dentro del consumidor se lee con item.SpecificContent["campo"].

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
reference	string	—	Referencia única por cola (hasta 200 caracteres). Si vuelves a encolar la misma referencia, Zoan Cloud devuelve el item existente en vez de duplicar (idempotencia).
priority	string	"normal"	high, normal o low. Los de mayor prioridad se entregan antes.
deferUntil	string	—	Fecha y hora ISO 8601 en UTC (con Z), ej. 2026-10-20T13:00:00Z o utcNow().AddHours(2).ToString("o"). El item no se entregará antes de ese momento. Vacío = procesable de inmediato.
needsReview	bool	—	Estado inicial del item: true → review (una persona lo aprueba antes de que un performer lo tome), false → new. Vacío = la política de aceptación de la cola. No aplica con taskTitle. Desde la versión 1.1.0.

Decisión humana

Todos estos parámetros existen desde la versión 1.2.0, salvo los de formulario (desde la versión 1.2.6).

Parámetro	Tipo	Por defecto	Descripción
taskTitle	string	—	Qué hay que decidir, en una línea (hasta 200 caracteres). Activa la tarea enlazada.
taskDescription	string	—	Contexto para quien decide. Editor de texto multilínea.
taskOptions	string	"Aprobar, Rechazar"	Opciones separadas por coma (también ; o |), entre 2 y 6.
taskFields	Dictionary	—	Campos que debe llenar quien decide, clave → Etiqueta:tipo[*] (text, number, date, select:A|B; * = obligatorio). Vuelven en item.Decision.Fields.
taskForm	string	—	Nombre de un formulario publicado en la biblioteca, en lugar de taskFields (no los dos). Las respuestas vuelven en item.Decision.Fields: tablas como listas de filas y archivos como { id, name, … } para Download Human Task File. Desde la versión 1.2.6.
taskFormVersion	int	—	Fija una versión publicada del formulario (entero positivo). Vacío = la vigente al crear la tarea. Desde la versión 1.2.6.
taskFormInputs	Dictionary	—	Valores de las entradas del formulario (entrada → valor), o una expresión que devuelva un diccionario. Si falta una obligatoria, la actividad falla sin crear el item ni la tarea. Desde la versión 1.2.6.
assignRole	string	—	Código del rol al que va dirigida la tarea. Obligatorio si no indicas assignUserEmail.
assignUserEmail	string	—	Correo de una persona activa del tenant. Tiene prioridad sobre assignRole. Obligatorio si no indicas assignRole.
dueInHours	int	—	Horas hasta vencer (laborales si la organización definió horario), entre 1 y 8760. Vacío = no vence. Al vencer, el item vuelve con Decision.Status = "expired" o se abandona, según la cola.
escalateToRole	string	—	Si pasa el plazo, reasignar la tarea una vez a este rol.
escalateToUserEmail	string	—	Si pasa el plazo, reasignar la tarea una vez a esta persona. Tiene prioridad sobre escalateToRole.
catalog	string	—	Catálogo de negocio de la tarea (facturas, reembolsos…) para filtrar y ver métricas en la bandeja.
labels	string	—	Etiquetas de la tarea separadas por coma.
taskWebhookUrl	string	—	URL pública que recibe un evento firmado al decidirse, cancelarse o vencer la tarea.

Salida

Devuelve el ZoanQueueItem encolado, con su Id, Reference, SpecificContent, Priority y Status:

• new o review para un item normal (según needsReview o la política de la cola);
• waiting_decision si lleva tarea humana (su id en HumanTaskId);
• si la referencia ya existía, el item existente tal como está (puede estar en cualquier estado, incluso ya procesado).

Errores comunes

Mensaje	Causa y solución
'queueName' es obligatorio.	Falta queueName.
'specificContent' debe ser un objeto.	specificContent no es un diccionario. Usa el editor clave → valor o una expresión que devuelva un Dictionary.
… HTTP 404: …Queue '…' not found / …La cola '…' no existe en este ambiente.	No hay una cola con ese nombre en el ambiente (el nombre distingue mayúsculas). Créala en Zoan Cloud o corrige queueName.
… HTTP 400: …Queue is inactive / …La cola '…' está inactiva.	La cola está desactivada. Actívala en Zoan Cloud.
… HTTP 422: …	Un valor no tiene el formato esperado: típicamente deferUntil con desfase horario (-05:00) o sin formato ISO, o una priority distinta de high, normal, low.
… HTTP 400: …La tarea necesita destino: indica assignUserEmail (una persona) o assignRole (un rol).	Pusiste taskTitle sin assignUserEmail ni assignRole.
… HTTP 400: …El destinatario «…» no es válido para este ambiente.	El correo no es de una persona activa o el rol no existe o no tiene personas activas.
… HTTP 409: …Ya hay un ítem con la referencia «…» en la cola «…» (estado: …).	Con tarea humana: la referencia ya está en un item que no tiene tarea enlazada. Usa otra referencia.
taskForm, taskFormVersion y taskFormInputs solo aplican con una tarea: indica 'taskTitle'.	Pusiste opciones de formulario sin taskTitle.
taskFormVersion y taskFormInputs solo aplican con un formulario: indica 'taskForm'.	Pusiste taskFormVersion o taskFormInputs sin taskForm.
Usa campos sueltos (taskFields) o un formulario (taskForm), no ambos.	Indicaste taskFields y taskForm a la vez.
taskFormVersion debe ser un entero positivo (recibido: «…»).	taskFormVersion no es un entero mayor que 0.
El formulario «…» necesita la entrada «…» (taskFormInputs).	Falta una entrada obligatoria del formulario.
Ya hay un elemento con la referencia «…» cuya tarea se creó sin el formulario «…»: usa otra referencia.	La referencia coincide con un item cuya tarea no usa ese formulario.
El servidor no soporta formularios: actualiza Zoan Cloud.	Tu Zoan Cloud aún no admite tareas con formulario.
Las actividades de colas necesitan el contexto de ejecución de Zoan Automation. Falta: …	El proceso no corre desde Zoan Cloud ni desde el Designer con sesión iniciada.

Los errores de Zoan Cloud llegan con el prefijo “No se pudo agregar el elemento a la cola: ”.

Ejemplo

Encolar una factura por validar, usando su número como referencia idempotente:

Add Queue Item
  queueName = "facturas-por-validar"
  reference = factura["numero"]
  priority  = normal
  specificContent = {
    "facturaId": factura["numero"],
    "monto":     = factura["monto"],
    "cliente":   = factura["cliente"]
  }
  → output: item
Log   level = info   message = "Encolada " + item.Reference + " (estado " + item.Status + ")"

Con una decisión humana

Cada factura de monto alto espera la aprobación de un supervisor antes de pagarse:

Add Queue Item
  queueName = "pagos"   reference = factura["numero"]
  specificContent = { "facturaId": factura["numero"], "monto": factura["monto"] }
  taskTitle = "Aprobar pago de la factura " + factura["numero"]
  taskOptions = "Aprobar, Rechazar"
  assignRole = "supervisores"   dueInHours = 48
  → output: item

El performer lee item.Decision.Value al procesarlo (ver Decisiones humanas en lotes).

Idempotencia con reference

Si tu dispatcher puede ejecutarse dos veces sobre el mismo origen (por reintentos o solapamiento de horarios), pon siempre una reference única (el número de factura, el id del registro). Así nunca encolarás el mismo trabajo dos veces.

Actividades relacionadas

• Get Queue Item — tomar items para procesarlos.
• Process Queue — procesar la cola entera.
• Create Human Task — la misma tarea desde el lado de las tareas (con queueName).
• Colas de trabajo — crear la cola y entender los estados.