Instance Troubleshooter User Guide

PLEASE NOTE:

• Beginning with the Now Platform® Xanadu release planned for September 2024, we will no longer deploy or activate the application listed below to new instances. It will remain active in your instance, including when you upgrade to a new release family.
• Beginning with the Now Platform® Yokohama release planned for March 2025, we will end support for the application listed below. While it will remain active in your instance, including when you upgrade to a new release family, we will not be able to support it. 

Overview

Instance Troubleshooter, a free store application, helps ServiceNow instance administrators to resolve issues on their instances by themselves. This application can detect issues in the instance across several product categories. When the administrator invokes the troubleshooter, each product troubleshooter runs one or more checks and reports findings with detailed information and links to resolving the issues by themselves. The administrator can view the progress, review the findings, and take actions to fix the issues on the instance. This user guide explains how Instance Troubleshooter helps perform these steps.

Instance Troubleshooter

This application allows system administrators to detect and resolve issues in the instance on their own instead of opening a case and waiting for assistance from Technical Support. The process of detecting issues is automated on the instance. The administrators run diagnostics themselves which provide crisp and clear recommendations and related Knowledge Base articles for the issues detected on the instance. If an issue is still not resolved, administrators can create a case for Technical Support.

Self Service UI

The user interface for the Instance Troubleshooter lets administrators perform activation, troubleshooting, and reviewing the findings. Each of these tasks is described in detail in this article.

Installing Instance Troubleshooter

The application is available for installation in your instance in System Applications > All Available Applications as well as in the plugin list, you will find it as "Instance Troubleshooter" or by the Id "com.sn_troubleshooter". Please find more information about how to install a plugin in Activate a plugin or in the video ServiceNow plugins on Now Support.

The application can be installed both on production and sub-production systems to troubleshoot issues in your instances. Choice of where to install the application is entirely dependent on development/deployment workflows customers have in place in their organization for customizing their instances.

Activation/Repair

The troubleshooter plugin provides the ability to click on a repair option. These reinstate the plugin to its earlier state.

Accessing Instance Troubleshooter

The permissions to run this store application are granted to the System Administrator (role: admin) and Scan user (role: scan_user). Users with lower privileges can be granted access to run the scan through scan_user role, but they cannot activate or make changes to the application.

Launching Instance Troubleshooter

When you search for "Instance Troubleshooter" in the navigation pane, you will be presented with the Get Started page, where you will find a collection of cards corresponding to each product category. Each card has a menu on the top right that has more options and can be accessed by clicking the vertical ellipsis icon. One of the choices in the menu is "Learn More" link that takes you to respective online product documentation to help you learn more about the product.

These are all searchable by the search bar. The product categories along with their references are:

• Access Control
• Authentication
• Clone
• Core Platform
• Currency
• Discovery
• Email
• Forms and Fields
• Import/Export
• MID-Server
• Mobile
• Performance
• Performance Analytics
• Reporting
• Service Catalog
• Service Portal
• SLA
• User Experience
• Workflow

The search bar allows us to search for product categories. Each product category has a Troubleshoot button that launches the troubleshooter and runs corresponding checks included in that product category.

Running a new scan

Invoking the Troubleshoot button in a product category displays a confirmation box:

Starting the troubleshooting displays a progress bar as.

The results of the scan are ready to view by selecting the Go to Result button once the scan has been completed. These results will appear in a related list name Scan Findings.

And here's a view of the information shown in each of the Scan finding records:

Organization

The product category is a group of checks organized in a suite for instance troubleshooting. The checks detect potential problems with the instance. Each product category checks for a set of issues on an instance. These issues are automatically diagnosed and are reported to the user as scan results with findings along with their resolutions. The list of issues detected by the troubleshooter is simple but sweeping in its coverage of the instance as we add more product categories to the troubleshooter. The troubleshooter detects common problems with simple solutions that can be resolved by instance administrators themselves.

Determine findings and results

The results page displays findings if any. A finding is a potential issue detected by a check in the product category that the troubleshooter ran. Troubleshoot action is not expected to always find issues as each product category is programmed to diagnose/look for a specific set of issues. When found, findings need to be investigated by reviewing the resolution details and documentation URL.

The columns in the scan findings are:

• Check – The script that was run
• Source - The table where the data was found
• Resolution Details – Resolution details for the administrator to follow to resolve the issue
• Documentation URL - Link to the documentation that describes the resolution

Navigate findings and scripts

Pre-defined scripts and their checks

Each script corresponds to three distinct types of checks. These are a table check, a column type check, or a script-only check. These checks are the same as those defined under the System section of the ServiceNow instance from the sidebar navigation panel. They can be listed in a ServiceNow instance using the scan checks listings. The results page from a troubleshooter run conveniently links these scripts, so they open individually and directly from the results page.

The corresponding suite is indicated in the tab adjacent to the findings. That links to the suite under which these checks are stored. The list of all checks can be seen from the suite. A product category usually has a one-to-one reference between a product category and the suite. All the checks in the suite can be seen from the suite page but the checks tab adjacent to the suite indicates those from the findings. A finding describes the ‘source_table’ as well as the ‘source’ which is a record in that table that caused the check to fail.

Checks and their follow-up

The checks are self-explanatory from their viewing on the ServiceNow instance portal. Usually, the checks describe the purpose and the method. It is advisable to make sure that the check indeed failed before attempting resolution. A check can be run again directly from the check page or via the Troubleshooter page.

Resolutions and follow-up

The resolution and documentation links provide additional information with which to resolve the finding

If the resolution you took failed in alleviating your case, please open a new request with ServiceNow Support. The troubleshooter is only intended to self-serve frequently encountered issues.

Instance improvement with Run

A single run may flag a finding. If the run were repeated without any resolution, the finding may be repeated. The troubleshooter should be run again after all the findings have been reviewed and some resolutions have been made. The instance improvement will be seen from the reduction in the number of findings.

Monitoring and Dashboard for troubleshooter executions

The Monitoring dashboard allows users to see the statistics on the findings and scans from their prior runs.

These include:

• The number of scan tasks 
• The number of scans this week
• The number of findings this week
• The number of scans this month
• The number of findings this month

Then there are charts for:

• Weekly Scans Report (bar chart)
• Weekly Findings Report (bar chart)
• Monthly Scan Report (line graph)
• Monthly Findings Report (line graph)

Use the information between the product categories and the total to determine the product category that is the heaviest contributor to findings. Then see the trends of these categories over daily, weekly, monthly periods.

Clicking on the chart takes you to the data source which appears as a table with rows.

Findings based on weekly, or monthly time ranges could also indicate broad trends on the health of a component.

Each scan has a set of findings, results, failures, and logs and they can be used to get more information about the product categories.

Screenshot of the dashboard:

Scheduling Troubleshooting

"Troubleshoot' action in Getting Started page requires an active user session and preferred when you are investigating an issue with the instance. If you are interested in keeping your instance healthy at all times and want to proactively identify issues, we recommend using the scheduling feature available in the app. "Schedule" option can be accessed through more options menu available in each card as seen below:

You can have any number of schedules per product category. Instance Troubleshooter leverages Instance Scan and so please navigate to Schedule a suite scan documentation to learn more about various options available for scheduling a troubleshooter scan.

Tracking Progress With Tasks

When you Troubleshoot a product category, whether as part of an active investigation or to keep instance healthy, application may surface zero or more findings and at times a large number of findings that need to be acted on. To facilitate task assignments for the findings, for the purpose of tracking the resolution, we added the ability to create tasks automatically based on customer configuration.

First step in enabling task integration is to set up task configuration for troubleshooter product categories for which you want automated task creation. You can create/view/edit/delete task configurations for each product category by choosing the "Scan Task Config" option in more options menu as below

Choosing the scan task configuration option will take you to task configurations for the suite it was invoked from. If you already have a task configuration, it would look similar to below

Here is what the various fields in task configuration mean

• Active - Whether this configuration is enabled or not for the suite in question
• Assignment Group - Assignment Group that the newly created tasks should be assigned to by default
• Assigned To - Person the newly created tasks should be assigned to by default
• AutoClose - When set to 'true, we will close all active tasks that are older than 90 days
• Priority - Allows users to list the priority of the findings for which to open tasks. For example, selecting "2" will only open tasks for that priority
• Suite - Product category/suite for which this configuration applies

Instance Troubleshooter application creates tasks for new findings based on the configuration through business logic. The application creates one task for all new findings associated with a check. Subsequent scans only create tasks for new findings that are not actively tracked by an already existing task. Users can view tasks created for each product category by going to the Getting Started page, and choosing the "Open Scan Tasks" option in the more options menu in the respective card. Instance Troubleshooter leverages Instance Scan and so please navigate to Creating scan tasks documentation to learn more about what tasks are and can do.

Target Scan

When users invoke the "Troubleshoot" action on a product category, instance diagnosis starts immediately which scans on the entire instance. If users know exactly which data source/table/record they have issues with, the target scan feature enables them to target diagnosis of just that. You can invoke a target scan by choosing the "Run Target Scan" option in the more options menu of the respective product categories you want to troubleshoot.

Invoking target scan brings up a modal dialog as shown below that allows you to choose the table and record to target for the troubleshooting.

Target scan feature uses Point Scan feature provided by Instance Scan plugin under the hood.

Providing feedback to product Team

Application provides few ways to share feedback about the product to the product team.

Have an Idea?

Use the "Have An Idea?" button on the "Get Started" page to share ideas or suggestions you have to improve the product. Invoking the button will take you to the Idea Portal page hosted at Now Community. Once there, select the "Create an Idea" button and provide your idea under the "Instance Troubleshooter Application" category. Once there, you can also view ideas submitted by others and vote on the ideas already submitted. If you would like to learn more about the Idea Portal itself, please go to Idea Portal - ServiceNow Product Enhancement Requests

Feedback on Scans

When you are on the "Scan Result" page, users can use the "Provide Feedback" link in the "Related Links" section to provide feedback on the scan. Invoking the link will prompt the user to make a couple of choices and provide feedback in a quick and easy way.

Feedback on Findings

When you are on the "Scan Finding" page, users can use the "Provide Feedback" link in the "Related Links" section to provide feedback on the specific finding. Invoking the link will prompt the user to make a couple of choices and provide feedback in a quick and easy way.

Demo Video

Disclaimer: The images used in this document are subject to change with the release of this store application. They are shown here for illustration purposes only. Please follow directions on the user interface of the application for the same steps described in this document.