Variables

Variables are placeholders that store values that can change. When a script runs, variables update with new information. 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 appears in a script, it pulls in and holds the caller ID. Each time the script runs, it handles a different caller, so the value of ANI changes.

Variables can be: 

• System-defined—System-defined variables are part of the code inside the 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.. Sometimes action properties are system-defined variables that you need to supply a value for. You cannot assign a custom value to a system variable or change what value Studio expects a system-defined variable to hold. System-defined variables include reserved variables and pre-defined variables.
• User-defined—You can create your own variables with the Assign action when you need a variable to hold data to use later in the script. You can also create your own variables when you add code snippets to the Snippet action. You can define global variables that you can use in multiple scripts. You can also create dynamic data variables.

Key Facts about Variables

When using variables in Studio scripts: 

• Assign them using this syntax:

  varName = value

• Use the keyword ASSIGN if you have older Snippet code in your script. This provides backward-compatibility. For example, ASSIGN varName = value.

• Variables are implicitly typed. This means you don't need to define the data type for any variables that you use. For example, varX can be assigned a string value in one statement (varX = "hello") and an integer value in another statement (varX = 1999. The Snippet compiler determines the type each time it encounters a variable.

• 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 dollar sign is the last character in a variable name, all boolean operations (=, >, <, >=, <=) using that variable treat the value as text. For example:

    a$ = 20
    b = 100
    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, and 20 is not larger than 100.

• Assign variables date/time values using this syntax:

  #"<date or time>", where <date or time> is the date/time you want to store in the variable. For example, date1 = #"7/15/2050 5:00pm".

• Use the date/time syntax to perform operations on the date/time values. 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.

• Reference the value stored in a string variable by enclosing the variable name in curly braces. For example, The customer's name is {customerName} .becomes "The customer's name is Fenrir Lokison."

Reserved Variables

Reserved variables are read-only, which means a script cannot save values to them. These variables always return a certain kind of information. Many of them return information about the current date or time. Studio has 10 reserved variables.

Click to view reserved variables

Variable Name	Description
date	Returns the current date based on the current time zone. String expression: Formats the date in the standard date format which isMM/DD/YYYY. Numeric expression: Returns the date as an OLE Automation date/time without the fractional portion. OLE Automation is a way to write dates as floating point numbers. The left side of the decimal point is the number of days since midnight, December 30, 1899. The right side of the decimal point is the time divided by 24. For example, 6:00 AM December 31, 1899 is 1.25.
dow	Day of Week. Returns the ordinal value for the current day of week based on the current time zone, where Sunday is 0.
gmt	Returns the current Coordinated Universal (UTC) date and time. String expression: Formats the date/time in the standard RFC 1123 format which is DAY, DD MMM YYYY hh:mm:ss GMT. Example: “Mon, 03 Oct 2021 13:35:14 GMT”. Numeric expression: Returns the date/time as an OLE Automation date/time. See also utc.OLE Automation is a way to write dates as floating point numbers. The left side of the decimal point is the number of days since midnight, December 30, 1899. The right side of the decimal point is the time divided by 24. For example, 6:00 AM December 31, 1899 is 1.25.
now	Returns the current date and time based on the current time zone. String expression: Formats the date/time in the standard date and time format, which is MM/dd/yyyy hh:mm:ss tt. Numeric expression: Returns the date/time as an OLE Automation date/time. OLE Automation is a way to write dates as floating point numbers. The left side of the decimal point is the number of days since midnight, December 30, 1899. The right side of the decimal point is the time divided by 24. For example, 6:00 AM December 31, 1899 is 1.25.
test	Do not attempt to set this variable. Doing so may result in severe consequences. This is reserved for debugging code in a Snippet action.
time	Returns the current time based on the current time zone. String expression: Formats the time in the standard time format which is hh:mm:ss tt. Numeric expression:] Returns the time as an OLE Automation date/time with only the fractional portion.
timestamp	Returns the number of 100-nanosecond intervals A period between points, limits, or events, such as dates or times. that have elapsed since midnight on January 1, 0001 UTC. This can be used as an ever increasing number – guaranteed to be unique across time. It is a very large number of at least 18 digits. String expression: Returns the full 18+ digit number representing the current UTC timestamp. For example: 633911474194623828. Numeric expression: Returns a double precision (64-bit) floating point representation of the current UTC timestamp. The floating point value will be slightly less precise than the string representation. For example: 6.33911474194624E+17.
timezoneid	Returns the ID of the current time zone. This is either set at the tenant level or using the Timezoneaction.
timezoneoffset	Returns the difference (in hours) between UTC and the current time zone and the current time and date.
utc	Returns the current Coordinated Universal (UTC) date and time. String expression: Formats the date/time in the standard date and time format which is MM/dd/yyyy h:mm:ss tt. Numeric expression: Returns the date/time as an OLE automation date/time. OLE Automation is a way to write dates as floating point numbers. The left side of the decimal point is the number of days since midnight, December 30, 1899. The right side of the decimal point is the time divided by 24. For example, 6:00 AM December 31, 1899 is 1.25.
weekday	Returns the unabbreviated string representation of the current week day based on the current time zone. For example, Thursday. This is only applicable within a string expression.

Pre-Defined Variables

Pre-defined variables are already defined, so you don't need to declare them.

Click to view pre-defined variables

Variable Name	Description
ANI	The caller's telephone number.
busno	The number of your tenant. This is the unique identifier for your company in CXone.
ContactID	The unique identifier for each contact. The ContactID makes it possible to find and report on a specific contact. A new ContactID is created if a secondary script is spawned.
Country	Name of the country designated by the country code (see next item) in the phone number string of an inbound or outbound call. The CXone telephony platform generates this automatically based on  International Telecommunication Union (ITU) values and passes it in the call metadata.
Country Code	International Telecommunications Union (ITU) code designating the country of origin for an inbound call, or the country of destination for an outbound call. This code appears at the beginning of any phone number string and is passed in the call metadata. For example, the ITU code for the United States is +1. To see the country code for any given country, do an Internet search for country code <country>.
DNIS	The number that the caller dialed.
MasterID	The unique identifier for a group of related scripts. For the parent or master script the ContactID and MasterID will be the same. For any child script, the ContactID will be a new unique value and the MasterID will be the same value as the parent script's MasterID. This enables all scripts originating from the same parent to be identifiable.
__Skill	The unique identifier for the particular skill Used to automate delivery of interactions based on agent skills, abilities, and knowledge. The __Skill variable makes it possible to find and report on a specific skill.
_customFilter	The value for this variable is used as the ACD Gate filter in NICE Uptivity.
_user1 - _user 8	The value for these variables is used to populate the User 1 through User 8 fields in NICE Uptivity.
User9	While User9 is not technically a variable, it does get its value from the agent's user account, specifically from the value in Custom 1 properties and populates the User 9 field in NICE Uptivity.
User10	While User10 is not technically a variable, it does get its value from the agent's user account, specifically the value in Custom 2 properties and populates the User 10 field in NICE Uptivity.
_surveyDNIS	This value is a user-created, unique ID that is assigned when you create a NICE Uptivity survey and used to determine which survey to run during callback Holds a customer's place in queue and automatically calls the customer when they move to the front of the queue.. Would you like to see a script with this variable?
_surveyCallbackDNIS	This value is the number that will be used in the callback for the survey. This variable is for use with a NICE Uptivity survey only. Would you like to see a script with this variable?
_surveyCallbackANI	This value is the caller ID that will display during callback used for the survey. This variable is for use with a NICE Uptivity survey only. Would you like to see a script with this variable?

User-Defined Variables

You can define string and numeric variables. Because these variables are implicitly typed, the Snippet compiler determines the type of each variable when compiles the script. This means that the same variable is treated differently depending on how you use it in your script. The following table shows examples of each type of variable based on what you want to do with the variable.

Click to view variable examples

Variable Purpose	String	Numeric
Assign a literal value	TRUE	27
Assign the value of another variable	{LeftVM}	NewRate
Use in an expression	LeftVM="TRUE"	TOTAL>0
Variable Substitution	Call from {ANI}	N/A
Calculations	N/A	HourlyRate*1,25+50

You can also create dynamic data variables.

Global Variables

A global variable allows you to use one variable in multiple scripts during the same contact. They're commonly used in subscripts or spawned scripts. You can create a global variable using an Assignaction or a Snippetaction. Include the keyword Global: before the variable name.

This example shows two ways to create a global variable with the Assign action: 

Global:<variable name>

Global:<variable name>="{firstname} {lastname}"

This example shows two ways to create a global variable with the Snippet action: 

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

Dynamic Data Variables

Dynamic data variables don't have defined types. You can use them to store any type of data. Other Snippet variables are implicitly typed, which means the type is determined when the Snippet compiler compiles the code. The type of dynamic variables is determined when the script runs.

Dynamic variables can hold more than one key/value pair. You can use the variable in any Studio action in the script and access the value you need using the corresponding key. This allows you to reduce the number of variables you use in a script. For example, instead of creating three unique variables, you can create a single dynamic variable: 

DYNAMIC beowulfCharacteristics

beowulfCharacteristics.name = "Beowulf"

beowulfCharacteristics.occupation= "Hero"

beowulfCharacteristics.foe = "Grendel"

You can use dynamic data variables to: 

• Handle the responses from the Workflowdata action. This action returns workflow data in a dynamic data variable.
• Access REST responses.
• Generate REST API calls.

Declare Dynamic Variables

To declare a dynamic data variable, use the keyword DYNAMIC in your code before the variable name, then add attributes to it. For example: 

DYNAMIC beowulfCharacteristics

beowulfCharacteristics.name = "Beowulf"

beowulfCharacteristics.occupation= "Hero"

beowulfCharacteristics.foe = "Grendel"

You can use a dynamic data variable to parse JSON. Define the dynamic variable and use the FROM command to specify the JSON key/value pairs with this syntax: 

DYNAMIC var1 FROM '{ "key1": "apple", "key2": "banana", "key3": "carrot"}'

Access REST Responses

You can use dynamic data variables to access responses from REST calls. These responses are in JSON, and Studio manages them with dynamic variables. For example:

In this example, MakeRestRequest returns a dynamic data object. You can parse the returned response using the DYNAMIC var1 FROM '{ "key1": "apple", "key2": "banana", "key3": "carrot"}' syntax.

Generate REST API Calls

Generate REST API calls and send them as JSON using the asjson() method. For example:

DYNAMIC TokenInput

TokenInput.grant_type = "password"
TokenInput.username = "Grendel.Cainson"
TokenInput.password = "MadeUpPassword"

<additional TokenInput properties>

TokenJsonInput = "{TokenInput.asjson()}"

ASSIGN proxy = GETRESTProxy()
<ASSIGN additional variables>

ASSIGN TokenResponse = proxy.MakeRestRequest(TokenRequestURL,TokenJsonInput, 0, "POST")

In this example, TokenInput is declared as a dynamic variable with three attributes, grant_type, username, and password. TokenJsonInput is declared to hold TokenInput in a stringified form using the asjson() method. In the last line of the example, the variable TokenResponse is declared to hold the REST request, which can then be used in the script code to send the request.

Implicit Typing

Variables in the Snippet language are implicitly typed. You don't need to declare the type when you declare a variable. You can declare and assign a variable in one step. For example, x = 10. Implicit typing means that variables can store different types of data.

By default, numeric values are always evaluated as numbers. For example: 

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

The result here is y = 1 (true) when the values are compared as numbers. If these values were compared as text, the result would be y = 0 (false). Because these values are both numbers, this expression is evaluated numerically.

Force Comparison as Text

You can force a value to be treated as text even if it's numeric. You can do this in two ways:

• Add a dollar sign to the end of the variable. For example, if you want a1 = "100" to be evaluated as text, you would add a dollar sign to make it a1$ = "100".
• Surround the names of the variables with curly braces. For example, y = "{a1}" = "{a2}".

Force Comparison as Date or Time

You can add a pound sign (#) in front of a value if you want it to be recognized as a date or time. You can 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 Redaction

Variable redaction eliminates variable values from traces and logs generated by a script.

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, meaning that 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. These names should correspond to variables created in Assign actions in the script.
5. Click OK.