Application Navigator: Pimp My Filter

Summary

An out-of-box UI Script, when activated and customized, can allow you to add new shortcuts to the Application Navigator’s filter.

Details

Built-in Filters

Any experienced ServiceNow admin or developer is familiar with the special filters that can be used as shortcuts in the Application Navigator:

  • <table_name>.list to open a list of “table_name” records in the current window/tab.
  • <table_name>.LIST to open a list of “table_name” records in a new window/tab.
  • <table_name>.do or <table_name>.form to open a form view in the current window/tab to create a new “table_name” record.
  • <table_name>.FORM to open a form view in a new window/tab to create a new “table_name” record.

Some may not yet be aware that, starting with the Jakarta release, the following shortcuts have been added:

  • <table_name>.config to open the configuration lists (such as Business Rules and Client Scripts) for “table_name”.
  • <table_name>.CONFIG to do so in a new tab or window.

NavFilterExtension

Fewer still may know that there is an inactive out-of-box UI Script called NavFilterExtension that allows you to extend the filter options. It contains sample code (commented out) to help you get started. Here’s what it looks like:

//**************************************************************************
//* This function is called before default nav filtering is done.
//* If function returns false, default nav filtering happens next.
//* If it returns true, no more nav filtering is done for current keystroke.
//*
//* val is the current content of the nav filter input
//* msg was the initial content of the nav filter input on focus
//**************************************************************************

function navFilterExtension(val, msg) {

//  if (val.endsWith('.dict')) {
//    // example: incident.dict
//    // navigates to Dictionary records for the specified table
//    val = val.replace(/ /g, '');
//    document.getElementById('gsft_main').src = "sys_dictionary_list.do?sysparm_query=name=" + val.replace('.dict','');
//    restoreFilterText(msg);
//    return true;
//  } 

//  if (val.endsWith('?')) {
//    // example: sys_user:nameLIKEbeth?
//    // query specified table using encoded query after the colon
//    val = val.replace(/ /g, '');
//    var table = val.split(":")[0];
//    var query = val.split(":")[1].replace('?','');
//    document.getElementById('gsft_main').src = table + "_list.do?sysparm_query=" + query;
//    restoreFilterText(msg);
//    return true;
//  }

  return false;
}

Examining the UI Script, we see the following:

  • It takes two parameters:
    • ‘val’
      • This is what the user typed into the filter before pressing ‘Enter’.
    • ‘msg’
      • This is what was in the filter before it had focus. (I would think this would generally be empty.)
      • It is passed along so it can be put back into the filter after the script runs.
  • There is an ‘if’ block for each type of filter you want to handle.
    • (You could also use a series of ‘else if’ blocks. Technically that would be more efficient as it would stop evaluating ‘if’ statements once it found a match.)
    • The contents of ‘val’ are used to determine which block to run.
      • For instance, in the first example if the value in ‘val’ ends with “.dict”, then the “.dict” will be stripped out and what is left should be a table name that will be used to filter dictionary records to display.
      • ‘val’ can contain multiple values separated by a delimiter of your choice.
        • For instance, in the second block above, a colon (‘:’) is used to separate the ‘val’ string into two tokens: a table name and an encoded query. The encoded query is then use to filter records from the table.
  • Once we’ve parsed ‘val’, we use what we’ve pulled from it to load a new page in the Main Content frame.
    • This is done by changing the source URL for the document element with id = ‘gsft_main’.
      • Note that this could be any valid URL; it does not have to be a URL from your ServiceNow instance.
      • If you’re curious, you can inspect the HTML of your ServiceNow session to find the iframe with id=”gsft_main”.
    • You don’t necessarily have to load new content in the Content frame. You can do whatever you can manage in JavaScript.
  • Finally we restore the original filter text using the ‘msg’ parameter and then return true (to stop the built-in nav filtering).
  • If none of the ‘if’ blocks match the ‘val’ string, the script returns false and the built-in nav filtering is checked.

AppNavigator+

Todd Fudala (Veracity Consulting Group LLC) has shared a version  of the NavFilterExtension UI Script that is a great resource as-is or as a source of examples and ideas. He calls it AppNavigator+ and he has kindly put it on the ServiceNow Share. His script allows the user to use the App Navigator for a global search, to open a specific task by number, to search a table using an encoded query and much more.

Resources