Rules

A Rule is an object representing a set of conditions to evaluate against some one or more target object(s) in the system. It also specifies an effect which is what what should occur on a successful match.

Rules are an internal construct and while they exist and are stored as units they are not intended to be constructed directly. Instead, rules are synthesized as users of the API make consumers of rules conditional. The best example of this is Segments where membership can be automated by using a series of conditions to match a member.

The basic structure of a Rule is as follows:

{
  "conditions": [
    {
      "subject": "type",
      "object": "PURCHASE",
      "predicate": "EQUAL"
    },
    {
      "subject": "metadata.value.amount",
      "object": 4.99,
      "predicate": "GREATER"
    }
  ],
  "effect": {
    "controller": "rule",
    "method": "noop",
    "values": {
      "foo": "bar"
    }
  },
  "matchType": "TYPE"
}

Validation

When attempting to create an object with one or more Rules attached conditions specified will be validated against a list of allowed matches and creation rejected if this process fails.

Predicates

A number of comparisons between values are allowed when creating rules. These comparisons are referred to as predicates and correspond to the property of the same name in condition blocks.

Most comparisons enforce the same type on both sides (Left-Hand side and Right-Hand side) with the exception of Date, where a DateOptions block on the RHS allows post-processing the subject date during comparison.

Predicate	Types	Notes
EQUAL	String, Integer
NOT_EQUAL	String, Integer
IN	Array	elements === compared
NOT_IN	Array	elements === compared
GREATER	Integer	strictly greater than
LESSER	Integer	strictly less than
EQUAL (processed Date)	Date (DateOptions RHS)	checks the current date equals a date to a certain precision and a certain period away

Properties

matchType

There are two ways the matching of rules can be triggered. The first is as a result of Actions occurring within the system - called TYPE rules. The second are TIME rules which are periodically evaluated against all users.

TYPE

• matches against an action in the system
• by definition this matches ones per used (actions are always tired to a User)
• evaluated at the point in time an action occurs

a type rule must include a type match for a valid condition

TIME

• evaluated periodically by the platform
• matched against all users for a particular Tenant

{
  "conditions": [
    {
      "subject": "type",
      "object": "PURCHASE",
      "predicate": "EQUAL"
    },
    {
      "subject": "metadata.value.amount",
      "object": 4.99,
      "predicate": "GREATER"
    }
  ],
  "occurrences": {
    "count": 3,
    "period": "MONTH"
  },
  "effect": {
    "controller": "rule",
    "method": "noop",
    "values": {
      "foo": "bar"
    }
  },
  "matchType": "TYPE"
}

occurrences

A rule can be configured so the set of conditions are required to match a given count number of times over a particular day, week or month period. Such a rule will additionally contain an occurrences dictionary containing those two keys.

At the point where it is being matched, historic actions for the specified period are loaded and the conditions evaluated against them. Should this match count number of times, the rule is said to match. In the example above, there must have been three PURCHASE actions over 4.99 over the past MONTH of actions for a particular user for the effect to be triggered.

occurrences historically match the current conditions