Rules

A rule describes, in a simplified language, what the platform should do with an event at the moment it arrives. It runs synchronously, during the submission to POST /events, and can enrich the event itself with new values before it is stored.

Every rule belongs to an event type. That binding is what defines which fields can be used in the conditions and which fields can receive values.

Structure

A rule is an ordered set of conditions. Each condition has:

  • a name, to identify it in the panel;
  • an expression, which results in true or false, written according to the expression syntax;
  • from zero to several actions, executed when the expression is true.

How a rule runs

  1. the event arrives at POST /events and is validated against the event type’s contract;
  2. the platform identifies which rule to apply;
  3. the conditions are evaluated in order, all of them: evaluation does not stop at the first satisfied condition;
  4. each satisfied condition runs its actions, in the order they are configured;
  5. the produced values are written to the event and returned in the response.

All conditions share the same working memory: a condition sees what the previous ones wrote. This allows the processing to be chained: one condition enriches the event with external data and another, further on, decides based on that data.

Which rule runs

The rule to run is chosen in two steps:

  1. the name provided in rule.name in the request;
  2. if the request provides none, the default rule configured in the event type.
{
  "event": {
    "type": "transaction",
    "id": "evt_8f3a",
    "attributes": { "amount": "1500.00", "status": "pending" },
    "rule": { "name": "my_rule" }
  }
}

The rule must have an active published version and belong to the same event type as the submitted event. See versioning to publish and revert versions.

When no rule runs

In the scenarios below the event is ingested normally, just without going through any rule:

  • the request does not provide a rule and the event type has no default rule;
  • the provided rule does not exist;
  • the rule exists but has no active published version;
  • the rule belongs to another event type.

The request does not fail in any of these cases. An incorrect rule name does not interrupt ingestion; so when setting up a new rule, confirm in the panel that it is active and bound to the correct event type.

What the rule writes to the event

Actions write to the fields of the event type itself. Those values become part of the event like any other data sent in the request: they are persisted, appear in the API response, can be queried in the panel, and can feed metrics and monitors.

In addition, the platform automatically records which rule processed the event and in which version, in reserved fields created the first time a rule of that event type is activated. These fields are available for querying and analysis, but are not returned in the API response and cannot be filled in at ingestion: field names starting with _ are rejected.

Limitations

There are quantity and size limits applicable to rules and lists. See limits and parameters before planning extensive configurations.

Table of contents