Technical Reference Guide

This section provides detailed technical reference information about scripting in Studio. The information generally applies to scripting with actions and in custom code snippets. In some cases, information applies only to one method of scripting or the other.

The information on this page summarizes the fundamental scripting concepts you need to know when scripting with Studio. More in-depth information is available on the other pages in this section.

Script and Snippet Structure 

Studio scripts can be contained in a single file or be made up of a main script and one or more subscripts in separate files. Every script must: 

• Start with a Begin action. Subscripts must also start with a Begin action.
• End with a terminating action, such as End. Subscripts end with Return, an action that returns the flow of the script back to the main script.
• Have a defined media type.

Within the script, the structure follows the flow required by the behaviors you need the script to provide. You can organize and arrange the flow of actions in your script in whatever way works best for you. For example, you could have the flow go from right to left or from left to right. Similarly, it can go from top to bottom.

Some things to note about the structure of scripts: 

• Use branch conditions to create branches in your script. This allows you to cover the many possible outcomes, variations, or situations that might happen at any given point during the script. You can use branches for error handling, for the options in an IVR Automated phone menu that allows callers to interact through voice commands, key inputs, or both, to obtain information, route an inbound voice call, or both. menu, or for the true/false paths based on an IF action.
• Some actions have several branch conditions available. You don't need to connect all of them every time. However, it's important that you always connect the Default branch. This is the branch the script takes if none of the other conditions apply. It can prevent contacts from getting stuck at that place in the script if something unexpected happens.
• Event actions aren't connected to the actions that trigger the event. They start a new section in the same script file. The new sections can be located anywhere in the script file. If you have several event actions in your script, it's a good idea to keep them organized in a way that makes it easy to locate later.

Snippets don't have any requirements for structure, other than the limits of the logical order of statements. They can hold a single ASSIGN statement, or complex scripting logic made up of a series of nested statements and blocks. If you need to create custom functions, you must use snippets.

You can use snippets for more than just holding custom code. You can use them to consolidate variable assignments into fewer locations. Instead of using an ASSIGN action every time you need to add a variable, you can put multiple declaration statements into a single Snippet action.

There are some things you can do to make your scripts easier to read. This can help other scripters who might need to work with the script later. You can: 

• Change the Caption property of each action. The contents of this property appear on the canvas workspace of the script. You can add a word or short phrase that helps you know what each action does. For example, you may want to indicate the skill the action uses, the music file it plays, or what the Snippet code does. In CXone Studio, the property name is Add caption.
• Use Annotation and Note actions to provide additional documentation in your script. In Snippet actions, you can add comments.
• Follow the other best practices for scripting in Studio.

Syntax

Like all programming languages, Snippet has syntax rules that must be followed. Each help page in the reference section has a section about syntax that covers the rules for that element of the language. You can learn about the syntax rules for:

• Keywords and statements.
• Variables, arrays, and objects.
• Escape sequences.
• Functions.

The syntax rules are described with syntax summaries. The summaries use certain conventions to distinguish between optional and required elements. Learn more about these conventions on the Statements help page.

Data Types

Data types describe how data is represented and the kinds of operations that can be performed with the data. Many programming languages support many data types that distinguish between different kinds of numeric and alphanumeric representations. Studio does not make these distinctions. In Studio, values are one of the following type types: 

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

You don't need to declare data types when creating variables, as you do with some programming languages. In Studio, variables are implicitly typed. This means the type is determined automatically when the script is compiled.

Data types are an integral part of scripting. You can learn more about data types in Studio scripts in the help pages about data structures, expressions, and variables. If you work with functions, you need to know about the types of data you're using in the script. You also need to know what the function you're using expects and how the output might differ depending on the type you use it with.

Data Structures: Variables, Arrays, and Objects

Data structures allow you to store data to use in your script. You can retrieve the data from the data structure when it's needed, or replace it with other data. In other programming languages, there can be many types of data structures and they can be very complex. In Studio, there are only three types of data structures:

• Variables: A standard variable holds a single value at a time.
• Arrays: An array can hold more than one value. They're useful for storing lists of data that are all the same kind, such as zip codes or the names of ACD skills Used to automate delivery of interactions based on agent skills, abilities, and knowledge. The full array and its contents are stored as a single string.
• Dynamic Objects: A dynamic data object holds more than one value. They're useful for storing data that's all related, such as a contact's name, address, and phone number.

You can create any of these data structures by declaring it with a declaration statement.

Expressions

An expression is anything in your script that compares a value or results in a value. The following are all examples of expressions: 

• x = 3(5+10)

• y = 123 North Street
• x != 5

There are different types of expressions, including string, numeric, and Boolean A data type that has two possible values: true and false.. Expressions have many uses in Studio scripts. They're used to: 

• Configure the properties of Studio actions or in snippets.
• Define logic in a script that creates branches and simulates decision-making.
• Supply literal values for action properties or in snippets.
• Provide mathematical or algebraic calculations.

Operators

Operators are mathematical symbols that indicate what mathematical or algebraic operation is to happen with the numbers. Studio supports all standard mathematical and some algebraic operators. It also supports Boolean A data type that has two possible values: true and false. operators, which are used in Boolean expressions. These are expressions that evaluate to either true or false. You can use Booleans in some statements to create a decision-making mechanism in your script.

Statements

Statements define the actions a script takes when it executes. This includes creating variables, assigning new values, performing calculations, and making logical choices based on a given condition. Some statements only perform a task, such as assigning a value to a variable. Other statements affect the flow of the script. Statements are executed in a logical order, but that order can change each time the script runs.

When scripting with actions, you generally don't need to think in terms of statements. Within snippets, you can use the following types of statements: 

• Declaration: Use declaration statements to declare, or create, new variables, objects, and functions.
• Decision-Making: Use decision-making statements to have the snippet code select a task to perform based on the conditions you specify. You can use them to control the linear flow of what happens in the script.
• Looping: Use looping statements to have the snippet perform a task or set of tasks repeatedly until the specified ending condition is met.
• Other: These statements allow allow you to terminate functions, display results in the Snippet editor window during debugging, and include web service proxy DLLs in your snippets.

Some of the statements have Studio actions that do the same thing. For example, the ASSIGN and IF actions do the same thing as the ASSIGN and IF statements that you can use in snippets. For many of the statements, the only option for using them is in snippets.

Reserved Words

Studio has some reserved words that aren't available for use as names for variables and other entities in scripts. Reserved words include the names of: 

• Keyword commands.
• Built-in functions.
• Predefined system variables.
• Reserved variables.

If you use a reserved word as the name of an entity in your script, it causes an error. You must rename the entity to resolve the error.

Comments

Comments allow you to document something in your script or snippet. You can use them to leave a note for yourself or a future scripter or to explain the purpose of something in the script.

In Studio scripts, you can add comments with the Note action or the Annotation action. Both actions allow you to add a comment to the script canvas. The Annotation action places the comment visibly on the canvas. To read the comment in a Note action, you must double-click the action.

In snippets, you can add comments by putting two forward slashes ( // ). Comments can be placed on their own lines or at the end of a statement.

You can also use comments in snippets to hide lines of code that you don't want to be part of the script when it runs. This is helpful when troubleshooting problems.

Functions

Functions are a way of creating code that you want to reuse. You can create your own functions, then call them elsewhere in your script when you want to use the code that the function contains. Studio also has some built-in functions you can use without having to declare them in your script.

String Handling

In snippets, you can use do many things with strings using built-in functions: 

• Concatenate them
• Split them into substrings
• Search them
• Replace part of the contents
• Compare them
• Change them from uppercase to the lowercase and vice versa.

In some cases, you may need to specify the formatting of strings that involve dates, times, or numbers. You can use the designated format specifiers to define the format you want the script to use. You can also use some of the built-in functions to convert strings into different formats.

There are certain characters that you cannot include in strings without using an escape sequence. Because strings must be enclosed in single or double quotes, if you include a literal single or double quote in a string, the script interprets it as the beginning or end of a string. The escape sequence tells the script that the character is intended as a literal and not the symbol it defaults to. Other characters that require escape sequences are tabs, backspaces, and open curly braces.