Debugging best practices
This article is based on the ServiceNow documentation article. See the original article on the ServiceNow doc site: Debugging Best Practices Overview.
Debugging can provide information to help you understand system processes. Debugging best practices can be classified into two main areas: Server-side vs. Client-side practices.
Before you start debugging, it is important to identify the source of the issue, and to be able to reproduce the defect or bug. Potential sources include user error, invalid test data, test script inaccuracy, and technical implementation. To help identify and remediate the issue, the tester should provide the following information:
Server-side debugging
Before starting work on an implementation, consider using one or more of the system debugging modules in the System Diagnostics and System Security applications. Enter debug in the navigation filter to display all debugging modules. Click a debugging module to activate it. For most but not all debugging features, when the debugging feature is active, and area labeled Debug Output appears at the bottom of the content frame.
Debug log
System Diagnostics > Debug Log displays gs.debug(), gs.info(), gs.print() and gs.log() statements as well as server logging information and error messages at the bottom of the content frame. This helps you avoid alternating between the record you are trying to debug and the log output.
However, gs.print() and gs.log() are not available in scoped applications, whereas gs.debug() and gs.info() work in both scoped applications and global and are often used instead.
Debug Business Rule
System Diagnostics > Debug Business Rule displays messages about business rules. These messages indicate which business rules are being run and when they are started (==>), finished (<==), or skipped (===). If a business rule is skipped, the failed condition is displayed.
Debug Security Rules
System Security > Debug Security Rules places a debug icon on each field of a form. Point to the icon to see if there are any debug messages for the associated element. Click the icon to expand details about read and write access. This module is very helpful when you are using ACLs to control access to records and fields. The debug security rules have enhanced functionality, allowing you to view a context parameter.
Stop Debugging
System Security > Stop Debugging disables all debugging processes.
Server-Side Debugging Persistence
When you activate a server-side debugging module, it remains active until one of the following occurs:
Log Messages Controlled by a Property
The recommended way to debug server-side scripts is to use gs.debug() statements controlled by system properties. It enables you to have distinct debugging in script includes so they can each be debugged independent of each other. They can be turned on and off the debug property in the script include with a property so you don’t have to modify code in production to enable/disable debugging.
A common use case is a debug function in a script include that checks the value of a specific system property to determine if it should output the message indicated.
If the system property debug.MyUtil is set to false, nothing will be output to the log. If it is set to true, the debug message will be displayed. When combined with Debug Log or Debug Business Rule, this property can be used to enable or disable debug information without changing code and without impacting the user experiences of others on the system.
If a tester or user reports that something is not behaving as expected in test, QA, production, or another instance, you can enable the property, enable debugging output, and investigate your results quickly.
Scoped Application Script Logging
gs.print() and gs.log() are older and not available in scoped applications, whereas gs.debug(), gs.info(), gs.warn(), gs.error() work in both scoped applications and global are therefore are more versatile going forward in future versions.
Another helpful function gs.isDebugging() and can be used to determine if session debugging is on OR the scoped property is debug.
Other Methods
Some developers use the gs.addInfoMessage() or gs.addErrorMessage() JavaScript methods, but these may have an impact on the user experience. Consider the following situation: another developer is trying to debug a business rule running on the Task table while you are trying to do a code review or demo on the Incident table. Suddenly several messages appear at the top of the content frame, leaving you to wonder if they will appear in production when you are not even sure where they came from in development.
Using gs.log() (and alert() for client-side scripts) statements in scripts may seem fairly anonymous to other users at first. They do not show up on the screen and you have to know where to look to see them. The drawback to using gs.log() and alert() statements to output debug messages is that they often get left in the code. If gs.log()and alert()statements are left in the code, they can have a considerable impact on the size of the system log file. Just one gs.log()and alert()in the right spot can be triggered hundreds or thousands of times by users, system imports, scheduled jobs, and so on. Large log files full of debug messages adversely impact back up and restore times for information with little value in production. Controlling log messages with a system property prevents gs.log()and alert()statements from filling up the log. Additionally, system back ups and restores can take longer with erroneous production messages.
Client-side debugging
To debug processes on the client side, click the settings icon in the banner frame, select Developer from the menu and turn on JavaScript Log and Field Watcher. This will open the log viewer at the bottom of the window. Along with useful system information, you may choose to include jslog() statements in client scripts and UI policy scripts to help isolate and resolve issues. Unlike server-side debug statements, jslog() statements in client-side scripts do not consume disk space. This means you can leave them enabled, even in production. alert() statements should be avoided if possible.
Browser Debugging
If available, check the browser’s console log for additional debugging information. For example, the Firefox and Chrome console logs often display error messages that do not appear anywhere else. Using these logs can help speed up the development and troubleshooting processes by locating undefined objects.
Service Portal and External User Debugging
The Service Portal is often the only way external users access ServiceNow in certain applications (e.g., Customer Service). Currently, in the Service Portal interface, the section for Debug Output does not appear at the bottom of the content frame and therefore, debugging logging messages are not viewable except in the log. In the case of Debugging Security Rules quickly via the graphical Debug Output, an alternate solution is required to see it at the bottom of the screen if you need to debug as an external user since these ACL rules do not display in the log.
You can impersonate the external user who should only go to the Service portal, then in the internal platform view it will say “Security constraints prevent this view…” and it hides the menu and the page is blank there is nothing to do. At this point you usually type the service portal page appended to your URL like “http://instance.service-now.com/csm“ and go to the Service Portal, but the Debug out will not show up at the bottom of the content frame.
Instead, as an admin, you can first go to the normal internal interface of ServiceNow and get the URL of a specific page you wish to view the Security Rules on. Then, impersonate the external user and in a new browser go to that URL – the view and or form will not look the same, but you can still see the correct Debug information at the bottom of the content frame. (It won’t actually bypass any true ACL security or Before Query Business Rules so of course the external user still can’t see any data they shouldn’t.) However, it does give you a better view than the SP pages and I can see the full graphical ACL debugging there which is incredibly helpful.
Disabling Debugging
Before you close out an update set or complete testing of the production instance, be sure to disable all server-side debugging to save log space in production. To disable debugging, search for all system properties that contain the string debug in the name and ensure they are all set to false.
This is another good reason to use properties to control debugging in a script. It makes enabling or disabling debugging a simple task, such as when you need to validate use cases or data.
