Expressions

Overview

Expressions are a feature in our system that enable flexible customization by allowing you to dynamically configure and calculate fields for various use cases. Expressions are used in two contexts: dynamic fields and user property automation.

Dynamic Field Configurations

In the context of reward rules, quests, and perks, expressions are used to dynamically calculate and configure fields based on specific data inputs. These expressions allow the system to aggregate and manipulate relevant data to produce the desired outcomes for these configurations.

Available variables:

event: The event that triggered the configuration, accessible with all parameters.
value: The value obtained from a field within the system.
user: The user associated with the triggering event.
userProperties: The properties of the user involved in the event. To access a specific property, use the following syntax: userProperties['$.properties.<property_name>'].
config: Additional configuration values specified within dynamic field configurations.

User Property Automation

In user property automation, expressions are used to dynamically calculate values related to user properties. This enables the system to automatically update or adjust user properties based on predefined logic.

Available variable:

aggregatedValue: The current value of the user property that is being calculated or updated.
event: The event that triggered the configuration, accessible with all parameters.
user: The user associated with the triggering event.
userProperties: The properties of the user involved in the event.

Mathjs Integration

The mathjs library powers the specified expressions, enabling the use of a wide range of mathematical operators and functions within configurations. This integration provides the flexibility to create complex and customized expressions tailored to specific requirements. For detailed information on the available syntax and functions, refer to the Mathjs Expressions Syntax.

Extended Functions

To further enhance the flexibility and functionality of expressions, our system includes a set of custom functions beyond the standard mathjs capabilities. These extended functions are designed to provide additional utility, especially for operations related to date manipulation and object handling:

isMonday, isTuesday, isWednesday, isThursday, isFriday, isSaturday, isSunday: These functions return true if the given date corresponds to the specified day of the week (e.g., isMonday returns true if the date is a Monday), and false otherwise. An optional timezone parameter can be provided to check the day of the week in the specified timezone; if not provided, the system's local timezone will be used.
indexOf: Returns the first index of a given element in an array, or -1 if not found.
objectValues: Returns an array of a given object's enumerable property values.
objectKeys: Returns an array of a given object's enumerable property names.

Examples

1. Loyalty Program Points Calculation

The system awards users with additional percentages based on their membership level and their total purchases. Each user has a property indicating their membership level, which can be 'Gold', 'Silver', or 'Bronze'. A custom event is triggered whenever the user performs certain actions, and one of the properties of this event is totalPurchases.

For every event, the reward is calculated as follows:

Membership Level Bonus: Users receive a percentage of aggregatedValue depending on their membership level: Gold: 20%, Silver: 15%, Bronze: 10% (default if the level is not recognized)
Total Purchases Bonus: An additional 10% of aggregatedValue is granted if totalPurchases exceeds 500.
Base Value: The original aggregatedValue is added to the final reward.

The formula for calculating the total reward is:

(value * 
    (equalText(userProperties['$.properties.membershipLevel'], 'Gold') ? 0.2 :
     equalText(userProperties['$.properties.membershipLevel'], 'Silver') ? 0.15 : 
     0.1)
  ) +
  (value * (event.body.totalPurchases > 500 ? 0.1 : 0)) +
  value

The math.equalText function is used to check equality of two strings and returns true if the values are equal, and false if not. For more information, refer to the documentation here.

Alternative Approach for Handling Multiple Options

When calculating values based on user membership levels, using ternary operators can become unwieldy, especially if there are many membership level options. A more scalable and maintainable approach is to define the membership level multipliers in a config object (for dynamic fields). This approach allows for easier updates and better readability.

First, define the config object::

{
  "Gold": 0.2,
  "Silver": 0.15,
  "Bronze": 0.1
};

Then, use this config object in the expression:

(value * config[userProperties['$.properties.membershipLevel']] ) +
  (value * (event.body.totalPurchases > 500 ? 0.1 : 0)) +
  value

2.Lucky Thursday Bonus

This calculation adds a bonus to the aggregatedValue for deposits made on a Thursday. The system checks if the deposit date is Thursday using the isThursday function. If it is, a random bonus between 10 and 50 is generated using math.random, rounded with math.round, and then added to the aggregatedValue. If it is not Thursday, no additional bonus is applied.

The formula for calculating the final value is:

aggregatedValue + round(
    isThursday() ?
    random(10, 50) :
    0
  )

The isThursday function returns true if the deposit date is Thursday, and false otherwise. For more details on how to use the math functions, refer to the Math.js documentation here.