Lists

Use a list to parameterize rules without editing them on every change. The list is a set of values, referenced in expressions by its name with the @ prefix:

$user_id in @quarantined_customers

The list separates operational responsibility, which maintains the items, from technical responsibility, which maintains the rules. That separation reduces the risk of accidental changes to the 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 you want 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.

Add items through the API as well, with POST /lists/{list_id}/items. Provide the expiration 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, the rule incorporates what it has already observed: a condition detects the behavior and records the value in the list. The following 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

Page through the items or search them with the search box at the top of the table. To remove an item, use ⋮ > Remove on the item’s row. To clear the list, use Remove all items.

The platform automatically removes items with an expiration, in periodic sweeps that run every few minutes. An item may keep counting in a condition for a few minutes past its expiration. The same sweep is what justifies the minimum expiration of 5 minutes.

Remove a list

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