Regras

Uma regra descreve, em uma linguagem simplificada, o que a plataforma deve fazer com um evento no momento em que ele chega. Ela é executada de forma síncrona, durante o envio para POST /events, e pode enriquecer o próprio evento com novos valores antes que ele seja armazenado.

Toda regra pertence a um tipo de evento. Esse vínculo é o que define quais campos podem ser usados nas condições e quais campos podem receber valores.

Estrutura

Uma regra é um conjunto ordenado de condições. Cada condição tem:

  • um nome, para identificá-la no painel;
  • uma expressão, que resulta em verdadeiro ou falso, escrita conforme a sintaxe para expressões;
  • de zero a várias ações, executadas quando a expressão é verdadeira.

Como uma regra é executada

  1. o evento chega em POST /events e é validado conforme o contrato do tipo de evento;
  2. a plataforma identifica qual regra aplicar;
  3. as condições são avaliadas em ordem, todas elas: a avaliação não para na primeira condição satisfeita;
  4. cada condição satisfeita executa suas ações, na ordem em que estão configuradas;
  5. os valores produzidos são gravados no evento e devolvidos na resposta.

Todas as condições compartilham a mesma memória de trabalho: uma condição enxerga o que as anteriores escreveram. Isso permite encadear o processamento: uma condição enriquece o evento com um dado externo e outra, mais adiante, decide com base nesse dado.

Qual regra é executada

A regra a executar é escolhida em duas etapas:

  1. o nome informado em rule.name na requisição;
  2. se a requisição não informar nenhum, a regra padrão configurada no tipo de evento.
{
  "event": {
    "type": "transaction",
    "id": "evt_8f3a",
    "attributes": { "amount": "1500.00", "status": "pending" },
    "rule": { "name": "minha_regra" }
  }
}

A regra precisa ter uma versão ativa publicada e pertencer ao mesmo tipo de evento do evento enviado. Consulte versionamento para publicar e reverter versões.

Quando nenhuma regra é executada

Nos cenários abaixo o evento é ingerido normalmente, apenas sem passar por nenhuma regra:

  • a requisição não informa uma regra e o tipo de evento não tem regra padrão;
  • a regra informada não existe;
  • a regra existe, mas não tem versão ativa publicada;
  • a regra pertence a outro tipo de evento.

A requisição não falha em nenhum desses casos. Um nome de regra incorreto não interrompe a ingestão; por isso, ao configurar uma regra nova, confirme no painel que ela está ativa e vinculada ao tipo de evento correto.

O que a regra grava no evento

As ações gravam nos campos do próprio tipo de evento. Esses valores passam a fazer parte do evento como qualquer outro dado enviado na requisição: são persistidos, aparecem na resposta da API, podem ser consultados no painel e podem alimentar métricas e monitoramentos.

Além disso, a plataforma registra automaticamente qual regra processou o evento e em qual versão, em campos reservados criados na primeira ativação de uma regra do tipo de evento. Esses campos ficam disponíveis para consulta e análise, mas não são devolvidos na resposta da API e não podem ser preenchidos na ingestão: nomes de campo iniciados por _ são rejeitados.

Limitações

Há limites de quantidade e tamanho aplicáveis a regras e listas. Consulte limites e parâmetros antes de planejar configurações extensas.

Índice