A

couple of weeks ago at Knowledge11 I presented a session on Advanced Incident Management. One of the topics discussed there was to help your users help themselves by finding solutions in a knowledge base. A simple way to make this more of a focus for your end users is to add a ‘Knowledge Search’ widget to the top of their homepage.
Even if you already have this functionality in your instance, this should serve as a good tutorial on adding any new custom homepage widget to your ServiceNow instance.

Knowledge Search Widget

The first step in creating a widget is to create the UI page to display the widget content. I’m not going to go into the complexities of UI page scripting here, but a UI page to add a knowledge search widget should look like this…

Note the ‘render_gadget_’ naming convention of the UI page! While it’s not an absolute necessity, you’ll want to follow this convention for any widget UI pages. You’ll definitely want to follow this convention if you want this example to work in your instance or if you want to add this to any of your out-of-box widget categories.
‘render_gadget_kbsearch’ UI Page
Name: render_gadget_kbsearch
Description: KB Search widget
HTML:

<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
   <g:inline template="kb_header_search.xml" />
</j:jelly>

Next, you’ll need to reference this UI page in a ‘Widget’ record in order to enable users (and you as an administrator) to add it to a homepage. Widgets can be found by navigating to ‘System UI -> Widgets’ and they control the options that people see when they click the ‘Add content’ link on a homepage. There are several out-of-box widgets, but I like to set up a new widget for any instance that I work on called ‘Custom Widgets’ so that I don’t have to modify any out-of-box code. If you’ve got a ‘Custom Widgets’ widget in your system then you’re okay to modify that or create a new one if you choose.

As you might expect, the widget needs to follow a very specific pattern if it is to work correctly. I always use the same pattern that is used for the out-of-box widgets to keep things more standard and simple. It really requires only a couple of things. First, your UI page MUST be named with a ‘render_gadget_’ prefix (notice how I’ve named the ‘render_gadget_kbsearch’ UI page above). Second, you need to modify the ‘sections’ function below to include a line telling the script what the label of the widget will be, and the name of the UI page…minus the ‘render_gadget_’ part. The part of the script below that displays the KB search looks like this…’Knowledge Search’ : { ‘type’ : ‘kbsearch’ }.

Chances are that you’ll have more than one item to include in your widget at some point. You can do this by comma-separating the lines included in the ‘sections’ function below like this…

function sections() {
   return {
      'Priority 1 Incidents' : { 'type' : 'pri1incidents' },
      'Priority 1 Problems' : { 'type' : 'pri1problems' },
      'Emergency Changes' : { 'type' : 'emergencyChanges' },
      'Knowledge Search' : { 'type' : 'kbsearch' }
   };
}
‘Custom Widgets’ Widget
Name: Custom Widgets
Renderer Type: Javascript
Script:

function sections() {
   return {
      'Knowledge Search' : { 'type' : 'kbsearch' }
   };
}

function render() {
   var type = renderer.getPreferences().get("type");
   var gf = new GlideForm(renderer.getGC(), "render_gadget_" + type, 0);
   gf.setDirect(true);
   gf.setRenderProperties(renderer.getRenderProperties());
   return gf.getRenderedPage();
}

function getEditLink() {
   return "sys_ui_page.do?sysparm_query=name=render_gadget_" + renderer.getPreferences().get("type");
}

Once you’ve set up your UI page and Widget record correctly you can open up a homepage and click the ‘Add content’ link in the top-left corner of the page. You’ll see your widget category name, ‘Custom Widgets’ in the first box, followed by the name of your ‘Knowledge Search’ widget in the second box to add to a homepage.

Add Knowledge Search Widget