Available Marigold Engage functions

Note: In order to manually use the functions mentioned in this topic within the Engage UI, they should be encapsulated in [% %].
For example : [%requestValue('FIELDNAME')%]
This notation is referred to as a usable Engage 'expression'.
More info about the usage of expressions can be found here.

 

In this topic:

• String operations : len - find - findoneof - reversefind - replace - reverse - trim - left - mid - right - upper - lower - proper - concat - explode - tostring - toint - todecimal - getprop

• Math functions : abs - average - mul - div - add - sub - round - mod - formatnumber

• Date functions : add+datetype - subtract+datetype - year - quarter - month - day - hour - minute - second - dayofyear - dayofweek - days - hours - minutes - seconds - sysdate - curdate - currentunixtimestamp - todatetime - tounixtimestamp - format

• Logical functions : eq - ne - lt - gt - le - ge - between - and / all - or / any - not - isempty - isnotempty - contains - containstag - startswith - endswith - isdate - tobool - notcontains - regex - chkmail / ismail - isnumeric - InWebContext()

• Array functions : union - intersect - distinct - join

• Other functions : propcount - matchcount - if - itemValue - cartValue - journeyLookupValue - mobileValue - translateValue - translateMobileValue - requestValue - listValue - profileValue - componentValue - eventValue - jsonValue - loadValue - urlencode - urldecode - convertphonenumber - hash - generatepwd - guid - striphtml - encode (base64) - decode (base64) - link - linkid - journey - position - count

• Addendum : Grid support

 

String operations

len

• Format: len(string str)
• Usage: Returns the length of the specified string.
• Parameter: str (string): string from which the length must be returned
• Return value: Integer: length of the string

Example:
Function:     len([MASTER.NAME]) / len('parana')
Output: 6

 

find

• Format: find(string haystack, string needle)
• Usage: Searches haystack for the first occurrence of needle. This is case sensitive.
• Parameters:
  • haystack (string): string to be searched
  • needle (string): string to find
• Return value: Integer: If needle found: offset of needle in haystack. If needle not found: -1.

Examples:
Function:     find([MASTER.NAME], 'e')
Output: 5

Function:     find('parana', 'a')
Output: 1

 

findoneof

• Format: findoneof(string needles, string haystack)
• Usage: Searches haystack for the first occurrence of any character contained in needles
• Parameters:
  • Needles (string): character to search for
  • Haystack (string): string to be searched
• Return value: Integer: If one of the characters from the needles is found : offset of the first character found in the  haystack. If none are found: -1.

Examples:
Function: findoneof ('ae', 'I love cats')
Output:     5
(starting from position 0, the e is the first character found, on position 5)

Function: findoneof (',','I love them, those cats')
Output: 11
(starting from position 0, the comma is found on position 11)

Function: findoneof ('b','I love cats')
Output: -1
(the b is not found in the haystack)

 

reversefind

• Format:reversefind(string haystack, string needle)
• Usage: Searches haystack for the last occurrence of needle
• Parameters:
  • needle (string): character to search for
  • haystack (string): string to be searched
• Return value: Integer: If one of the characters from needles found: last offset of character in haystack. If none found: -1.

Example:
Function: reversefind('I love cats', 'a')
Output: 8

 

replace

• Format: replace(string haystack, string originalNeedle, string newNeedle)
• Usage: Searches haystack for the every occurrence of originalNeedle, and replaces them with newNeedle.
• Parameters:
  • haystack (string): string to be searched
  • originalNeedle (string): substring that should be replaced by another one
  • newNeedle (string): String that is used to replace any occurrence of originalNeedle
• Return value: string: returns the modified haystack string

Example:
Function: replace( 'I love cats', 'cats', 'dogs')
Output: I love dogs

 

reverse

• Format: reverse(string str)
• Usage: Returns the reverse of a string value.
• Parameter: str (string): string to be reversed
• Return value: string: returns the reverse string

Example:
Function: reverse('I love cats')
Output: stac evol I

 

trim

• Format: trim(string str)
• Usage: Trims spaces, newlines and tabs from both ends of str.
• Parameter: str (string): string to be trimmed
• Return value: string: returns the trimmed string

Example:
Function: trim('             abc         ')
Output: abc

 

left

• Format: left(string str; integer count)
• Usage: Returns the first count characters from str.
• Parameters:
  • str (string): source string
  • count (integer): Number of characters to select, starting from the most left character
• Return value: string: returns the left part from str

Example:
Function: left('I love cats',5)
Output: I lov

 

mid

• Format: mid(string str; integer offset, integer count)
• Usage: count characters from the middle of str, starting at offset.
• Parameters:
  • str (string): source string
  • offset (integer): starting offset
  • count (integer): Number of characters to select, starting from the offset
• Return value: string: returns the mid part from str

Example:
Function: mid('I love cats',2,4)
Output: love

 

right

• Format: right(string str, integer count)
• Usage: Returns the last count characters from str.
• Parameters:
  • str (string): source string
  • count (integer): Number of characters to select from the end of str
• Return value: string: returns the right part from str

Example:
Function: right('I love cats',4)
Output: cats

 

upper

• Format: upper(string str)
• Usage: Returns str, with all characters converted to uppercase.
• Parameter: str (string): source string
• Return value: string: returns the uppercased str

Example:
Function: upper('I love cats')
Output: I LOVE CATS

 

lower

• Format: lower(string str)
• Usage: Returns str, with all characters converted to lowercase.
• Parameter: str (string): source string
• Return value: string: returns the lowercased str

Example:
Function: lower('I love cats')
Output: i love cats

 

proper

• Format: proper(string str)
• Usage: str, with every first character of every contained word converted to uppercase.
• Parameter: str (string): source string
• Return value: string: returns the converted str

Example:
Function: proper('I love cats')
Output: I Love Cats

 

concat

• Format: concat(string str1, string str2, string strn)
• Usage: Concatenates the strings.
• Parameters:
  • str1 (string): First string
  • str2 (string): Second string
  • strn (string): Nth string
• Return value: string: returns the concatenated string

Example:
Function: concat('I', ' Love ', 'Cats')
Output: I Love Cats

 

explode

• Format: explode(string haystack, string needle)
• Usage: convert a string to an array by splitting up on needle
• Parameters:
  • haystack (string): string to be split up
  • needle (string): string to split the string up by
• Return value: array: a multivalue list containing the elements of the split up haystack

Example:
Function: explode('a+b+c+d+e', '+')
Output: ['a', 'b', 'c', 'd', 'e']

Note: The output will not be shown in the message preview in Marigold Engage, as it's an array. You can for example add an extra function around it like join in order to view output in the message preview :  join(explode('a+b+c+d+e', '+'),'-') will result in a-b-c-d-e

 

tostring

• Format: tostring(variant value)
• Usage: converts the value to a string
• Parameter: value to be converted
• Return value: a string

Example:
Function: tostring(123)
Output: 123

 

toint

• Format: toint(string text)
• Usage: Convert a string to a (truncated) integer value. Only numeric values up to the first separator are included in the output result. When the string starts with other than numeric values, the output result is 0.
• Parameter: string to be converted
• Return value: the integer representation of the string value

Examples:
Function: toint ('123.678')
Output: 123

Function: toint ('-123.678')
Output: -123

Function: toint ('2022 is the current year')
Output: 2022

Function: toint ('16-10-1981')
Output: 16

Function: toint ('text')
Output: 0

Note: Instead of using a string value, a decimal (without quotes) also can be used.

In that case, the resulting integer is the rounded value of the decimal.

For example : toint(123.789) returns 124.

 

todecimal

• Format: todecimal(variant value)
• Usage: convert the value to its decimal value
• Parameter: value to be converted
• Return value: the decimal representation of the value, with 2 decimal digits (.00), rounded

Examples:
Function: todecimal('123')
Output: 123.00

Function: todecimal('123.3456')
Output: 123.35

Function: todecimal(123.3456)
Output: 123.35

Note: Any data type can be used as value (integer, string, etc).

Keep in mind that using a nonsensical value (such as a date) results in a decimal representation that doesn't make sense.

 

getprop

• Format: getprop(str, idx, sep)
• Usage: Automatically escapes single quotes and removes parentheses from the variable to be used in JavaScript.
• Parameters:
  • str : string containing the properties
  • idx : 1-based property index
  • sep (optional) : string containing accepted separators
• Return value: string

Example:
Function:     getprop('Barcelona; Brussels; New York',3,';')
Output:     New York

 

Math functions

abs

• Format: abs(integer number)
• Usage: number, without sign (basically converts negative numbers to positive ones = the ‘absolute’ values)
• Parameter: Number (integer): Number to convert
• Return value: integer: returns the converted number

Examples:
Function:     abs(5)
Output:     5

Function:     abs(-5)

Output:     5

 

average

• Format: average(number_1, number_2, …., number_n)
• Usage: returns the average of the provided numbers
• Parameters: (all numeric types are accepted as input values, including integer, float, decimal, …)
  • number_1
  • number_2
  • ...
  • up to number_n
• Return value: integer: returns the calculated number (truncated)

Examples:
Function:     average(1,2,3,4,5)
Output:     3

Function:     average(2.25,4.83,60.88)

Output:     22

 

mul

• Format: mul(integer number_1, integer number_2)
• Usage: Returns the integer result of multiplying number_1 with number_2
• Parameters: numbers to multiply
  • number_1 (integer)
  • number_2 (integer)
• Return value: integer

Example:
Function:     mul(8,4)
Output:     32

 

div

• Format: div(integer nominator, integer denominator)
• Usage: Returns the integer result of the division of nominator with denominator
• Parameters: numbers to divide
  • nominator (integer)
  • denominator (integer)
• Return value: integer

Example:
Function:  div(6, 2)
Output: 3

 

add

• Format: add(integer number_1, integer number_2)
• Usage: Returns the integer result of adding number_1 with number_2
• Parameters: numbers to add up
  • number_1 (integer)
  • number_2 (integer)
• Return value: integer

Example:
Function:     add(12, 34)
Output:     46

 

sub

• Format: sub(integer number_1, integer number_2)
• Usage: Returns the integer result of subtracting number_2 from number_1
• Parameters: numbers to subtract
  • number_1 (integer)
  • number_2 (integer)
• Return value: integer

Example:
Function:     sub(34, 12)
Output:     22

 

round

• Format: round(decimal number, int digits)
• Usage: rounds the float number to the specified number of digits
• Parameters:
  • Number (decimal): number to convert
  • Digits (int): number of digits
• Return value: string: returns the rounded number

Examples:
Function:     round(1.23456,3)
Output:     1.235

Function:     round(1.23456, 1)

Output:     1.2

 

mod

• Format: mod(integer number_1, integer number_2)
• Usage: calculates the remainder on a division of number_1 by number_2
• Parameters:
  • Number_1 (integer): divided number
  • Number_2 (integer): divider
• Return value: int: the remaining number

Examples:
Function:     mod(3, 2)
Output:     1

Function:     mod(12, 8)
Output:     4

 

formatnumber

• Format: formatnumber(decimal value, string format)
• Usage: formats a given number with the specified format
• Parameters:
  • value (decimal): The number to format
  • format (string): The format to use
• Return value: string: The formatted number

Examples:
Function:     formatnumber(1234567.1234, '0,0.00')
Output:     1,234,567.12

Function:     formatnumber(todecimal(1000), '#,000.00')
Output:     1,000.00

Function:     formatnumber(todecimal(1000), '#000.00')
Output:     1000.00

Note: A comma is used as a thousands separator, while a dot is used for decimals.
- If a comma is present in the format string, it's used as thousands separator. Otherwise, no thousands separator is used.
- If a dot is present in the format string, then the number of tokens following the dot are the amount of decimals that will be rendered.

 

Date functions

add+datetype

• Format:
  • addyears(datetime date, integer amount)
  • addquarters(datetime date, integer amount)
  • addmonths(datetime date, integer amount)
  • addweeks(datetime date, integer amount)
  • adddays(datetime date, integer amount)
  • addhours(datetime date, integer amount)
  • addminutes(datetime date, integer amount)
  • addseconds(datetime date, integer amount)
• Usage: Returns date, added with an amount of years, months, days,… depending on the selected function.
• Parameters:
  • date (datetime): date to add to
  • amount (integer): amount in years, months, days, hours, minutes or seconds to add
• Return value: Datetime: Returns the resulting datetime value

Examples:
Function:     adddays(todatetime('2009-09-24','yyyy-MM-dd'), 4)
Output:     2009-09-28 00:00:00

Function:     adddays(todatetime('2009-09-24','yyyy-MM-dd'), -4)
Output:     2009-09-20 00:00:00

 

subtract+datetype

• Format:
  • subtractyears(datetime date, integer amount)
  • subtractquarters(datetime date, integer amount)
  • subtractmonths(datetime date, integer amount)
  • subtractweeks(datetime date, integer amount)
  • subtractdays(datetime date, integer amount)
  • subtracthours(datetime date, integer amount)
  • subtractminutes(datetime date, integer amount)
  • subtractseconds(datetime date, integer amount)
• Usage: Returns date, subtracted with an amount of years, months, … depending on the selected function.
• Parameters:
  • date (datetime): date to subtract from
  • amount (integer): amount in years, months, days, hours, minutes, seconds to subtract
• Return value: Datetime: Returns the resulting datetime value

Examples:
Function:     subtractdays(todatetime('2019-10-19','yyyy-MM-dd'), 6)
Output:     2019-10-13 00:00:00

Function:     subtractdays(todatetime('2019-10-19','yyyy-MM-dd'), -6)
Output:     2019-10-25 00:00:00

 

year

• Format: year (datetime dt)
• Usage: returns the year of a specific date/time.
• Parameter: dt (datetime)

Example:
Function:     year(todatetime('1981-07-12','yyyy-MM-dd'))
Output:     1981

 

quarter

• Format: quarter (datetime dt)
• Usage: returns the quarter of a specific date/time.
• Parameter: dt (datetime)

Example:
Function:     quarter(todatetime('1981-07-12','yyyy-MM-dd'))
Output:     3

 

month

• Format: month (datetime dt)
• Usage: returns the month of a specific date/time.
• Parameter: dt(datetime)

Example:
Function:     month(todatetime('1981-07-12','yyyy-MM-dd'))
Output:     7

 

day

• Format: day (datetime dt)
• Usage: returns the day of a specific date/time.
• Parameter: dt(datetime)

Example:
Function:     day(todatetime('1981-07-12','yyyy-MM-dd'))
Output:     12

 

hour

• Format: hour (datetime dt)
• Usage: returns the hour of a specific date/time.
• Parameter: dt (datetime)

Example:
Function:     hour(todatetime('1981-07-12 11:22:56','yyyy-MM-dd hh:mm:ss'))
Output:     11

 

minute

• Format: minute (datetime dt)
• Usage: returns the minutes of a specific date/time.
• Parameter: dt (datetime)

Example:
Function:     minute(todatetime('1981-07-12 12:34:56','yyyy-MM-dd hh:mm:ss'))
Output:     34

 

second

• Format: second (datetime dt)
• Usage: returns the seconds of a specific date/time.
• Parameter: dt (datetime)

Example:
Function:     second(todatetime('1981-07-12 12:34:56','yyyy-MM-dd hh:mm:ss'))
Output:     56

 

dayofyear

• Format: dayofyear (datetime dt)
• Usage: returns the day of the year for a specific date/time.
• Parameter: dt (datetime)

Example:
Function:     dayofyear(todatetime('1981-07-12','yyyy-MM-dd'))
Output:     193

 

dayofweek

• Format: dayofweek (datetime dt)
• Usage: Returns the day of the week of the specified datetime, with Sunday as first day of week.
• Parameter: dt (datetime)
• Return value: integer

Example:
Function:     dayofweek(todatetime('1981-07-14','yyyy-MM-dd'))
Output:     3

 

days

• Format: days (datetime dt1, datetime dt2)
• Usage: returns the difference in days between two date times.
• Parameters:
  • dt1 (datetime)
  • dt2 (datetime)

Examples:
Function: days(todatetime('2018-01-12','yyyy-MM-dd'),todatetime('2018-01-20','yyyy-MM-dd'))
Output:     -8
Negative output value in case dt1 is an earlier datetime than dt2

Function: days(todatetime('2018-01-20','yyyy-MM-dd'),todatetime('2018-01-12','yyyy-MM-dd'))
Output:     8
Positive output value in case dt1 is a later datetime than dt2

 

hours

• Format: hours (datetime dt1, datetime dt2)
• Usage: returns the difference in hours between two date times.
• Parameters:
  • dt1 (datetime)
  • dt2 (datetime)

Examples:
Function:     hours(todatetime('2009-01-12','yyyy-MM-dd'),todatetime('2009-01-13','yyyy-MM-dd'))
Output:     -24
Negative output value in case dt1 is an earlier datetime than dt2

Function:     hours(todatetime('2009-01-13','yyyy-MM-dd'),todatetime('2009-01-12','yyyy-MM-dd'))
Output:     24
Positive output value in case dt1 is a later datetime than dt2

 

minutes

• Format: minutes (datetime dt1, datetime dt2)
• Usage: returns the difference in minutes between two date times.
• Parameters:
  • dt1 (datetime)
  • dt2 (datetime)

Examples:
Function:     minutes(todatetime('2009-01-12 00:00:00','yyyy-MM-dd hh:mm:ss'),todatetime('2009-01-13 00:00:00','yyyy-MM-dd hh:mm:ss'))
Output:     -1440
Negative output value in case dt1 is an earlier datetime than dt2

Function:     minutes(todatetime('2009-01-13 00:00:00','yyyy-MM-dd hh:mm:ss'),todatetime('2009-01-12 00:00:00','yyyy-MM-dd hh:mm:ss'))
Output:     1440
Positive output value in case dt1 is a later datetime than dt2

 

seconds

• Format: seconds (datetime dt1,datetime dt2)
• Usage: returns the difference in seconds between two date times.
• Parameters:
  • dt1 (datetime)
  • dt2 (datetime)

Examples:
Function:     seconds(todatetime('2009-01-12 00:00:00','yyyy-MM-dd hh:mm:ss'),todatetime('2009-01-13 00:00:00','yyyy-MM-dd hh:mm:ss'))
Output:     -86400
Negative output value in case dt1 is an earlier datetime than dt2

Function:     seconds(todatetime('2009-01-13 00:00:00','yyyy-MM-dd hh:mm:ss'),todatetime('2009-01-12 00:00:00','yyyy-MM-dd hh:mm:ss'))
Output:     86400
Positive output value in case dt1 is a later datetime than dt2

 

sysdate

• Format: sysdate()
• Usage: Returns the current system datetime (= platform timezone)
• Parameter: none
• Return value: datetime: Returns the current system datetime (= platform timezone)

Example:
The current UTC datetime is September 24^th 2023 at 1PM, while my machine is in UTC+1 timezone (September 24^th 2023 at 2PM).

Function:    sysdate()
Output:     2023-09-24 14:00:00

 

curdate

• Format: curdate()
• Usage: Returns the current UTC datetime
• Parameter: none
• Return value: datetime: Returns the current UTC datetime

Example: The current UTC datetime is September 24^th 2023 at 1PM, while my machine is in UTC+1 timezone (September 24^th 2023 at 2PM).

Function:    curdate()
Output:     2023-09-24 13:00:00

 

currentunixtimestamp

• Format: currentunixtimestamp()
• Usage: retrieves the unix timestamp in milliseconds
• Parameter: none
• Return value: datetime

Example:
Function:     currentunixtimestamp()
Output:     1476177429.89314

 

todatetime

• Format: todatetime(string value)
• Usage: converts the value to a datetime.
• Parameter: value (string): value to convert
• Return value: A datetime

 

tounixtimestamp

• Format: tounixtimestamp(date)
• Usage: converts a date to UNIX timestamp in seconds
• Parameter: date (datetime): date to be converted
• Return value: datetime: returns a UNIX timestamp for a specific date/time.

Example:
Function:     tounixtimestamp(todatetime('1981-07-12 13:34:56','yyyy-MM-dd HH:mm:ss'))
Output:     363792896

 

format

• Format: format(datetime date, constant format)
• Usage: Returns a string representation of the specified date in the supplied format.
• Parameters:
  • Date (datetime): date to convert to string
  • Format (constant) :

d	The day of the month, from 1 through 31.
dd	The day of the month, from 01 through 31.
ddd	The abbreviated name of the day of the week.
dddd	The full name of the day of the week.
G	The period or era.
h	The hour, using a 12-hour clock from 1 to 12.
hh	The hour, using a 12-hour clock from 01 to 12.
HH	The hour, using a 24-hour clock from 00 to 23.
mm	The minute, from 00 through 59.
M	The month, from 1 through 12.
MM	The month, from 01 through 12.
MMM	The abbreviated name of the month.
MMMM	The full name of the month.
ss	The second, from 00 through 59.
tt	The AM/PM designator.
T	The time (hours, minutes, seconds) in AM/PM format.
yy	The year, from 00 to 99.
yyyy	The year as a four-digit number.

• Return value: string: Returns the formatted string

Example:
On January 11^th 2023 at 10:29 AM :

Function:     format(sysdate(), 'dddd MMMM d yyyy T')
Output:     Wednesday January 11 2023 10:29:05 AM

 

Logical functions

Note:
Logical functions return boolean values ('true' or 'false').
They should not be used to display the outcome directly.

Logical functions are useful in the following context :

1. in an IF expression
Example :  [% if(isnumeric([MASTER.cardid]), 'Your card id is correct', 'Your card id is incorrect. It should be a numeric value.')) %]
=> If the card id value is numeric, the first message is displayed. If not, the second message is shown.

2. in a visibility constraint
Example : <sg:content expression="all(eq(tobool([VARIABLE.Loyal]),tobool('true')))">
=> The text content is only visible when the boolean variable Loyal is set to true.

3. in an expression in a Split component.

All examples used below are within an 'IF' expression.

 

eq

• Format: eq(variant var1, variant var2)
• Usage: Compare 2 variables of the same type. Use the appropriate conversion-function on each variable that is not of type string.
• Parameters:
  • var1 (variant): value to be compared with var2
  • var2 (variant): value to be compared with var1
• Return value: boolean: true if both variables are equal

Examples:
Function:     if(eq('A', 'A'), 'equal', 'not equal')
Output:     equal

Function:     if(eq([MASTER.COUNTRYCODE], 'ES'), 'Spain', 'Other country')
=> For a contact in the Audience List with countrycode field value equal to ES :
Output:     Spain
=> For a contact in the Audience List with countrycode field value equal to NL :
Output:     Other country

Function:     if(eq(tobool([VARIABLE.isVisible]), tobool('TRUE')) , 'The item is visible', 'The item is not visible')
For example, a variable is used in an email message to define if a component should be shown or hidden.
=> If the variable is set to true :
Output:     The item is visible
=> If the variable is set to false :
Output:     The item is not visible

 

ne

• Format: ne(variant var1, variant var2)
• Usage: Compare 2 variables of the same type. Use the appropriate conversion-function on each variable that is not of type string.
• Parameters:
  • var1 (variant): value to be compared with var2
  • var2 (variant): value to be compared with var1
• Return value: boolean: true if both variables are not equal

Examples:
Function:     if(ne('A', 'A'), 'Not equal comparison is true', 'Not equal comparison is false')
Output:     Not equal comparison is false

Function:     if(ne([MASTER.COUNTRYCODE], 'ES'), 'Other country', 'Spain')
=> For a contact in the Audience List with countrycode field value equal to NL :
Output:     Other country
=> For a contact in the Audience List with countrycode field value equal to ES :
Output:     Spain

Function:     if(ne(tobool([VARIABLE.isVisible]), tobool('TRUE')) , 'The item is visible', 'The item is not visible')
For example, a variable is used in an email message to define if a component should be shown or hidden.
=> If the variable is set to true :
Output:     The item is not visible
=> If the variable is set to false :
Output:     The item is visible

 

lt

• Format: lt(variant var1, variant var2)
• Usage: checks if var1 is less than var2
• Parameters:
  • var1 (variant): value to be compared with var2
  • var2 (variant): value to be compared with var1
• Return value: boolean: true if var1 is less than var2

Example:
Function:     if(lt(1, 5), '1 is lower than 5', '1 is not lower than 5')
Output:     1 is lower than 5

 

gt

• Format: gt(variant var1, variant var2)
• Usage: checks if var1 is greater than var2
• Parameters:
  • var1 (variant): value to be compared with var2
  • var2 (variant): value to be compared with var1
• Return value: boolean: true if var1 is greater than var2

Example:
Function:     if(gt(1, 5), '1 is greater than 5', '1 is not greater than 5')
Output:     1 is not greater than 5

 

le

• Format: le(variant var1, variant var2)
• Usage: checks if var1 is less than or equal to var2
• Parameters:
  • var1 (variant): value to be compared with var2
  • var2 (variant): value to be compared with var1
• Return value: boolean: true if var1 is less than or equal to var2

Examples:
Function:     if(le(1, 5), '1 is less than or equal to 5', '1 is not less than or equal to 5')
Output:     1 is less than or equal to 5

Function:     if(le(2, 2), '2 is less than or equal to 2', '2 is not less than or equal to 2')
Output:     2 is less than or equal to 2

 

ge

• Format: ge(variant var1, variant var2)
• Usage: checks if var1 is greater than or equal to var2
• Parameters:
  • var1 (variant): value to be compared with var2
  • var2 (variant): value to be compared with var1
• Return value: boolean: true if var1 is greater than var2

Example:
Function:     if(ge(1, 5), '1 is greater than or equal to 5', '1 is not greater than or equal to 5')
Output:     1 is not greater than or equal to 5

Function:     if(ge(2, 2), '2 is greater than or equal to 2', '2 is not greater than or equal to 2')
Output:     2 is greater than or equal to 2

 

between

• Format: between(variant value, variant minValue, variant maxValue)
• Usage: checks if value is between minValue and maxValue (numeric, date or datetime)
• Parameters:
  • value (variant): value to be compared with minValue and maxValue
  • minValue (variant): the minimum value
  • maxValue (variant): the maximum value
• Return value: boolean: true if value is between minValue and maxValue

Examples:
Function:     if(between(1, 5, 8), '1 is between 5 and 8', '1 is not between 5 and 8')
Output:     1 is not between 5 and 8

Function:     if(between(5, 5, 8), '5 is between 5 and 8', '5 is not between 5 and 8')
Output:     5 is not between 5 and 8

Function:     if(between(6, 5, 8), '6 is between 5 and 8', '6 is not between 5 and 8')
Output:     6 is between 5 and 8

Function: if(between([MASTER.ID], toint('10'), toint('16')), 'MASTER.ID is between 10 and 16', 'MASTER.ID is NOT between 10 and 16')
=> when MASTER.ID is equal to 6 :
Output: MASTER.ID is NOT between 10 and 16'
=> when MASTER.ID is equal to 12 :
Output: MASTER.ID is between 10 and 16'

Function: if(between([MASTER.BIRTHDAY], todatetime('2018-03-01 00:00:00','yyyy-MM-dd HH:mm:ss'), todatetime('2018-06-01 00:00:00','yyyy-MM-dd HH:mm:ss')), 'Birth date is between the 1st of March 2018 and the 1st of June 2018', 'Birth date is NOT between the 1st of March 2018 and the 1st of June 2018')
=> when MASTER.BIRTHDAY is equal to 2018-05-22 :
Output: Birth date is between the 1st of March 2018 and the 1st of June 2018
=> when MASTER.BIRTHDAY is equal to 2008-05-22 :
Output: Birth date is NOT between the 1st of March 2018 and the 1st of June 2018

 

and / all

• Format:
  • and(boolean bool1, boolean bool2)
  • all(boolean bool1, boolean bool2)
• Usage: checks if both bool1 and bool2 are applicable
• Parameters:
  • bool1 (boolean): first boolean to be evaluated
  • bool2 (boolean): second boolean to be evaluated
• Return value: boolean: true if both bool1 and bool2 evaluate “true”

Examples:
For a contact from the Audience List with gender equal to male (‘m’) :

Function:     if(and(eq(1,5), eq([MASTER.GENDER], 'm')), '1 is equal to 5 AND gender is equal to male', 'one or both values are not equal')
Output:     one or both values are not equal

Function:     if(and(eq(5,5), eq([MASTER.GENDER], 'm')), '5 is equal to 5 AND gender is equal to male', 'one or both values are not equal')
Output:     5 is equal to 5 and gender is equal to male

Function:     if(all(eq(1,5), eq([MASTER.GENDER], 'm')), '1 is equal to 5 AND gender is equal to male', 'one or both values are not equal')
Output:     one or both values are not equal

Function:     if(all(eq(5,5), eq([MASTER.GENDER], 'm')), '5 is equal to 5 AND gender is equal to male', 'one or both values are not equal')
Output:     5 is equal to 5 and gender is equal to male

 

or / any

• Format:
  • or(boolean bool1, boolean bool2)
  • any(boolean bool1, boolean bool2)
• Usage: checks if at least one of bool1 or bool2 is applicable
• Parameters:
  • bool1 (boolean): first boolean to be evaluated
  • bool2 (boolean): second boolean to be evaluated
• Return value: boolean: true if bool1 or bool2 evaluates “true”

Examples:
For a contact from the Audience List with gender equal to male (‘m’) :

Function:     if(or(eq(1,5), eq([MASTER.GENDER], 'f')), '1 is equal to 5 OR gender is equal to female', 'both comparisons have different values')
Output:     both comparisons have different values

Function:     if(or(eq(1,5), eq([MASTER.GENDER], 'm')), '1 is equal to 5 OR gender is equal to male', 'both comparisons have different values')
Output:     1 is equal to 5 OR gender is equal to male

Function:     if(any(eq(5,5), eq([MASTER.GENDER], 'f')), '5 is equal to 5 OR gender is equal to female', 'both comparisons have different values')
Output:     5 is equal to 5 OR gender is equal to female

Function:     if(any(eq(5,5), eq([MASTER.GENDER], 'm')), '5 is equal to 5 OR gender is equal to male', 'both comparisons have different values')
Output:     5 is equal to 5 OR gender is equal to female

 

not

• Format: not(boolean bool1)
• Usage: inverts the result from the evaluation of bool1
• Parameter: bool1 (boolean): boolean to be evaluated
• Return value: boolean: true if bool1 evaluates “false”, false if bool1 evaluates “true”.

Example:
Function:     if(not(eq(5,5)), 'The eq comparison is true (values equal). The inverted resulted is thus false.', 'The eq comparison is false (values not equal). The inverted resulted is thus true.')
Output:     The eq comparison is true (values equal). The inverted resulted is thus false.

 

isempty

• Format: isempty(variant value)
• Usage: checks if value is empty
• Parameter: value (variant): value to be checked
• Return value: boolean: true if value is empty

Examples:
Function:     if(isempty([MASTER.BOUNCEDT]), 'No bounce date/time.', 'There's a bounce date/time.')
=> when the MASTER.BOUNCEDT field doesn't contain a value :
Output:     No bounce date/time.

Function:     if(isempty([MASTER.NAME]), 'No name set.', 'There's a name in the field.')
=> when the MASTER.NAME field contains a value :
Output:     There's a name in the field.

 

isnotempty

• Format: isnotempty(variant value)
• Usage: checks if value is not empty
• Parameter: value (variant): value to be checked
• Return value: boolean: true if value is not empty

Examples:
Function:     if(isnotempty([MASTER.BOUNCEDT]), 'There's a bounce date/time.', 'No bounce date/time.')
=> when the MASTER.BOUNCEDT field doesn't contain a value :
Output:     No bounce date/time.

Function:     if(isnotempty([MASTER.NAME]), 'There's a name in the field.', 'No name set.')
=> when the MASTER.NAME field contains a value :
Output:     There's a name in the field.

 

contains

• Format: contains(string haystack, string needle)
• Usage: text search within a string (appears somewhere inside the string)
• Parameters:
  • haystack (string): string to perform the search in
  • needle (string): text to search for
• Return value: string: returns true if the needle is found

Examples:
Function: if(contains('CAT,Frog,doggybag,hotdog','dog'), 'dog can be found somewhere inside the string', 'no dog found')
Output:     dog can be found somewhere inside the string
(even multiple times in this example 'CAT,Frog,doggybag,hotdog')

Function: if(contains('CAT,Frog,doggybag,hotdog','bird'), 'bird can be found somewhere inside the string', 'no bird found')
Output:     no bird found

 

notcontains

• Format: notcontains(p1, val)
• Usage: determines whether a string does not contain a particular string
• Parameters:
  • p1 : string/field to search in
  • val : value to search for
• Return value: boolean: true or false

Example:
Function: if(notcontains([MASTER.POSTAL_CODE], '1000'), 'The postal code does NOT contain the value 1000', 'The postal code contains the value 1000')

=> when MASTER.POSTAL_CODE is equal to 3600:
Output: The postal code does NOT contain the value 1000

=> when MASTER.POSTAL_CODE is equal to 1000:
Output: The postal code contains the value 1000

=> when MASTER.POSTAL_CODE is equal to 10002:
Output: The postal code contains the value 1000

=> when MASTER.POSTAL_CODE is equal to 21000:
Output: The postal code contains the value 1000

 

containstag

• Format: containstag(string haystack, string needle)
• Usage: Search for a specific string within a string of separate values. The ‘string of values’ is split into separate items by separators (a separator can be : comma, pipe or semicolon). The search is performed on each individual item.
• Parameters:
  • haystack (string): string to perform the search in
  • needle (string): string to search for
• Return value: string: returns true if the needle is found

Examples:
Function:  if(containstag('CAT,DOG,Frog,doggybag,hotdog','dog'), 'dog can be found as value', 'no dog found')
Output:      dog can be found as value
(In this example, the string values are split by commas. Note that only ‘dog’ matches the search, as ‘doggybag’ and ‘hotdog’ are different values, and thus do not match the searched needle.)

Function: if(containstag('CAT,doggy,bird','dog'), 'dog can be found as value', 'no dog found')
Output:     no dog found (as neither ‘cat’, ‘doggy’ or ‘bird’ match the searched string ‘dog’)

 

startswith

• Format: startswith(p1, val)
• Usage: determines whether a string starts with the characters of a particular string
• Parameters:
  • p1 : string/field to search in
  • val : value to search for
• Return value: boolean: true or false

Example:
Function: if(startswith([MASTER.NAME], 'Jo'), 'The name field value starts with JO', 'The name field value starts with other chars')
=> When the MASTER.NAME field value is equal to 'Jochen':
Output: The name field value starts with JO
=> When the MASTER.NAME field value is equal to 'Peggy':
Output: The name field value starts with other chars

 

endswith

• Format: endswith(p1, val)
• Usage: determines whether a string ends with the characters of a particular string
• Parameters:
  • p1 : string/field to search in
  • val : value to search for
• Return value: boolean: true or false

Example:
Function: if(endswith([PREFERENCES.INTERESTS], 'fashion'), 'The interests value ends with FASHION', 'The interests value ends with another value')
=> When the PREFERENCES.INTERESTS field value is equal to 'Women's Fashion':
Output: The interests value ends with FASHION
=> When the PREFERENCES.INTERESTS field value is equal to 'Clothing':
Output: The interests value ends with another value

 

isdate

• Format: isdate (string dt)
• Usage: Returns 1 (=true) if the specified string dt can be converted into a date(/time), otherwise returns 0 (=false)
• Parameter: dt (string): date(/time) to be checked
• Return value: boolean: If date(/time) appears to be valid, the return value is 1, otherwise 0

Examples:
Function:     if(isdate('01-05-2023'), 'This is a valid date/time', 'This is NO valid date/time')
Output:     This is a valid date/time

Function:     if(isdate('2028-02-31'), 'This is a valid date/time', 'This is NO valid date/time')
Output:     This is NO valid date/time

Function:     if(isdate('2023-02-28 10:00'), 'This is a valid date/time', 'This is NO valid date/time')
Output:     This is a valid date/time

Function:     if(isdate('2023-11-10 10h00'), 'This is a valid date/time', 'This is NO valid date/time')
Output:     This is NO valid date/time

 

tobool

• Format: tobool(string text)
• Usage: convert a value to a boolean (1 which indicates TRUE or 0 which indicates FALSE)
• Parameter: text (object): value to be converted
• Return value: boolean: the boolean value of ‘text’

Examples:
Function: if(tobool('TRUE'), 'The converted string to bool results in a boolean value', 'The converted string to bool does NOT result in a boolean value')
Output: The converted string to bool results in a boolean value

Function: if(tobool([VARIABLE.isVisible]), 'The converted string to bool results in a boolean value', 'The converted string to bool does NOT result in a boolean value')
=> Being a boolean variable containing the text value ‘TRUE’:
Output: The converted string to bool results in a boolean value
=> Being a boolean variable containing another text value:
Output: The converted string to bool does NOT result in a boolean value

 

regex

• Format: regex (string value, string regularExpression)
• Usage: Validates a value with Regular Expression.
• Parameters:
  • value (string): the value to be validated
  • regularExpression (string): the regular expression to compare with
• Return value: integer: true or false

Examples:
Function:     if(regex([MASTER.MAIL], '^([0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*@(([0-9a-zA-Z])+([-\w]*[0-9a-zA-Z])*\.)+[a-zA-Z]{2,9})$'), 'The MAIL field value uses proper email formatting (compared with a regular expression)', 'The MAIL field value DOES NOT use proper email formatting (compared with a regular expression)')
Output:     The MAIL field value uses proper email formatting (compared with a regular expression)

Function:     if(regex([MASTER.NAME], '^([0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*@(([0-9a-zA-Z])+([-\w]*[0-9a-zA-Z])*\.)+[a-zA-Z]{2,9})$'), 'The NAME field value uses proper email formatting (compared with a regular expression)', 'The NAME field value DOES NOT use proper email formatting (compared with a regular expression)')
Output:     The NAME field value DOES NOT use proper email formatting (compared with a regular expression)

 

chkmail / ismail

• Format:
  • chkmail (string emailaddress [,integer timeout])
  • ismail (string emailaddress [,integer timeout])
• Usage: Performs a basic syntax check of the supplied email address. If the optional parameter timeout has been specified, the function will perform a physical check of the email address on the appropriate domain.
• Parameters:
  • emailaddress (string): email address to check
  • timeout (integer): unit is in milliseconds (optional)
• Return value: boolean: If emailaddress is valid, the return value is 1, otherwise 0

Examples:
Function: if(chkmail('info@parana.com'), 'Basic syntax check of the email address = all good', 'Basic syntax check of the email address = something seems to be wrong...')
Output: Basic syntax check of the email address = all good

Function: if(ismail('info@parana.com'), 'Basic syntax check of the email address = all good', 'Basic syntax check of the email address = something seems to be wrong...')
Output: Basic syntax check of the email address = all good

Function: if(chkmail('infoparana.com'), 'Basic syntax check of the email address = all good', 'Basic syntax check of the email address = something seems to be wrong...')
Output: Basic syntax check of the email address = something seems to be wrong...

Function: if(ismail('infoparana.com'), 'Basic syntax check of the email address = all good', 'Basic syntax check of the email address = something seems to be wrong...')
Output: Basic syntax check of the email address = something seems to be wrong...

Function: if(chkmail('info@parana.com',3000), 'Physical check of the email address on the parana mail domain = all good', 'Physical check of the email address on the parana mail domain = something seems to be wrong...')
Output: Physical check of the email address on the parana mail domain = all good

Function: if(ismail('info@parana.com',3000), 'Physical check of the email address on the parana mail domain = all good', 'Physical check of the email address on the parana mail domain = something seems to be wrong...')
Output: Physical check of the email address on the parana mail domain = all good

 

isnumeric

• Format: isnumeric(variant param)
• Usage: Checks if param is (or can be converted to) a valid numeric value.
• Parameter: param (variant)
• Return value: boolean: If param appears to be numeric, the return value is 1, otherwise 0

Examples:
Function:     if(isnumeric('abc'), 'The parameter is (or can be converted to) a valid numeric value.', 'The parameter is NOT (or CAN'T be converted to) a valid numeric value.')
Output:     The parameter is NOT (or CAN'T be converted to) a valid numeric value.

Function:     if(isnumeric('123'), 'The parameter is (or can be converted to) a valid numeric value.', 'The parameter is NOT (or CAN'T be converted to) a valid numeric value.')
Output:     The parameter is (or can be converted to) a valid numeric value.

Function:     if(isnumeric('123abc'), 'The parameter is (or can be converted to) a valid numeric value.', 'The parameter is NOT (or CAN'T be converted to) a valid numeric value.')
Output:     The parameter is NOT (or CAN'T be converted to) a valid numeric value.

 

InWebContext()

• Format: InWebContext()
• Usage: To show (part of) the message in the email client only, or also in the web browser.
• Parameter: none
• Return value: boolean: true if viewing message in web browser

Examples:
For a single block of text content :
Function:      <sg:content id="content-4" expression="all(ne(tobool(InWebContext()),tobool('true')))" />
Output:     This will not show the text when viewing in the web browser.

For an entire message :
Function:     <sg:conditional expression="all(ne(tobool(InWebContext()),tobool('false')))" />
Output:     This will show the message when viewing in the web browser.

 

Array functions

union

• Format: union(array arr1, array arr2)
• Usage: combine 2 arrays into 1 array
• Parameters:
  • arr1: array of objects
  • arr2: array of objects
• Return value: Array: combined array containing all elements from arr1 and all elements from arr2.

Example:
Function: union(array('1', '2'), array('3', '4'))
Output: ['1', '2', '3', '4']

 

intersect

• Format: intersect(array arr1, array arr2)
• Usage: Get the intersection of 2 arrays
• Parameters:
  • arr1: array of objects
  • arr2: array of objects
• Return value: Array: array containing all common elements from arr1 and arr2.

Example:
Function: intersect(array('1', '2', '4'), array('1', '3', '4'))
Output: ['1', '4']

 

distinct

• Format: intersect(array arr1, array arr2)
• Usage: Get the distinct values of 2 arrays
• Parameters:
  • arr1: array of objects
  • arr2: array of objects
• Return value: Array: array containing all unique elements from arr1 and arr2.

Example:
Function: distinct(array('1', '2', '4'), array('1', '3', '4'))
Output: ['1', '2', '3', '4']

 

join

• Format: join(array arr1, string separator)
• Usage: join all elements from arr1 into a string, with the separator in between
• Parameters:
  • arr1 (array): the array of elements to be joined into a string
  • separator (string): the string to glue the elements together
• Return value: string

Example:
Function: join(array('1', '2', '3', '4'), '|'))
Output: 1|2|3|4

 

Other functions

propcount

• Format: propcount(string multivalue)
• Usage: The amount of values, contained in a multi-value field.
• Parameter: multivalue (string) : string to search, separators can be "," or "|"
• Return value: integer: The amount of contained values

Examples:
Function:     propcount('a,b,c,d,e')
Output:     5

Function:     propcount('a|b|c|d')
Output:     4

 

matchcount

• Format: matchcount(string multivalue_1, string multivalue_2)
• Usage: Counts the amount of values that match between 2 multi-value fields.
• Parameters:
  • Multivalue_1 (string)
  • Multivalue_2 (string)
    
• Return value: integer: The amount of matched values found

Example:
Function:     matchcount ('a,b,c,d,e','b,d,e,f,g')
Output:     3

 

if

• Format: if(boolean constraint, variant ifTrue, variant ifFalse)
• Usage: ifTrue if constraint evaluates to true, otherwise returns ifFalse.
• Parameters:
  • constraint (boolean): Constraint to evaluate. Can be a combination or nesting of every supported Engage function
  • ifTrue (variant): Return value if constraint evaluates to true
  • ifFalse (variant): Return value if constraint evaluates to false
• Return value: variant: ifTrue or ifFalse, depending of the evaluation of constraint

Examples:
Function:     if(eq('A','A'),'Identical', 'Different')
Output:     Identical

Function:     if(eq('A','B'),'Identical', 'Different')
Output:     Different

Function:    if(eventvalue(‘Boolean’), ‘correct’, ‘incorrect’)
Output:    Correct in case of Boolean = true, Incorrect in case of Boolean = false

 

itemValue

• Format: itemValue(string dataSelection, int itemIndex, string fieldName)
• Usage: value from field fieldName of the itemIndex item in the data selection dataselection.
• Parameters:
  • dataSelection (string): Name of the data selection defined in the message/template
  • itemIndex (int): Index of the item in the data selection (zero-based)
  • fieldName (string): Name of the field to return the value from
• Return value: variant: fieldvalue of given field in the given item in the given data selection

Example:
Function:     itemValue('Productlist', 0, 'NAME')
Output:     iPhone 7

 

cartValue

• Format:
  • inside a Repeater : cartValue(stringfieldName)
  • outside a Repeater : cartValue(stringdataSelection, intitemIndex, stringfieldName)
• Usage: returns the value from the field fieldName of an abandoned cart journey.
  This uses data coming from the Site cart. When no Sitecart data can be found for the selected field, then by default the value is taken from the data selection list in Marigold Engage.
  The cartValue expression is available for every field in the data selection. However, currently only Price and Quantity are supported.
• Parameters:
  • dataSelection (string): Name of the data selection defined in the message/template
  • itemIndex (int): Index of the item in the data selection (zero-based)
  • fieldName (string): Name of the field to return the value from
• Return value: variant: fieldvalue of the given field in the given data selection (coming from Site abandoned cart data when available).

Examples:
Function:     cartValue('PRICE')
Output:     299

Function:     cartValue('QUANTITY')
Output:     8

Function:    cartValue('Products',0,'PRICE')
Output:    299

 

journeyLookupValue

• Format:
  • without scope : journeyLookupValue(string list_api_name, string fieldName)
  • with scope : journeyLookupValue(string list_api_name, string fieldName, string scopeName)
• Usage:
  In a Lookup component in a Custom Journey, the property 'Load data' can be selected. When selecting this option, the loaded data will be available in the journey components that follow the Lookup component and for personalization in resulting pages.
  The journeyLookupValue function can also be used with a third parameter, namely the 'scope'. The scope should be used when multiple Lookup components, used in the same Custom Journey, perform a lookup on the same list. The scope can then retrieve the right data from the right lookup component.
• Parameters:
  • listName (string): Name of the list in which the lookup is done
  • fieldName (string): Name of the list field to return the value from
  • scopeName (string): Name of the scope (optional), in case multiple identical lookups are performed, to retrieve the data of that one specific scope
• Return value: variant: fieldvalue of the given field in the given list (with the given scope)

Examples:
Function:     journeyLookupValue('Orders', 'ProductName')
Output:     iPhone 11

Function:     journeyLookupValue('Orders', 'ProductName', 'FirstOrder')
Output:     Samsung Galaxy S20

 

mobileValue

• Format: mobileValue(string fieldName)
• Usage: For personalization in Marigold Engage mobile messages, mobileValue('FIELD_NAME') can be used to retrieve the data from the specified field from the Devices list (which is linked to the Audience list). As the properties of a mobile message define a mobile app or the default one, the right scope is used automatically.
• Parameter: fieldName (string): Name of the list field from the Devices list to return the value from
• Return value: variant: field value of the given field in the Devices list

Example:
Function:     mobileValue('SYSTEM_VERSION')
Output:     Android 9 Pie

 

translateValue

• Format: translateValue(string fieldname)
• Usage: Translates a value of a field that’s linked to an option list.
• Parameter: Fieldname (string): Name of the field to which the option list is linked
• Return value: string: returns the converted translated value

Example:
Function:     translateValue('MASTER.GENDER')

where the GENDER field in the user list contains the value ‘m’ for male users with English translation ‘male’ and French translation ‘masculin’ (translations in the Option List)

Output:         male
    when the selected/user language is EN

    masculin
    when the selected/user language is FR

 

translateMobileValue

• Format: translateMobileValue(string fieldName)
• Usage: For personalization in Marigold Engage mobile messages, mobileValue('FIELD_NAME') can be used to retrieve the data from the specified field from the Devices list (which is linked to the Audience list). As the properties of a mobile message define a mobile app or the default one, the right scope is used automatically.
  When the field contains Option list field values though, translateMobileValue('FIELD_NAME') needs be to used to retrieve the actual translated field values. Otherwise, the Option list codes are returned instead.
• Parameter: fieldName (string): Name of the list field from the Devices list to return the translated value from
• Return value: variant: translated field value of the given field in the Devices list

Example:
The field 'DEVICE_COUNTRY' in the Devices list contains values linked to an Option list.
For a record, containing the code ‘FR’ for that field, the English translation in the Option list is ‘France’.

When using mobileValue :
Function:     mobileValue('DEVICE_COUNTRY')
Output:     FR

When using translateMobileValue :
Function:     translateMobileValue('DEVICE_COUNTRY')
Output:     France

 

requestValue

• Format: requestValue(fieldName)
• Usage: lookup and return a posted value from a form field
• Parameter: fieldName: Name of the form field for which the value needs to be returned
• Return value: variant: field value of the form field

Example:
A form is submitted containing an email address in the 'MAIL' form field.

Function:     requestValue(MAIL)
Output:     john.doe@parana.com

 

listValue

• Format: listValue([listName.fieldName])
• Usage: lookup and return a field value in the lookup list (current scope) or in any (1:1 or 1:N) linked list
• Parameter: [listName.fieldName] : Name of the list and field for which the value needs to be returned
• Return value: variant: field value of the list

Example:
The lookup list (current scope) is the main Audience List, with a linked list ‘Preferences’ that contains a field ‘Interests’ from which we’d like to get the value from.

Function:     listValue([Preferences.Interests])
Output:     fashion

 

profileValue

• Format: profileValue([listName.fieldName])
• Usage: lookup and return a field value in the Audience List (or in a 1:1 profile extension of that Audience List)
• Parameter: [listName.fieldName] : Name of the list and field for which the value needs to be returned
• Return value: variant: field value of the list

Example:
The current scope is the ‘Products’ List (which is a Data List that's not linked to the main Audience List).
We’d like to get the contact’s email address from the Audience List.

Function:     profileValue([MASTER.MAIL])
Output:     john.doe@parana.com

 

componentValue

• Format: componentValue('scope.variable')
• Usage: When using a 'Custom Component' or 'Custom Channel Component' with output parameters in a Custom Journey, the output can be accessed through the componentValue function.
• Parameter: The 'scope' is defined in the properties of the Custom Component/Custom Channel Component. The 'variable' is the name of the output parameter (for example to show the value in an email).
• Return value: variant: output parameter value

Example:
There are two Custom Components added to a Custom Journey. Each one generates an output parameter called Product. The first Custom Component is given the scope 'Delivery' and the second is given the scope 'Invoice'. To be able to use the information returned by the Custom Components, the appropriate scope is used.

Function:     componentValue('Delivery.Product')
Output:     Phone35rt

Function:     componentValue('Invoice.Product')
Output:    iPhone X 64GB Silver

 

eventValue

• Format: eventValue('fieldname')
• Usage: When using Custom Events, to retrieve the value of a Custom Event field. Or to add transactional field values to a message.
• Parameter: Fieldname : Name of the Custom Events list field or transactional field for which the value needs to be returned
• Return value: variant: field value

Example:
When using Custom Events, to retrieve the value of a Custom Event field called ‘Favoriteshops’ :
Function:     eventValue('Favoriteshops')
Output:     Parana Store Brussels

For a transactional field called ‘Client’ :
Function:     eventValue('Client')
Output:     parana

 

jsonValue

• Format: jsonValue(field, JSON key)
• Usage: To use the data returned in a Custom Events list field of type JSON (array).
• Parameters:
  • field : an expression returning the JSON field, e.g.: eventValue('FAVORITESHOPS')
  • JSON key : the path to navigate to the specific key in the JSON (array). Use "." as a separator and "[x]" as (zero-based) index operator.
• Return value: variant: JSON field value of the Custom Events list

Example:
A Custom Events field called FAVORITESHOPS contains this JSON structure :



Function:     jsonValue(eventValue('FAVORITESHOPS'), 'ADDRESS[0].CITY')
Output:     Brussels ( = the 'city' from the first element in the ADDRESS array)

Function:     jsonValue(eventValue('FAVORITESHOPS'), 'ADDRESS[1].CITY')
Output:     Paris ( = the 'city' from the second element in the ADDRESS array)

 

loadValue

• Format: loadValue(Value1, Value2, DefaultValue)
• Usage: To load page form values (for example a Combobox) or parameter values in an Input Component in a Custom Journey. The loadValue function is commonly used in combination with the requestValue function.
• Parameters:
  • Value1 : The value that will be loaded, when available.
    For example, requestValue('NAME') to load a name entered by a contact on a page form.
  • Value2 : The value that will be used when Value1 can't be loaded/is empty.
    
    For example, the value from the Audience List field 'NAME', when on an initial page view no name value has been entered in the page form yet.
  • DefaultValue : In case both Value1 and Value2 are empty, it's possible to display a default value.
    
    For example, during a registration process of a new user, where no name value has been entered in the page form yet and the Name field in the Audience List is still empty, as it's a new user.
• Return value: string: loaded value

Example:
A registration page form is shown to a new contact that contains, among other things, a name field.
Function:     loadValue(requestValue('NAME'),'NAME','Please enter your name here')
Output:     Please enter your name here
It’s a new contact, for whom we have no info yet.
Value1 (requestValue('NAME')) doesn’t exist.
Value2 ('NAME') is empty in the Audience List, as this is a new contact.
The third parameter is used in this case, which is a default value that we’ve set.

The name ‘Jane’ is entered in the registration page form, which we want to load in a next step in a journey.
Function:     loadValue(requestValue('NAME'),'NAME','')
Output:     Jane
The first parameter requestValue('NAME') is used in this case, which is the value ‘Jane’, as that’s what she entered in the form.

After Jane registered, she logs in. She then receives a new page form to enter her newsletter preferences.
The form contains a name field with loaded data.
Jane doesn’t enter her name (yet) in the name field.
Function:     loadValue(requestValue('NAME'),'NAME','')
Output:     Jane
Jane didn’t enter any value.
Value1 (requestValue('NAME')) couldn’t be loaded.
The second parameter 'NAME' is used in this case, which gets the Name value from the Audience List field ‘NAME’.

 

urlencode

• Format: urlencode(string value)
• Usage: Returns the urlencoded version of value.
• Parameter: value (string): value to convert
• Return value: string: Urlencoded version of value

Example:
Function:     urlencode('info@parana.com')
Output:     info%40parana%2Ecom

 

urldecode

• Format: urldecode(string encodedvalue)
• Usage: Returns the urldecoded version of value.
• Parameter: encodedvalue (string): value to convert
• Return value: string: Urldecoded version of encodedvalue

Example:
Function:     urldecode('info%40parana%2Ecom')
Output:     info@parana.com

 

convertphonenumber

• Format: convertphonenumber(string phone_nr, integer country_dial_prefix, integer maxshortcodelength)
• Usage: Normalizes a phone number to the international format if possible.
  
• Parameters: normalized 
  • phone_nr (string) : The phone number to be converted.
  • country_dial_prefix (integer) : The country dial prefix. If the phone number doesn't contain the country dial prefix, the provided country_dial_prefix parameter will be used.
  • maxshortcodelength (integer) :
    • When the maxshortcodelength parameter contains a lower value than the length of the phone number, the converted phone number will be in short code format when possible (depending on operator and region).
    • When the maxshortcodelength parameter contains a greater value than the length of the phone number, the number is untouched (spaces and symbols other than numbers and the + sign are removed though).
• Return value: string: Converted phone number (leading zeros are replaced with a '+' sign and a country code - when applicable).

Examples:
Function:     convertphonenumber('0477 112345',32,11)
Output:     0477112345
→ Untouched, as the maxshortcodelength is greater than the length of the phone number (the space is removed though).

Function:     convertphonenumber('0477 112345',32,4)
Output:     +32477112345
→ The leading zero is replaced by a + sign and the country code that is provided as prefix is used (and the space is removed).

Function:     convertphonenumber('01712',32,5)
Output:     01712
→ The provided maxshortcodelength of 5 results in the phone number (short code) to remain 01712, as it's considered to be valid.

Function:     convertphonenumber('1712',32,4)
Output:     1712
→ The provided maxshortcodelength of 4 results in the phone number (short code) to remain 1712, as it's considered to be valid.

Function:     convertphonenumber('01712',32,4)
Output:     +321712
→ The provided maxshortcodelength of 4 results in '1712' to be recognized as short code, the leading zero to be removed and replaced by a + sign and the country code 32 that is provided as prefix is used, resulting in the phone number +321712.

Function:     convertphonenumber('+32 477 112345',32,4)
Output:     +32477112345
→ Nothing changes, as the phone number already starts with a + sign and the country code 32 (spaces are removed though).

Function:     convertphonenumber('0032 477 112345',32,4)
Output:     +32477112345
→ The 2 leading zeros are replaced with a + sign (and spaces are removed).

Function:     convertphonenumber('0477 112345',32,4)
Output:     +32477112345
→ The leading zero is replaced by a + sign and the country code that is provided as prefix is used (and the space is removed).

Function:     convertphonenumber('+324-77/12 31 23',32,4)
Output:     +32477123123
→ All symbols are removed (including spaces) other than numbers and the + sign.

 

hash

• Format: hash(string value, string encoding)
• Usage: Returns the hashed value of the provided value.
• Parameters:
  • value (string): String to be encoded.
  • encoding (string): Name of the encoding to be used. Possible values are “md5”, “sha256”, “sha512”.
• Return value: string: Converted value

Examples:
Function:     hash('abcdefgh', 'md5')
Output:     E8DC4081B13434B45189A720B77B6818

Function:     hash('abcdefgh', 'sha256')
Output:     9C56CC51B374C3BA189210D5B6D4BF57790D351C96C47C02190ECF1E430635AB

 

generatepwd

• Format: generatepwd(integer length)
• Usage: Returns a strong password of the desired length. Minimum length is 7. If a length smaller than 7 is specified, the function will default to 7.
• Parameter: length (integer): the length of the password to generate
• Return value: string: a string of random characters with the length that was defined as parameter

Examples:
Function:     generatepwd(1)
Output:     qB1Ps!K

Function:     generatepwd(10)
Output:     4hNNMD?t9g

 

guid

• Format: guid( )
• Usage: validates a unique string
• Parameter: none
• Return value: string: Unique ID

Example:
Function:     guid()
Output:     7f57c9ad-13f5-4a97-9da7-1b913f2e4888

 

striphtml

• Format: striphtml(string HTML)
• Usage: Returns an HTML in which some tags have been removed. Typically, this function replaces BR-tags and P-tags by a linefeed or LI-tags are replaced by lists.
• Parameter: HTML: The html to parse.
• Return value: string: stripped HTML

Examples:
Function:     striphtml ('<p>Hello <strong>world</strong></p><p>This is an example</p>')
Output:
Hello world
This is an example

Function:     striphtml ('<ul><li>item 1</li><li>item 2</li><li>item 3</li></ul>')
Output:
• item 1
• item 2
• item 3

 

encode (base64)

• Format: encode(string, 'base64')
• Usage: encodes a specific string in base64.
• Parameters:
  • string : The string value to be encoded (between single quotes).
  • 'base64': Type of coding (between single quotes). This is a fixed value.
• Return value: string: encoded value

Example:
Function:     encode('Password', 'base64')
Output:     UGFzc3dvcmQ=

 

decode (base64)

• Format: decode(string, 'base64')
• Usage: decodes a base64 encoded string value.
• Parameters:
  • string : The encoded string to decode (between single quotes).
  • 'base64': Type of coding (between single quotes). This is a fixed value.
• Return value: string: decoded value

Example:
Function:     decode('SGVsbG8gd29ybGQ=', 'base64')
Output:    Hello world

 

link

• Format:
  • link(id)
  • link('name')
• Usage: Returns the optiextension url with the linkid as query string.
• Parameters:
  • id: Engage link ID
  • name (between quotes): Engage link name
• Return value: string: optiextension url with linkid

Example:
A message contains a link with id=100 and name=my_link.

Function:     link(100)
Output:         http://someserver/optiext/optiextension.dll?ID=_ybRiQFKotGvrCkU2%2BeisQrZoCaRlvUSpYkt0avMFlrsOI8QWS6eKHiRfuScf2cvwfF2pNTFYCqPZ5N9YfVWJFq__%2B

Function:     link('my_link')
Output:         http://someserver/optiext/optiextension.dll?ID=_ybRiQFKotGvrCkU2%2BeisQrZoCaRlvUSpYkt0avMFlrsOI8QWS6eKHiRfuScf2cvwfF2pNTFYCqPZ5N9YfVWJFq__%2B

 

linkid

• Format: linkid(id)
• Usage: Returns the linkid.
• Parameter: id: Engage link ID
• Return value: string: linkid

Example:
Function:     linkid(100)
Output:    _ybRiQFKotGvrCkU2%2BeisQrZoCaRlvUSpYkt0avMFlrsOI8QWS6eKHiRfuScf2cvwfF2pNTFYCqPZ5N9YfVWJFq__%2B

 

journey

• Format:
  • journey('name')
  • journey('run_dt')
• Usage: Returns the journey name, or the most recent run date/time of the journey.
• Parameters: one of these strings can be used, including the single quotes : 'name' or 'run_dt'
• Return value:
  • string: name of the journey (when 'name' is used)
  • string: most recent run date/time of the journey (when 'run_dt' is used)

Examples:
Function:     journey('name')
Output:    Newsletter Journey

Function:     journey('run_dt')
Output:    2021-01-26 11:51:04

 

position

• Format: position()
• Usage: Returns the index position of a Data Selection item inside a Repeater.
• Parameter: none
• Return value: numeric value of the index position of the Data Selection item inside the Repeater

Example:
As example, let’s say the DTS items in the Repeater in ascending order are : Smartphone A, Laptop B, Tablet C.

Function:     position()
Output:
0 => for the first item Smartphone A
1 => for the second item Laptop B
2 => for the third item Tablet C

 

count

• Format: count(string DataSelectionName)
• Usage: Returns the number of items within a Data Selection.
• Parameter: DataSelectionName (string) : name of the Data Selection setup in the properties of the message (that’s linked to a Data Selection List containing the data).
• Return value: numeric value of the number of items within the given Data Selection

Example:
In the message properties, the data selection ‘DTS_prods’ has been setup (linked to the Data Selection List ‘Products’), that contains 145 product items.

Function:     count('DTS_prods')
Output:    145

 

Addendum

Grid support

All the Marigold Engage functions are supported on Grid, except the following ones :

• regex

• union

• distinct

• explode

• intersect

• join