Table of Contents

Description

“Scriptlets” is the name of our programming language used within Maileon newsletters to realize extensive requirements on data processing and output. Scriptlets allow for example generating random numbers or UUIDs for each contact within a sendout in order to attach it to some link. It allows generating an (MD5) hash of data like the email address or encrypt data with some given key and supports complex processing of data like parsing a string as a datetime object, adding 7 days and printing it in some other format. Also accessing external data sources for each individual contact is possible in order to e.g. display individual products for each contact.

Thus, Scriptlets support a huge number of language elements and even if it is not possible to create an infinite loop, you can use loops, e.g. when iterating over the items of some shopping cart in order to calculate the overall sum or to display the items in a newsletter.

The formal description is provided as BNF in the next section, however, most readers will benefit at the beginning more of some unformal description or the examples later on. Scriptlets are always wrapped in double square brackets [[ ]]. Inside the brackets, a Scriptlet is started with a “%” sign to avoid mixing up regular Maileon-Mergetags and Scriptlets. For Scriptlets a preorder syntax has been chosen, this means that the operator is in the beginning of an expression and the parameters follow behind, separated by a whitespace “ “. If an parameter is an expression with some operator itself, it has to be wrapped in single round brackets ().

Simple examples:

For date and time formats please refer to https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/SimpleDateFormat.html

Formal Description

 This section defines the BNF of the language elements.

Language Elements

The 'mine' Function

• mine

  • Description: Causes the message generation to fail. Can be used e.g. to not send an automated transaction mail under certain circumstances.

• mine <string>

  • Description: Same as “mine” without parameter but fires a “named” personalization error, if triggered.

String Functions

• to_string <none_void_expr>

• lower_case <string_expr>

• md5 <string_expr>

• capitalize <string_expr>

• normalize_space <string_expr>

• reverse <string_expr>

• trim <string_expr>

• uncapitalize <string_expr>

• upper_case <string_expr>

• default_if_blank <string_expr> <string_expr>

• default_if_empty <string_expr> <string_expr>

• remove <string_expr> <string_expr>

• remove_end <string_expr> <string_expr>

  • Description: Removes the second string from the end of the first string

• remove_end_ignore_case <string_expr> <string_expr>

• remove_start <string_expr> <string_expr>

• remove_start_ignore_case <string_expr> <string_expr>

• substring <string_expr> <numeric_expr> <numeric_expr>

  • substring 'abc' 0 2   = 'ab' substring 'abc' 2 0   = '' substring 'abc' 2 4   = 'c' substring 'abc' 4 6   = '' substring 'abc' 2 2   = '' substring 'abc' -2 -1 = 'b'

• substring_after <string_expr> <string_expr>

• substring_after_last <string_expr> <string_expr>

• substring_before <string_expr> <string_expr>

• substring_before_last <string_expr> <string_expr>

• substring_between <string_expr> <string_expr> <string_expr>

• random_alphabetic <numeric_expr>

• random_alphanumeric <numeric_expr>

• random_numeric <numeric_expr>

• to_string_on_off <logical_expr>

• to_string_true_false <logical_expr>

• to_string_yes_no <logical_expr>

• replace <string_expr> <string_expr> <string_expr>

  • [[ % replace '12.50' '.' ',' ]] à 12,50

• replace_once <string_expr> <string_expr> <string_expr>

• center <string_expr> <numeric_expr> <string_expr>

• abbreviate <string_expr> <numeric_expr>

  • Description: Cuts down the string to the given length INCLUDING the three abbreviation indicating dots. If nothing will be cut, the dots will not be added.
    [[ % abbreviate '123456' 6]] will be evaluated to '123… '
    Thus, the length MUST be greater or equal to 4.

• abbreviate_middle <string_expr> <string_expr> <numeric_expr>

• repeat <string_expr> <numeric_expr>

• random <numeric_expr> <string_expr>

• boolean_to_string <logical_expr> <string_expr> <string_expr>          

• join <sequence_expr> <string_expr>

• concat <sequence_expr>

• unescape_html <string_expr>

• date_to_string <date_expr> <string_expr> <string_expr>

• datetime_to_string <datetime_expr> <string_expr> <string_expr>

• format_date <string_expr> <string_expr> <string_expr> <string_expr>

• format_datetime <string_expr> <string_expr> <string_expr> <string_expr>

• aes_encrypt_hex <string_expr> <string_expr>

• format_number <numeric_expr> <string_expr> <string_expr> <numeric_expr>

  • [[ format_number 1234.560' '.' ',' 2 ]] -> 1.234,56

  • Warning: if the number comes from a custom contact field (type float) and is not set, it returns the STRING value “NaN”, which will cause the formatting to fail. Use an “if” around the expression:

    [[ % if (negate(equals (contact 'float_number') 'NaN')) % format_number (contact 'float_number') '.' ',' 2 % endif ]]

• url_encode <string_expr>

  • Description: Encodes a string as a URL parameter that can be passed

• url_decode <string_expr>

  • Description: Decodes a string as URL parameters that will be interpreted

• assigned_voucher <string-literal>

  • Description: Print voucher code, parameter is pool name (not the ID)! Fails if voucher does not exist.

• assigned_voucher <string-literal> <string-literal>

  • Description: Print voucher code, parameter is pool name (not the ID) + fallback value! Fails if voucher does not exist.

• voucher <string-literal> <string-literal>

  • Description: Print voucher code, parameter is pool ID (as a string) + fallback value! Fails if voucher does not exist.

• conditional_content  <string-literal>

  • Description: Print COCO ruleset result, parameter is rulset name (not the ID)! Fails if the ruleset does not exist. Default COCO rulesets cannot be referred to as their representation is language dependent.

Logical functions

As Maileon uses a three state value for Booleans (not set, true or false), these methods define a fallback behavior, which is added in [brackets] behind the expression. They will return this result, if e.g. a custom field is not set. Methods without annotation will fail if the field is empty, so a check for existence is mandatory.

• to_boolean <none_void_expr>

• exists <none_void_expr>

• or <logical_expr>*
  This method checks every expression, even if earlier expressions evaluated to true

• logical_or <logical_expr>*
  or with early abort

• and <logical_expr>*
  This method checks every expression, even if earlier expression evaluated to false

• logical_and <logical_expr>*
  and with early abort

• negate <logical_expr>

• xor <logical_expr>*

• is_all_upper_case [false]

• is_boolean <none_void_expr> [false]

• is_number <none_void_expr> [false]

• is_date <none_void_expr> [false]

• is_datetime <none_void_expr> [false]

• is_string <none_void_expr> [false]

• is_time <none_void_expr>

• is_sequence <none_void_expr> [false]

• contains_whitespace <string_expr> [false]

• is_all_lower_case <string_expr> [false]

• is_alpha <string_expr> [false]

• is_alphanumeric <string_expr> [false]

• is_alphanumeric_space <string_expr> [false]

• is_alpha_space <string_expr> [false]

• is_blank <string_expr> [true]

• is_empty <string_expr> [true]

• is_not_blank <string_expr> [false]

• is_not_empty <string_expr> [false]

• is_numeric <string_expr> [false]

• is_numeric_space <string_expr> [false]

• is_whitespace <string_expr> [false]

• string_to_boolean <string_expr> [false]

• contains <string_expr> <string_expr> [false]

  • [[% if (contains (transaction 'someAttribute') 'X') % 'Contains X' % endif]]

• contains_ignore_case <string_expr> <string_expr> [false]

  • [[% if (contains_ignore_case (transaction 'someAttribute') 'X') % 'Contains X' % endif]]

• ends_with <string_expr> <string_expr> [false]

• ends_with_ignore_case <string_expr> <string_expr> [false]

• starts_with <string_expr> <string_expr> [false]

• starts_with_ignore_case <string_expr> <string_expr> [false]

• equals <string_expr> <string_expr> [false]

  • Description: Compares two STRINGS for equality. Not applicable, if variable content is numeric, in this case use “eq”

• equals_ignore_case <string_expr> <string_expr> [false]

• is_false <logical_expr>

• is_not_false <logical_expr>

• is_not_true <logical_expr>

• is_true <logical_expr>

• negate <logical_expr>

• seq_contains <sequence_expr> <none_void_expr> [false]

• seq_contains_any <sequence_expr> <sequence_expr> [false]

• seq_contains_none <sequence_expr> <sequence_expr> [true]

• seq_contains_all <sequence_expr> <sequence_expr> [false]

  • Description: Checks if sequence1 contains all elements of sequence2

• equals_any(_ignore_case) <string-expr> <sequence-expr>

• equals_none(_ignore_case) <string-expr> <sequence-expr>

• contains_any(_ignore_case) <string-expr> <sequence-expr>

• contains_none(_ignore_case) <string-expr> <sequence-expr>

• contains_all(_ignore_case) <string-expr> <sequence-expr>

• starts_with_any(_ignore_case) <string-expr> <sequence-expr>

• starts_with_none(_ignore_case) <string-expr> <sequence-expr>

• ends_with_any(_ignore_case) <string-expr> <sequence-expr>

• ends_with_none(_ignore_case) <string-expr> <sequence-expr>

• gt <numeric_expr> <numeric_expr>

• ge <numeric_expr> <numeric_expr>

• eq <numeric_expr> <numeric_expr>

  • Description: Compares numeric values, not strings

• ne <numeric_expr> <numeric_expr>

• lt <numeric_expr> <numeric_expr>

• le <numeric_expr> <numeric_expr>

• is_preference_true <string> <string>

  • Arguments: category name, preference name

• preference_has_value <string> <string>

  • Arguments: category name, preference name

• preference_has_no_value <string> <string>

  • Arguments: category name, preference name

• preference_has_no_value_or_false <string> <string>

  • Arguments: category name, preference name

• is_preference_false <string> <string>

  • Arguments: category name, preference name

• is_any_preference_true <string>

  • Arguments: category name

• is_matched_by_filter <string >

  • Arguments: Parameter is the name of the filter, not its ID! No failure if filter does not exist but returns false. Works reliably in regular mails only but might represent outdated results in transactional or DOI confirmation mails.

• is_not_matched_by_filter <string >

  • Arguments: Parameter is the name of the filter, not its ID! No failure if filter does not exist but returns false. Works reliably in regular mails only but might represent outdated results in transactional or DOI confirmation mails.

Numeric Functions

• to_number <none_void_expr>

• add <numeric_expr> <numeric_expr>

• length <string_expr>

• mul <numeric_expr> <numeric_expr>

• sub <numeric_expr> <numeric_expr>

• div <numeric_expr> <numeric_expr>

• pow <numeric_expr> <numeric_expr> 

• ceil <numeric_expr>

• floor <numeric_expr>

• round <numeric_expr>

• abs <numeric_expr>

• max <sequence_expr> 

• min <sequence_expr> 

• sum <sequence_expr>  

• seq_size <sequence_expr>

• mod <numeric_expr> <numeric_expr>

• datetime_to_time <datetime_expr>

  • Description: Translates a datetime into a timestamp

• date_to_time <date_expr>

  • Description: Translates a date into a timestamp

• parse_number <string_expr> <string_expr> <string_expr>

  • [[ parse_number '1.234,560' '.' ',' ]]

• increment <numeric_expr>

  • [[ % set $var 1 % increment $var % $var]] -> 2

• decrement <numeric_expr>

  • [[ % set $var 1 % decrement $var % $var]] -> 0

Sequence Functions

• split <string_expr> <string_expr>

• split (contact 'listField' ';')

• csv <string_expr>

• seq_add_all <sequence_expr> <sequence_expr>

• seq_add <sequence_expr> <none_void_expr>

  • Description: Add an element to a sequence. This method does not change the input sequence, make sure to save the result

• seq_replace <sequence_expr> <sequence_expr>

• partition <sequence_expr> <numeric_expr>

  • [[% partition <1, 2, 3, 4, 5, 6, 7, 8, 9, 10} 3]] -> [[1,2,3], [4,5,6], [7,8,9], [10]]

• reverse_seq <sequence_expr>

  • [[% reverse <1, 2, 3, 4}]] -> [4, 3, 2, 1]

• shuffle <sequence_expr>

  • [[% shuffle <1, 2, 3, 4}]] -> e.g. [2, 4, 3, 1]

• select_true_preferences <string>

  • Arguments: category name - return sequence of preference names that are true

• select_false_preferences <string>

  • Arguments: category name - return sequence of preference names that are false

Object Functions

• item <sequence_expr> <numeric_expr>

  • Description: Selects the n-th item from a sequence. The index starts with 0 for the first item.

  • [[ % item $someSequence 0 ]]

Date Functions

• now

• to_date <string_expr> <string_expr>

• cast_date <string_expr>

• time_to_date:<numeric_expr>

Datetime Functions

• date_sent

  • Description: The datetime of the sendout, also works for triggermails

• to_datetime <string_expr> <string_expr>

• cast_datetime <string_expr>

• time_to_datetime <numeric_expr>

• add_seconds <date_or_datetime_expr> <numeric_expr>

• add_minutes <date_or_datetime_expr> <numeric_expr>

• add_hours <date_or_datetime_expr> <numeric_expr>

• add_days <date_or_datetime_expr> <numeric_expr>

• add_weeks <date_or_datetime_expr> <numeric_expr>

• add_months <date_or_datetime_expr> <numeric_expr>

• add_years <date_or_datetime_expr> <numeric_expr>

External Data

Maileon can retrieve external data, either as JSON or plain HTML. The following facts and restrictions are valid for both features.

Maileon uses caching strategies to reduce the amount of request. Please make sure that the server always returns the same response for the same request within one sendout. As URLs can contain variables it might result in a lot of different URLs and thus, a lot of requests. Make sure your server can process the request fast enough as it will delay the sendout process. If a service times out, the mailing(s) the response was meant for are not processed any further and are reported as “failed sendouts”.

External JSON