Open Loyalty 5.16.1
Search…
⌃K
Links

Expressions

Introduction to Open Loyalty language

When setting up conditions and effects for rules in Campaigns, you may find that some situations are not covered by premade values. However, you are not limited to using these values - you can use an Open Loyalty language to create very specific conditions and values. In conditions, you can find a condition called "Expressions."
You can set the value of such an expression. It can be set as a combination of attributes and operators using the meta language created by Open Loyalty. It allows you to create a fully customizable condition that meets the rules of your planned loyalty program.
For example, you can create a campaign that is triggered when a customer buys a product from a certain category. You can do it in two ways:
Set a premade condition:
Or use an expression:
In the same way, you can create a custom campaign effects - you can use a premade values, or enter it yourself:
In this section, you will find a description of the meta language together with all the supported syntaxes, which is based on the expression syntax of Symfony Expression.

The component supports:

  • strings - single and double quotes (e.g. 'hello')
  • numbers - integers (e.g. 103), decimals (e.g. 9.95), decimals without leading zeros (e.g. .99, equivalent to 0.99); all numbers support optional underscores as separators to improve readability (e.g. 1_000_000, 3.14159_26535)
  • arrays - using JSON-like notation (e.g. [1, 2])
  • hashes - using JSON-like notation (e.g. { foo: 'bar' })
  • booleans - true and false
  • null - null
  • exponential - also known as scientific (e.g. 1.99E+3 or 1e-2)

Meta language attributes and operators:

Below you can find a list of all the meta language objects with supported triggers and operators you can use while configuring your Campaign in Open Loyalty.
Context object
Transaction
Internal event
Custom event
customer.firstName
customer.lastName
customer.email
customer.phone
customer.birthDate
customer.address.street
customer.address.address1
customer.address.address2
customer.address.city
customer.address.postal
customer.address.province
customer.address.country
customer.loyaltyCardNumber
customer.legalConsent
customer.marketingConsent
customer.dataProcessingConsent
customer.gender
customer.registeredDate
customer.level
customer.firstTransactionDate
customer.lastTransactionDate
customer.levelAchievementDate
customer.numberOfPurchases
customer.averagePurchaseAmount
customer.availablePoints
customer.usedPoints
customer.totalEarnedPoints
customer.lockedPoints
customer.blockedPoints
customer.expiredPoints
customer.labels
transaction.grossValue
transaction.documentNumber
transaction.purchasedAt
transaction.purchasePlace
transaction.shippingCity
transaction.sku(‘SKU123’).qty
transaction.sku(‘SKU123’).grossValue
transaction.category(‘shoes’).qty
transaction.category(‘shoes’).grossValue
transaction.maker(‘Nike’).qty
transaction.maker(‘Nike’).grossValue
transaction.itemLabel(‘SKU123’).qty
transaction.itemLabel(‘SKU123’).grossValue
transaction.itemLabel(‘SKU123’, ‘Value’).qty
transaction.itemLabel(‘SKU123’, ‘Value’).grossValue
transaction.itemLabels
transaction.labels
transaction.qty
transaction.channelId
event.body.sampleatributename
Arithmetic Operators:
+ (addition)
- (subtraction)
* (multiplication)
/ (division)
% (modulus)
** (pow)
Bitwise Operators
& (and)
| (or)
^ (xor)
Comparison Operators
== (equal)
=== (identical)
!= (not equal)
!== (not identical)
< (less than)
> (greater than)
<= (less than or equal to)
>= (greater than or equal to)
matches (regex match)
contains
starts with
ends with
Logical Operators
not or !
and or &&
or or ||
String Operators
~ (concatenation)
Array Operators
in (contain)
not in (does not contain)
Numeric Operators
.. (range)
Ternary Operators
foo ? 'yes' : 'no'
foo ?: 'no' (equal to foo ? foo : 'no')
foo ? 'yes' (equal to foo ? 'yes' : '') Custom Operators
to_date(string)
agg(array)
  • agg(array).count()
  • agg(array).sumBy(path)
  • agg(array).findOneByEq(path, value)
  • agg(array).findOneByEq(path, value)
  • agg(array).matchLabel(key, value)
round_down(value): int round_up(value): int ends_with(string, endsWith): bool lower(string): string starts_with(string, startsWith): bool day(date): string day_of_month(date): int month(date): string is_after(valueDate, afterDate): bool is_before(valueDate, beforeDate): bool is_between(valueDate, beforeDate, afterDate): bool is_not_between(valueDate, beforeDate, afterDate): bool is_time_between(valueDate, beforeDate, afterDate): bool timestamp(date): int

Expression Examples

Type
Example
Has label
{
"operator": "expression",
"data": "agg(transaction.labels).matchLabel('k1')"
}
{
"operator": "expression",
"data": "agg(customer.labels).matchLabel('k1', 'v1')"
}
Has item label
{
"operator": "expression",
"data": "transaction.itemLabel('k1').qty > 2"
}
Has item label with value
{
"operator": "expression",
"data": "transaction.itemLabel('k1', 'v1').qty > 2"
}
Sum by
{
"operator": "expression",
"data": "agg(transaction.items).sumBy('qty') > 2"
}
Transaction item by
{
"operator": "expression",
"data": "transaction.maker('Company').qty > 0
}
{
"operator": "expression",
"data": "transaction.category('C1').qty > 0
}
{
"operator": "expression",
"data": "transaction.sku('AB1122').qty > 0
}

Open Loyalty language usage

Excluding users from campaigns

There are pre-made conditions that let you target campaigns to a specific group of users - different tiers, members’ segments, or members with set custom attributes.
However, there is no predefined condition to exclude a group of users from the campaign. For example, you have a custom attribute called Debt, with two possible values set: true or false. Let it be that you want to set a campaign for all users, but not for those who are in debt with your app. The best way to do so is to create a condition using an expression. How to do it? To include a customer with a specific custom value, you would use an expression that looks like this: agg(customer.labels).matchLabel('debt', 'true') To exclude those users, you have to set the opposite of it, which you can accomplish by adding “!” at the beginning of it: !agg(customer.labels).matchLabel('debt', 'true')
This will allow you to create a campaign that affects all users except for those with the custom attribute Debt equal true.

Using Member Custom Attributes in the Campaign Condition Expression

In order to provide users with more flexibility in performing Campaign actions, it is possible to use a member's Custom Attributes as a condition in the Campaign. Depending on the value provided in the Custom Attributes we can also perform various operations on the stored data
These types of data are supported:
  • datetime, e.g. “2022-12-20T14:15:22+01:00”
  • number, e.g. “10.2”
  • string, e.g. “featured”
We can use it in the following scenarios:
  • In order to retrieve the given Custom Attribute use: e.g. agg(customer.labels).getFirstLabelValue('post_date') In this example, the function will return a value of the key “post_date”.
  • In order to parse the custom attribute to date use function to_date e.g. to_date(agg(customer.labels).getFirstLabelValue('post_date'))
  • In order to compare dates use timestamp(), e.g. timestamp(to_date(agg(customer.labels).getFirstLabelValue('post_date')))
  • To compare numerical values you don’t have to use any functions. Remember to use dot separator “.”, e.g. agg(customer.labels).getFirstLabelValue('posts_number') > 10
  • Give Effect for transaction in 5 days of given date:
    (timestamp(transaction.purchasedAt) - timestamp(to_date(agg(customer.labels).getFirstLabelValue('post_date')))) <= 432000

Campaigns based on passing time

One way of keeping the customers engaged with the loyalty program is to occasionally reward them for taking some actions. The way to do it in Open Loyalty is to use an expression timestamp, which allows you to measure how much time has passed between certain events.
For example, you want to reward a user for purchasing items in your store in the first week after registering.
To do so, you can create the following expression:
timestamp(transaction.purchasedAt) - timestamp(customer.registeredDate) <= 86400 * 7
The first part of the expression:
timestamp(transaction.purchasedAt) - timestamp(customer.registeredDate)
This means that you want to define the time passed between those two events: transaction and registration. In the second part of the expression, you define how much time passed in seconds. 86400 seconds is the number of seconds in a day, so <= 86400 * 7 means that less than 7 days passed between two events.

Birthday campaigns for members that registered on their birthday

Normally, birthday campaigns do not trigger if a member is registered on his birthday. There is a way to create such a campaign using the following expression in conditions:
customer.birthDate.format("d-m") === event.eventDate.format("d-m")
This way, a reward will be given to the members who registered on their birthday. To give rewards to other members on their birthdays, you still have to create a regular birthday campaign.
Creating a transaction based birthday campaign
Birthday campaigns are triggered only on the customer birthday- no additional triggers are needed or possible to add.
However, we might want to reward the users for activities at their birthday. Using the similar expression to the previous one, we can say:
customer.birthDate.format("d-m") === transaction.purchasedAt.format("d-m")
This way, a reward will be given to the members who made any transaction at their birthday, and we can always follow up with another conditions.

Creating a complex campaign effects

We want to set the the granted points to twice the amount member spent in transaction that triggered the campaign. We also want to set a point limit for transaction to 100 - we want to avoid the situation when the member spends a lot in one transactions, and gets more points than he can spend for the rewards. We can use Open Loyalty language, and set following effect:
(transaction.grossValue * 2 >=100) ? 100 : transaction.grossValue * 2
Which means that if the transaction value multiplied by two is smaller or equal 100, than user will get the multiplied value of points, if it is bigger - user will always get 100 points. This way, we can create a campaign that is triggered by all transactions, but all transactions above the 50 value will result in 100 points given to the user.