Rules

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

Every rule belongs to an event type. That binding defines which fields the conditions can use and which fields can receive values.

Structure

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

  • a name, which identifies the condition 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 the platform validates it against the event type’s contract;
  2. the platform identifies which rule to apply;
  3. the platform evaluates the conditions 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 platform writes the produced values to the event and returns them in the response.

All conditions share the same working memory: a condition sees what the previous ones wrote. That sharing chains the processing. One condition enriches the event with external data and another condition, further on, decides based on that data.

Which rule runs

The platform chooses the rule to run 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 platform ingests the event normally, 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. 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: the platform persists them and returns them in the API response. The values can be queried in the panel and can feed metrics and monitors.

The platform also automatically records which rule processed the event and in which version. That record sits in reserved fields, created the first time a rule of the event type is activated. These fields are available for querying and analysis. The API does not return them in the response and does not accept filling them in at ingestion: the platform rejects field names starting with _.

Limitations

Rules and lists have quantity and size limits. See limits and parameters before planning extensive configurations.

Table of contents