Action Basics

Actions are the building blocks of Studio scripts. A script is a network of actions that route and manage customer traffic for your contact center. Each action has a specific purpose, and together they define what a script accomplishes. There are actions that play audio files, instruct the script to wait, request an agent, and much more.

Each action represents code that has already been written. This means you don't need to be a scripting expert to create simple scripts in Studio. If you want to create more complex scripts, however, some custom scripting is required.

In the following image of an example script, you can see a series of actions linked by connector arrows. The description of this script shows how each action serves a specific purpose in the script. The description is located after the image in the drop-down.

This image shows the beginnings of a basic inbound phone script. A description follows the image.

Image of example phone script.

  1. When a contact calls this organization, the script starts (Begin action) and counts the number of available agents (Countagents action).
  2. If (If action) the number of agents is zero, the script follows the path that goes up, labeled False. A message plays (Play action) and the system disconnects the call (Hangup action).
  3. If (If action) the number of available agents is greater than zero, then 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 (Menu action) offers the caller the option to connect to an agent (Reqagent action). This IVR menu offers only one option. More complex menus can offer multiple options, each with a different result.
  4. The contact waits until an agent comes on the line. During the on hold wait, music plays in 30 second intervals (Music and Wait actions).

Types of Actions

There are many different kinds of actions in Studio. The following are three of the most basic types, which you will use in nearly every script you create: 

  • Starting action: There is only one action that can begin a script, Begin. This is the first action in every script, including subscripts.
  • Event actions: Event actions start a new branch in a script. They fire when a specific event occurs during an interaction. Examples are Onanswer, Onrelease, and Onhold. Event
  • Terminating actions: These are actions that can end a script. You must use the appropriate action for the script media type. If you use the wrong terminating action, the script might not be properly ended. For example, background processes may be left running. Additionally, contacts handled by the script may not be ended, which can have negative impacts on your business unitClosed High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment.

You can learn more about starting and terminating actions on the Fundamentals help page. You can learn more about event actions in the section after this one.

All other Studio actions fall into categories based on what the action does in a script or the parts of the CXone platform they interact with. Each category has an icon color associated with it. However, many actions fall into more than one category, so the icon color only indicates one of the categories an action may fall into. The categories are described in the following table.

Category Details Examples
ACD These actions interact with the CXoneACD. Their icons have a bright pink background color A bright pink square. . Reqagent

Getqueue

Automation, speech, virtual agent bots

  • These actions provide automation, connection to virtual agents and bots, and speech-related capabilities. Their icons have a teal background color A teal square. .
    		• ASR

    Textbot Exchange

    Chat These actions work with chat scripts. Their icons have a yellow-green background color A yellow-green square. . Askcaller

    Chatblindxfer

    Data These actions allow you to access data and databases. Their icons have a dark gray background color A dark gray square. .

    Setdb

    Getlist

    Email These actions work with email scripts. Their icons have an orange background color An orange square. . Getemail

    Createemail

    General and script flow These actions are generally useful or help create the flow of the script. Their icons have a dark blue background color A dark blue square. . Wait

    Annotation

    Logic These actions allow you to include scripting logic in your script. Their icons have a yellow background color A yellow square. . If

    Snippet

    Script These actions allow you to control and interact with the script itself. Their icons have a red-violet background color A red-violet square. . Signal

    RunScript

    Security These actions provide security capabilities. Their icons have a purple background color A purple square. . Setsecurityuser
    Strings These actions allow you to work with strings. Their icons have a red background color A red square. . Sort

    Parse

    System and files These actions allow you to work with files on the system. Their icons have a bright blue background color A bright blue square. . Filesize

    Writefile

    Voice and audio These actions work with voice scripts. Their icons have a green background color A green square. . Menu

    Play

    Event Actions

    Events actions execute only when a specific trigger occurs. Event triggers include things such as a call being answered, transferred, or put on hold. For example, Onanswer is an event that triggers when a request for interaction is answered, such as a contact answering a live agent's phone call or a live agent answering a contact's chat question.

    When an event is triggered, any script execution that may have been happening before the trigger occurred is terminated. The script proceeds from the event action.

    The following example script demonstrates the Onanswer event. The script sets up a basic inbound IVR with menu options for Customer Service, Technical Support, and Sales, which correspond to 1, 2, and 3. These represent the numbers the contact presses on the keypad to choose a menu option. The Onanswer event is in the bottom left corner of the script. It's not connected to the main part of the script. Instead it's separate, indicating that it's an event action. As soon as an agent answers the interaction, the script jumps to Onanswer and sends a message to the agent. The message is configured in the Messages action.

    Location of Studio Actions

    Studio actions are found on the Tools tab and the Framework tab. The Framework tab isn't available for all users by default. It's an option that your CXone Account Representative must enable for your business unitClosed High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment.

    Tools Tab

    The Tools tab contains the most common actions used for scripting. On this tab, actions are organized on a palette that has several default categories, such as standard, system, and speech. On the Tools tab, you can choose to view all actions or have them organized into their categories. You can also choose to sort the actions alphabetically or view them in their default order.

    Framework Tab

    The Framework tab is a complete list of all available actions. Actions on this tab are organized in a tree structure of folders. Each folder is a category. You can expand a folder to see the actions it contains. The Framework tab isn't enabled by default. You can request access to the tab by contacting your CXone Account Representative.

    Action Availability and Media Type

    Some actions are visible in Studio only if the product or feature they're related to is enabled for your CXone system. Other actions are visible only if the active script has the media type that the action requires. For example, if an action only works with chat scripts and the active script is a phone script, the action might not be visible unless you switch to a chat script.

    Palettes and Categories

    On the Tools tab, actions are organized with palettes. There's one palette by default, but you can create custom palettes. Palettes allow you to customize the organization of actions in Studio. For example, you could create palettes for different scripts you work on, or you could create a palette for actions you use a lot and another for actions you only use sometimes.

    Each palette must have at least one category. Categories allow you to further organize the actions in the palette. The default palette has several categories, such as system, events, web, and Personal Connection. You can choose to view the actions in a palette by category, or you can choose to view all of the actions at once. Additionally, you can sort actions alphabetically or by the default order they were added to the palette.

    Image of the drop-down options for the Manage Palettes button in the Tools tab of Studio.

    Action Properties

    Most actions have a set of properties that you can configure. Some properties are required, while others are optional. Properties are how you customize the action to do what you need it to in your script.

    You can view an action's properties when it's on the script canvas. The properties appear on the Properties tab when the action is selected. You can also right-click on the action to view its properties in a pop-up window. All actions have a minimum of four properties, but most have other properties as well. The four default properties are: 

    • ToolName: The name of the action. This is a system property and cannot be changed.
    • Category: The location of the action on the Framework tab. This is a system property and cannot be changed.
    • ActionID: The ID of the action in the script. IDs are assigned in the order actions are added to the script. The ID is a system property and cannot be changed, except by deleting the action from the script and adding it back. If you delete an action from a script, all connectors that link to and from the action are deleted too.

    • Caption: The label for the action that appears on the script canvas. You can change the caption so that it describes the action's function in the script. This helps scripts be easier to understand and troubleshoot. They are also used in 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. reporting for some actions.

      You may want to use the setting from one of an action's other properties as the caption. For example, you can give a Music action the name of the music file it plays. You can type the information into the Caption field, or you can copy the value of the property and paste it into the Caption field. To do this, click the name label of the property and press CTRL+C, then click the Caption label and press CTRL+V.

    Some actions have an editor that allows you to configure additional properties or add data to the action. To access action editors, double-click the action on the canvas. For example, when you double-click on the Play action, the Play Properties window, also called the sequence editor, opens. In this window, you can create sequencesClosed A segment of an audio prompt played for the contact. for prompts, such as recording an audio message or designing a TTS prompt.

    You can cut, copy, and paste actions in your scripts. When you add an action by copying and pasting into your script, make sure that you update the actions properties if needed.

    Input and Output Properties

    Some properties hold data the action uses. Other properties store data passed into the action for the rest of the script to use. Properties that store data the rest of the script uses are called output variables. Both properties and output variables appear in the Properties list on an action's Properties tab. You can identify output variables because the property name ends with (out). For example, the REST API action has two output variable properties, errorArgList (out) and resultSet (out).

    When you configure an output variable property, you are naming a variable to store data passed to the action. You don't need to format the variable name in the property field with curly braces.

    Branches and Conditions

    The flow of a script is defined by connecting actions to each other. Sometimes an action has only one possible outcome, so it's connected to one other action. When an action has more than one possible outcome, you can create a path for each possibility. These paths are called branches.

    Branches allow you to design your script to handle all kinds of different possibilities, such as errors, unexpected key presses, or what to do when a phone call isn't answered. You can also use branches to build choices into your script, such as creating a menu that prompts the contact to choose an option.

    Image of overly complex script.

    Each time you create a branch, you must choose the condition for the branch. The condition defines what has to happen for the script to follow that path. All actions have at least one condition, Default. Some actions have more than one condition available. There are some actions that support custom conditions, which allow you to define what must happen for the script to take that path.

    Every action in your script should have a branch that uses the Default condition, even if you're connecting the action's other branches. When an action has more than one path, the Default branch is the one taken when none of the other conditions are met. This is important to keep contacts from getting stuck at that point in the script in the event that something unexpected occurs.

    When you connect two actions, you're prompted to select the branch you're creating. The list of branches belongs to the action you pull the connector from. Select the branch for the condition that needs to be met for the script to follow that connection to the second action.

    Deadends

    It's important to be on the lookout for dead ends in your scripts when an action has multiple branches. Dead ends can happen when branches are missing or not configured properly. For example, a Music action needs to be connected with a Wait action. Wait allows you to specify how long the Music action plays before resetting and repeating. Without Wait, Music plays indefinitely.

    Multiple Connections to the Same Action

    You can create multiple connections to the same action. This is necessary when there is more than one condition that can result in the script ending up at the target action. Instead of adding a copy of the target action to the script once for each condition, you can create three branches that all end at the same action.

    In the following image, you can see an example of a script with three branches that go from the Hours action to the Hangup action. Each branch has a different conditions to address three scenarios where the contact center is closed.

    An example of a script with three branches that go from the Hours action to the Hangup action. The conditions for the branches are Default, Closed, and Holiday.

    Connectors

    Connectors are lines that connect two actions. The connector's arrow points in the direction of the flow of the script. You can connect actions by clicking the small triangle in the corner of the action icon and dragging to the next action.

    Key facts About Connectors

    • Click the connector icon in the lower right corner of the action icon and drag it to the second action. Drop it in the center of the second action.
    • When you move an action to a different place on the canvas workspace, the connector moves with the action. It doesn't change shape, but it moves to the nearest side of the stationary action. It the length of the connector changes, too.

    • You can change the shape of the connector so that all branches are easy to see. This helps make your script more readable and easier to update.

    • If you need to change the branch that a connector uses, you must delete the connector and add it again.

    • Delete a connector by clicking on the arrow in the center of the line and pressing the Del key on your keyboard.

    Types of Connectors

    There are three types of connectors and they each look slightly different on the canvas. Learning to identify them can help you understand a script at a glance. The following example of a script shows the three types.

    An example of a script showing the three types of connectors.

    The types of connectors are: 

    • Default: This is a connector that uses the Default branch condition. It's a solid black line without a label. In the example image, the connector linkingBegin to Menu and Menu to Play are default connectors.
    • Regular: This is a connector that uses any branch condition except Default. It's a dashed grey line with a label. The label matches the condition the branch uses. In the example image, the connector linking Loop to Menuis a regular connector. Its label is Repeat, which is the name of the branch assigned to the branch.
    • Custom: This is a connector that uses a variable branch condition. It's a solid gray line with a label. The label matches the name of the custom condition assigned to the branch. In the example, the connectors linking from Menu to each of the Reqagent actions on the right are custom connectors. Their labels are 1, 2, and 3, which are the names of the variable conditions assigned to each branch.

    Key Actions to Know

    The following table contains some of the key actions you need to know to begin scripting. There are many more important and useful actions. This actions described here are only a starting place.

    Action Details
    Assign Use this action to create a variable and assign a value to it.

    Begin

    		This is the first action in every script.
    Countagents This action checks the total number of agents in a particular stateClosed The availability status of an agent for a particular ACD skillClosed Used to automate delivery of interactions based on agent skills, abilities, and knowledge.
    Createemail Use this action to automatically generate and send an email message.
    End, Hangup, and other terminating actions Terminating actions are the last actions in the script. They end the script and the contact, and terminate background processes.
    For, If, and Loop Use these actions to create looping or conditional statements in your script.
    Hours Use this action so the script can determine whether your organization is open, closed, or on holiday.
    Menu This action plays a message and creates a menu of choices the contact can choose from.
    Music This action plays a music file. You can select from a set of files provided with the action. It's useful to play music while a contact is on hold.
    Note and Annotation Use these actions to add notes or annotations to your script.
    OnAnswer, Onhold, Onrelease, Ontransfer, and other event actions Event actions start a new branch of the script when a certain event happens during an interaction. For example, when an agent answers a call, the script jumps to the Onanswer action of the script.
    Play This action plays an audio file for the contact. It can use prerecorded audio or text-to-speech, or both.
    Record Use this action to record the caller's voice in MP3 format for playback purposes, such as for voicemail. Use Delete to remove saved files.
    Reqagent This action requests the next available agent to handle a contact. For digital scripts, use the digital version of this action.
    Runsub or Runscript These actions spawn subscripts or begin another script.
    Snippet Use this action to add custom code to your script. You can use it to create and assign values to variables or dynamic objects.
    Transfer This action directs an existing call to a different phone number outside of CXone.
    Voiceparms Use this action to choose the voice and language you want to use with text-to-speech generated by actions such as Play or Menu.
    Wait This action adds a pause to the script.
    Whisper This action plays a custom message to the contact, the agent, or both during an interaction.