Variables

Variables are placeholders that store values that can change. Use them when a value is different each time a script runs. For example, ANI is a variable that holds the caller's ANI Also known as caller ID. Listed phone number of an incoming voice call., or phone number. When ANI is used in a script, it holds the contact's caller ID. Each time the script runs, it handles a different contact, so the value of ANI changes.

You can create your own variables anytime you need one. Variables can hold single values. They can also hold dynamic data objects and arrays.

Some variables used in Studio scripts are system-defined. This means they're part of the code inside Studio actions Performs a process within a Studio script, such as collecting customer data, playing a message or music, or routing a contact to an agent. so you don't have to create them. There are two kinds of system-defined variables:

• Reserved variables: Read-only variables that you can use when you need to include a specific kind of information in your script.
• Pre-defined variables: Variables that are already defined. They're writable, so you can assign a value to them.

Try It Out

Download the Variable 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.

Variable Syntax Summary

The following list summarizes variable syntax. More information about these points is available in other sections on this page.

• Create and assign a value to a variable using an ASSIGN action or a Snippet action. In a Snippet, you can use the ASSIGN keyword when you declare a variable. It's optional, but highly recommended. Use this syntax in a Snippet: ASSIGN <var name> = <var value> or <var name> = <var value>.

• When assigning values to a variable: 
  • String and date/time values must be enclosed in single or double quotes. For example:  ASSIGN life = "forty-two".
  • To assign a date/time value that will be used with date/time functions, place a pound sign ( # ) in front of the value, but outside of the double quotes. For example: ASSIGN var = #"02/09/2023". If the date/time value will not be used with date/time functions, you don't need to use the pound sign character. However, without the pound sign, the value is a string type, not a date/time type.
  • Numeric values don't need to be enclosed in quotes. If you enclose a numeric value in quotes, it's treated as a string unless it's being evaluated in a mathematical expression.
  • Numeric and Boolean A data type that has two possible values: true and false. expressions cannot be enclosed in quotes. If a these expressions are enclosed in quotes, it's treated as a string. For example: ASSIGN myVar = var2 > 42 evaluates to true or false depending on the value of var2. However, ASSIGN myVar = "var2 > 42" results in the value of myVar being literally var2 > 42.
  • Boolean values should not be enclosed in quotes.
  • Use escape sequences if you need to include the following characters in a string value: double quotes ( " ), single quote ( ' ), open curly brace ( { )tab (ASCII 9), carriage return (ASCII 13), line feed (ASCII 10), backspace (ASCII 8), null.
• When substituting a variable's value in a string: 
  • Enclose variables in curly braces. For example: ASSIGN myVar = "the meaning of life is {life}"
  • If the variable is a dynamic data object, you must refer to a property within the object. For example: ASSIGN myVar = "the meaning of life is {anObj.thisProperty}". Referring to the object alone will result in an error.
  • If the variable contains an array, you must include the index of the value you want to assign. For example: ASSIGN myVar = myArray[4].
• When assigning the value of one variable to another:
  • You don't need double quotes or curly braces. For example:  ASSIGN myVar = var2. This results in a copy of the variable's value being assigned to myVar.
  • If a variable contains an array, you can assign it to another variable.
  • If a variable is an object, you can only assign it to another object.

• When referring to variables in Studio action properties, the following guidelines generally apply. Always refer to the online help page for the action you're using, as there are exceptions to these statements.

  • Properties expect either a variable or data. Data can consist of literals or variables. When a property expects data, generally it can accept either a literal or a variable. However, exceptions exist, so always refer to the online help for the action if you're not sure what a property expects.

  • If the property expects a variable name, enter the name of the variable without curly braces.

  • If the property expects data and you want to use variable substitution, enclose the variable name in curly braces: {varName}.

Data Types and Implicit Typing

Data types define what kind of data a variable holds and how it should be used in the program. In Studio, variables can have the following data types:

• String: The variable’s value contains alphanumeric and special characters, such as periods, commas, and underscores. String values must be enclosed in double quotes.
• Numeric: The variable’s value is a number. Numeric values don't need double quotes.
• Date/Time: The variable's value is a date, time, or both. When a date/time value is used with date/time functions in Studio, the value must be enclosed in quotes and be preceded by a pound sign outside of the quotes: var = #"11-23-2023".
• Boolean: The variable's value is either true or 1, or false or 0. Do not enclose Boolean values in quotes.

In many programming and scripting languages, you must explicitly assign a data type to a variable when you create it. In Studio, variables are implicitly typed. The Studio compiler determines the type of each variable when it compiles the script. This means you don't need to define the data type for any variables that you use. The only exception is when a variable holds a date/time value that you want to use with date/time functions.

Type Inference

Implicit typing impacts the way variables are evaluated. For example, comparisons of variables have different outcomes depending on what type Studio recognizes the variables as. The default behavior in Studio is that everything is treated as a string until mathematical calculations are required. Then, if something can be evaluated as a number, it will be, even if it's enclosed in quotes. This is known as type inference.

The Studio compiler recognizes a value as numeric even if it's enclosed in quotes. Quotes signify that a value is a string. When a numeric value is enclosed in quotes, Studio treats it as a string unless you use it in mathematical calculations in the script. For example: 

var1 = "42"
var2 = 42

var3 = var2 + var1	

The result of the example is var3 = 84. Studio infers that the value of var1 is numeric and treats it as such when evaluating the expression in var3, even though it's enclosed in double quotes.

Create Variables

You can create your own variables to use in scripts. You can do this using either an Assign action or a Snippet action in the script.

Assign Action

The Assign action lets you create a single variable and assign a value to it. You do this using the action's Variable and Value properties. The benefit of Assign is that it's an easy-to-use, configurable way to create variables.

This action has other properties that allow you to define how the variable is used. You can:

• Have the variable's value included in the screen pop A configurable pop-up window with information about the contact. It appears on an agent's screen after a certain event, usually when the agent connects to a contact. that's assigned at the ACD skill Used to automate delivery of interactions based on agent skills, abilities, and knowledge level.
• Have the variable's value saved to the database.

Snippet Action

The Snippet action is a code-based way to create variables . Using a single action, you can create one or more variables, in addition to any other custom code you may need to include. The benefit of using Snippet is that if you want to add more variables to your script later, you can add them to the same action. You don't need to add more actions and redo the connectors in your script, as you would if you had originally used an Assign action.

Use either of the following syntax formats:

ASSIGN varName = value or varName = value

You can add properties to the variable that match the properties in the Assign action:

• To have the variable's value included in a screen pop, add setscreenpop(1) to the variable name.
• To have the variable's value saved to the database, add savetodb(1) to the variable name.

For example: 

ASSIGN epicPoem = "Beowulf"
epicPoem.setscreenpop(1)
epicPoem.savetodb(1)

For both properties, the 1 is a Boolean A data type that has two possible values: true and false. value that sets the property to true.

Key facts about creating variables in Snippet actions: 

• You don't need to declare the type when you declare a variable, except for date/time variables.
• Including the ASSIGN keyword is optional. However, it's best practice to use this keyword every time you create a variable. When you use advanced search, you can quickly locate where a variable is created if it includes this keyword.
• If you declare a variable in a subscript and want it passed back to the originating script, add global: to the beginning of the variable name. This denotes it as global in scope.

Single Quotes, Double Quotes, or No Quotes

When assigning the value of a variable to another variable, some values must be enclosed in quotes. Other values don't need quotes. Follow these guidelines: 

• String values must be enclosed in single or double quotes. This is true even if the variable name ends in a dollar sign. If a string is not enclosed in quotes, the script assumes the value is a variable. In the following example, a1, a2, and a1$ all evaluate to the literal value Example. The value of a3 and a3$ depend on whether Example has been declared as a variable. If a variable Example exists in the script, a3 and a3$ evaluate to the value of Example. If Example doesn't exist, a3 and a3$ result in empty values.

  ASSIGN a1 = "Example"
  ASSIGN a2 = 'Example'
  ASSIGN a1$ = "Example"
  ASSIGN a3 = Example
  ASSIGN a3$ = Example

• Numeric values don't require quotes. However, you can use them if you want to. In the following example, b1, b2, and b3 all evaluate to 123.

  ASSIGN b1 = "123" 
  ASSIGN b2 = '123' 
  ASSIGN b3 = 123

• 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.
• Date/time values must be enclosed in quotes if you're declaring them as the date/time type.
• Boolean values should not be enclosed in quotes.
• If you're assigning an array or a dynamic object member's value to a variable, do not use quotes or curly braces with the array or object member name.

Create Variables with Date/Time Values

Studio does not implicitly identify date/time as a type. However, you can add an identifier before a variable value to declare it as this type. You only need to do this if the value will be used in date/time functions or if you want to perform operations with the value.

To declare a variable value as a date/time, use the syntax ASSIGN <varName> = #"<datetime>", where <datetime> is the date/time value you want to store in the variable. For example, date1 = #"7/15/2050 5:00pm". If a variable isn't declared as a date/time, you can use the asdatetime() function to convert it to one.

Some functions that manipulate dates and times require the variables to be declared as a date/time. Even if the date/time format is correct, the function won't work if the variable isn't properly declared. You can also use this syntax to perform operations on dates and times that you wouldn't otherwise be able to do. For example, you can compare them:

date1 = #"7/15/2050 5:00pm" 
date2 = #"7/15/2050 4pm"
x = date1 > date2 

The result is 1 (true) because the literal value of date1 is greater than the literal value of date2.

Variable Naming

Name variables following these guidelines: 

• Use alpha-numeric characters (a-z, A-Z, 0-9).

• The first character in the name must be a letter.
• Use the underscore character ( _ ) and the dollar sign ( $ ) anywhere in the name.
• If the last character in a variable name is a dollar sign, the value is treated as text.
• Do not use the names of pre-defined variables or reserved words.

Variable Substitution

When you need to use a variable's value in your script, include the name of the variable in the snippet code or in the action's property field.

If you are substituting the variable's value into a string, enclose the name of the variable in curly braces. In a string, everything is treated as plain text unless it's formatted as a variable. For example: 

ASSIGN foeName = "Grendel"
ASSIGN numberFoes = "3"
ASSIGN x = numberFoes
ASSIGN y = "One of Beowulf's foes is {foeName}. He faced {numberFoes} foes in all." 
ASSIGN z = "One of Beowulf's foes is foeName. He faced numberFoes in all." 

The results of the example are : 

• x=3.
• y=One of Beowulf's foes is Grendel. He faced 3 foes in all.
• z=One of Beowulf's foes is foeName. He faced numberFoes in all.

When you're copying the value of a variable onto another variable, you don't need to use curly braces. This applies to text and numeric values. In the following example, the result is:x=3 and z=Grendel: 

ASSIGN numberFoes = "3"
ASSIGN name = "Grendel"
ASSIGN x = numberFoes 
ASSIGN y = name 

If you're doing mathematical operations with variables, you don't need to enclose them in curly braces. In the following example, the result is y=200.

ASSIGN a1 = "100"
ASSIGN a2 = "100.00"
ASSIGN y = (a1 + a2) 

Variable Substitution in Action Properties

Many action properties can accept variables in place of literal values. This is true even if the action's help page doesn't specify that you can use a variable to configure a property.

Using variables in action properties allows you to reuse scripts. For example, if your organization has three lines of business, you would need three queuing scripts to define the ACD skill Used to automate delivery of interactions based on agent skills, abilities, and knowledge, priority management and other settings for each line of business if you use literal values. If you use variables to configure the properties where the value differs between lines of business, you can have one script instead of three.

When referring to variables in Studio action properties, the following guidelines generally apply: 

• Properties expect either a variable or data. Data can consist of literals or variables. When a property expects data, generally it can accept either a literal or a variable. However, exceptions exist, so always refer to the online help for the action if you're not sure what a property expects.

• If the property expects a variable name, enter the name of the variable without curly braces.

• If the property expects data and you want to use variable substitution, enclose the variable name in curly braces: {varName}.

Pass Variable Values from Script to Script

Variable values can pass from script to script. They can pass from the:

• Originating Script to Subscript: All variables in the originating script are present and available for use in subscripts . However, they are in global scope. To use them in subscripts, you need to preface the variable name with global:. For example, global:varName. This includes pre-defined system variables and variables that you create.
• Subscript to Originating Script: Variables that you declare in a subscript do not automatically pass back to the originating script. If you want to pass a custom variable from a subscript back to the originating script, you must declare it as global. Similarly, if you declare variables in a sub-subscript, you must declare them as global and reference them as global in the subscript and the top-level originating script.

You can view global variables in script traces. You may need to enable this option in the Trace Output window when viewing a trace.

Some data may come from a source outside your scripts, such as a CRM Third-party systems that manage such things as contacts, sales information, support details, and case histories. or an API APIs allow you to automate certain functionality by connecting your CXone system with other software your organization uses. call. You can pass these values into subscripts or spawned scripts using the Parameters property in the RunSub action or the Spawn action. The Begin action also has a Parameters property. Configure the Begin action in the subscript with the names of variables to receive the values passed through the RunSub or Spawn.

If the data you need to pass is contained in an object, the object must be converted into JSON or XML first. You can pass the variable that contains the JSON or XML string. In the second script, you can reform the data into an object, if you want to.

Variable Comparison and Evaluation

The fact that Studio implicitly types variables impacts how they're in evaluated expressions and Boolean A data type that has two possible values: true and false. comparisons.

For example: 

ASSIGN a1 = "100"
ASSIGN a2 = "100"
ASSIGN y = (a1 = a2)

In this example, the expression y = (a1 = a2) evaluates to y = 1 (true).

Force Comparison as Text

You can force a variable to be evaluated as text even if its value is numeric. You can do this in two ways:

• Add a dollar sign to the end of the variable name. For example: varName$ = 42. When doing a comparison, only one of the two variables needs a dollar sign suffix.
• Surround the names of the variables with curly braces and double quotes. For example, y = ("{a1}" = "{a2}").

When a variable name ends in a dollar sign, all Boolean An attribute of information that defines how it is used in a program, such as integer (numbers that can be manipulated) or boolean (true/false). operations (=, >, <, >=, <=) using that variable treat the value as text. For example: 

ASSIGN a$ = 20
ASSIGN b = 100
ASSIGN x = a$ > b

In this example, the variable x is 1 (true). Because the variable a$ ends with a dollar sign, the value 20 is treated as text. This means that a$ > b is a comparison of 20 and 100 as strings of text and not integers. When comparing as text, 20  is larger than 100 because 20 starts with a 2 and 100 starts with a 1. Without the dollar sign in the variable name, x = a > b is 0 (false) because the values are compared as integers. The integer 20 is not larger than the integer 100.

Reserved and Predefined Variables

There are preexisting variables in Studio. They are: 

• Reserved Variables: These variables return a certain kind of information, such as the current time or the ID of the current time zone. Reserved variables are read-only, which means a script cannot save values to them. They exist only to return information. You can use them in your script when you want to input the information they return. Studio has 10 reserved variables.
• Predefined Variables: These are system variables. They're already defined in Studio, so you can use them in your scripts without creating them. Use system variables in your scripts anytime you need the information they hold. Only override predefined system variables if the online help or a CXone Account Representative instructs you to. You can learn more about predefined variables on the Predefined Variables page.

Global Variables

Global variables allow you to declare a variable in a subscript and have it automatically passed back to the originating script after the Return action. When you declare a global variable in a subscript, you don't have to pass it back to the originating script with the Return action.

You can create a global variable using the Snippet action or the Assign action. Use the following syntax when creating a global variable with Snippet:

ASSIGN global:<variable name>

ASSIGN global:<variable name>="{firstname} {lastname}"

Ensure that there is no space between the colon and the variable name.

If you're using the Assign action, do not include the ASSIGN keyword.

You don't need to declare variables in the originating script as global. Limiting the declaration of global variables to subscripts provides you a visual clue about the script you're working in. When you see global:var, you know you're in a subscript.

Global Variables Example

The following example shows how to use global variables.

View All Variables in a Script

There are two ways to see all of the variables in your script: 

• The Variables tab in Studio shows you all variables used in a script. If this tab is closed, open it by clicking Validation > Windows > Variables.
• You can also see the variables used in a script when you run a trace. As you select each line in the trace output, the variables in the script at that point are visible in the Variables pane. You can click through each line in the trace to see how the contents of the variables changes as the script progresses.

Variable Redaction

Variable redaction eliminates variable values from traces and logs generated by a script. You can redact variables and objects.

Redaction is configured at the script level in the VariableRedaction field of a script's properties. Redacted values are replaced with a string of X characters. The length of the variable value determines how many X's are used. A redacted five-letter word would result in five X's. Partial variable redaction, such as part of a credit card number, is not supported.

1. In Studio, click on the script canvas to make sure nothing is selected.
2. Click the Properties tab.
3. Click the Ellipsis button next to the VariableRedaction field to open the String Collection Editor.
4. Enter the names of the variables you want to redact. Place one variable per line.
5. Click OK.
6. If you want to delete data from the variable, place a Snippet action in the script after the sensitive data has been used and is no longer needed.
7. Double-click Snippet action and add the following to the Text View tab in the Snippet editor window: 
   • For a dynamic data object: DYNAMIC <object name>
   • For a regular variable: ASSIGN <var name> = ""
8. Click OK to save your changes.