Reglas

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

Toda regla pertenece a un tipo de evento. Ese vínculo define qué campos pueden usar las condiciones y qué campos pueden recibir valores.

Estructura

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

  • un nombre, que identifica la condición 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.

Ejecución de una regla

  1. el evento llega a POST /events y la plataforma lo valida según el contrato del tipo de evento;
  2. la plataforma identifica qué regla aplicar;
  3. la plataforma evalúa las condiciones 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. la plataforma graba los valores producidos en el evento y los devuelve en la respuesta.

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

Elección de la regla

La plataforma elige la regla a ejecutar 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.

Eventos sin regla

En los escenarios siguientes la plataforma ingiere el evento normalmente, 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. Al configurar una regla nueva, confirme en el panel que está activa y vinculada al tipo de evento correcto.

Valores grabados 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: la plataforma los persiste y los devuelve en la respuesta de la API. Los valores pueden consultarse en el panel y pueden alimentar métricas y monitoreos.

La plataforma también registra automáticamente qué regla procesó el evento y en qué versión. Ese registro queda 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. La API no los devuelve en la respuesta y no acepta completarlos en la ingestión: la plataforma rechaza los nombres de campo que comienzan con _.

Limitaciones

Las reglas y las listas tienen límites de cantidad y de tamaño. Consulte límites y parámetros antes de planificar configuraciones extensas.

Tabla de contenidos