Reglas

Una regla describe, en un lenguaje simplificado, qué debe hacer la plataforma con un evento en el momento en que llega. Se ejecuta de forma síncrona, durante el envío a POST /events, y puede enriquecer el propio evento con nuevos valores antes de que sea almacenado.

Toda regla pertenece a un tipo de evento. Ese vínculo es el que define qué campos pueden usarse en las condiciones y qué campos pueden recibir valores.

Estructura

Una regla es un conjunto ordenado de condiciones. Cada condición tiene:

  • un nombre, para identificarla en el panel;
  • una expresión, que resulta en verdadero o falso, escrita según la sintaxis para expresiones;
  • de cero a varias acciones, ejecutadas cuando la expresión es verdadera.

Cómo se ejecuta una regla

  1. el evento llega a POST /events y se valida según el contrato del tipo de evento;
  2. la plataforma identifica qué regla aplicar;
  3. las condiciones se evalúan en orden, todas ellas: la evaluación no se detiene en la primera condición satisfecha;
  4. cada condición satisfecha ejecuta sus acciones, en el orden en que están configuradas;
  5. los valores producidos se graban en el evento y se devuelven en la respuesta.

Todas las condiciones comparten la misma memoria de trabajo: una condición ve lo que escribieron las anteriores. Esto permite encadenar el procesamiento: una condición enriquece el evento con un dato externo y otra, más adelante, decide en función de ese dato.

Qué regla se ejecuta

La regla a ejecutar se elige en dos etapas:

  1. el nombre informado en rule.name en la solicitud;
  2. si la solicitud no informa ninguno, la regla predeterminada configurada en el tipo de evento.
{
  "event": {
    "type": "transaction",
    "id": "evt_8f3a",
    "attributes": { "amount": "1500.00", "status": "pending" },
    "rule": { "name": "mi_regla" }
  }
}

La regla necesita tener una versión activa publicada y pertenecer al mismo tipo de evento que el evento enviado. Consulte versionado para publicar y revertir versiones.

Cuándo no se ejecuta ninguna regla

En los escenarios siguientes el evento se ingiere normalmente, solo que sin pasar por ninguna regla:

  • la solicitud no informa una regla y el tipo de evento no tiene regla predeterminada;
  • la regla informada no existe;
  • la regla existe, pero no tiene versión activa publicada;
  • la regla pertenece a otro tipo de evento.

La solicitud no falla en ninguno de estos casos. Un nombre de regla incorrecto no interrumpe la ingestión; por eso, al configurar una regla nueva, confirme en el panel que está activa y vinculada al tipo de evento correcto.

Qué graba la regla en el evento

Las acciones graban en los campos del propio tipo de evento. Esos valores pasan a formar parte del evento como cualquier otro dato enviado en la solicitud: se persisten, aparecen en la respuesta de la API, pueden consultarse en el panel y pueden alimentar métricas y monitoreos.

Además, la plataforma registra automáticamente qué regla procesó el evento y en qué versión, en campos reservados creados en la primera activación de una regla del tipo de evento. Esos campos quedan disponibles para consulta y análisis, pero no se devuelven en la respuesta de la API y no pueden completarse en la ingestión: los nombres de campo que comienzan con _ se rechazan.

Limitaciones

Existen límites de cantidad y tamaño aplicables a reglas y listas. Consulte límites y parámetros antes de planificar configuraciones extensas.

Tabla de contenidos