Set Transaction Status

Set Transaction Status

Tipo: queue-set-transaction-status  ·  Paquete: Queue Activities v1.2.9

Cierra la transacción de un item: lo marca como successful (procesado bien) o failed (procesado con error). Es lo que hace el performer al terminar con cada item. El item debe estar in_progress y haber sido tomado por esta ejecución con Get Queue Item o Add Transaction Item.

Cómo funciona

• successful: el item pasa a successful, guarda output en item.Output y libera el bloqueo.
• failed: guarda exception en item.Exception, libera el bloqueo y decide el estado final:
  • si exception tiene "type": "BusinessRuleException" (o "BusinessException"), es un error de negocio: el item queda en business_exception («Excepción») y no se reintenta, aunque la cola tenga reintentos;
  • si la cola tiene reintento automático, quedan intentos y no pusiste retryable = false, vuelve a new con una espera creciente (1, 2, 4, 8… minutos, hasta 30) antes de entregarse de nuevo;
  • si no, queda failed, o abandoned si ya agotó los reintentos de la cola.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
item	ZoanQueueItem	—	El item devuelto por Get Queue Item (ej. item), o un diccionario con su id.
status	string	—	successful (éxito) o failed (error). No distingue mayúsculas.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
output	Dictionary	—	Objeto JSON con el resultado del procesamiento. Solo para status = successful. Queda guardado en item.Output.
exception	Dictionary	—	Objeto JSON con el detalle del error (ej. { "type": "...", "message": "..." }). Solo para status = failed. Con type = BusinessRuleException el fallo es de negocio y no se reintenta.
retryable	bool	true	Solo para failed. true = respeta el reintento automático de la cola. false = marca el fallo de inmediato, sin reintento.

Salida

Esta actividad no devuelve ningún valor.

Errores comunes

Mensaje	Causa y solución
'item' es obligatorio. / 'status' es obligatorio.	Falta un parámetro requerido.
'item' debe ser un ZoanQueueItem o un objeto con un campo 'id'.	item no es el item de la cola.
'status' debe ser 'successful' o 'failed'; se recibió '…'.	status tiene otro valor.
… HTTP 400: …Cannot complete an item in status '…' / …Cannot fail an item in status '…'	El item ya no está in_progress: ya se cerró (por ejemplo, dos veces seguidas) o se aplazó.
… HTTP 400: …This item is not locked by your execution	El item lo tiene otra ejecución (su bloqueo venció y otro robot lo tomó).
… HTTP 404: …Queue item not found	El item no existe en el ambiente.
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 cambiar el estado del elemento: ”.

Cuándo usar retryable = false

Por defecto, un item failed se reintenta si la cola tiene auto-retry y quedan reintentos. Eso es lo correcto para errores del sistema (la web se cayó, un timeout). Pero para errores de negocio —un dato inválido, un campo faltante— reintentar daría exactamente el mismo error: ahí usa retryable = false, o mejor aún un exception con "type": "BusinessRuleException", para que el item quede como excepción de negocio. Ver reintentos.

Ejemplo

Procesar el item dentro de un Try / Catch y reportar según el resultado:

Try
  └─ body:
       (… procesar la factura …)
       Set Transaction Status
         item = item   status = successful
         output = { "validada": true, "revisadaPor": "bot" }
  └─ catch (err):
       Set Transaction Status
         item = item   status = failed
         exception = { "type": err.Type, "message": err.Message }
         retryable = true

Si el error vino de un Throw con la excepción de negocio, err.Type es BusinessRuleException y el item no se reintenta.

Actividades relacionadas

• Get Queue Item — tomar el item antes de cerrarlo.
• Postpone Transaction — en vez de cerrar, aplazar el item.
• Try / Catch — capturar el error para reportarlo.