Expressions
In this section, you will learn about Open Loyalty language and more complex campaign conditions.
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.activePoints | |||
customer.usedPoints | |||
customer.totalEarnedPoints | |||
customer.lockedPoints | |||
customer.blockedPoints | |||
customer.expiredPoints | |||
customer.labels | |||
event.body.sampleatributename | |||
**event.body.progressStatuses[0].currentPeriodValue | |||
**event.body.progressStatuses[0].periodGoal | |||
**event.body.progressStatuses[0].consecutivePeriods | |||
**event.body.progressStatuses[0].completedConsecutivePeriods | |||
**event.body.progressStatuses[0].progressChanges | |||
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 |
In the referral campaigns, customer context refers to the referee.
If you want to aim the referrer, use refferer context, e.g.
referrer.labels, referrer.lastTransactionDate
** The objects of expressions are available only in the Achievement progressed option in the Internal Event Campaign.
event.body.progressStatuses[0] - The number [0] in the object refers to the first rule in the achievement.
Operators
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 | |
Has item label | |
Has item label with value | |
Sum by | |
Transaction item by | |
Achievement progressed |
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).getLabelValue('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).getLabelValue('post_date'))
In order to compare dates use timestamp(), e.g. timestamp(to_date(agg(customer.labels).getLabelValue('post_date')))
To compare numerical values you don’t have to use any functions. Remember to use dot separator “.”, e.g. agg(customer.labels).getLabelValue('posts_number') > 10
Give Effect for transaction in 5 days of given date:
(timestamp(transaction.purchasedAt) - timestamp(to_date(agg(customer.labels).getLabelValue('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.
Last updated
