Add Transaction Item

Add Transaction Item

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

Añade un item a una cola de trabajo y te lo devuelve ya en in_progress, bloqueado para la ejecución actual — add + start en un solo paso. Sirve para flujos donde el mismo bot crea el trabajo y lo procesa en la misma ejecución, conservando la trazabilidad y los reintentos de la cola.

Cómo funciona

A diferencia de Add Queue Item —que deja el item en new para que otro performer lo tome más tarde—, esta actividad crea el item directamente en in_progress y lo reserva para ti: no pasa por new ni por revisión. Lo recibes listo para procesar, con Attempts = 1.

Con reference, si la cola ya tiene un item vivo con esa referencia:

• si es tuyo (lo tiene bloqueado esta misma ejecución), lo devuelve tal cual;
• si está en new, o in_progress con el bloqueo vencido, lo toma para esta ejecución y suma un intento;
• en cualquier otro estado (ya procesado, o en curso en otra ejecución), la actividad falla.

Como cualquier transacción, debes cerrarlo: cuando termines, marca el resultado con Set Transaction Status (successful o failed). Si no lo haces, el item queda in_progress hasta que su bloqueo vence (15 minutos) y Zoan Cloud lo devuelve a la cola o lo abandona según sus reintentos.

¿Cuándo usar esta y no Add Queue Item?

• Add Transaction Item (esta): el bot crea y procesa el item en el mismo run. Útil para registrar una unidad de trabajo “sobre la marcha” sin separar dispatcher y performer.
• Add Queue Item: el productor encola trabajo que otro bot (o el mismo, después) tomará con Get Queue Item o Process Queue.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
queueName	string	—	Nombre de la cola. Debe existir y estar activa en el ambiente de la ejecución.
specificContent	Dictionary	—	El payload: datos mapeados como clave → valor (literales o expresiones). Los lees con item.SpecificContent["mi_campo"].

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
reference	string	—	Referencia para trazabilidad (hasta 200 caracteres). Si ya existe un item con ella, se aplican las reglas de arriba.
priority	string	"normal"	high, normal o low.

Salida

Devuelve un ZoanQueueItem en estado in_progress y bloqueado para esta ejecución, listo para procesar y cerrar.

Errores comunes

Mensaje	Causa y solución
'queueName' es obligatorio. / 'specificContent' debe ser un objeto.	Falta la cola o el payload no es un diccionario.
… HTTP 404: …Queue '…' not found or inactive in this environment	La cola no existe en el ambiente o está inactiva.
… HTTP 409: …Ya hay un ítem con la referencia «…» en la cola «…» (estado: …).	La referencia ya está en un item procesado o que procesa otra ejecución. Usa otra referencia.
… HTTP 409: …La cola '…' la procesa un flujo…	La cola pertenece a un flujo: sus items no se procesan con robots. Aliméntala con Add Queue Item.
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 de transacción: ”.

Ejemplo

Crear una transacción, procesarla y cerrarla en el mismo flujo:

Add Transaction Item
  queueName       = "reprocesos"
  specificContent = {
    "facturaId": factura.numero,
    "motivo":    "revalidación manual"
  }
  → output: item

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

Actividades relacionadas

• Set Transaction Status — cerrar la transacción (obligatorio).
• Add Queue Item — encolar trabajo para que otro performer lo tome.
• Get Queue Item — tomar el siguiente item de la cola.
• Process Queue — procesar la cola entera en un bucle.