Date, Time, Number, and Other Formatting

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

This page describes the valid formatting options for dates, times, and numeric values in Studio. You can use the formatting options to define how you want certain information to be formatted in the output of your script. For example, if your organization wants dates displayed in a certain way, you can convert the dates from their existing format into the desired format using the datefmt() function and the date format specifiers on this page.

Examples of many of the format specifiers on this page are available in the example script for functions. You can download and import the script, then open the datefmt and format Snippet actions.

Date and Time Formats

Use format specifier characters when you need to specify the format you want an actionClosed Performs a process within a Studio script, such as collecting customer data, playing a message or music, or routing a contact to an agent. or date/time function such as datefmt() to return a date or time value in. There are specifier characters for each portion of a date/time value, such as day, month, year, hour, minute, and so on.

By combining specifier characters with separator characters, you can define how you want date/time values to appear. This is helpful if your organization has requirements for the appearance of date/time values. After you know what date/time format you need, use the format specifiers defined in this section to build the format in your script.

The following table shows some examples of dates and times with their corresponding formats. The Format with Specifiers column shows how you would use format specifier characters to construct each date/time example in the Date Style column. The specifier characters, such as M, d, h, s, and so on, represent a portion of the date/time value such as month, day, hour, and so on.

Date Style Format with Specifiers
04/04/2022 04:29:12 AM MM/dd/yyyy hh:mm:ss tt

6/29/2022 3:15:45 PM

M/d/yy h :m:s tt

Sat Apr 22 2023  ddd MMM dd yyyy
Thursday, June 15 2023 dddd, MMMM dd yyyy

OLE Automation

An OLE Automation Date is a date written as a floating point number. 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 on that day divided by 24. For example, 6:00 AM December 31, 1899 is 1.25.

OLE Automation date-times are used in various places in Studio scripts. Some functions that handle dates and times use this format as input or output. Many of the date-time formats described on this help page use OLE Automation date-times.

Date and Time Formatting Specifiers

When using date and time formatting specifiers, the following things matter: 

  • Upper and lower case: The case of the specifier changes the output. For example, a lower case f results in a number of milliseconds that includes a trailing zero if applicable. An upper case F strips trailing zeroes. In another example, a lower case m outputs minutes, but an upper case M outputs the month.
  • The number of each character that you include: Including one, two, or more of a formatting specifier changes the output. For example, using a single h for the hour results in all single-digit hours having no leading zero. Two hh characters results in single-digit hours with leading zeroes.
  • Combining characters or using alone: To use a single specifier character alone without other specifiers, you must prefix it with a percent sign %. For example, to output just the minutes, you would use %m. If you don't include the percent sign, the formatting will not work. If you use a single specifier in combination with other specifiers, you don't need to include the percent sign. For example, if your format includes the hours and a single m, as in hh:m, you don't need the percent sign.

Any non-specifier characters included in the date/time format specification are passed into the output and do not affect the date/time value. You can use this to separate the parts of the date/time value. The colon (:) and forward slash (/) are traditionally used to separate parts of a date/time value. You can use any separator you want in the formats you specify, including non-traditional characters such as a dash (-).

For example, if you wanted to separate the date and the time with a pipe character, you could include it in the format and it would be added to the output. The colon and forward slash may be required depending on the function you use. For example, the asdatetime() function requires these characters.

To Represent Format Specifier Details
Day d

Represents the day of the month as a number from 1 to 31: 27.

A single-digit day is formatted without a leading zero: 3.

If using alone, prefix with %.

dd

Represents the day of the month as a two-digit number from 01 through 31: 27.

A single-digit day is formatted with a leading zero: 03.

ddd Represents the abbreviated name of the day of the week: Thu.
dddd Represents the full name of the day of the week: Thursday.
Month M

Represents the month as a number from 1 to 12: 11.

A single-digit month is formatted without a leading zero: 5.

If using alone, prefix with %.

MM

Represents the month as a two-digit number from 01 to 12: 11.

A single-digit month is formatted with a leading zero: 05.

MMM Represents the abbreviated name of the month: Oct.
MMMM Represents the full name of the month: October.
Year y

Represents the year as a one- or two-digit number: 23.

If the year has more than two digits, only the two low-order digits appear in the result. For example, given the year 2023, 23 appears.

If the first digit of a two-digit year begins with a zero (for example, 02), the number is formatted without a leading zero: 2.

yy

Represents the year as a two-digit number: 23.

If the year has more than two digits, only the two low-order digits appear in the result. For example, given the year 2023, 23 appears.

If the two-digit year has fewer than two significant digits, the number is padded with leading zeros to achieve two digits: 02.

If using alone, prefix with %.

yyy

Represents the year with a minimum of three digits: 2023.

If the year has more than three significant digits, they are included in the result string. If the year has fewer than three digits, the number is padded with leading zeros to achieve three digits.

Note:  For the Thai Buddhist calendar, which can have five-digit years, this format specifier displays all five digits.

yyyy

Represents the year as a four-digit number: 2023.

If the year has more than four digits, only the four low-order digits appear in the result. If the year has fewer than four digits, the number is padded with leading zeros to achieve four digits.

Note:  For the Thai Buddhist calendar, which can have five-digit years, this format specifier displays all five digits.

yyyyy

Represents the year as a five-digit number.

If the year has more than five digits, only the five low-order digits appear in the result. If the year has fewer than five digits, the number is padded with leading zeroes to achieve five digits: 02023.

If there are more than five y specifiers, the number is padded with as many leading zeroes as necessary to achieve the number of y specifiers. For example, if there are eight y specifiers, the output is 00002023.

Period or Era g, gg (plus any number of additional g specifiers)

Represents the period or era, such as A.D. The script ignores this specifier if the date to be formatted does not have an associated period or era string.

A single g cannot be used alone. If you want to output only the name of the era or period, use a double gg.

Hour (12-hour Clock) h

Represents the hour as a number from 1 to 12 on 12-hour clock that counts the whole hours since midnight or noon.

A particular hour after midnight is indistinguishable from the same hour after noon. For example, 1:00 AM is the same as 1:00 PM.

The hour is not rounded, and a single-digit hour is formatted without a leading zero.

If using alone, prefix with %.

For example, given a time of 5:43, this custom format specifier displays 5.

hh

Represents the hour as a two-digit number from 01 to 12 on a 12-hour clock that counts the whole hours since midnight or noon.

A particular hour after midnight is indistinguishable from the same hour after noon. For example, 1:00 AM is the same as 1:00 PM.

The hour is not rounded, and a single-digit hour is formatted with a leading zero.

For example, given a time of 5:43, this custom format specifier displays 05.

Hour (24-Hour Clock) H

Represents the hour as a number from 0 to 23 on a 24-hour clock that counts the hours since midnight.

A single-digit hour is formatted without a leading zero.

For example, given a time of 5:43 PM, this custom format specifier displays 17.

If using alone, prefix with %.

HH

Represents the hour as a two-digit number from 00 to 23 on 24-hour clock that counts the hours since midnight.

A single-digit hour is formatted with a leading zero.

For example, given a time of 5:43 PM, this custom format specifier displays 17.

Minute m

Represents the minute as a number from 0 to 59.

The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted without a leading zero.

For example, given a time of 5:43:34, this custom format specifier displays 43.

If using alone, prefix with %.

mm

Represents the minute as a two-digit number from 00 through 59.

The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted with a leading zero.

For example, given a time of 5:03:34, this custom format specifier displays 03.

Second s

Represents the seconds as a number from 0 to 59.

The result represents whole seconds that have passed since the last minute. A single-digit second is formatted without a leading zero.

For example, given a time of 5:43:04, this custom format specifier displays 4.

If using alone, prefix with %.

ss

Represents the seconds as a two-digit number from 00 to 59.

The result represents whole seconds that have passed since the last minute. A single-digit second is formatted with a leading zero.

For example, given a time of 5:43:04, this custom format specifier displays 04.

Fractional Seconds ff, F

Represents a number of digits of the seconds fraction. Lowercase f specifiers include the trailing zeroes. Upper case F specifiers omit trailing zeroes.

This specifier only works with OLE automationClosed A way to write dates as a floating point integer. Indicates the number of days since December 30, 1899. date/times.

The number of f or F characters includes determines how many significant digits of the second fraction to include:

  • F: Tenths of a second, or the most significant digit. If the digit is a zero, nothing is displayed.
  • ff or FF: Hundredths of a second, or two significant digits.
  • fff or FFF: Thousands of a second, or three significant digits. This is also called milliseconds.
  • ffff or FFFF: Ten thousandths of a second, or four significant digits.
  • fffff or FFFFF: Hundred thousandths of a second, or five significant digits.
  • ffffff or FFFFFF: Millionths of a second, or six significant digits.
  • FFFFFFF: Ten millionths of a second, or seven significant digits.

The more precision you specify, the less reliable or meaningful it may be. The precision of the time value depends on the resolution of the computer's system clock.

AM/PM t

Represents the first character of the AM/PM designator. The AM designator is used if the hour in the time being formatted is less than 12. Otherwise, the PM designator is used.

For languages that use an AM/PM designation where the first character is the same and the second character changes, use the tt specifier.

If using alone, prefix with %.

tt

Represents the AM/PM designator. The AM designator is used if the hour in the time being formatted is less than 12. Otherwise, the PM designator is used.

Use the tt specifier for languages such as Japanese that use an AM/PM designator where the first character is the same and the second character changes.

Local Offset from UTC z

Represents the signed offset of the local operating system's time zone from Coordinated Universal Time (UTC). The number of z characters defines how much of the offset to display: 

  • z, zz: Measures the offset in hours.
  • zzz: Measures the offset in hours and minutes.

The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of and a minus sign (-) indicates hours behind UTC. The offset ranges from –12 through +13. A single-digit offset is formatted with a leading zero.

If using alone, prefix with %.

Numeric Formats

Use these format specifier characters when you need to define the format you want an actionClosed Performs a process within a Studio script, such as collecting customer data, playing a message or music, or routing a contact to an agent. or function such as format() to return a numeric value in. There are specifier characters for many uses, such as currency, percentages, fixed-point numbers, and more.

Precision Specifier

Many of the format specifiers described in this section accept a precision specifier. The precision specifier allows you to define the number of digits after the decimal point to include in the output.

A precision specifier is a number that you include after the format specifier. In the following example, C is the format specifier and 3 is the precision specifier. It indicates that the output will have three digits after the decimal point.

ASSIGN CurrencyResultBigC = "{StringVal.format('C3')}"

Given a starting number of 0013001.93912837, the output of this example is $13,001.939.

Numeric Specifiers

Number Type Format Specifier Details Description
Currency C or c

The number is converted to a string that represents a currency amount. Include a number with the format specifier to indicate the number of decimal places you want the number to have. The case of the format specifier does not affect the results.

ASSIGN StringVal = "0013001.93912837"
ASSIGN CurrencyResult = "{StringVal.format('C')}"
ASSIGN CurrencyResult3 = "{StringVal.format('C3')}"

Result:

CURRENCYRESULT=$13,001.94

CURRENCYRESULT3=$13,001.939

Exponential Notation (Scientific) E or e

E0

E-0

e0

e+0

e-0

The number is converted to a string of the form -d.ddd…E+ddd or -d.ddd…e+ddd, where each d indicates a digit (0-9). The string starts with a minus sign if the number is negative. One digit always precedes the decimal point.

Include a number with the format specifier to indicate the number of digits you want after the decimal point. If you don't include the precision specifier, the script defaults to six decimal places.

The case of the format specifier indicates whether the exponent in the output is prefixed with an E or an e. The exponent always consists of a plus or minus sign and a minimum of three digits. The exponent is padded with zeros to meet this minimum, if required.

If any of the strings E, E+, E-, e, e+, or e- are present in the format string and are followed immediately by at least one 0 character, then the number is formatted using scientific notation with an E or e inserted between the number and the exponent.

The number of 0 characters following the scientific notation indicator determines the minimum number of digits to output for the exponent. The E+ and e+ formats indicate that a sign character (plus or minus) should always precede the exponent. The E, E-, e, or e- formats indicate that a sign character should only precede negative exponents.

 ASSIGN StringVal = "0013001.93912837"
ASSIGN ScientificResult = "{StringVal.format('e')}"		
ASSIGN ScientificResult = "{StringVal.format('E2')}"	

Result:

SCIENTIFICRESULT=1.300194e+004

SCIENTIFICRESULT2=1.300194E+004

Fixed-Point F or f

The number is converted to a string of the form -ddd.ddd… where each d indicates a digit (0-9). The string starts with a minus sign if the number is negative.

Include a number with the format specifier to indicate how many decimal places you want the result to have. Without the precision indicator, the script defaults to two decimal places.

ASSIGN StringVal = "0013001.93912837"
ASSIGN FixedPointResult = "{StringVal.format('F3')}"
ASSIGN FixedPointResult2 = "{StringVal.format('f')}"

Result:

FIXEDPOINTRESULT=13001.939

FIXEDPOINTRESULT2=13001.94

General G or g

The number is converted to the most compact of either fixed-point or scientific notation, depending on the type of the number and whether a precision specifier is included. If the precision specifier is omitted or is zero, the type of the number determines the default precision, as indicated by the following list:

  • Byte or SByte: 3
  • Int16 or UInt16: 5
  • Int32 or UInt32: 10
  • Int64 or UInt64: 19
  • Single: 7
  • Double: 15
  • Decimal: 29

Fixed-point notation is used if the exponent that would result from expressing the number in scientific notation is greater than -5 and less than the precision specifier; otherwise, scientific notation is used. The result contains a decimal point if required and trailing zeroes are omitted.

If the precision specifier is present and the number of significant digits in the result exceeds the specified precision, then the excess trailing digits are removed by rounding. The exception to this rule is if the number is a Decimal and the precision specifier is omitted. In that case, fixed-point notation is always used and trailing zeroes are preserved.

If scientific notation is used, the exponent in the result is prefixed with E if the format specifier is G, or with e if the format specifier is g.

ASSIGN StringVal = "0013001.93912837"
ASSIGN GeneralResult1 = "{StringVal.format('G')}"
ASSIGN StringVal2 = 6002348902348890234.234432234
ASSIGN GeneralResult2 = "{StringVal2.format('G')}"

Result:

GENERALRESULT1=13001.93912837

GENERALRESULT2=6.00234890234889E+18

Hexadecimal X or x

This format is supported only for integral types. The number is converted to a string of hexadecimal digits. The case of the format specifier indicates whether to use uppercase or lowercase characters for the hexadecimal digits greater than 9. For example, use X to produce ABCDEF and x to produce abcdef.

The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.

Number N or n

The number is converted to a string of the form -d,ddd,ddd.ddd…, where: 

  • The minus sign ( - ) indicates a negative number symbol if required.
  • Each d represents a digit (0-9).
  • A comma ( , ) indicates a thousand separator between number groups.
  • The period ( . ) indicates a decimal point symbol.

Include a precision specifier to indicate the number of decimal places you want the result to have. If no precision specifier is included, the default is two decimal places. If the number does not include a decimal point, .00 is added to the output number.

ASSIGN StringVal = "0013001.93912837"
ASSIGN NumberResult = StringVal.format('N')
ASSIGN NumberResult2 = "{StringVal.format('n2')}"

Result

NUMBERRESULT=13,001.94

NUMBERRESULT2=13,001.9391

Percent P or p

The number is converted to a string that represents a percent. The converted number is multiplied by 100 in order to be presented as a percentage.

Include a precision specifier to indicate the number of decimal places you want the result to have. If no precision specifier is included, the default is two decimal places. If the number does not include a decimal point, .00 is added to the output number.

ASSIGN StringVal = "0013001.93912837"
ASSIGN PercentResult = "{StringVal.format('P')}"
ASSIGN PercentResult2 = StringVal.format('P2')	

Result

PERCENTRESULT=1,300,193.91%

PERCENTRESULT2=1,300,193.91%

Round-Trip R or r

This format is supported only for the Single and Double types. The round-trip specifier guarantees that a numeric value converted to a string will be parsed back into the same numeric value. When a numeric value is formatted using this specifier, it is first tested using the general format, with 15 spaces of precision for a Double and 7 spaces of precision for a Single. If the value is successfully parsed back to the same numeric value, it is formatted using the general format specifier. However, if the value is not successfully parsed back to the same numeric value, then the value is formatted using 17 digits of precision for a Double and 9 digits of precision for a Single.

Although a precision specifier can be present, it is ignored. Round trips are given precedence over precision when using this specifier.

ASSIGN StringVal = "0013001.93912837"
ASSIGN RoundTripResult = "{StringVal.format('R')}"	

Result

ROUNDTRIPRESULT=13001.93912837

Zero Placeholder 0

Use one or more zero placeholders to define the format for numbers in the output. You can combine this placeholder with the other placeholder characters defined in this table.

If the value being formatted has a number in the position where a 0 appears in the format string, that number appears in the output string. If no number appears in the position where a 0 appears in the format string, 0 appears in the output string instead. This can be helpful to add zeroes to a number that needs leading zeroes but doesn't have them.

The position of the leftmost 0 before the decimal point and the rightmost 0 after the decimal point determine the number of digits that are always present in the output string.

The 00 specifier causes the value to be rounded to the nearest whole number.

ASSIGN number = "2343456.2343"
ASSIGN zeroPlaceholders = "number.format(000,000.00)
ASSIGN number = "456.47"
ASSIGN doubleZeroSpecifier = number.format('00')

The results of the example are

zeroPlaceholders = 2,343,456.23

doubleZeroSpecifier = 456

Digit Placeholder #

Use one or more digit placeholders to define the format for numbers in the output. You can combine this placeholder with the other placeholder characters defined in this table.

If the value being formatted has a number in the position where a # appears in the format string, that number appears in the output result. If no number appears in the position where a # appears in the format string, that place is empty in the output string.

If the number being formatted contains a 0 as a significant digit, the 0 appears in the output string. If the 0 is not a significant digit, it doesn't appear in the output string, even if 0 is the only number in the string to be formatted.

The ## format string causes the value to be rounded to the nearest whole number.

ASSIGN number = "2343456.2043"
ASSIGN digitPlaceholders = "number.format(###,###.##)
ASSIGN number = "456.47"
ASSIGN doubleDigitSpecifier = number.format('##')

The results of the example are

digitPlaceholders = 2,343,456.2

doubleDigitSpecifier = 456

Decimal Point .

The first period ( . ) character in the format string determines the location of the decimal separator in the formatted value. Any additional period characters are ignored.

Thousands Separator and Number Scaling ,

The comma ( , ) character serves as both a thousands separator specifier and a number scaling specifier.

Thousand separator specifier: If one or more comma ( , ) characters is specified between two digit placeholders (0 or #) that format the integral digits of a number, a group separator character is inserted between each number group in the integral part of the output. For example, if the string #,# and the invariant culture are used to format the number 1000, the output is 1,000.

Number scaling specifier: If one or more comma ( , ) characters is specified immediately to the left of the explicit or implicit decimal point, the number to be formatted is divided by 1000 for each number scaling specifier. For example, if the string 0,, is used to format the number 100 million, the output is 100.

You can use thousand separator and number scaling specifiers in the same format string. For example, if the string #,0,, and the invariant culture are used to format the number one billion, the output is 1,000.

Section Separator ;

Allows you to define two or three possible formatting options for numbers. Formatting is applied depending on whether the number is positive, negative, or zero.

The formatting options are defined in a single string. Each option is separated by a semicolon ( ; ) character. Use the zero, digit, thousands, and decimal placeholders to define the formatting, as shown in the examples below. These placeholders are described in this table.

If there are two sections in the custom format string:

  • The left section defines the formatting of positive and zero numbers.
  • The right section defines the formatting of negative numbers.

For example:

ASSIGN number9 = 928374
ASSIGN sectionSeparator4 = number9.format('000,000.##;00.##')

ASSIGN number10 = -998822.25
ASSIGN sectionSeparator5 = number10.format('000,000.##;00.##')

ASSIGN number11 = 0
ASSIGN sectionSeparator6 = number11.format('000,000.##;00.##')	

The results of the example are

sectionSeparator4 = 928,374

sectionSeparator5 = 998822.25

sectionSeparator6 = 000,000

If there are three sections:

  • The left section defines the formatting of positive numbers.
  • The middle section defines the formatting of negative numbers.
  • The right section defines the formatting of zero numbers.

For example: 

ASSIGN number1 = 1789789
ASSIGN sectionSeparator1 = number1.format('000,000.##;00.##;000.0000')

ASSIGN number2 = 0
ASSIGN sectionSeparator2 = number2.format('000,000.##;00.##;000.0000')

ASSIGN number3 = -4321
ASSIGN sectionSeparator3 = number3.format('000,000.##;00.##;000.0000')

The results of the example are

sectionSeparator1 = 1,789,789

sectionSeparator2 = 000.0000

sectionSeparator3 = 4321

All Other Characters Other

All other characters

Any other character is copied to the result string, and does not affect formatting.

Escape Sequences

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.

Other Characters

Character Description
" Represents a quoted string (quotation mark). Displays the literal value of any string between two quotation marks ("). Use the escape character (\) anywhere in your script where you need to display a literal quotation mark.
' Represents a quoted string (apostrophe). Displays the literal value of any string between two apostrophe (') characters. Use the escape character (\) anywhere in your script where you need to display a literal apostrophe character.
$

Use to prefix a string that includes an escape sequence. The $ character must be outside the double quotes. For example: 

z = $"Use the \{myVar} variable."

#

Use to prefix a value to declare it as a date/time type. The # character must be outside the double quotes. For example: 

ASSIGN var = #"02/09/2023"

% Use with date/time formatting specifiers when using a single specifier alone. The % character goes directly before the formatting specifier character. For example, to output just the minutes, use %m.