Built-In Functions

Studio has built-in functions that you can use in your scripts. Some of the built-in functions are available in the auto-completion list that pops up when you type in the Snippet editor window. There are other built-in functions that aren't available in this list, but you can still use them. Detailed information about all available built-in functions is available in the second half of this page.

This page also provides lists of the built-in functions grouped into categories. This makes it easier to locate a function when you know the kind of data you're working with and what you'd like to accomplish, but not the function name. You can view lists of functions that allow you to: 

• Work with dates and times
• Work with numbers
• Work with letters
• Perform calculations
• Modify values
• Determine what's in a value
• Extract part of a value
• Work with arrays

There's also a list with other functions that don't fit into a category.

You can learn more about using functions in Studio, including creating your own custom functions, on the Functions help page.

Try It Out

Download the Function 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 see how each example works.

Functions to Use with Dates and Times

Use following functions with dates and times in your scripts. Studio supports 24-hour time, not 12-hour time. Take this into consideration when working with time in scripts.

Functions to Use with Numbers

Use the following functions with variables that contain numeric values. Other functions that you can use with numbers are the functions for mathematical calculations.

Functions to Use with Letters

Use the following functions with variables that contain letters:

Functions to Perform Calculations

Use these functions to perform mathematical calculations. These functions aren't available in the auto-completion list that pops up when using a SNIPPET action, but they work if you enter them manually.

Functions to Modify Values

Use the following functions when you want to change something about a variable's value when assigning the value to a different variable.

In addition to the functions in this table, many of the functions for dates and times allow you to modify values. For example, you can convert a date value to different date format.

Functions to Determine What's in a Value

Use these functions to see what a variable contains:

Functions to Extract Part of a Value

Use these functions when you want to pull part of a value from a variable to use in a different variable:

Functions to Use with Arrays

The following functions work with arrays.

Other

ASSIGN val1 = "name"
ASSIGN popthis = val1.setscreenpop(1)

All Available Functions

This section provides detailed information about using each built-in function. Unless otherwise specified, you can call these functions anywhere you would use a variable or expression.

abs(value)

Returns the absolute value of the specified value.

ASSIGN abVal = "{abs(-42)}"

The result of the example is abVal = 42

acos(value)

Returns the angle in radians whose cosine is the specified value.

ASSIGN angleRad3 = "{acos(cosNum)}"

The result of the example is angleRad3 = 0.394791119699762

append(string)

Appends the string to the end of the existing contents within the variable. This function only works within a Snippet or an ASSIGN action.

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

The results of the example are:

• originalString = My name is Inigo Montoya.

• originalString2 = Whose pajamas are these? They're the cat's pajamas.

asdate()

Converts the contents of a variable to a date/time string using the default date format.

When used as a string expression: Converts the contents of the variable to a date/time string.

When used as a 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.

IF TEST = 1
{
  ASSIGN myDate = "{date}"
}

//This example converts a date string into its OLE numeric equivalent
ASSIGN numericDate = myDate.asdate()

//This example converts an OLE numeric date to its string equivalent
ASSIGN stringDate = "{numericDate.asdate()}" 

The results of this example depend on the current local date when the function runs. If the current local date is 07/03/2023. the results are: 

• numericDate = 45110
• stringDate = 07/03/2023

asdatedow()

Converts the contents of the variable to an OLE automation date-time by parsing the string contents, and then returns the day of the 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.

IF TEST = 1
{
  ASSIGN MyDate = "07/03/2023"
}
ASSIGN MyDow = MyDate.asdatedow()
SWITCH MyDow
{
  CASE 0   { ASSIGN newToday = "Sunday" }
  CASE 1   { ASSIGN newToday = "Monday" }
  CASE 2   { ASSIGN newToday = "Tuesday" }
  CASE 3   { ASSIGN newToday = "Wednesday" }
  CASE 4   { ASSIGN newToday = "Thursday" }
  CASE 5   { ASSIGN newToday = "Friday" }
  CASE 6   { ASSIGN newToday = "Saturday" }
}

The results of the example are

• myDow = 1
• newToday = Monday

asdatetime()

Converts the value of the variable to a date/time string using the specified date/time format.

When used as a string: Converts the contents of the variable to a date and time string.

When used as a numeric value: 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 such as MM/dd/yyyy HH:mm:ss.

If you pass in a date without a time, the function adds a time. It defaults to 12:00 AM.

IF TEST = 1
{
  ASSIGN MyDateTime = "{now}"
  ASSIGN anotherDateTime = "04/03/23 11:34:09 PM"
}
ASSIGN numericDateTime = myDateTime.asdatetime()
ASSIGN numericDateTime2 = anotherDateTime.asdatetime()

ASSIGN stringDateTime = "{numericDateTime.asdatetime()}"
ASSIGN stringDateTime2 = "{numericDateTime2.asdatetime()}"
		

The results of the example are:

• numericDateTime = 45110.3720486111 (when the current local time date/time is 7/3/2023 8:55:45 AM)
• numericDateTime2 = 45019.9820486111
• stringDateTime = 7/3/2023 8:55:45 AM
• stringDateTime2 = 4/3/2023 11:34:09 PM

asgmt() and asutc()

The asgmt() function converts time into GMT and the asutc() function converts time into UTC. The format of the date depends on the original contents of the variable.

When with a string expression: The functions convert the value to an OLE automation date/time translated into GMT or UTC. The variable must contain a valid string representation of a date/time. The source time is based on the tenant High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment time zone or the time zone set through the Timezone action (help page in CXone Studio: Timezone action).

When used with a numeric expression: The functions convert the value to a date/time string translated into GMT or UTC. For example: “Mon, 03 Oct 2022 13:35:14 GMT”.

When using these functions, the format of the time contained in the variable cannot include either:

• An offset from UTC.
• A Z character, such as 2022-03-04 18:54:39.000Z. Including a Z indicates that the time has zero offset from GMT/UTC.

Including either of these causes an error when asgmt() or asutc() attempts to convert time zones because the original time zone is seen as being different from the business unit's time zone. In addition, to avoid the error while using the ISO 8601 date/time format, include a Timezone action before the Snippet action and set it to use your business unit's time zone. This sets the time zone at the script level so the script and your business unit have the same time zone.

IF TEST = 1
{
  ASSIGN MyDateTime = #"{now}" 
}

ASSIGN GMTDateTimeNumeric = MyDateTime.asgmt()
ASSIGN GMTDateTimeString = "{GMTDateTimeNumeric.asdatetime()}"

ASSIGN UTCDateTimeNumeric = MyDateTime.asutc()
ASSIGN UTCDateTimeString = "{UTCDateTimeNumeric.asdatetime()}"

asin(value)

Returns the angle in radians whose sine is the specified value.

ASSIGN angleRad4 = "{asin(sinNum)}"

The result of the example is angleRad4 = 0.394791119699762

asisodatetime()

Converts the value of a variable to an ISO 8601 date/time format: yyyy-MM-ddTHH:mm:ss.SSSXXX. The output of this function is always the ISO date/time format.

In REST API calls, ISO time stamps that have an offset from UTC specified and appear in the response are converted to Mountain Time (MT). If no offset is specified, the timestamp is not converted.

IF TEST = 1
{
	ASSIGN myDateTime = "{now}"
	ASSIGN anotherDateTime = "04/03/23 11:34:09 PM"
}
ASSIGN numericDateTime = myDateTime.asisodatetime()
ASSIGN numericDateTime2 = anotherDateTime.asisodatetime()
ASSIGN stringDateTime = "{numericDateTime.asisodatetime()}"
ASSIGN stringDateTime2 = "{numericDateTime2.asisodatetime()}"

The results of the example are:

• numericDateTime = 2023-07-03T09:43:06.000Z (when the current local time date/time is 7/3/2023 9:43:06 AM)
• numericDateTime2 = 2023-04-03T23:34:09.000Z
• stringDateTime = 2023-07-03T05:43:06.000Z
• stringDateTime2 = 2023-04-03T19:34:09.000Z

asjson() and asxml()

Converts a JSON or XML object to a string and assigns it to a new variable. The following example uses a dynamic data object, but you can use these functions with objects returned from an API call or the objects from virtual agent bot A software application that handles customer interactions in place of a live human agent. actions).

The asjson() function converts everything in the object as a string with double quotes around it, including numeric or Boolean A data type that has two possible values: true and false. values. You can account for this in your script if you need a properly-formatted numeric or Boolean value in your JSON. One solution is to use the replace() function. It allows you to replace the double quotes in the string value with null.

DYNAMIC object1
ASSIGN object1.value1 = "this"
ASSIGN object1.value2 = "that"
DYNAMIC object2				
ASSIGN object2.value1 = "first"
ASSIGN object2.value1 = "last"			

ASSIGN objectjson = "{object1.asjson()}"
ASSIGN objectxml = "{object2.asxml()}"		

Another solution is to inject placeholder strings that are manually replaced after you convert the dynamic object into a JSON string.

ASSIGN integerValue = 1234
ASSIGN trueValue = true
ASSIGN falseValue = false
DYNAMIC object
ASSIGN object.myIntegerValue = "INTEGERVALUE_PLACEHOLDER"
IF trueValue = true
  {
	ASSIGN object.myTrueValue = "TRUE_PLACEHOLDER"
  }
ELSE
  {
	ASSIGN object.myTrueValue = "FALSE_PLACEHOLDER"
  }
IF falseValue = true
  {
	ASSIGN object.myFalseValue = "TRUE_PLACEHOLDER"
  }
ELSE
  {
	ASSIGN object.myFalseValue = "FALSE_PLACEHOLDER"
  }
ASSIGN objectJSON = "{object.asjson()}"

ASSIGN objectJSON = objectJSON.replace("{char(34)}TRUE_PLACEHOLDER{char(34)}","true").replace("{char(34)}FALSE_PLACEHOLDER{char(34)}","false")
ASSIGN objectJSON = objectJSON.replace("{char(34)}INTEGERVALUE_PLACEHOLDER{char(34)}",integerValue)

Best practice: Use the asjson() function in a Snippet actionand store the resulting JSON in a string variable. Use the string variable in the properties of other Studio actions when you need to pass the JSON data. This approach avoids the possibility of validation errors when saving the script.

The results of the example are:

• objectjson={"value1":"this","value2":"that"}

• objectxml=<?xml version="1.0" encoding="utf-16" standalone="yes"?><DynamicDataObject><value1>first</value1><value2>last</value2></DynamicDataObject>

astime()

Converts the contents of a variable to a time value.

When used with a string value: Converts the contents of the variable to an OLE automation A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899. date-time. For example, 0.353506944447872.

When used with a numeric value: Converts the contents of the variable to a time string. The variable must contain an OLE automation time value. For example, 8:29:03 AM.

IF TEST = 1
{
  ASSIGN myTime = "{time}"
}

//This example converts a time string into its OLE numeric equivalent
ASSIGN numericTime = myTime.astime()

//This example converts a OLE numeric time to its string equivalent
ASSIGN stringTime = "{numericTime.astime()}" 

The results of this example depend on the local time when testing the function. If the value of time is 8:37:42 AM, the results are: 

• numericTime = 0.359513888892252
• stringTime = 8:37:42 AM

atan(value)

Returns the angle in radians whose tangent is the specified value.

ASSIGN angleRad = "{atan(0.4166666666666667)}"		

The result of the example is angleRad=0.394791119699762

atan2(value)

Returns the angle in radians whose tangent is the quotient of the two specified numbers (x, y).

ASSIGN angleRad2 = "{atan2(5,12)}"

The result of the example is angleRad2=0.394791119699761

ceil(value) and floor(value)

ceil returns the smallest whole number greater than or equal to the specified value.

floor returns the largest whole number less than or equal to the specified value.

IF TEST = 1
{
  ASSIGN value = 102.589
}
ASSIGN newValue1 = floor(value)

ASSIGN newValue2 = ceil(value)

The results of the example are:

• newValue1 is 102.
• newValue1 is 103.

contains(value)

Returns a value of 1 (true) if the variable contains a specified value. If the variable is an array, all the elements are checked for the exact value.

contains() is not case-sensitive.

IF TEST = 1
{
  ASSIGN varString1 = "abc!123"
  ASSIGN varString2 = "8001234567|8881234567|8771234567"
  ASSIGN dnis = 8881234567
  ASSIGN dnis2 = 8887654321
}
ASSIGN stringFoundRes1 = varString1.contains('!') // true
ASSIGN stringFoundRes2 = varString1.contains('D') // false 

ASSIGN DNISFoundRes1 = varString2.contains(dnis) // true
ASSIGN DNISFoundRes2 = varString2.contains(dnis2) // false

The results of the example are:

• stringFoundRes1 is 1 (true).
• stringFoundRes2 is 0 (false).
• DNISFoundRes1 is 1 (true).
• DNISFoundRes2 is 0 (false).

char(code)

Returns a character from the ASCII code value, which enables a script to programmatically add special characters to a string. For example, you can add carriage returns, tabs, and new line characters.

IF TEST = 1
{
  ASSIGN textToSpeech = "John Doe"
  ASSIGN varWithCommas = "one,two,three,four"
}

ASSIGN character1 = "{char(34)}"
ASSIGN character2 = "{char(44)}"
ASSIGN character3 = "{char(39)}"

ASSIGN marqueeMessage = "Marquee {char(10) char(13)} Message on {char(10) char(13)} different lines."

ASSIGN promptListWithDoubleQuotes = "{char(34)}Prompts\File with space.wav{char(34)} {char(34)}{textToSpeech}{char(34)}"

ASSIGN varWithReplacedCommas = "{varWithCommas.replace(char(44),' ')}"

ASSIGN character4 = "{char(123)}"
ASSIGN character5 = "{char(125)}"
ASSIGN cssWithReplacedBrackets = "a {char(123)}text-decoration: none;{char(125)}"

The results of the example are:

• marqueeMessage = "Marquee

  Message on

  different lines."

• promptListWithDoubleQuotes = "Prompts\File with space.wav" "John Doe"
• varWithReplacedCommas = one two three four

• cssWithReplacedBrackets = a {text-decoration: none;}

copy(objectName)

Creates a copy of the data that the dynamic data object objectName holds. The copy is separate from the original, so you can change a value in one version and not affect the same value in the other version. Learn more about copying dynamic objects.

You can use the copy() function with sub-properties: For example: currentContact.who = copy(beowulfCharacteristics.name).

DYNAMIC firstObject
DYNAMIC secondObject

secondObject = copy(firstObject)

cos(value)

Returns the cosine of the specified value. The value must be in radians.

ASSIGN angleRad = 0.394791119699762 //in radians
ASSIGN cosNum = "{cos(angleRad)}"		

The result of the example is cosNum=0.923076923076923

cosh(value)

Returns the hyperbolic cosine of the specified value. The value must be in radians.

 ASSIGN hCosine = "{cosh(angleRad)}"

The result of the example is hCosine=1.07894746856059

count() and size()

Returns the number of elements within an array. size() works only with arrays. count() works with arrays in objects.

If the value is not an array but is not empty, the value 1 (true) is returned. If the value is empty, 0 (false) is returned.

IF TEST = 1
{
  ASSIGN example1 = "Beowulf|Grendel|Hrothgar|Wyrm|Breca|Scyld|Hrethel"
  ASSIGN example2 = "8015551234"
  ASSIGN example3 = ""
  DYNAMIC example4 
  ASSIGN example4[1].name = "Beowulf"
  ASSIGN example4[2].name = "Grendel"
}
ASSIGN ex1Size = example1.size()
ASSIGN ex2Size = example2.size()
ASSIGN ex3Size = example3.size()

ASSIGN ex1Count = example1.count()
ASSIGN ex2Count = example2.count()
ASSIGN ex3Count = example3.count()

ASSIGN ex4Count = count(example4)

The results of the example are:

• exSize and ex1Count are 7.
• ex2Size and ex2Count are 1.
• ex3Size and ex3Count are 0.
• ex4Count is 2.

dateadd(unit, date, value)

Returns a new date based on date plus value.. The new date is returned in as an OLE automation A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899. date/time. The interpretation of value is determined by unit. If value is negative, value is subtracted from date.

Best practice is to pass in a valid date/time variable, as shown in the example below, where the value of myDateTime has a number sign ( # ) in front of it. This makes it a date/time variable.

Possible choices for unit are: year, month, week, day, hour, minute, and second.

unit is case sensitive. Enclose unit in double or single quotes, or pass a variable that contains unit. If passing a variable, do not enclose the variable in quotes or curly braces.

To use this function in a string, include asdatetime(), as shown in the example below.

IF TEST = 1
{
  ASSIGN myDateTime = #"{now}"
}
//These are examples of adding to a datetime variable:

ASSIGN newDateYearNumeric = dateadd('year', myDateTime, 1) //add a single year
ASSIGN newDateYearString = "{newDateYearNumeric.asdatetime()}"

ASSIGN newDateMonthNumeric = dateadd('month', myDateTime, 1) //add a single month
ASSIGN newDateMonthString = "{newDateMonthNumeric.asdatetime()}"

ASSIGN newDateWeekNumeric = dateadd('week', myDateTime, 1) //add a single week
ASSIGN newDateWeekString = "{newDateWeekNumeric.asdatetime()}"

ASSIGN NewDateDayNumeric = dateadd('day', MyDateTime, 1) //add a single day
ASSIGN NewDateDayString = "{NewDateDayNumeric.asdatetime}"

ASSIGN newDateHourNumeric = dateadd('hour', myDateTime, 1) //add a single hour
ASSIGN newDateHourString = "{newDateHourNumeric.asdatetime()}"

ASSIGN NewDateMinuteNumeric = dateadd('minute', myDateTime, 1) //add a single minute
ASSIGN NewDateMinuteString = "{NewDateMinuteNumeric.asdatetime()}"

ASSIGN newDateSecondNumeric = dateadd('second', myDateTime, 1) //add a single second
ASSIGN newDateSecondString = "{newDateSecondNumeric.asdatetime()}"

//This is an example of subtracting from a date:
ASSIGN oldDateMonthNumeric = dateadd('month', myDateTime, -2) //remove 2 months
ASSIGN oldDateMonthString = "{0ldDateMonthNumeric.asdatetime()}"

The results of the example are as follows, using 3 March 2023 in the format 3/3/2023 10:42:44 AM as the value of now: 

newDateYearString = 3/3/2024 10:42:44 AM

newDateMonthString = 4/3/2023 10:42:44 AM

newDateWeekString = 3/10/2023 10:42:44 AM

newDateDayString = 3/4/2023 10:42:44 AM

newDateHourString = 3/3/2023 11:42:44 AM

newDateMinuteString = 3/3/2023 10:43:44 AM

newDateSecondString = 3/3/2023 10:42:45 AM

datebuild(year, month, day)

Returns a date/time string using the provided Year, Month, and Day.

When used in a string:  Returns a numeric date formatted in the standard date/time format, which includes the time. The time defaults to midnight. If you want the date using the names of months and days, use the asdate() or asdatetime() functions, as shown in the example below.

When used in a numeric expression: Returns a date as an OLE automation A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899. date-time string.

IF TEST = 1
{
  ASSIGN month = "1"
  ASSIGN day = "24"
  ASSIGN year = "1936"
}

ASSIGN stringDate1 = "{datebuild(Year,Month,Day).asdate}"
ASSIGN stringDate2 = "{datebuild(Year,Month,Day)}"

ASSIGN numericDate = datebuild(Year,Month,Day)

The results of the example are:

• stringDate1 = 1/24/1936
• stringDate2 = 1/24/1936 12:00:00 AM
• numericDate = 13173

datediff(unit, date2)

Returns the difference between two dates, date1 and date2.

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 are positive.

Possible choices for unit are: week, day, hour, minute, and second.

unit is case sensitive. Enclose unit in double or single quotes, or pass a variable that contains unit. If passing a variable, do not enclose the variable in quotes or curly braces.

If the difference is fractional, the return value is also fractional. For instance, if the variable contains the date-time 10/15/2022 6:00 AM and date2 is 10/16/2022 6:00 PM, the result for unit day is 1.5.

IF TEST = 1
{
  ASSIGN myDateTime = #"{now}"
  ASSIGN myBirthday = #"4/24/1936 10:42 PM"
}
ASSIGN weekDiff = datediff("week", myBirthday, myDateTime)
ASSIGN dayDiff = datediff("day", myBirthday, myDateTime)
ASSIGN hourDiff = datediff("hour", myBirthday, myDateTime)
ASSIGN minuteDiff = datediff("minute", myBirthday, myDateTime)
ASSIGN secondDiff = datediff("second", myBirthday, myDateTime)

The results of the example are:

• dayDiff = 1584.9546875
• hourDiff = 38038.9125
• minuteDiff = 2282334.75
• secondDiff = 136940085
• weekDiff = -368.850553902116

You can use datediff() to determine if a week is even or odd. This is helpful if your organization's hours of operation alternates every other week, or is open every other Saturday.

If your hours of operation alternate open and closed, set the value of the HOO variable in the IF statement to when your office is open. Set the value of HOO in the ELSE statement to when your office is closed.

ASSIGN currentDateTime = #"{now}"
ASSIGN startingDateTime = #"6/04/2016 3:16:10 PM"
ASSIGN weekDiff = datediff("week", currentDateTime, startingDateTime)
ASSIGN numberOfWeek = ceil(weekDiff)

IF numberOfWeek % 2 = 0 {
HOO = 123
}
ELSE {
HOO = 124
}		

The results of the example depend on the value of now when the function runs.

datefmt(date, format)

Outputs date using the specified format string. The value of date must be one of the following: 

• A date specified using the date/time prefix (#) followed by a valid string representation of a date. For example: ASSIGN myDate = #"April 8, 1968"
• An OLE automation A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899. date/time. For example: ASSIGN thisDate = "24936.6402853983"
• The reserved variable now, which returns the current date and time.

When you define the output format, use the format specifiers to define how you want the date and time to look.

ASSIGN currentTime = now
ASSIGN formCurrentTime1 ="{datefmt(currentTime, 'yyyy-MM-dd HH:mm:ss')}"
ASSIGN formCurrentTime2 ="{datefmt(currentTime, 'MM/dd/yyyy hh:mm:ss')}"
ASSIGN formCurrentTime3 ="{datefmt(currentTime, 'HHmmssyyyyMMdd')}"
ASSIGN formCurrentTime4 ="{datefmt(currentTime, 'HH:mm:ss')}"

The results of the example are: 

• formCurrentTime1 = 2023-06-30 14:03:17
• formCurrentTime2 = 06/30/2023 02:03:17
• formCurrentTime3 = 14031720230630
• formCurrentTime4 = 14:03:17

The datefmt() function also allows you to extract part of the date from an existing date/time value. To do this, use this syntax: 

ASSIGN <var> = "{<date var>.datefmt('<format>')}"

For example: 

ASSIGN myDate = #"{now}"
ASSIGN myYear2 = "{myDate.datefmt('yyyy')}"

The result of the example is myYear2 = 2023

datepart(unit)

Returns a portion of a date or time. Returns a portion of a date or time according to the specified unit. The variable must contain a date/time type or a string that's a properly-formatted date/time or OLE automation number A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899.. unit specifies the date part to return. This function must be called on a date/time variable. It will not work if you pass a date/time value into the function, it will not work.

Possible choices for unit are: year, month, day, hour, minute, second, and dow.

unit is case sensitive. Enclose unit in double or single quotes, or pass a variable that contains unit. If passing a variable, do not enclose the variable in quotes or curly braces.

If the function cannot complete due to incorrect or unexpected input, the default output is December 30, 1899.

When used in a string: 

 Returns the string representation of the specified date part:

• Month returns the three-character month abbreviation.
• Year returns the full four-digit year.
• Hour returns the hour in 24-hour format.
• Dow stands for Day of Week and returns the full. unabbreviated string representation of the name of the day of the week. For example, Thursday.

All numeric values except year are prefixed with a 0 if there are fewer than two digits.

When used in a numeric expression: 

Returns the numeric representation of the specified date part: 

• Year returns the full four-digit year.
• Hour returns the hour in 24-hour format.
• Dow stands for Day of Week and returns the ordinal value (0-6) for the weekday, where Sunday is 0, Monday is 1, and so on.

IF TEST = 1
{
  ASSIGN myDateTime = now
}
ASSIGN myYear = myDateTime.datepart('year')
ASSIGN myHour = myDateTime.datepart('hour')				
ASSIGN myMinute = myDateTime.datepart('minute')
ASSIGN mySecond = myDateTime.datepart('second')
				
ASSIGN stringMyDay = "{myDateTime.datepart('day')}"
ASSIGN numericMyDay = myDateTime.datepart('day')
				
ASSIGN stringMyMonth = "{myDateTime.datepart('month')}"
ASSIGN numericMyMonth = myDateTime.datepart('month')
							
ASSIGN stringMyDow = "{myDateTime.datepart('dow')}"
ASSIGN numericMyDow = myDateTime.datepart('dow')

The results of the example are:

• myYear = 2023
• myHour = 13
• myMinute = 51
• mySecond = 3
• stringMyDay = 30
• numericMyDOW = 5
• stringMyDOW = Friday
• numericMyMonth = 6
• stringMyMonth = Jun

datetimebuild(year, month, day, hour, minute, second)

Returns a date/time value. If the function cannot complete due to incorrect or unexpected input, the default output is December 30, 1899.

When used in a string: Returns a date/time formatted in standard date/time format.

When used as a numeric expression: Returns an OLE automation A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899. date/time .

IF TEST = 1
{
  ASSIGN month = "1"
  ASSIGN day = "24"
  ASSIGN year = "1985"
  ASSIGN hour = "15"
  ASSIGN minute = "42"
  ASSIGN second = "13"
}
ASSIGN stringDate = "{datetimebuild(year,month,day,hour,minute,second)}"
ASSIGN numericDate = datetimebuild(year,month,day,hour,minute,second)

The results of the example are:

• numericDate = 31071.6543171296
• stringDate = 1/24/1985 3:42:13 PM

dow()

Returns the day of week as an ordinal value from 0 to 6 where 0 is Sunday.

The variable must contain a date/time type or a string that's a properly-formatted date/time or OLE automation number A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899.. If the function cannot complete due to incorrect or unexpected input, the default output is December 30, 1899.

ASSIGN myNow = "{now}"
ASSIGN myDow = myNow.dow()

The results of the function depend on the value of now when dow is evaluated.

format(specifiers)

Returns a string formatted using the specifiers specified. The specifiers applies only to the numeric values contained within the variable. For pscifiers, use the following format specifiers: 

• C or c: Currency
• E or e: Scientific/exponential
• F or f: Fixed-point

• N or n: Number

• P or p: Percent
• R or r: Round-Trip
• X or x: Hexadecimal

• 0: Zero placeholder

You can learn more about these numeric formats to use with this function.

IF TEST = 1
{
  ASSIGN stringVal = "0013001.93912837"
  ASSIGN stringVal2 = 6002348902348890234.234432234
}
ASSIGN currencyResultBigC = "{stringVal.format('C3')}"
ASSIGN currencyResultLilC = "{stringVal.format('c')}"

ASSIGN scientificResult = "{stringVal.format('e')}"
ASSIGN scientificResult2 = "{stringVal.format('E2')}"

ASSIGN fixedPointResult = "{stringVal.format('F3')}"
ASSIGN fixedPointResult2 = "{stringVal.format('f')}"


ASSIGN numberResult = "{stringVal.format('N')}"
ASSIGN numberResult2 = "{stringVal.format('n4')}"

ASSIGN percentResult = "{stringVal.format('P')}"
ASSIGN percentResult2 = "{stringVal.format('P2')}"

ASSIGN roundTripResult = "{stringVal.format('R')}"

ASSIGN number1 = "1789789"
ASSIGN sectionSeparator1 = number1.format('###,###.##;0000.00;000.0000')

ASSIGN number2 = "0"
ASSIGN sectionSeparator2 = number2.format('0.00;0000.00;000.0000')

ASSIGN number3 = "-4321"
ASSIGN sectionSeparator3 = number3.format('0.00;0000.00;000.0000')

ASSIGN number6 = "2343.56"
ASSIGN digitPlaceholders1 = number6.format('###.###')

//Examples of the double ## and 00 placeholders

ASSIGN number4 = "456.47"
ASSIGN doubleZeroSpecifier = number4.format('00')

ASSIGN number7  = "456.47"
ASSIGN doubledigitSpecifier = number7.format('##')

//in the following example, notice the 0 in the hundredths place. 
//With the zero placeholder, it appears in the output. With the # placeholder
//it does not. 

ASSIGN number5 = "2343456.2043"
ASSIGN zeroPlaceholders = number5.format('000,000.00')

ASSIGN number8 = "2043456.2043"
ASSIGN digitPlaceholders2 = number8.format('###,###.##')

The results of the example are:

• currencyResultBigC = $13,001.939
• currencyResultLilC = $13,001.94
• fixedPointResult = 13001.939
• fixedPointResult2 = 13001.94
• numberResult = 13,001.94
• numberResult2 = 13,001.9391
• percentResult = 1,300,193.91%
• percentResult2 = 1,300,193.91%
• roundTripResult = 13001.93912837
• scientificResult = 1.300194e+004
• scientificResult2 = 1.30E+004

index(indexValue)

Returns the array element from the variable's contents according to the specified indexValue. This is the same as reading an array using square brackets. For example, variable[3] is the same as variable.index(3).

Arrays in Studio start with 1, not 0.

IF TEST = 1
{
  ASSIGN example1 = "Beowulf|Grendel|Hrothgar|Wyrm|Breca|Scyld|Hrethel"
  ASSIGN indexValue = 3
}
ASSIGN arrayPart1 = "{example1.index(indexValue)}"

indexof(string)

Returns the character position of the string as contained within the variable. The first position is 1. If the variable does not contain string, the function returns the value 0. This function is case sensitive.

IF TEST = 1
{
  ASSIGN example1 = "Beowulf|Grendel|Hrothgar|Wyrm|Breca|Scyld|Hrethel"
  ASSIGN example2 = "The Epic Poem"
}
ASSIGN arrayLoc = example1.indexof('Breca')
ASSIGN characterLoc = example2.indexof('E')
ASSIGN invalidLoc = example2.indexof('e')

iif(compare, trueval, falseval)

Inline-If for numbers. Evaluates compare, then returns either trueval or falseval depending on results from the evaluation.

If compare is non-zero (true), the trueval is returned.

If compare is zero (false), the falseval is returned.

Both trueval and falseval must be numeric values or expressions. Strings cannot be used. This function is identical to the iifs() function, except it expects numeric values.

ASSIGN val1 = 4 > 5
ASSIGN val2 = 4  < 5

ASSIGN test1 = val1 > val2
ASSIGN test2 = val1 < val2

ASSIGN trueS = "you win"
ASSIGN falseS = "try again"

ASSIGN varFalse = "{iif(test1,trueS,falseS)}"

ASSIGN varTrue = "{iif(test2,trueS,falseS)}"

The results of the example are:

• varFalse = "try again"
• varTrue = "you win"

iifs(compare, truestr, falsestr)

String inline-if. Evaluates compare, then returns either trueval or falseval depending on results from the evaluation.

If compare is non-zero (true), the truestr is returned.

If compare is zero (false), the falsestr is returned.

This function is identical to iif() except it expects strings.

ASSIGN val1 = "grapes" 
ASSIGN val2 = "grapey"

ASSIGN test1 = val1 >  val2
ASSIGN test2 = val1 <  val2

ASSIGN trueS = "you win"
ASSIGN falseS = "try again"

ASSIGN varFalse = "{iifs(test1,trueS,falseS)}"

ASSIGN varTrue = "{iifs(test2,trueS,falseS)}"

The results of the example are :

• varFalse = "try again"
• varTrue = "you win"

isalpha()

The isalpha() function returns 1 (true) if all characters within the variable are letters of the alphabet (A-Z, a-z). If all of the characters are not alphabetic, the function returns 0. An empty variable or a value that includes special characters (such as # or $) or numbers return 0. See also: isletter().

IF TEST = 1
{
  ASSIGN varAlpha = "abcde"
  ASSIGN varNum = "12345"
}
ASSIGN alphaRes1 = varAlpha.isalpha() //true
ASSIGN alphaRes2 = varNum.isalpha() //false

isdigit()

The isdigit() function returns 1 (true) if the first character within the variable is a numeric digit (0-9). Otherwise the function returns 0 (false). An empty variable or a value that starts with a special characters returns 0. See also: isletter().

IF TEST = 1
{
  ASSIGN example1 = "12Monkeys"
  ASSIGN example2 = "Oceans11"
}
ASSIGN result1 = example1.isdigit() //This is True
ASSIGN result2 = example2.isdigit() //This is False

isletter()

The isletter() function returns 1 (true) if the first character within the variable is a letter of the alphabet (A-Z, a-z). Otherwise the function returns 0 (false). An empty variable or a value that starts with a special character returns 0. See also: isdigit().

IF TEST = 1
{
  ASSIGN example1 = "12Monkeys"
  ASSIGN example2 = "Oceans11"
}
ASSIGN result3 = example1.isletter() //This Is False
ASSIGN result4 = example2.isletter() //This Is True

isnumeric()

The isnumeric()function returns 1 (true) if the all characters within the variable are numbers. If any of the characters are non-numeric, the function returns 0An empty variable or a value that includes special characters (such as # or $) or numbers return 0. See also: isdigit().

IF TEST = 1
{
  ASSIGN varAlpha = "abcde"
  ASSIGN varNum = "12345"
}
ASSIGN numRes1 = varNum.isnumeric() //true
ASSIGN numRes2 = varAlpha.isnumeric() //false

islower() and isupper()

The isupper() function returns 1 (true) if the first character of the variable is an uppercase letter. Otherwise the function returns 0 (false).

The islower() function returns 1 (true) if the first character of the variable is a lowercase letter. Otherwise the function returns 0 (false).

IF TEST = 1
{
  ASSIGN example1 = "Beowulf"
  ASSIGN example2 = "monster fighter"
}
ASSIGN result1 = example1.isupper() //This is true
ASSIGN result2 = example2.isupper() //This is false
ASSIGN result3 = example1.islower() //This is false
ASSIGN result4 = example2.islower() //This is true

left(number) and right(number)

Returns the left- or right-most number characters.

IF TEST = 1
{
  ASSIGN example1 = "Abc.456"
  ASSIGN locationVar = 4
}
ASSIGN stringLeftVariable = "{example1.left(locationVar - 1)}"
ASSIGN numericLeftVariable = example1.left(locationVar - 1)
ASSIGN stringRightVariable = "{example1.right(locationVar + 1)}"
ASSIGN numericRightVariable = example1.right(locationVar + 1)

The results of the example are: 

• numericLeftVariable = Gre
• numericRightVariable = 34567
• stringLeftVariable = Gre
• stringRightVariable = 34567

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 is returned as 7. Spaces and special characters count toward the length.

IF TEST = 1
{
  ASSIGN example1 = "8015551234"
  ASSIGN example2 = 2357.984
  ASSIGN example3 = "Beowulf Herot"
}

ASSIGN ex1Len = example1.length()
ASSIGN ex2Len = example2.length()
ASSIGN ex3Len = example3.length()

The results of the example are: 

• ex1Len = 10
• ex2Len = 8
• ex3Len = 13

ln(value)

Returns the natural (base e) logarithm of the value. The value is specified as a base 10 number.

ASSIGN natLog = "{ln(434)}"

The result of the example is natLog=6.07304453410041

log10(value)

Returns the base 10 logarithm of the specified value.

ASSIGN log10Num = "{log10(434)}"

The result of the example is log10Num=2.63748972951251

log2(value)

Returns the base 2 logarithm of the specified value. The value is specified as a base 10 number.

ASSIGN log2Num = "{log2(434)}"

The result of the example is log2Num=8.76155123244448

logn(value,base)

Returns the logarithm of the specified value in the specified base. Both parameters are specified as base 10 numbers.

ASSIGN lognNum = "{logn(434,5)}"

The result of the example is lognNum=3.77339472817288

max(value1,value2) and min(value1,value2)

max() returns the larger of the two numeric values specified.

min() returns the smaller of the two numeric values specified.

If you pass in string values, both functions always evaluate to 0.

IF TEST = 1
{
  ASSIGN value1 = 10
  ASSIGN value2 = 12
}
ASSIGN resultMin = min(value1, value2)

ASSIGN resultMax = max(value1, value2)

The results of the example are:

• resultMin = 10
• resultMax = 12

mid(start,length)

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 automatically truncates at the end of the source text.

This function is similar to substr(). Both mid() and substr() return a subset of characters. The difference is that with substr(), the function returns the characters between the specified starting and ending points. With mid(), the function returns a specified number of characters, defined by length, after the specified start.

IF TEST = 1
{
  ASSIGN phoneNum = "8015553549"
  ASSIGN fullName = "Hrothgar King"
}
ASSIGN localNumber = "{phoneNum.mid(4,7)}"

ASSIGN spaceLoc = fullName.indexof(' ')
ASSIGN fullNameLength = fullName.length
ASSIGN firstName = "{fullName.mid(1,SpaceLoc - 1)}"
ASSIGN lastName = "{fullName.mid(SpaceLoc + 1,fullNameLength - spaceLoc)}"

The results of the example are:

• firstName = Hrothgar
• lastName = King
• localNumber = 1234567

random(value)

Returns an integer, non-negative random number greater than or equal to zero and less than the specified maximum value.

If you need a value within the range of one through value, you can add 1 to the random function's output:

ASSIGN d20Result = random(20) + 1

IF TEST = 1
{
  ASSIGN value = 10
}
ASSIGN newValue1 = random(Value)
ASSIGN newValue2 = random(Value)
ASSIGN newValue3 = random(Value)
ASSIGN newValue4 = random(Value)

replace(old,new)

Replaces all occurrences of old with new. This function works with all of the following formatting variations:

• ASSIGN result = "{value.replace(char,'-')}"
• ASSIGN result = value.replace(char,'-')
• ASSIGN result = value.replace('{char}','-')
• ASSIGN result = value.replace("{char}",'-')

IF TEST = 1
{
	ASSIGN replaceTest1 = "$1234.56"
	ASSIGN replaceTest2 = "Beowulf%Grendel^Hrothgar*@Grendel\'s mom"
	ASSIGN replaceTest3 = "It   was   a   hard   battle."
	ASSIGN replaceTest4 = "Beowulf%Grendel^Hrothgar*@Grendel\'s mom"
}

//The first example will replace the dollar sign in an amount with nothing

ASSIGN replaceTest1 = "{replaceTest1.replace('$','')}"

//The second example we are just replacing random charcters and replacing
//them with a space.  The final result is a space between each name

ASSIGN replaceTest2 = "{replaceTest2.replace('%',' ')}"
ASSIGN replaceTest2 = "{replaceTest2.replace('^',' ')}"
ASSIGN replaceTest2 = "{replaceTest2.replace('*',' ')}"
ASSIGN replaceTest2 = "{replaceTest2.replace('@','')}"

ASSIGN replaceTest3 = "{replaceTest3.replace('  ',' ')}"
ASSIGN replaceTest3 = "{replaceTest3.replace('  ',' ')}"

//The following example is the second example, but broken out so 
//each step is preserved in a separate variable that you can see
//in the Debugger panel on the right. 

ASSIGN replaceTest4a = "{replaceTest4.replace('%',' ')}"
ASSIGN replaceTest4b = "{replaceTest4a.replace('^',' ')}"
ASSIGN replaceTest4c = "{replaceTest4b.replace('*',' ')}"
ASSIGN replaceTest4d = "{replaceTest4c.replace('@','')}"

The results of the example are:

• replaceTest1 = 1234.56
• replaceTest2 = Beowulf Grendel Hrothgar Grendel\'s mom
• replaceTest3 = It was a hard battle.
• replaceTest4 = Beowulf%Grendel^Hrothgar*@Grendel\'s mom
• replaceTest4a = Beowulf Grendel^Hrothgar*@Grendel\'s mom
• replaceTest4b = Beowulf Grendel Hrothgar*@Grendel\'s mom
• replaceTest4c = Beowulf Grendel Hrothgar @Grendel\'s mom
• replaceTest4d = Beowulf Grendel Hrothgar Grendel\'s mom

round(value)

Returns the value rounded to the nearest integer using IEEE Standard 754, section 4 (also called banker's rounding).

IF TEST = 1
{
  ASSIGN numEx = 102.5689
}
ASSIGN newValue = round(numEx)

The result of the example is numEx = 102.5689

savetodb(1or0)

This function saves the value of a variable to the database at the end of the interaction. Be aware that the value of a variable can change as a script runs. Various actions and processes can modify or clear a variable's value. If this happens and you want to save the value from a specific point in the script, you may need to create a new variable, assign the desired value to it, and use savetodb() with it.

savetodb() isn't a true function. It's a property of variables in Studio. You can apply it to variables when working in snippets. You can also set it when using the Assign action. You can access the stored data in two ways: 

• In the Custom Data report in Data Download.
• On the Published Variables tab in the Contact History prebuilt report.

Add savetodb() to a variable with 1 as the argument to have the variable's value saved to the database, as shown in the following example: 

ASSIGN variable='123123123'
variable.savetodb(1)

If using savetodb() in subscript spawned with a RUNSUB action, you must declare the variable as global. This ensures that the variable will persist after the subscript returns control to the calling script. If you don't declare the variable as global, it's a local variable, which only exists in the subscript. savetodb() only works with variables that exist in the calling script.

screenpop() and setscreenpop(1or0)

screenpop() and setscreenpop() aren't true functions. They're properties of variables in Studio that you can set when working with screen pops 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.. You can apply them to variables when working in snippets. You can also set them with the Assign action.

Add setscreenpop() to a variable with 1 as the argument to have the variable's value passed to the screen pop.

Add screenpop() to a variable to check if the ScreenPop flag is set. The property returns 1 if true and 0 if false.

ASSIGN val1 = "name"
//ASSIGN popthis = val1.setscreenpop(1)
ASSIGN ispop = thispop.screenpop

sgn(value)

Returns a value that indicates the sign of the specified value. Returns -1 if value is less than zero, 0 if value is equal to zero, and 1 if value is greater than zero.

ASSIGN signOfNum = "{sgn(89)}, {sgn(0.00)}, {sgn(-89)}"

The result of the example is signOfNum = 1, 0, -1

sin(value)

Returns the sine of the specified value. The value must be in radians.

ASSIGN angleRad = 0.394791119699762
ASSIGN sinNum = "{sin(angleRad)}"

The result of the example is sinNum = 0.384615384615385

sinh(value)

Returns the hyperbolic sine of the specified value. The value must be in radians.

ASSIGN hSine = "{sinh(angleRad)}"

The result of the example is hSine=0.405126696125173

split(delimiter)

Returns the contents of the variable as a pipe-delimited string suitable to be treated as an array. The delimiter is converted to the pipe ( | ) symbol.

When the results are assigned to a new variable, the new variable behaves like an array and supports 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 changes the contents of the variable.

IF TEST = 1
{
  ASSIGN varString = "one,two,three,four"
}
//Example One using split to assign result to a new variable

ASSIGN varArray = "{varString.split(',')}"

//Example Two using split to change the value of an existing variable to an array

VvarString.split(',')

The results of the example are:

• varArray = one|two|three|four
• varString = one|two|three|four

sqrt(value)

Returns the square root of the specified value.

ASSIGN root = "{sqrt(25)}"

The result of the example is root = 5

substr(start,end)

Returns the characters from start through end. The first character position is 1. If end exceeds the length of the source text, it automatically truncates at the end of the source text.

This function is similar to mid(). Both mid() and substr() return a subset of characters. The difference is that with substr(), the function returns the characters between the specified starting and ending points. With mid(), the function returns a specified number of characters, defined by length, after the specified start.

IF TEST = 1
{
  ASSIGN enteredAmount = 15269
  ASSIGN phoneNum = "8015553437"

}
ASSIGN areaCode = "{phoneNum.substr(1,3)}"

ASSIGN amountLength = enteredAmount.length()
ASSIGN dollars = enteredAmount.substr(1,amountLength - 2)
ASSIGN cents = enteredAmount.substr(amountLength - 1,amountLength)
ASSIGN totalAmount = "${dollars}.{cents}"

The results of the example are:

• areaCode = 801
• totalAmount = $152.69

tan(value)

Returns the tangent of the specified value. The value must be in radians.

ASSIGN angleRad = 0.394791119699762
ASSIGN tanNum = "{tan(angleRad)}"

The result of the example is tanNum = 0.416666666666667

tanh(value)

Returns the hyperbolic tangent of the specified value. The value must be in radians.

ASSIGN angleRad = 0.394791119699762
ASSIGN hTan = "{tanh(angleRad)}"

The result of the example is hTan = 0.375483244486081

trim(), ltrim(), and rtrim()

The trim() function returns a string with all leading and trailing white space characters removed. White space includes spaces, tabs, and line breaks.

The ltrim() function returns a string with all leading white space characters removed.

The ritrim() function returns a string with all trailing white space characters removed.

IF TEST = 1
{
  ASSIGN varString = "      Beowulf      "
}
ASSIGN trimRes = varString.trim

ASSIGN lTrimRes = varString.ltrim

ASSIGN rTrimRes = varString.rtrim

The results of the example are : 

• trimRes = " Beowulf "
• lTrimRes = "Beowulf      "
• rTrimRes = "      Beowulf".

trunc(value)

Calculates the integral part of the specified value. trunc() rounds value to the nearest integer towards zero.

ASSIGN truncNum = "{trunc(945.6)}, {trunc(946.9)}"

The result of the example is truncNum = 945, 946

upper() and lower()

The upper() function returns the contents of the variable with all letters converted to uppercase.

The lower() function returns the contents of the variable with all letters converted to lowercase.

IF TEST = 1
{
  ASSIGN variable1 = "Beowulf is a monster fighter"
  ASSIGN variable2 = "BEOWULF IS A MONSTER FIGHTER"
}
ASSIGN variable1  = "{variable1.upper()}"

ASSIGN variable2  = "{variable2.lower()}"

urlencode() and urldecode()

The urlencode() function returns the contents of the variable encoded using the Internet standard for URL encoding. For example, some of the data that needs to be added to a URL for sceen pops 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. must be encoded so it sends correctly.

The urldecode() function returns the contents of the variable decoded from the Internet standard for URL encoding. In the following example urldecode() is decoding the variable URL, which means URL and newURL have the same value.

IF TEST = 1
{
  ASSIGN dnis= "5551234567"
  ASSIGN ani = "5550987654"
  ASSIGN waitTime = "2 02:39:42"
  ASSIGN callOriginationTime = "{datefmt(now, 'yyy-MM-dd HH:mm:ss')}"
}

ASSIGN URL = "?&sys_id=-1&sysparm_query=u_source_phone={DNIS}^u_caller_phone={ANI}^u_wait_time_string={waitTime}^opened_at={callOriginationTime}"
ASSIGN eURL = URL.urlencode()
ASSIGN popURL = "http://www.incontact.com{eURL}"

ASSIGN newURL = eURL.urldecode()