The Snippet language handles text differently than many traditional languages. There is no support for string concatenation using the plus (+) operator; the following is not supported: A = “text” + B. Instead, string expressions must always be fully enclosed in double (or single) quotes and where the value of another variable is required, you use the variable substitution syntax. To embed the value of B in a string beginning with the word ‘text’, an expression like this may be used: A = “text{B}”.
Curly braces within quotes introduce variable substitution. Complex expressions may also be used within curly braces: “text{b+10*c-a^2}”.
Brief background: the reason that Snippet string expressions do not support traditional concatenation operators is based on the origin of the expression language. Outside of Snippets, expressions are used throughout the Studio scripting environment. For example, the deprecated action Marquee accepted a text string as a message to be broadcasted to a list of agents. This text string is entered literally without the need for surrounding double-quotes. It would be counter-intuitive for a user to enter a message that is supposed to be text and require the text be enclosed in double-quotes. To allow embedding the value of a variable within a text string, then, required a new syntax – this is where the use of curly braces originated. Additionally, Snippets are just an extension to the well accepted icon-based scripting environment, so the syntax follows.
Escape Sequences
The Snippet language also supports escape sequences within string constants. To enable escape sequences, the string must be prefixed with a dollar sign ($) in this manner: $"…". Within the double-quotes, the following escape sequences are supported:
| Sequence | Details |
|---|---|
| \" | Embed a double quote. |
| \' | Embed a single quote. |
| \t | Embed a tab (ascii 9). |
| \r | Embed a carriage return (ascii 13). |
| \n | Embed a line feed (ascii 10). |
| \b | Embed a backspace (ascii 8). |
| \{ | Embed an open curly brace. |
| \0 | Embed a null (0 is a zero). |
Examples:
x = $"A phrase\nAnd a new line" y = $"Embedding \"double-quotes\" in a string"
To include curly braces in a string without causing string substitution, escape the open curly brace. The closing curly brace need not be escaped.
z = $"Using \{curly} braces"
String and Numeric Handling
A variable method is like a function but it is always bound to another object. For example, the length method returns the number of characters contained in a variable. It makes sense only in reference to the variable in question. Therefore, the expression name.length returns the length of the variable called "name."
Two types of contexts exist:
- String expressions
- Numeric expressions
String expressions are found in actions that accept arbitrary text – such as an email address or the sequence within a Play action. To allow the use of variables within strings, a unique syntax is provided called variable substitution. Variable substitution uses curly braces to designate the presence of a variable. Thus, the text my name is {name} tells the scripting engine that the value of the variable called "name" should replace the text "{name}". The text within and including the curly braces is known as the string expression.
Numeric expressions are found in actions that accept numeric values – such as the number of repetitions for a Loop action or the number of seconds to play a Music action. Within a numeric expression, no special syntax is required to reference a script variable. Simply using the variable name directly is sufficient. Numeric expressions can be more complex, however, x+1 can be used to express the addition of the value of "x" and the literal "1". Note that string expressions also support complex operations such as {x+1}.
Within Studio, both string and numeric expressions support the exact same syntax and, wherever appropriate, variable methods are applicable in both contexts.
The syntax of the variable method should be:
variable.method
or
variable.method(parameters)
Variable Methods
The following table covers all the variable methods available within the Studio. The context (Numeric or String) changes the behavior of certain methods. Where necessary, the respective context is shown within square brackets.
| Method Name | Description |
|---|---|
| asdate |
[String expression] Converts the contents of the variable to a date string. The variable must contain a numeric value representing an OLE automation date/time. [Numeric expression] Converts the contents of the variable to an OLE automation date/time by parsing the string contents. The string contents must match one of the Windows standard date formats like mm/dd/yyyy. |
| asdatetime |
[String expression] Converts the contents of the variable to a date and time string. The variable must contain a numeric value representing an OLE automation date/time. [Numeric expression] Converts the contents of the variable to an OLE automation date/time by parsing the string contents. The string contents must match one of the Windows standard date/time formats like mm/dd/yyyy hh:mm:ss. |
| asjson |
Convert a JSON object in a script and assign it to a new variable. The below example is with a Dynamic Data object, but you can do it with return objects from an API call or the objects from bot actions (TextBot, VoiceBot, and so forth). DYNAMIC object1
ASSIGN object1.var1 = "val1"
ASSIGN object1.var2 = "val2"
ASSIGN objectjson = "{object1.asjson()}"
|
| astime |
[String expression] Converts the contents of the variable to a time string. The variable must contain a numeric value representing an OLE automation date/time. An OLE automation date/time is a double-precision floating-point number that represents a date as the number of days before or after the base date, midnight, 30 December 1899. The sign and integral part encode the date as a positive or negative day displacement from 30 December 1899, and the absolute value of the fractional part encodes the time of day as a fraction of a day displacement from midnight. [Numeric expression] Converts the contents of the variable to an OLE automation date/time by parsing the string contents. The string contents must match one of the Windows standard time formats like HH:mm:ss. |
| dow | The variable must contain a numeric value representing an OLE automation date/time. Returns the day of week as an ordinal value from 0 to 6 where 0 is Sunday. |
| asdatedow | Converts the contents of the variable to an OLE automation date/time by parsing the string contents, and then returns the day of week as an ordinal value from 0 to 6 where 0 is Sunday. The string contents must match one of the Windows standard date formats like MM/dd/yyyy. |
| length | Returns the length of the textual representation of the variable’s value. For instance, if the value is a number like 1234.56, the length will be 7. |
| size | If the variable contains an array, this returns the number of elements within the array. If the value is not an array, but is not empty, the value 1 is returned. Otherwise, 0 is returned. |
| count | This is a synonym for size. |
| indexof(text) | Returns the character position of the text as contained within the variable. The first position is 1. If the text is not contained, the value 0 is returned. The method is case sensitive. |
| isdigit | Returns 1 (true) if the first character within the variable is a numeric digit (0-9). Otherwise, 0 (false) is returned. |
| isletter | Returns 1 (true) if the first character within the variable is a letter of the alphabet (A-Z, a-z). Otherwise, 0 (false) is returned. |
| isupper | Returns 1 (true) if the first character within the variable is an uppercase letter (A-Z). Otherwise, 0 (false) is returned. |
| islower | Returns 1 (true) if the first character within the variable is a lowercase letter (a-z). Otherwise, 0 (false) is returned. |
| datepart(unit) |
Returns a portion of a date or time. The variable must contain a numeric value representing an OLE automation date/time. The unit specifies the date part to return. Possible choices for unit are: year, month, day, hour, minute, second, and dow. Enclose the unit in double or single quotes, or pass a variable which contains the unit name. The unit name is case sensitive. [String expression] Returns the string representation of the specified date part. Month returns the 3 character month abbreviation. Year returns the full 4 digit year. Hour returns the hour in 24 hour format. All numeric values, except year, are prefixed with a 0 if there are less than two digits. Dow stands for Day of Week and is returned as the full string representation of the week day, unabbreviated. [Numeric expression] Returns the numeric representation of the specified date part. Year returns the full 4 digit year. Hour returns the hour in 24 hour format. Dow stands for Day of Week and is returned as the ordinal value for the week day where Sunday is 0. |
| datediff(unit, date2) |
Returns the difference between two dates. The variable must contain a numeric value representing an OLE automation date/time. The unit specifies the date part to compare and date2 specifies the date to compare with the value from the variable. If date2 is greater than the value within the variable, the results will be positive. Possible choices for unit are: week, day, hour, minute, and second. Enclose the unit in double or single quotes, or pass a variable which contains the unit name. The unit name is case sensitive. If the difference is fractional, the return value will be fractional also. For instance, if the variable contains the date “10/15/2021 6:00 AM” and date2 is “10/16/2021 6:00 PM”, the result for unit day will be 1.5. |
| dateadd(unit, value) |
Returns a new date based on the original date plus value in either OLE automation format or as a string formatted date. The interpretation of value is determined by the unit. Possible choices for unit are: year, month, week, day, hour, minute, and second. Enclose the unit in double or single quotes, or pass a variable which contains the unit name. The unit name is case sensitive. [String expression] Resulting date will be formatted as a standard date/time string: MM/dd/yyyy h:mm.ss AM/PM. [Numeric expression] Resulting date will be a floating point value in OLE automation format. |
| index(value) | Returns the specified array element within the variable. This is synonymous to reading an array using square brackets. variable[3] is the same as variable.index(3). |
| asgmt |
[String expression] Converts the contents of the variable to a date/time string formatted to RFC 1123 which is “ddd, dd MMM yyyy HH:mm:ss GMT”. Example: “Mon, 03 Oct 2021 13:35:14 GMT”. [Numeric expression] Converts the contents of the variable to an OLE automation date/time translated to Coordinated Universal Time (UTC). The variable must contain a valid string representation of a date/time. The source time is based on the tenant |
| asutc | This is a synonym for asgmt. |
| left(count) |
[String expression] Returns the left most count characters. [Numeric expression] Takes the left most count characters and tries to read them as a number. If the characters do not represent a number, 0 will be returned instead. |
| right(count) |
[String expression] Returns the right most count characters. [Numeric expression] Takes the right most count characters and tries to read them as a number. If the characters do not represent a number, 0 will be returned instead. |
| substr(start, end) |
[String expression] Returns the characters from start through end. The first character position is 1. If end exceeds the length of the source text, it will automatically truncate at the end of the source text. [Numeric expression] Takes the characters from start through end and tries to read them as a number. If the characters do not represent a number, 0 will be returned instead. |
| mid(start, length) |
[String expression] Returns the characters from start through start+length. The first character position is 1. If start+length exceeds the length of the source text, it will automatically truncate at the end of the source text. [Numeric expression] Takes the characters from start through start+length and tries to read them as a number. If the characters do not represent a number, 0 will be returned instead. |
| replace(old, new) |
Replaces all occurrences of old with new. You must use single quotes inside the parentheses and enclose in curly braces and double quotes. For example:
ASSIGN String= "Anyone can do this. I believe in you." |
| upper | Returns the contents of the variable with all letters converted to upper case. |
| lower | Returns the contents of the variable with all letters converted to lower case. |
| urlencode | Returns the contents of the variable encoded using the Internet standard for URL encoding. |
| urldecode | Returns the contents of the variable decoded from the Internet standard for URL encoding. |
| datefmt(format) |
Converts the contents of the variable to a date and time string using custom formatting. The variable must contain a numeric value representing an OLE automation date/time. The value of format specifies how the resulting date/time string will be returned. |
| split(delimiter) |
Returns the contents of the variable as a pipe delimited string suitable to be treated as an array. The delimiter will be converted to the pipe (|) symbol. When the results are assigned to a new variable, the new variable will behave like an array and will support the array indexer syntax as in variable[index]. Split can also be used within a Snippet to convert a variable to an array. Using it in this manner will change the contents of the variable. Example:
ASSIGN a=”one,two,three,four,five” a.split(“,”) Output: three |
| isalpha | Returns 1 (true) if all characters within the variable are letters of the alphabet (A-Z, a-z). Otherwise, 0 (false) is returned. An empty variable returns 0 (false). See also isletter. |
| isnumeric | Returns 1 (true) if the textual value within the variable can be converted to a number. Otherwise, 0 (false) is returned. See also isdigit. |
| trim | Returns a string with all leading and trailing white space characters removed. White space includes spaces, tabs, and line breaks. |
| ltrim | Returns a string with all leading white space characters removed. See trim. |
| rtrim | Returns a string with all trailing white space characters removed. See trim. |
| contains(value) | Returns 1 (true) if the variable contains the value specified. If the variable is an array, all elements will be checked for the exact value specified. It is case sensitive. |
| format(format) | Returns a string formatted using the format specified. The format applies only to the numeric value contained within the variable. |
| append(text) |
Only applicable within a Snippet. This method will append the text to the end of the existing contents of the variable. Example:
ASSIGN a="one two" |
