Built-in Functions
A number of built-in functions may be used in the Scenario Builder application. This page describes such functions and provides examples of how to use them.
How to Invoke Functions
To invoke a function from a text field, prefix it with an equal sign. For example: =random(100)
Function Descriptions
applytimezone(UTC timestamp, time zone name)
When provided with a UTC timestamp parameter and a time zone parameter, this function returns a time zone offset in seconds.
This function is useful if customers from inbound interactions need to know whether a specific business location is open or closed, when it is possible to contact a web-form lead during an outbound campaign, and so forth.
How to Use
The UTC_timestamp parameter may be entered as a specific value (e.g., 1609459200); however, it is also possible to use the now() function as the parameter. Note that determining the offset depends on the UTC timestamp time and does not depend on the current time (i.e., Standard Time or Daylight Saving Time (DST)).
For example:
=applytimezone(now(),"America/Los_Angeles")
If now() returns "1609459200," and "America/Los_Angeles" is "- 28800," the end result will be:
1609430400
Specifically, the function returns the number of seconds supplied by the first parameter plus the time zone offset corresponding to the time zone name supplied by the second parameter. Note that the returned offset may depend on the first parameter value as well (i.e., to account for possible DST shifts).
base64encode(string)
Encodes the entered string in the Base64 encoding scheme
base64decode(string)
Decodes a Base64-encoded string to an unencoded string
escapeJSON()
(deprecated, please use variable expansion escaping JSON)
Escapes the control characters or other special characters that occur within a JSON expression before adding JSON to another JSON as a text field. One way to use this function is to use a Set Variable block to JSON-escape each individual variable before including the variable in JSON. See also escaping JSON when expanding variables.
Example 1
When using the function with string literal:
=escapeJSON('{"firstName":"John", "lastName":"Doe"}')
Example 2
When using the function with JSON variable (i.e., data received by the FetchURL block or Zendesk, Salesforce.com, or other CRM Search blocks):
=escapeJSON('$(varJSON)')
For example, if a FetchURL block received a JSON object that was stored in the variable varJSON the actual content looks like:
{
"firstName": "John",
"lastName": "Doe"
}
Applying the escapeJSON() function looks like:
=escapeJSON('$(varJSON)')
And the result will be:
{\"firstName\":\"John\",\"lastName\":\"Doe\"}
formatdatetime(int unixtimestamp, string format)
Formats the time as specified in the format argument. This format is the same as in Java SimpleDateFormat, as implemented by the International Components for Unicode (ICU)library.
For example:
"yyyy-MM-dd'T'HH:mm'Z'" yields 2012-07-20T20:45:44.0973928Z
formatduration(duration_in_seconds)
Converts duration in specified in seconds into MM:SS or HHH:MM:SS formats. It produces formatted string as output.
For example:
formatduration(121) will return "02:01"
hash("hash_function","message","format")
This function allows you to convert a message (i.e., any string) into a hash value.
The following hash algorithm values are allowed for hash_function:
- MD5
- SHA-1
- SHA-256
The following values are allowed for "format:”
- base64
- hex
The function returns an empty string if either the hash_function or the format values do not match the list of valid values specified above.
Example
Invoking the function as such:
=hash("SHA-256","$(item.from)","hex")
Will return something like the following:
0ffe885acd9763ca3ff08c30c9db1807c63689983ecd205b99a6a4f4b5c4ed1c
hex(string)
Converts the entered string into the hexadecimal, positional numeral system; for an ASCII-encoded string, the function replaces non-ASCII (1-255) characters with a space.
hmac(hash_function, key, message)
Creates an authentication hash (HMAC) for MD5, SHA-1, and SHA-256, where Hash_function = (“MD5” | “SHA-1” | “SHA-256”). The returned value is a string with base64-encoded hash.
length(string)
Returns the number of characters in a string.
lowercase(string)
Converts all letters in a string to lowercase; the function may be used with variables
For example:
=lowercase("AbCdEfG") will return "abcdefg”
now()
Returns a Unix timestamp (i.e., the number of seconds elapsed since 1/1/1970, 00:00:00 UTC).
parsedatetime(string datetime, string format)
Returns the specified date and time in Unix format (i.e., number of seconds elapsed since 1/1/1970, 00:00:00 UTC). The date and time input is expected in the ICU’s Java SimpleDateFormat.
random(max)
Inputs an integer parameter and returns a random integer in the configured range (i.e., 0 to one less than whatever number is defined as “max”). This function can be used to launch a random percentage of surveys.
For example:
=random(100) will return integers between 0 and 99 (i.e., a total of 100 integers)
For an example of how to use this function, see section Scenario Building Exercises.
replace(string, search_pattern, replace_pattern, flags)
Performs search and replace in the input string. It returns the modified string after replacements are made.
Parameters:
- string - The input string to be searched.
- When passing a variable to this argument, use the 'escapejson' variable parameter if the value could contain any JSON-invalid characters such as double quotes ("), backslashes (\), or control characters (\n, etc.)
- search_pattern - The regular expression pattern to match against the string argument. The list of supported patterns can be found in the table Pattern Types below.
- Note the double backslash (\\) in the regular expression patterns. Literal insertions of the quote character (") and new line symbol (\n) are escaped with a single backslash (\).
- Use
()around a group of characters to designate a capture group that can be referenced in the replace_pattern using backreferences, where \\1 is the first capture group, \\2 is the second, and so on. For example, capture the first word from the fullname variable:=replace("$(fullname,escapejson)","(.*?)\\s+(.*?)","\\1","i")
- The search_pattern can optionally be prefixed with (*UCP) to enable the \\d (digit) and \\w (word) patterns to match Unicode characters. By default, \\d and \\w only match ASCII characters. For example, capture the first word of the fullname variable, even if fullname contains Unicode characters:
=replace("$(fullname,escapejson)","(*UCP)(\\w+)\\s+(\\w+)","\\1","i")
- replace_pattern - The text to insert in place of the text matched by the search pattern. \\1 - \\9 may be used to backreference captured character groups defined in the search_pattern.
- flags - Specify one or more of the following flags:
- i – Ignore case when matching
- g – Replace all matches instead of only the first match. For example:
replace("a8 d8","8","c","")returns"ac d8"replace("a8 d8","8","c","g")returns"ac dc"
round(floating_number, precision)
Rounds the number to the <precision> number of digits after the point. The result is still a floating point number.
stripnondigits(string)
Removes non-digit characters from string, leaving only digits from 0 to 9, * and # symbols.
For example:
stripnondigits("123abc456") will return "123456"
titlecase(string)
This function converts string to title case (i.e., each word is capitalized).
tostring(integer)
This function converts an integer to a string.
For example:
tostring(-2+1) should return "-1" as a string
unhex(string)
This function converts an ASCII-encoded hex string to an unencoded string. If the string contains characters other than 0-9, a-z, A-Z, or whitespaces, an empty string is returned; note that the following exceptions are ignored:
- \0x9
- \0xd
- \0xa
- \x20
Additionally, if the string contains a non-even number of significant characters, an empty string is returned.
Example
Invoking the function as such:
=unhex("7b227573654964223a2022553230366432356332656136626438376331373635353630396131633337636238227d")
Will return the following:
{"userId": "U206d25c2ea6bd87c17655609a1c37cb8"},Abc.123(zzz)
uppercase(string)
Converts all letters in a string to uppercase; the function may be used with variables
For example:
Where "$(item.from)" = "user_name”, =uppercase("$(item.from)") will return "USER_NAME"
urlencode(string)
URL encodes a string, replacing special characters using the %dd notation. This is a conservative implementation that replaces all characters that are not explicitly in allowed characters.
validatePAN(string)
Validates the entered primary account number (PAN) (i.e., the credit card number). The length of the number is checked to be within the 10 to 19 digit range; if it passes the Luhn check, it returns a 1 if the number is valid and 0 if the number is invalid.
Note: If the entered number starts with "2014" or "2149", which is a Diners enRoute Club card, the Luhn check is not performed.
validateCCExpirationDate(string)
Validates a four-digit credit card expiration date. The date should be in the form MMYY (four digits); the first two digits should range from 01 to 12 (month) and the last two digits shoud range from 00 to 99 (year).
The function validates the expiration date and returns the value 1 if the data is valid and 0 if the data is invalid.
Note: This function does not check the specified date against the current date, as in some cases payment processors may honor expired cards.
validateCCV(string)
Validates a credit card's CCV; it returns a 1 if the data is valid and 0 if the data is invalid.
Both three-digit and four-digit CCV numbers are recognized. A four-digit value is recognized as valid for Amex (i.e., based on analysis of a previously entered PAN); a three-digit value is recognized as valid for all other cards.
Pattern Types
| Pattern | Description |
| ^ | Match beginning of a buffer |
| $ | Match end of a buffer |
| () | Grouping and substring capturing |
| […] | Match any character from the set |
| [^…] | Match any character but the ones from the set |
| \\s | Match whitespace |
| \\S | Match non-whitespace |
| \\d | Match decimal digit |
| \\D | Match anything but decimal digit |
| \\w | Match any alphanumeric or underscore character |
| \\W | Match any character that is neither alphanumeric nor an underscore |
| \\r | Match carriage return |
| \\n | Match new line |
| + | Match one or more times (greedy) |
| +? | Match one or more times (non-greedy) |
| * | Match zero or more times (greedy) |
| *? | Match zero or more times (non-greedy) |
| ? | Match zero or once |
| \\meta | Match one of the meta characters: ^$().[*+?\ |