Expressions

The information on this help page applies to both CXone Studio and Desktop Studio.

An expression is anything in your script that compares a value or results in a value. For example, X = 5, Y = dog, and Z = "{var1}" can all be expressions if used in a way that compares the values or results in a value. For example, X = 5 compares the value of the variable X to 5. Similarly, Z = "{var1}" compares the value of the variable Z to the current value of the variable var1.

Any of the preceding examples could also be assignment statements. An assignment statement assigns the value on the right side of the equal sign to the variable on the left side. Variable assignments are not expressions.

Expressions can be used to:

Perform mathematical or algebraic calculations.
Compare two values and take an action based on the result of the comparison.
Make logical decisions based on whether an expression evaluates to true or false.

The values compared in an expressions can be made up of letters, numbers, or a combination of both. They can also include variables. In Studio there are three types of expressions, numeric, string, and Boolean.

Try it Out

Download the Expression Examples script and import it into Studio. The examples from this help page are available in Snippet actions in the example script. You can open the Snippet editor window and run the debugger to how each example works.

Numeric Expressions

Numeric expressions include only numerals and mathematical or Boolean operators, such as +, -, and so on. They can also include variable references, if the variables hold numeric values used in the calculations.

Numeric expressions are used in snippets and to configure the properties of Studio actions. For example, in the IF action, you configure the Expression property with an expression to be evaluated as the decision-making mechanism of the action. You can do the same thing in a snippet using the IF keyword.

Numeric Expression Syntax

Numeric expressions cannot be enclosed in quotes. This includes mathematical and Boolean A data type that has two possible values: true and false. expressions. If you enclose a numeric expression in quotes it's treated as text. For example, c1 = 123 + 456 evaluates to 579 but c2 = "123 + 456" results in 123 + 456.

Don't enclose variables used in numeric expressions in curly braces and double quotes. This results in an error in your script.

Evaluation of Numeric Expressions

In a numeric expression, if the script can evaluate numeric values as numbers, it does. This means that:

Anything that cannot be evaluated as a numeric value, such as letters or a word, is assumed to be a variable reference.
If non-numeric characters in the expression are a variable in the script with a string value, the script ignores the non-numeric characters and evaluates the numeric portion of the original expression.
If the non-numeric characters in the expression are a variable with a numeric value, the script includes that value in the evaluation of the expression.
If the non-numeric characters in the expression are not a variable in the script, the script ignores those characters in the original expression.

In the following example, the script attempts to evaluate nextNum as a variable because it cannot be evaluated as number: c1 = 123 + 456 + nextNum. The following examples show the outcome of three scenarios depending on whether nextNum is a variable and what its value is.

When nextNum is a variable with a string value, the result is c1 = 579:

ASSIGN nextNum = "my string"
ASSIGN c2 = 123 + 456 + nextNum

When nextNum is a variable with a numeric value, the result is c2 = 1368:

ASSIGN nextNum = 789
ASSIGN c3 = 123 + 456 + nextNum

When nextNum is not a variable, the result is c3 = 579:

ASSIGN c3 = 123 + 456 + nextNum

If you evaluate an expression that includes two variables that both hold numeric that are treated as string values, the script converts the values into numbers and evaluates them accordingly. The result of the following example is c4 = 50:

ASSIGN nextNum = "20"
ASSIGN otherNum = "30"
ASSIGN c4 = nextNum + otherNum

You can include numeric expressions in string values by enclosing the expression in curly braces. For example:

ASSIGN nextNum = 6
ASSIGN otherNum = 7
ASSIGN c5 = "There are {nextNum + otherNum} fish in the aquarium."

Numbers with Leading Zeroes

There is a difference in how Studio handles numbers when they are being treated as strings versus when they're being treated as numbers. When numbers are being treated as a string, they can have leading zeroes. If you add together two variables that hold numeric string values that have leading zeroes, the leading zeroes are removed. For example, the result of the following expression is c6=59:

ASSIGN nextNum = "00020"
ASSIGN otherNum = "000039"
ASSIGN c6 = nextNum+otherNum

If you need the resulting value to have leading zeroes, you can use the format() function and the zero placeholder to add the zeroes back to the value.

String Expressions

String expressions include alphanumeric and special characters, such as #, @, and so on. The syntax for string expressions is similar to the syntax for assigning string vales to variables:

In snippets, string values for expressions must always be enclosed in single or double quotes. This is the same as for string values
To do variable substitution in string expressions, enclose the variable name in curly braces.
Some characters, such as double quotes, are considered code. To include these characters in string values, you must use escape sequences.

String Comparisons

Strings can be evaluated as values in Boolean expressions. For example, you can use the following expression in an IF statement:

customer = "Grendel Cainson"

When customer contains the exact value Grendel Cainson, the result is true. For any other value, the result is false.

You can use greater-than and less-than operators in string comparisons. In this kind of comparison, each letter character is assigned a value (A = 1 and Z = 26). The script starts by comparing the first character. If they're different, the one that starts with a letter later in the alphabet is larger. For example, in the comparison apple > banana, the result is false. This is because banana is larger than apple, because b is later in the alphabet.

If the first characters are the same, the script compares the second characters. If they're different, the comparison stops there. If the second characters are the same, the script continues comparing characters until it reaches a pair that are different. For example, in the comparison of grapes > grapey, the script compares each character until it reaches the end. The result is false, because grapey is larger than grapes, because y is later in the alphabet than s.

In greater-than-or-equal-to or less-than-or-equal to comparisons, the same rules apply. If the scripts finds that the string on the left side of the operator is the same as the string on the right side, the expression evaluates to true.

String comparisons are case sensitive.

Escape Sequences in Strings

Studio supports escape sequences within string constants. Escape sequences allow you to include certain special characters in a string. Characters such as double quotes or an opening curly brace are recognized as code. When they're included in a string, the compiler interprets them with the non-literal code meaning instead of their literal value. Escape sequences allow you to include these characters in strings. If you include these characters in strings without an escape sequence, the output won't be what you expect, and an error may result.

You don't need to add escape sequences to strings that contain converted XML or JSON. Escape sequences are automatically added for characters that require them.

Prefix any string where you use an escape sequence with a dollar sign ($): $"...". Within the double quotes, you can use any of the following escape sequences:

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. You only need to escape the closing curly brace if there isn't an escaped open curly brace in the text before it. If you need to escape a closing curly brace, it looks like this: \}
\0	Embed a null (0 is a zero).

The following example uses the \n escape sequence to add a linefeed to the string. This moves the cursor down to the next line without returning to the beginning of the line.

x = $"A phrase\nAnd a new line"

When the string is printed, the output looks like this:

A phrase

And a new line ]

In the preceding example, the closing square bracket represents the cursor.

The following example uses the \" escape sequence to include double quotes in the string:

y = $"Embedding \"double quotes\" in a string."

When the string is printed, it looks like this: Embedding "double quotes" in a string. Without the escape sequence, the script would only recognize the string up to the double quote symbol before the word double.

The following example uses the \{ escape sequence to include literal curly braces in the string:

z = $"Using \{curly} braces."

When the string is printed, it looks like this: Using {curly} braces. Without the escape sequence, the script would have interpreted {curly} as a variable. When no value for the variable curly is found, the script would replace it with nothing, so the value of the variable would be Using braces.

Boolean Expressions

Studio supports using Boolean A data type that has two possible values: true and false. expressions. They can be used to create decision-making logic in your script. Because Boolean expressions evaluates to either true or false, you can use them to create conditions that must be met decide which path to take. If the condition is met, then the script takes that branch, but if it's not, it takes the other branch.

There are a number of operators you can use in Boolean expressions. This lets you define a logical condition statement that fits the needs of your script. For example, you can check if one value is the same as another using the equal sign (=) or you can check if one value is greater than another using the greater than operator (>).

You can use Boolean expressions with actions such as If and Snippet (help pages in CXone Studio: If and Snippet). A number of statements that you can use in snippets use Boolean expressions as the decision-making mechanism, including:

IF
IF ... ELSE
SELECT

The following example shows using a Boolean expression with an IF...ELSE statement in a snippet:

ASSIGN var1 = "Cat"
IF var1 = "Dog"
{
	ASSIGN dogWasFound = true
}
ELSE
{
	ASSIGN dogWasFound = false
}

Boolean expressions can also be used in scripting with actions. The following image shows the same IF...ELSE statement using Studio actions. You can test this example in the Expressions sample script.

A script version of the Boolean example from this section of the page.

Boolean Values to Enable or Disable Settings

Boolean values are sometimes used in scripts to enable or disable settings in CXone. In these cases, you assign a Boolean value to a variable. To enable a setting, assign the value true or 1. To disable a setting, assign the value false or 0.

Both the words and the numbers are valid Boolean values. However, check the online help for the Studio action you're using to see if there is a preferred value for the action's properties. In either case, the value you use must not be enclosed in quotes. If you enclose the value in quotes, the script treats it as a literal string instead of a Boolean value.

Operators

An operator is a symbol that represents a mathematical operation or a comparison. Symbols such as +, -, and = are operators. Boolean operators compare two expressions and result in a true/false response. Snippet supports both mathematical operators and Boolean operators.

In addition to regular mathematical operators for multiplication, division, addition, and subtraction, you can also use these operators:

Modulus operator (%)
Power/exponent (^)
Integer divide (\)
Exclusive OR (~)

Regular mathematical order of operations apply to all expressions. Anything in parentheses is evaluated first as a subunit. Exponents/power operators are evaluated second. Multiplication and division are evaluated next, then addition and subtraction. Comparison operators are the last to be evaluated, after all mathematical operations have been completed.

Boolean Operators

You can use the following Boolean operators in snippets. All of these operators can be used with numeric or stringnumeric or string comparisons. String comparisons use alphabetical order to determine which is greater or less than. In comparisons, A = 1 and Z = 26. String comparisons are case sensitive.

Operator SYMBOL	OPERATOR NAME	Details
=	Equal	If the two sides of the expression are equivalent, the expression results in true (1), otherwise the expression results in false (0).
!=	Not equal	If the two sides of the expression are not equivalent, the expression evaluates to true (1), otherwise it results in 0 false (0).
>	Greater-than	If the right side of the expression is less than the left, the expression results in true (1), otherwise it results in false (0).
>=	Greater-than-or-equal	If the right side of the expression is less than or the same as the left, the expression results in true (1), otherwise it results in false (0).
<	Less-than	If the left side of the expression is less than the right, the expression results in true (1), otherwise it results in false (0).
<=	Less-than-or-equal	If the left side of the expression is less than or the same as the right, the expression results in true (1), otherwise it results in false (0).
&	And	If all sub-expressions evaluate to true, the whole expression results in true (1), otherwise it results in false (0).
\|	Or	If either sub-expression evaluates to true, the expression results in true (1), otherwise it results in false (0).

Equal Signs in Expressions

The equal sign operator ( = ) means different things depending on the kind of expression you're working with.

The expressions used in assignment statements assign an expression to be the value of a variable. The equal sign used in these statements represents the assignment of the value on the right side of the expression to the variable on the left side.

In other expressions, the equal sign indicates evaluation of equality. For example, in the algebraic expression x = 3 * (5 + 10) the equal sign means that x represents the value resulting from the algebraic expression 3 * (5 + 10). In this case, x = 45. You can use this algebraic expression in an assignment statement to assign the value of the expression to a variable x. However, if the same expression were used as a Boolean, it would evaluate to either true or false depending on the value of x.

Boolean expressions are commonly used in Studio scripts. If you use an equal sign as the operator in these expressions, it compares the value on the left side of the equal sign to the value on the right side to determine equality. If you need to change the value of a variable used in a Boolean expression, use either an ASSIGN action or an ASSIGN statement in a Snippet action.