Studio Fundamentals

This help page is for CXone Studio. This information is also available for Desktop Studio.

Scripts are an essential part of how CXone works in your contact center. They define how the people who contact your organization reach the agents who can help them. Scripts specify what happens to data during and after an interaction. This includes displaying data as screen popsClosed 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. for agents, capturing data from contacts, and storing data in databases.

Your contact center may have many different scripts, or just a few. The exact number and kind of scripts that you need depends on the applications and features your organization uses and the kinds of interactions that are handled. Scripts can range from very simple to quite complex. Simple scripts don't require much knowledge of scripting or coding. Complex scripts can require custom script code.

This page provides an overview of fundamental information and concepts about scripts and how they work. It also describes how scripting fits in with CXone in the big picture of your contact center.

Classics, Inc., an international bookseller, is in the process of setting up CXone in their contact center. Christopher Robin, the contact center administrator for Classics, Inc, works with Eeyore Thistleflower, the Classics Studio scripter, to plan the scripts they need to create.

The Classics contact center receives inbound phone calls, emails, and chat messages from their website. They also make outbound calls and send emails. Additionally, Christopher knows that the company plans to start sending SMS messages to customers to notify them about upcoming sales and promotions. Based on this, Eeyore determines that they need scripts for inbound phone, email, and chat, as well as outbound phone, email, and SMS.

The next thing Christopher and Eeyore determine is the information that each script needs. Inbound scripts need to collect certain data from the contacts. For example, for chat interactions, the script can prompt the contact to provide details such as their name and the kind of help they're looking for. This information can be passed on to the agent. Some information, such as the contact's name, their concerns, and the resolution, can be passed to the CRMClosed Third-party systems that manage such things as contacts, sales information, support details, and case histories. system that Classics uses.

Once the scripts are planned, Eeyore begins to develop and test the scripts.

CXone Terminology

The following list defines some CXone terminology that's important to know when scripting: 

  • ACD skill: ACD skills are used to automate routing of contacts to the agent most likely to be able to help them. They can be created to use any criteria, such as department, team, specialty, or trained abilities. They can also use other factors such as location, language, and so on. ACD skills are assigned to agents. Studio scripts use ACD skills to carry out automated routing.
  • Channel: A channel is a method of communicating with contacts, such as phone, email, SMS or text messages, chat, social media, voicemail, and so on. Every kind of channel has its own script media type in Studio.
  • Contact: The people your organization interacts with are known as contacts. Contacts have ID numbers associated with them that are used to track an interaction across the platform. In the Studio online help, contact can also refer to the item within CXone that references data related to the interaction.
  • Digital: This term refers to channels, skills, scripts, contacts, and interactions associated with Digital Experience.
  • Interaction: This is the complete conversation between contacts and agents. Interactions can be a single phone call, a chat conversation that stretches over several hours, or an email thread that includes several back-and-forth messages. On digital channels, interactions can last for days, weeks, or longer.
  • Media type: The media type is the kind of channel a script works with, such as phone, chat, email, and so on. When you create a script, you create it for a specific media type.
  • Point of contact: A point of contact (POC) is an entry point to the CXoneplatform. POCs are created CXone to define specific instances of a channel. Each POC is assigned an ACD skill and a Studio script. Scripts assigned to POCs must define the flow of what happens to contacts from the start of an interaction on that channel.

Scripts and CXone

CXone cannot function without scripts. Each communication method your organization uses with CXone, such as phones, email, chat, and so on, requires a script. Scripts define what happens during and after interactions between your organization's agents and the people they talk to.

The following diagram provides an overview of CXone and where it fits into the larger picture of your organization. It also shows how scripts interact with every part of CXone and applications and systems outside of CXone.

There are several things to notice about the diagram:

Contacts in CXone and Studio

The term contact represents two important concepts in CXone:

  • The people the agents in your organization interacts with. For example, customers, clients, website visitors, and so on.
  • The item within the CXoneplatform that references data related to the interaction. Each contact has an ID number associated with it. This ID tracks an interaction across the platform.

Tigger Tigerson has a question about his order, so he calls Classics, Inc. In the CXone platform, Tigger is an inbound contact, because he called into the company as a customer. His call enters the CXone platform with contact ID 7892349239. This contact ID references data related to the interaction, such as the transcript, recordings, and contact history.

When a contact enters the system, an instance of a script runs and the ACD assigns that instance a contact ID. This occurs for inbound and outbound interactions. Information is gathered during the interaction, such as the contact's name, account number, and so on. Other information may generated during the interaction, such as a call transcript and recording. All of this information is associated with the contact ID in the script during the interaction. After the interaction ends, most of the information associated with the contact ID is discarded unless the script is designed to save it. Some information, such as call recordings and contact history, is kept for use in other uses in the platform.

A contact ID identifies one segment of an interaction. A complete interaction may involve several segments. New segments can occur for things such as the call being transferred to another agent or when the script spawns another script. When these events occur, a new contact ID begins. In most cases, both contact IDs remain active during the entire interaction. The new contact ID is sometimes called a child contact.

In digital scripts, contact IDs don't change. The contact retains the same ID throughout the interaction. The exception to this is if the agent elevates the interaction to a different channel. The interaction will have different contact IDs for each channel.

To keep track of all of the contact IDs associated with a single interaction, a contact is also assigned a master ID. Any contact ID assigned to a contact is grouped under its master ID.

When you want to reference a contact in a script, you need to use the contact ID for appropriate segment of the interaction. Contact and master IDs are stored in the contactId and masterId variables. They're pre-defined variables and you can use them in your scripts. Pre-defined variables are automatically created in your scripts, so you don't need to declare them before you use them.

Scripting for Digital and Traditional ACD Channels

Digital refers to channels, skills, scripts, contacts, and interactions associated with Digital Experience (Digital). Digital entities are different from their ACD counterparts. Some differences are found in where the entities are managed in the CXoneplatform. Other differences are found in how the platform handles digital interactions compared to interactions on traditional ACD channels.

There are channels for email, chat, and SMS in both Digital Experience and traditional ACD. The traditional ACD versions of these channels use the email, chat, and SMS script media types. The digital versions of these channels all use the digital script media type.

Additionally, many of the Studio actions for working with emails, chats, and SMS messages only work with the traditional ACD versions of the channels. You can check the Supported Script types section of online help page for an action to determine if you can use it with a digital channel.

You can learn more about the channels available in Digital Experience, as well as how the digital entities are managed in the Digital Experience online help. If your organization uses digital channels, you can learn more about working with them on the Digital Scripts help page.

Script Components

Scripts include the following components: 

  • Actions: In Studio, scripts are made up of connected blocks called actions. Each action serves a specific purpose in the script. Actions can create a menu of choices, play an audio file, or request the next available agent. Most actions have a set of properties that must be configured to define the specific behavior for each unique instance of an action in your script. Properties include things such as choosing ACD skillsClosed Used to automate delivery of interactions based on agent skills, abilities, and knowledge, setting variables, and selecting an audio file to play.

    You can learn more about using actions on the Action Basics help page. Online help is available for individual actions in the Studio Actions section of the online help.

  • Connectors: The flow of your script is defined by how actions are connected. The connections between actions are shown with lines and arrows.

  • Branches: You can create branches in your script to cover situations where an action has more than one possible outcome. For example, this allows you to define what happens when there are errors. You can also use branches to give contacts a choice, such as in an IVRClosed 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. Multiple branches can stem from a single action. In this case, you would define the conditions that must be met for the script to take each branch. You can also have more than one branch end at the same action.

  • PromptsPrompts are a common component of many scripts. They are messages the script can play to offer the contact a choice or give them information. For example, an IVR menu uses prompts to let contacts know their options for proceeding with the interaction. This could be messages such as "For Sales, press 1. For Support, press 2." You can also use prompts to give the contact information, such as your organization's operating hours or the contact's current account balance. Prompts can be prerecorded audio files or text that's read by a text-to-speech (TTSClosed Allows users to enter recorded prompts as text and use a computer-generated voice to speak the content.) service.

  • Custom Code: It's sometimes necessary to use custom scripting in Studio scripts. Custom code allows you to expand the range of what your scripts can do. It's required when using certain products, such as virtual agentsClosed A software application that handles customer interactions in place of a live human agent.. It can be helpful to use even if not required, because it can simplify certain aspects of managing Studio scripts.

    Custom code must be written in Snippet, an in-house scripting language developed by NICE CXone. Reference material for using Snippet is available in the Technical Guide section of the online help.

Script Media Types

Scripts have a property called media type. The media type is the kind of channelClosed A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on. the contact and agent use to communicate. A script's media type must match the type of channel it's assigned to work with.

When you create a script, you're prompted to select the media type. You can change this setting later, if necessary. Currently, this option is not available in CXone Studio so you must use the Desktop Studioapplication.

The media types in Studio are shown in the following table:

A square with a line branching from it that goes to three other squares.

Generic

Email Chat Phone Voicemail Work Item SMS Digital

The generic script type is labeled system in places that display script type. For example, you can see this in the Media Type field of the script properties.

Media type can influence what actions are available to use in a script. Most actions work with any type, but some actions only work with certain media types. For example, ASRClosed Allows contacts to respond to recorded voice prompts by speaking, pressing keys on their phone, or a combination of both. actions only work with phone scripts. If you are working on an email script, ASR actions aren't visible in the Actions palette of that script.

Suppression Scripts

A suppression script is a custom subscript that's used with outbound phone ACD skills to determine if the request for the call should continue or to perform custom logic before a call is placed. Suppression scripts can run on calls placed by agents or by the dialer.

When an outbound call is requested, the system script that makes the call checks to see if a suppression script is assigned to the ACD skill being used to request the call. If there is a suppression script, the requeset is routed to it. When the logic in the suppression script is complete, the call request must be returned to the system script.

Suppression scripts must end with either the PERMITCALLaction or the SUPPRESSCALL action. Use PERMITCALL if the call can continue or SUPPRESSCALL if the call should not be placed. Both actions return the call request to the originating system script.  The system script then completes the request appropriately.

You can learn more about creating suppression scripts on the Set Up Call Suppression help page.

Script Templates and Examples

Script Version Management

You can manage the versioning of your scripts by developing a naming convention. A common naming convention is to include DEV or PROD at the end of the script file name. These additions help you identify a script as being in development or production. You can include other information such as dates or version numbers, if it fits your organization's requirements.

Studio doesn't allow script names to be changed after they're saved. When you need to change the name of a script, make a copy of the script using Save As and give it a new name. For example, you'd need to do this when moving a script from development into production. After you put a script into productionyou can deactivate the older production and development versions if you want keep your script folders uncluttered. If you ever need to use them again, you can reactivate them.

Scripts have two types of historical versions in Studio. There are:

  • Individual files that accumulate as you move scripts in and out of development and production.
  • Previous versions that are automatically saved and maintained by Studio. Each time you save a script file, Studio adds a new version to that file's history. You can revert to previous versions of a script file if needed. The number of versions that Studio keeps is configurable.

Because another version is added each time you save a script, you could completely replace all of the saved versions of that script during a session of working on a script. You may want to export a copy of the script before you start working on it, especially if you're making significant changes. This way, you can refer to it or completely revert back to it if needed. It may be helpful to name your exported copies so that you know which version it is and why you kept it.

Never edit a production script directly. Saved changes go into effect immediately. If a change causes a problem with a script, it could impact your contact center's ability to function. If you need to make changes, use Save As to create a copy of the script and name it to indicate that it's in development. Only put it into production when it's fully tested and ready.

Starting and Ending Scripts

Scripts start in one of three ways. They can be: 

Every script starts with the Begin action. Scripts end with terminating actions. There are several terminating actions. The one you use matters and is dependent on the script media type:

  • Discard: Terminates an email script.
  • End: Terminates a phone, voicemail, SMS, or digital script. Does not terminate a digital contact, but terminates contacts in scripts with other media types.
  • End a Contact: Terminates the active contact. Does not terminate the current script.
  • EndText: Terminates an SMS workflow that doesn't include a Regagent action (for digitalClosed Any channel, contact, or skill associated with Digital Experience. channels only).
  • EndWi: Terminates a work item with a cause code. Does not terminate the current script.
  • Exit: Terminates a chat session and disconnects the chat contact.
  • Hangup: Terminates a phone script.
  • Return: Terminates a subscript and returns control to the originating script.

Do not use the Stop action to end a script. It does not terminate the script and leaves contacts running. This has a negative impact on the CXone servers.

If you use the End action, the following information applies: 

  • If you use End in a script with an unsupported media type, it may not end all processes properly or the contact. Ending background processes is a key function of terminating actions. For this reason, it's important to use the action best suited for the media type of your script.
  • If you use End in a subscript, it terminates both the subscript and the originating script. Use the Return action if you want to terminate the subscript but for the originating script to continue.
  • End should be used to terminate the logic flow of an active script and invoke the OnRelease event action. For this reason, it shouldn't be used after the OnRelease event logic.

Custom Coding with Snippets

Simple scripts don't require custom coding. For these scripts, using the available actions is sufficient to manage essential routing functions in CXone.

Custom coding is required for more complex routing or with certain products or features in CXone. In some cases, Studio actions or entire CXone applications require code snippets to work properly. The Snippet action allows you to insert code into your script anywhere you need to add custom code.

Studio uses an in-house scripting language called Snippet. This language executes server-side and compiles into MSIL (Microsoft Intermediate Language) just like C# and Visual Basic .NET. A complete reference guide to Snippet is available in the online help.

Notes and Annotations in Scripts

Studio offers several ways to add comments to your scripts. This is an important step that can help ensure that you, and anyone who works in the script after you, understands the script later. You can: 

  • Use the Note and ANnotationStudio actions.
  • Change the labels that appear on the canvas workspace for actions in your script.
  • Add comments to Snippet action code.

Use NOTE and ANNOTATION Actions

Studio has two actions you can include in your scripts, Note and Annotation. Neither of these actions affect how the script works. They are informational only. The difference between the actions is: 

  • The Note action can be placed anywhere on the script canvas and doesn't need to be connected to other actions. To add or view comments made with this action, you must double-click on it.

  • The Annotation action displays your comments directly on the canvas in a gray rectangle. You can also connect Annotation to another action if you want to point directly to the part of the script the note refers to.

Change Action Labels

Another option available for making notes in a script is changing the caption on the actions in the script. In the properties of each action is a Add caption or Caption field that lets you add a name or short description that appears on the canvas under the action in CXone Studio. In Desktop Studio, it changes the name of the action on the canvas. You can use this to name each action with a word or short phrase to remind you of that action's purpose in the script.

For example, you could change the name of a Snippet action to indicate what the code that it contains does. Or you could name each Play action in your IVRClosed 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 with the name of the audio file or prompt that it plays.

Add Comments in SNIPPET Actions

You can add comments to your custom code in Snippet actions. Comments can be on separate links or at the end of a line of code. The Snippet language uses two forward slashes to indicate comments ( // ). The following example shows comments in a snippet:

//custom payload parameters are optional and
//customizable
DYNAMIC customPayload
customPayload.context.id="123"
customPayload.context.parameters.name="Beowulf"
CustomPayload.context.parameters.age=25
ASSIGN tokenjson = "{customPayload.asjson()}" //converts to JSON	

Key Facts about Using Studio

  • The Error and Warning panel shows any warnings and errors related to your script. You can use this information to help test and debug your scripts. In CXone Studio, warnings and errors appear on the right side of the canvas workspace.
  • You can import and export scripts as JSON files.
  • Studio does not allow scripts to be renamed once they're saved. If you need to change a script's name, you can duplicate it to create a copy with a new name, then deactivate the old script or move it into a separate folder so it's out of the way.

  • You can view previous versions of a script in two places: 
    • In Desktop Studio, right-click on the script in the Browse tab (View> Browser) and hover over the History option. Currently this option is not available in CXone Studio.
    • In CXone, click ACD > Scripts. On this page, you can also revert a script to a previous version.
  • You can schedule scripts to run using the ACDScript Scheduling option in CXone.
  • On the ACD > Scripts page in CXone, you can spawn a script with temporary custom parameters that the script uses as variables.
  • To prevent a script from becoming too large and complex, you can break it into multiple smaller scripts and link them using Runsub or Runscript actions.
  • Studio has some script APIs you can use to programmatically open and save scripts. This requires advanced scripting skills.
  • Changes to scripts are automatically saved locally in your browser. This prevents you from losing unsaved work if your browser closes unexpectedly. If this happens, the next time you open the script, CXone Studio prompts you to open it with the unsaved changes.