When developing complex OL Connect templates, User Scripts typically grow in number and complexity. You may encounter situations where they not always do what you expect them to do. See how the Script Debugger allows you to debug the scripts by tracing script execution and figure out the state of local and global variables.

A common technique for debugging is to write information to the Messages view using the logger.info() command or to temporarily write information to the section using, for example, results.after(). This can be a tedious process and requires you to clean up the code after the debug session.

The Script Debugger feature introduced in OL Connect Designer 2019.1 makes this process way easier and will save you a lot of time. The debugger provides options to step through code (e.g. execute code line by line) and to add breakpoints to pause execution at strategic points, and it shows the state of local and global variables. The main template editor displays the document which is merged up to the point where the script is paused.

The Script Debugger dialog

The Script Debugger simulates an output run for all sections in the current context, including section clones. The output run is limited to running scripts and pagination for the current record. For a print context it will not generate the actual output, and for an email context it will not generate attachments or send the email message.

In order to debug your code, you will first need to invoke the Script Debugger dialog. There are two ways to invoke the dialog:

• Click the Debug Scripts button in the toolbar of the Scripts panel. The debugger will pause and accept input as soon as it processes the first script.
• Or right-click an enabled script in the Scripts panel and choose Debug… from the contextual menu. The debugger will pause and accept input as soon as it processes the selected script.

Scripts pane

The Scripts pane on the left hand side of the Script Debugger shows a list of all enabled scripts that apply to the current context, in the order in which they are expected to be processed. The actual order may be different though; scripts with selectors without matches will be skipped, and there are usually multiple passes for different resources.

Variables pane

This shows a hierarchical overview of the state of all local and global variables. It includes the special entry “(this)”, which represents the JavaScript “this” object.

Debugging a script

Although thelogger.info() method may get the job done, breakpoints help you to fix bugs faster. Breakpoints have a few advantages over the logger.info() method:

• With logger.info(), you need to manually open the script entry in the Scripts view, find the relevant code, and insert one or more logger.info() statements. Subsequently you need to trigger the Preview mode and check the Messages view. You will need to repeat these steps when the message entry is not showing the desired result.
• In your console.log() statements you need to explicitly specify each value that you want to inspect. With breakpoints, the Script Debugger shows you the values of all variables at that time.

A breakpoint lets you pause the code in the middle of its execution, and examine all values at that time via the Variables pane.

Example

Let’s take a look at the following debug session. Previewing the document showed that a certain placeholder in the programmatically created detail table was not populated with the value of the data field.

A debug session was started by choosing Debug… from the contextual menu for the respective script entry. One could use the Step Into and Step Over buttons to execute the code line by line. When you have a hunch about the code that could cause the problem, add a breakpoint to it. In the image shown below, a breakpoint was set for the function that is responsible for adding the data.

Note! Breakpoints only apply to the current debug session; they are discarded when the dialog is closed.

To add a breakpoint simply click in the left margin of the source editor. A small blue dot is added in the margin to mark the breakpoint. Subsequently click the Resume button at the bottom of the dialog; the script executes all code up to the line of the breakpoint. Now use the Step Into option to execute the code line by line. The current line is highlighted and shows the instruction pointer.

Hovering over the ItemNumber property (line 24) reveals the value of the respective field in the data object. This matches the data as shown in the Variables pane and matches the information shown in the Data Model view.

Clicking Step Into moves the script to the line which should add the item description data to the table. Hovering over the ItemDesc property does not return a value, but hovering over the data object on that same line reveals the tree of the data object. A keen observer will notice the missing fields level in the source code.

The Script Debugger helped us identify the erroneous line in our code. Click the Close button and fix the code in the respective script after opening it from the Scripts pane and off you go.