Saltar al contenido

Manejo de mensajes fallidos usando una Dead Letter Queue en Jitterbit Studio

Introducción

El conector Jitterbit MQ permite procesar mensajes de una cola usando una actividad Get. Cuando falla el procesamiento, un enfoque común es usar la actividad NACK con Requeue Messages After NACK para devolver el mensaje a la cola e intentarlo más tarde. Sin embargo, con colas Quorum, este enfoque tiene un límite máximo: después de 20 confirmaciones fallidas, el mensaje se elimina permanentemente de la cola sin error. Para integraciones que requieren comportamiento de reintentos controlado y entrega garantizada, usa el patrón Dead Letter Queue (DLQ) en su lugar.

Esta guía te muestra cómo construir un patrón DLQ usando múltiples colas y un conjunto de operaciones Studio. Los mensajes fallidos se rechazan de la cola principal y se enrutan a una serie de colas de reintentos con retrasos crecientes. Después de un número configurable de intentos, los mensajes se envían a una DLQ final para inspección manual.

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart TD A([Message in orders.main]) --> B[Main processor] B -->|Success| C([ACK: message removed]) B -->|Failure| D{retryCount} D -->|1| E([orders.retry.1m]) D -->|2| F([orders.retry.5m]) D -->|3 or 4| G([orders.retry.30m]) D -->|greater than 4| H([orders.dlq]) E -->|Forwarder runs every 1 min| A F -->|Forwarder runs every 5 min| A G -->|Forwarder runs every 30 min| A

Para necesidades de reintentos más simples que no requieran enrutamiento de retrasos de múltiples niveles, consulta Reintentar una operación fallida. Para obtener información sobre la configuración del comportamiento al éxito y al fallo, consulta Configurar el manejo de errores en operaciones.

Esta guía asume lo siguiente:

  • Tienes una conexión Jitterbit MQ funcionando en Studio. Para instrucciones de configuración, consulta la documentación del conector Jitterbit MQ.
  • Estás familiarizado con la creación y ejecución de operaciones Studio.
  • Usas colas Quorum, que son necesarias para la durabilidad pero imponen el límite de 20 intentos de entrega que este patrón aborda.

Parte 1: Crear las colas

Paso 1: Crear las colas en la Management Console

  1. Abre la página Message Queues de la Management Console.

  2. Crea las siguientes cinco colas. Establece el Type en Quorum para cada una.

    Nombre de la cola Propósito TTL de mensaje
    orders.main Cola de procesamiento principal —
    orders.retry.1m Primer reintento (retraso de 1 minuto) 3,600,000 ms
    orders.retry.5m Segundo reintento (retraso de 5 minutos) 3,600,000 ms
    orders.retry.30m Tercer reintento (retraso de 30 minutos) 3,600,000 ms
    orders.dlq Cola final para inspección manual 864,000,000 ms

    Adapta los nombres de las colas y el número de niveles de reintentos según tu integración.

Nota

Los valores de TTL en las colas de reintentos son una medida de seguridad que evita que los mensajes se acumulen indefinidamente si una operación de reenvío falla. El retraso entre reintentos se controla por la frecuencia con que se ejecutan las operaciones de reenvío, no por el TTL.

Parte 2: Configurar la operación del procesador principal

Paso 2: Añade un campo retryCount a tu carga de mensaje

El patrón DLQ usa un campo retryCount en la carga del mensaje para rastrear cuántas veces se ha intentado procesar. Añade este campo a tu carga de mensaje con un valor inicial de 0 antes de que la operación se active por primera vez.

Carga de ejemplo

{
  "orderId": "ORD-12345",
  "retryCount": 0
}

Usa un nombre de campo consistente en el nivel superior en todas las operaciones del patrón. El campo retryCount es el único mecanismo para rastrear el historial de intentos entre ejecuciones.

Paso 3: Construir la operación de enrutamiento al fallar

Cuando falla el procesador principal, la operación al fallar debe leer el retryCount actual, enrutar el mensaje a la cola de reintentos apropiada y luego rechazar el mensaje original de la cola principal.

  1. Lee retryCount del campo messageBody en el esquema de respuesta de la actividad Get.

  2. Incrementa el valor por 1 usando un script o transformación.

  3. Enruta a la cola apropiada según el recuento actualizado:

    Valor de retryCount Cola de destino
    1 orders.retry.1m
    2 orders.retry.5m
    3 o 4 orders.retry.30m
    Mayor que 4 orders.dlq

  4. Escribe el retryCount actualizado de vuelta en el campo messageBody del esquema de solicitud de la actividad Send al enrutar a la cola de destino.

  5. Después de que se complete la actividad Send, usa la actividad NACK con la opción Reject Messages After NACK para eliminar el mensaje de orders.main.

Importante

La actividad Send a la cola de reintentos debe completarse antes de que se ejecute la actividad NACK. Este orden garantiza que el mensaje no se pierda si la actividad Send falla. No uses Requeue Messages After NACK, que omite la lógica de enrutamiento de DLQ y cuenta hacia el límite de 20 intentos de entrega.

Paso 4: Configurar la operación del procesador principal

  1. En Studio, abre o crea la operación que procesa mensajes de orders.main.

  2. Agrega una actividad Get configurada para leer desde orders.main.

  3. Agrega los pasos que procesan cada mensaje (por ejemplo, consultar un sistema ERP para el estado de pedido esperado).

  4. Abre la configuración de acciones de la operación y configura lo siguiente:

    • On Success: Ejecuta una operación que usa la actividad Acknowledge para reconocer el mensaje de orders.main.
    • On Fail: Ejecuta la operación de enrutamiento de falla construida en el Paso 3.

Parte 3: Configurar las operaciones del reenviador de reintentos

Crea una operación reenviadora para cada cola de reintentos. Cada reenviador lee mensajes de su cola de reintentos, los envía de vuelta a orders.main para su reprocesamiento, y se ejecuta según una programación que coincida con el retraso previsto para ese nivel.

Paso 5: Construir cada operación reenviadora

Para cada nivel de reintentos, crea una operación con los siguientes pasos:

  1. Agrega una actividad Get para recuperar un mensaje de la cola de reintentos.

  2. Agrega una actividad Send para enviar el mensaje a orders.main, preservando el valor de retryCount en la carga útil.

  3. Agrega una actividad Acknowledge para reconocer el mensaje de la cola de reintentos.

Importante

La actividad Send a orders.main debe completarse antes de que se ejecute la actividad Acknowledge. Si la actividad Send falla, el mensaje permanece en la cola de reintentos y será recogido en la próxima ejecución del reenviador. Reconocer antes de que se complete la actividad Send eliminaría silenciosamente el mensaje de la cola de reintentos sin garantía de que llegue a orders.main.

Paso 6: Programar cada operación reenviadora

Adjunta una programación de operación a cada operación reenviadora con un intervalo que coincida con su nivel de reintentos:

Operación Cola de origen Intervalo de programación
Reenviador de reintentos 1m orders.retry.1m Cada 1 minuto
Reenviador de reintentos 5m orders.retry.5m Cada 5 minutos
Reenviador de reintentos 30m orders.retry.30m Cada 30 minutos

Para obtener instrucciones sobre cómo configurar una programación, consulta Programar una operación para que se ejecute automáticamente.

Operación del inspector de DLQ (opcional)

Crea una operación que lea desde orders.dlq para alertar sobre o registrar mensajes que hayan agotado todos los intentos de reintento. Esta operación puede enviar una notificación por correo electrónico, escribir en un registro o activar un flujo de trabajo de revisión manual. Para obtener instrucciones sobre cómo enviar correo electrónico desde una operación de Studio, consulta Enviar una notificación por correo electrónico desde una operación de Studio.

Nota

Los mensajes en orders.dlq requieren intervención manual. Permanecen en la cola hasta que se reconozcan explícitamente o expire su TTL.

Verificar la integración

  1. Implementa el proyecto.

  2. Envía un mensaje de prueba a orders.main con retryCount: 0 en la carga útil.

  3. Activa una falla de procesamiento en la operación del procesador principal (por ejemplo, devolviendo un error desde el script de procesamiento).

  4. Abre los registros de operación en Studio y confirma que la operación de falla se ejecutó y que el mensaje se envió a orders.retry.1m.

  5. Espera a que se ejecute el reenviador de 1 minuto. Confirma en los registros de operación que el reenviador recuperó el mensaje de orders.retry.1m y lo envió de vuelta a orders.main.

  6. Continúa activando fallas para avanzar el mensaje a través de los niveles de reintento restantes. La cola orders.retry.5m maneja un pase (retryCount 2), y orders.retry.30m maneja dos pases (retryCount 3 y 4). Después del quinto intento fallido, el mensaje se enruta a orders.dlq.

  7. Abre la página Colas de mensajes de Management Console y confirma que un mensaje ha llegado a orders.dlq.