Debug Scripts in Desktop Studio

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

Required permissions: ACD > 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 ValidationSyntax 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 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 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.

  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.

  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.

  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.

  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.

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 . 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 .
  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.

  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.