Regras

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

Toda regra pertence a um tipo de evento. Esse vínculo define quais campos as condições podem usar e quais campos podem receber valores.

Estrutura

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

  • um nome, que identifica a condição 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.

Execução de uma regra

  1. o evento chega em POST /events e a plataforma o valida conforme o contrato do tipo de evento;
  2. a plataforma identifica qual regra aplicar;
  3. a plataforma avalia as condições 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. a plataforma grava os valores produzidos no evento e os devolve na resposta.

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

Escolha da regra

A plataforma escolhe a regra a executar 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.

Eventos sem regra

Nos cenários abaixo a plataforma ingere o evento normalmente, 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. Ao configurar uma regra nova, confirme no painel que ela está ativa e vinculada ao tipo de evento correto.

Valores gravados 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: a plataforma os persiste e os devolve na resposta da API. Os valores podem ser consultados no painel e podem alimentar métricas e monitoramentos.

A plataforma também registra automaticamente qual regra processou o evento e em qual versão. Esse registro fica 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. A API não os devolve na resposta e não aceita preenchê-los na ingestão: a plataforma rejeita nomes de campo iniciados por _.

Limitações

Regras e listas têm limites de quantidade e de tamanho. Consulte limites e parâmetros antes de planejar configurações extensas.

Índice