.png%3Falt%3Dmedia%26token%3D344bedb3-cf12-4242-a985-b63b1d676eb7)
.png%3Falt%3Dmedia%26token%3D344bedb3-cf12-4242-a985-b63b1d676eb7)
Expressions
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.
- 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)
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
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 } |
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.
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
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.
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.
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 modified 10d ago