Debug Scripts

Required permissions: Applications > Studio > Scripts > Debug

Studio provides two ways you can check for issues in your scripts: 

  • Check for syntax errors.
  • Run a script trace, which shows you what's happening as the script processes each action.

If you have Snippet actions in your script, you can debug the snippet code from within the Snippet Editor window.

Check for Syntax Errors

When you check for syntax errors, any issues found in your script appear in the Script Errors tab. The tab shows you all warnings and errors related to your script, including in snippets. Warnings don't prevent your script from running or saving, but errors do. Best practice is to address all warnings before putting the script into production, even though they don't keep the script from working.

Syntax checks happen automatically when you save a script, but you can run a syntax check anytime you want. You won't be able to run or save a script that contains errors. If you attempt to run or save a script that has errors, Studio displays a notification window. You can check the Script Errors tab for more information. Errors can include things such as:

  • Incorrectly spelled variables. For example: Snippet Line 2. Function: NameLabel has not been defined.
  • Using a function as a method parameter. For example: Unterminated function parameters.
  • Using an incorrect data type in a function that requires a specific data type. For example: Unterminated function parameters.

There are some errors that may not appear on the Script Errors tab. Some validation errors appear in an error notification window with details about the error. Validation errors include things such as invalid JSON in the REST API action. If you attempt to save when the script contains a validation error, the script may revert back to the most recent version of the script without the validation error. If this happens, any unsaved changed are lost.

Double-click any a warning or error in the Script Errors tab to see the action on the canvas where the issue occurs.

  1. In Studio, open a script.
  2. Click Validation > Syntax Check.
  3. Click the Script Errors tab to view the results of the syntax check.
  4. Double-click any warning or error on the Script Errors tab to see the action on the canvas where the issue occurs.

Script Traces

You can track the progress and performance of your script with the Trace Output tool. This tool traces the contact through the script and displays the results of each action that fired, what variables are being set and when, and the values the variables held at each point. This is a helpful tool to test and debug your scripts. You can run traces on live interactions or simulated ones.

You can only run a trace if the script is saved. If you attempt to run a script trace on a script with unsaved changes, Studio prompts you to save the script. If you have errors in the script, Studio won't save the script. You must resolve errors before you can save the script and run the trace. Any validation errors in the script cause Studio to revert to the last version of the script without the validation error. If you've started a trace, it runs, but will run on the last saved version of the script.

Use the Trace Output Window

When you run a trace, the output appears in the Trace Output window. You can use this window to view the variables in the script and see how they change as the script progresses through each 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..

  1. In Studio, open a script and run a trace or open a saved trace file.

    The Trace Output windowm, showing the output of a trace on an inbound voice script.
    Field Details
    IBVoice The name of the script. IBVoice is the name of the script in this example image.
    Toolbar

    Under the script name is the Trace Output window toolbar. This toolbar contains options that allow you to:

    • The icon for the View and Layout options in the Trace output window. A rectangle that looks like an empty window.: Change the layout of the Trace Output window, including the panes and tabs that are visible.
    • The Tools icon in the Trace output window, a hammer and a wrench crossed in the shape of an X. : Change the variables that are visible in the Variables tab, save the current watch list, and save the current trace to a file on your computer.
    • The set of icons in the Trace Window toolbarthat allow you to create and manage a watch list.: Create and manage a list of variables you want to watch in this trace.
    • A set of icons that allow you to expand and collapse all of the variables or actions that have information inside them in the lists.: Expand or collapse all actions or variables that have information inside them.
    • The contact ID and name and path of the script that's being traced.: This part of the toolbar shows you the contact ID of the current contact. It also shows you the name and path of the script being traced.

    You cannot change the location of the toolbar.

    Properties

    When you select an action in the Script Details pane, the Properties pane shows you all of the action's properties and their configuration settings.

    The default location of the Properties pane is on the top left side of the Trace Output window under the toolbar.

    Script Details

    The Script Details pane shows you all of the actions that fire as the script runs, in the order they fired. It doesn't include actions that are part of the script but didn't fire, such as actions that are part of a branch that wasn't taken.

    When you click an action, all variables in the script at that point appear in the Variables tab.

    The default location of the Script Details pane is on the top right side of the Trace Output window under the toolbar.

    See the drop-down table in step 2 for information about the column headings in this pane.

    Variables Tab

    When you select a variable in the Script Details pane, all variables currently in the script appear on this tab.

    The default location of the Variables tab is at the bottom of the Trace Output window.

    Watch List Tab

    You can create a list of script variables that you want to track as the script runs. The variables that you add appear on this tab.

    The default location of the Watch List tab is at the bottom of the Trace Output window.

  2. In the top right of the Trace Output window, click an action in the script details pane. If you're watching a live trace, this pane updates in real time as the script progresses and fires off each action.

    Field Details
    Script The name of the script containing the action. If a main script spawns a subscript, you may see more than one name in the list.
    Time The time that the action fired.
    Action The name of the action, including the arguments for each. The arguments are all of the configuration settings in the action properties.
    Result

    The outcome of the action firing. This indicates what happened as a result of the script processing action. This may be the branch the script followed or the action that occurred as a result of the action firing. 

    For example, in the example image in step 1 of this section, Default and Error are branches. DirectJump to 4 and StartAt ONRELEASE are the outcome of those actions firing. DirectJump to 4 indicates that the contact selected an option in the 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 that caused the script to jump to the action with Action ID 4. StartAt ONRELEASE indicates that the script is currently waiting and will restart when an agent answers the interaction.

  3. Click the icons in the toolbar at the top of the Trace Output window to expand The Expand All icon in the Trace Output window, a square with a minus sign it in and a series of stacked horizontal lines next to it, rrepresenting an open list. or collapse all The Expand All icon in the Trace Output window, a square with a + in it and a series of horizontal lines stacked next to it representing a list. of the details for variables in the script details pane. This affects any variable that has additional details within it. These variables are indicated by a + icon next to the name.

  4. Click the Variables tab at the bottom of the window to scroll through all of the variables present in the script when the selected action fired.

    Field Details
    Name The name of the variable. Variables with names that start with two underscore characters are system variables.
    Value The value of the variable. This can change as the script progresses from action to action.
    Type The type of variable. Options are Variable for standard single-value variables or UCN.Data.Dynamic for dynamic data objects.

  5. Click the Tools icon The Trace Tools icon, a hammer and a wrench crossed like an X. and select an option to change what variables are displayed in the Variables tab.

    Field Details
    Show Global Variables in Subs Select this option if you want global variables to appear in the Variables tab. This includes global variables that are set in this script or are set in another script and can be used in this script. For example, a subscript.

    Show System Variables

    Select this option if you want pre-defined system variables to appear in the Variables tab. These are variables added to the script automatically by the system, including the actions in the script.

    Show Private Members Select this option if you want private members to appear in the Variables tab.
  6. On the Properties pane, you can see the properties of the selected action and how they're configured.
  7. Add variables to a watch list, if you want to track specific variables through the trace.

Change Variable Visibility in a Trace

You can change which sets of variables show in a trace. This allows you to focus on specific kinds of variables, depending on what you're looking for in the trace.

  1. In Studio, open a script and run a trace.
  2. In the toolbar of the Trace Output window, click the Tools icon The Trace Tools icon, a hammer and a wrench crossed like an X. .

  3. Select the option for the variable set you want to view or hide in the trace. Options with a check mark next to them are currently visible in the trace.

    Field Details
    Show Global Variables in Subs Select this option if you want global variables to appear in the Variables tab. This includes global variables that are set in this script or are set in another script and can be used in this script. For example, a subscript.

    Show System Variables

    Select this option if you want pre-defined system variables to appear in the Variables tab. These are variables added to the script automatically by the system, including the actions in the script.

    Show Private Members Select this option if you want private members to appear in the Variables tab.

Capture a Script Trace

You can capture a trace on a script as it runs. You can do this with production scripts processing live contacts. This allows you to diagnose issues that your contact center is experiencing, or capture data for troubleshooting with technical support. You can choose to capture a trace on the next instance when the script runs, or you can capture a continuous trace. A continuous trace captures every interaction the script processes. When you capture a single trace, the resulting information appears in the Trace Output window.

  1. In Studio, open the script you want to capture a trace of.
  2. Click Debug > Capture Script > Next Instance.
  3. When an interaction starts and the script begins to run, the Trace Output window opens. The window displays the trace as the script runs.

Capture a Continuous Script Trace

A continuous trace captures every interaction the script processes. The trace output is saved to files in your CXone business unitClosed High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment. You can specify where these files are saved.

  1. In Studio, open the script you want to capture a trace of.
  2. Click Debug > Capture Script > Continuous. Studio begins to capture all instances of the script running.

View Trace Files

You can view the trace files saved from a continuous trace.

  1. In Studio, click the Debug menu, then select whether you want to load a trace file that's located on your system or remotely in your CXone business unitClosed High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment.
  2. Select the file you want to open from the file window that appears.
  3. Click the button to open the selected trace file. The name varies depending on whether you're opening a local or remote file. The selected file loads in the Trace Output window.
  4. If you want to download trace files from CXone to your local computer, click the Tools icon The Trace Tools icon, a hammer and a wrench crossed like an X. in the Trace Output window, then select Save Trace As.

Capture a Trace with a Specific ANI or DNIS

You can set a specific ANIClosed Also known as caller ID. Listed phone number of an incoming voice call. or DNISClosed Identifies the number the contact dialed to reach you for inbound voice calls and the number the agent or system dialed on outbound voice calls. to fire a trace when a call from the specified number comes into the system.

  1. In Studio, open the script you want to capture a trace of.

  2. In the Studio toolbar, click the Trace Script drop-down and select Trace when ANI is or Trace when DNIS is.

    Image of the trace options in the Studio toolbar.
  3. Enter the ANI or DNIS number you want to trigger the trace in the Insert <number> field.
  4. Click the Capture Next Instance icon A grey sphere. . The number of times you click changes the behavior: 
    • Click once to trace the next instance of the script running with the specified number. The icon turns red.
    • Click twice to continuously trace future instances of the script running with the specified number. The icon changes into two red circles.
    • Click three times to clear the capture. The icon reverts to its original gray color.
  5. The next time the script runs with the specified ANI or DNIS, a trace is captured and saved to a file.

Watch Variables in a Trace

You can create a list of variables that you are particularly interested in. The watch list allows you to track only these variables without having to search for them in the trace. You can save the list so that each time you run a trace on that particular script, the watch list is saved and loads into the Trace Output window.

  1. In Studio, open the script you want to trace.
  2. Run an initial trace of the script.
  3. In the Trace Output window, click through the list of actions in the script details pane. The variables associated with each action appear on the Variables tab.
  4. For each variable you want to add to the watch list:
    1. Select the variable on the Variables tab.
    2. Click the Add to Watch List icon The Add to Watch List icon - a pair of glasses..
  5. You can add a variable manually if you know the name:
    1. In the toolbar of the Trace Output window, click the plus sign icon. The Watch List tab appears with a field for a new variable.
    2. Enter the name of the variable you want to watch and press Enter.
  6. If you want to remove a variable from the watch list, select it on the Watch List tab and click the minus sign icon in the toolbar on the Trace Output window.
  7. To save this watch list, click the Tools icon The Trace Tools icon, a hammer and a wrench crossed like an X. in the toolbar of the Trace Output window and select Save Watch List. The list is saved in Studio. Each time you run a trace on this script, the watch list loads in the Trace Output window.
  8. When you're ready to watch the variables in your watch list, run a new trace on the script.