Lists

Lists are sets of values used to parameterize rules without having to edit them on every change. In expressions, a list is referenced by its name with the @ prefix:

$user_id in @quarantined_customers

Keeping data in lists separates operational responsibility (maintaining the items) from technical responsibility (maintaining the rules), reducing the risk of accidental changes to rules. Each list holds text values of up to 128 characters, with no line breaks.

Create a list

Under Settings > Lists > New list:

  1. Choose a name using only letters, numbers, hyphens, and underscores (e.g., quarantined-customers).
  2. Add an optional description.
  3. Click Create list.

The name is the identifier used in expressions and cannot be changed after creation: a rule referencing the old name would stop finding the items.

Add items

Open the list and click Add items:

  1. Enter one item per line.
  2. Add an optional description, repeated across every item in the insertion (useful for referencing a support ticket, for example).
  3. Optionally, set an expiration, in minutes, hours, or days, at least 5 minutes and at most 2 years. Without an expiration, the item stays until removed manually.

Each list holds up to 10,000 items. You can add up to 1,000 items per insertion; to register larger volumes, split the content across more than one insertion.

Items can also be added through the API, with POST /lists/{list_id}/items. The expiration is provided in expires_in, as an ISO 8601 period (PT30M, PT12H, P1D).

Items added by rules

A rule can write to a list while processing an event, with the add to list action. This way, a rule incorporates what it has already observed: a condition detects the behavior and records the value in the list, and later events check that list with an ordinary condition.

When following a list written by rules, keep in mind that:

  • items appear with no description and no author, since they were not registered by a person;
  • a value detected again renews the expiration of the existing item, instead of creating another one;
  • when the list is full, new values stop being added; it is worth tracking the item count in automatically fed lists.

Query and remove items

Items can be paginated or searched through the search box at the top of the table. To remove one, use ⋮ > Remove on the item, or Remove all items to clear the list.

Items with an expiration are removed automatically by periodic sweeps, which run every few minutes. That is why an item may still count in a condition for a few minutes past its expiration, and also why the minimum expiration is 5 minutes.

Remove a list

A list can only be removed when it is empty and is not used by any active rule or monitor. Remove the items and the references before deleting it.