Creating a Knowledge Search Homepage Widget

//Creating a Knowledge Search Homepage Widget

Creating a Knowledge Search Homepage Widget

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

By | 2018-07-09T14:59:59-06:00 June 6th, 2011|Categories: System UI|Tags: , , , , , |10 Comments

About the Author:

10 Comments

  1. Steve Darity June 6, 2011 at 7:51 am - Reply

    Works Great. Thanks

  2. Yogesh More August 8, 2011 at 4:13 am - Reply

    Hi Mark,

    I have implemented this in SNSB and SNDEV instances.
    When I add it to my home page it works great for that moment, but when I go for any other application and return back to home page and click on ‘Advanced Search’ then that link doesn’t work.
    Can you please advice me on this and please let me know is it the case with me only.

    Thanks & Regards,
    Yogesh More.

    • Mark Stanger August 8, 2011 at 6:16 am - Reply

      This issue must be specific to you. Since I wrote this article, this functionality has actually been added to the out-of-box product. You can see it at https://demo.service-now on the Employee Self Service homepage. It seems to be working just fine there for me and I’ve never had anyone report the issue you describe.

      • Yogesh More August 10, 2011 at 7:37 am - Reply

        Thanks!! Can you please tell me in which upgrade this is going to be the out-of-box feature?

        • Mark Stanger August 10, 2011 at 7:38 am - Reply

          This is out-of-box starting with the June 2011 release.

  3. Rick M October 25, 2012 at 2:56 pm - Reply

    Mark – I’m taking a look at implementing this widget to do a search for Knowledge and Catalog. How do I determine the inline template for the catalog search?

    Thanks

    Rick

    • Mark Stanger October 25, 2012 at 4:58 pm - Reply

      The UI page is ‘catalog_find’ and the template would be named ‘com.glideapp.servicecatalog_category_search.xml’. I’m not sure how (or if) this will work however. Please post back here with your results.

      • Rick M October 26, 2012 at 8:08 am - Reply

        Mark – Your suggestion worked. However, I thought that I would be creating a single widget that would search the Knowledge Base and the Catalog. Somehow I’ve ended up with two search widgets (one for KB and one for catalog). Both work well though.

  4. JP July 24, 2013 at 7:13 am - Reply

    Hey Mark, Would it be possible to create an incident Search widget using this method? What would the inline template be for that?

Leave A Comment