Debugging is an essential tool to troubleshoot problems with your code and determine the solution to a defect.
What method is best?
Like other languages, Snap offers multiple methods to debug code. Every programmer has their own preferences, but we suggest the following:
- If you are debugging server-side rules, use logging.
Your log messages will appear in the Infrastructure > Logs page of the administration interface.
- For debugging client-side rules, you can use logging or breakpoints.
Your log messages, breakpoints, and other info will appear inside your web browser, next to the running Epicor CPQ web page.
- For more advanced client-side logging, you can also activate automatic logging to trace your client-side rules: see when rules run, and how long they take to complete.
Method One: Logging
If your logic is not performing as you expect it to, an easy and always useful technique is using the "write log" block to add messages to the log. You can log anything from the simple value of a variable, to the complex structure of a custom type or the contents of a web service call. Using multiple log statements, you can show the value of variables, function returns, and other constructs to see their contents change over time.
Example A: logging a client-side rule
Example B: logging a server-side rule
To turn on automated logging
Method Two: Breakpoints
- Consider a simple client-side rule, such as this value rule:
- Insert log statements into the code:
- And run the configurator. If you press F12 in your browser, you'll see the debugger appear on the side of the screen:
- Given a simple safe function, like this one:
- You can insert log statements into the code:
- And then visit admin > logs to see your results:
- Note how the most recent entry appears at the top of the server logs: you can change the sort order by clicking any of the columns in the log display.
- Note the different types of logs we used in our "write log" Snap blocks result in different info, warning, and error icons next to the log entries. Any log entries tagged with "error" can also result in automated alerts to administrators who have subscribed to error notifications.
You are not limited to logging simple text or numbers. Use the "Serialize to JSON" block to convert just about anything into loggable text, including query results, web service call results, or complex types.
Breakpoints pause the execution of client-side code and provide you with a snapshot of the code at that moment. From there you can inspect variable values, use a stack trace to determine how you got to your present position, and many other powerful tools. Breakpoints are only available for client-side rules: you cannot set breakpoints on server-side rules, such as pricing rules, workflows, or safe functions.
- Insert a breakpoint into your rule:
- Run your configurator on your web browser of choice
- Press F12 (or on some computers, Fn+F12) to open the developer tools for that browser. The next time the rule is run (for most configurator rules, this is anytime you change a field value), the execution will pause and you should see the highlighted code where your breakpoint was hit.
In the screen recording below, see how...
- the configurator and debugger can be resized, to appear side-by-side
- execution is paused
- the current step in the code is highlighted
- the values of other fields and settings can be seen
- variables of interest can be "watched" for easy reference
You don't need to create many breakpoints to pause execution. Look in your browser debugger for a checkbox with a name like "Pause on Caught Exceptions". Activating this feature in your browser debugger will pause the debugger at those times and let you inspect the code and values at runtime when the error occurs.
Method 3: automated logging/tracing of client-side rules
When running your client-side rules in more complex situations – such as with nested configurators or using message rules – you may want more information:
- Across all the Epicor CPQ objects that work together in this user interface, what rules or other complex code were run? From what objects? In what order?
- How much time did each take to complete?
Rather than adding many separate debug statements to show this flow, you can turn on automated logging. By setting this one flag, you can have all your rules announce themselves in the debug console. You can also see how much time they took to complete. This helps you to profile your client-side code, find slower rules, and optimize their performance.
- Launch your application in the Chrome browser as usual.
- Turn on the Chrome debugger as described above. In the debugger, click the "Application" tab, and then in the tree that appears, open "Storage" > "Local Storage". You will see a local storage container named after the URL of your application.
- Click on that local storage container: a table of key-value pairs will appear, with entries like "userGuid" and the like. These entries help your Epicor CPQ application work. Leave the current keys alone.
- Add a new key-value pair to the storage container, which will turn on automated logging. Specifically:
- Double-click the empty part of the table. A new row appears, and your cursor focus moves into the key column.
- To debug your configurator, enter "writeRuleCycleLogs" for the key, and "true" for the value.
- To debug your 3D scene, enter "writeSceneChangeLogs" for the key, and "true" for the value.
- Refresh the page: in the console window, see color-coded entries appear for each component in your configurator or scene that is run. Note the time in milliseconds next to the end of each event.
To deactivate automated logging
Follow the steps above, but enter "false" for the values instead of "true".
- If you use the Chrome browser, watch a short video introducing debugging with breakpoints.
- If you use Mozilla Firefox as your browser, here's a similar starting point on debugging with that browser.
- If another browser is your favorite, search online for debugging with that browser.