m (Elizabeth moved page 5.3:Scenario-builder-reference-guide/Built-inFunctions to 5.3:Scenario-builder-reference-guide/VariablesandExpressions/Built-inFunctions)
Revision as of 20:02, 15 March 2019
A number of built-in functions may be used in the Scenario Builder application.
To invoke a function from a text field, prefix it with an equal sign. Example: =now("UTC")
The functions are described as follows.
formatdatetime(int unixtimestamp, string format)
This function 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.
Example: "yyyy-MM-dd'T'HH:mm'Z'" yields 2012-07-20T20:45:44.0973928Z
This function converts duration in specified in seconds into MM:SS or HHH:MM:SS formats. It produces formatted string as output (e.g., formatduration(121) will return "02:01").
hmac(hash_function, key, message)
This function is used to create an authentication hash (HMAC) for MD5, SHA-1, and SHA-256, where Hash_function = (“MD5” | “SHA-1” | “SHA-256”). Returned value is a string with base64-encoded hash.
This function returns the number of characters in a string.
This function returns the current time in the specified time zone in Unix format (number of seconds elapsed since 1/1/1970, 00:00:00 UTC). Time zone is optional; if not specified, the current time will be returned in the tenant’s default time zone.
parsedatetime(string datetime, string format)
This function returns the specified date and time in Unix format (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.
replace(string, search_pattern, replace_pattern, flags)
- This function performs search and replace in the input string. It returns the string with replacements performed.
- Parameters are as follows:
- string is the input string to be searched.
- search_pattern is the regular expression pattern to be matched in the input string. The list of supported patterns can be found in the table below. Note the extra \ in escapes. This is necessary in order to allow literal insertions of " and new line symbols.
- replace_pattern is the text to insert instead of matched text according to search pattern. \\0 - \\9 are allowed in replacements.
- flags denote one or more of the following additional conditions:
- i – ignore case in the search
- g – replace all matches because otherwise only the first match will be replaced (e.g., replace("abcdefg","c","z","ig") produces "abzdefg").
Example that takes first name from fullname variable and could be used in value section of Set Variable block: =replace("$(fullname)","(.*)\s+(.*)","\1","i")
This function takes one integer parameter and returns a random integer number in the configured range (i.e., 0 to whatever number is defined as “max”). This function can be used to launch a random percentage of surveys.
For an example of how to use this function, see section Scenario Building Exercises.
This function rounds the number to the <precision> number of digits after the point. The result is still a floating point number.
This function removes non-digit characters from string, leaving only digits from 0 to 9, * and # symbols (e.g., stripnondigits("123abc456") will return "123456").
This function converts string to title case (i.e., each word is capitalized).
This function converts an integer to a string (e.g., tostring(-2+1) should return "-1" as a 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.
Pattern types are described as follows.
|^||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|
|\\d||Match decimal digit|
|\\D||Match anything but decimal digit|
|\\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: ^$().[*+?\|