Some time ago we showed you how to refresh the left navigation pane via a script. The server-side solution in that article utilizes ServiceNow’s UINotification object/class. On versions prior to Calgary, this is the Java class Packages.com.glide.ui.UINotification. 

There’s another use for UI notifications. In addition to refreshing the left navigator, the object can also be used to display informational messages. You’ve probably already seen these in your own instance. When you change update sets, the system reminds you by using a UI Notification similar to the one shown below:

Update Set Change

If you’re like me, you may have wondered how these notifications are created. Displaying a custom UI notification is slightly more complex than using the addInfoMessage() method provided by the GlideSystem (server) and GlideForm (client) classes. In return, it gives you some capabilities that aren’t otherwise available. These include options to set fade-in and fade-out effects and the ability to make the notification persistent or to close it after a user-specified interval. If you want to learn more about the various types of notifications available in ServiceNow, check out our UI Info and Error Message Cheat Sheet.

The example below uses the UINotification object to display a list of all fields that have been changed on an incident. I’d like to take credit for this solution, but it was actually my colleague Jim Coyne who did the heavy lifting. I’m most especially indebted to him for compiling the all-important list of option properties that determine how the notification behaves.

As with any undocumented API, ServiceNow could make changes to the UINotification class at any time that might break the functionality we’re describing. Also, ServiceNow Technical Support won’t give you any help if you have trouble with this. Be sure to keep those things in mind if you decide to use custom UI Notifications in your instance.

Creating The Notification

To create the UI Notification and its options, use a global UI Script:

‘Popup UI Notification’ UI Script
Name: Popup UI Notification
Active: true
Global: true
Description: Adds a popup UI Notification to the DOM. Can be called from any server-side script. For an example, see ‘Changed Fields UI Notification’ business rule on the Incident table.
Script:

//Ensure that the CustomEvent object exists
var intervalTest = setInterval(function(){
   if(typeof CustomEvent != 'undefined'){
      clearInterval(intervalTest);
      setCustomEvents();
   }
},500);

//Add the UI Notification to the DOM using the CustomEvent object
function setCustomEvents(){
   //Set the name of the notification
   var notifName = "demo_notification";
   CustomEvent.observe('glide:ui_notification.' + notifName,
   function(notification){
      var msgText = notification.getAttribute('text1'); //get the message text from the attribute passed in by the business rule
      var options = {}; //create a new object to store all of the message attributes.
      options.text = "<span style='color:red;'>" + msgText + "</span>";
      options.sticky = true;
      options.closeDelay = 5000;
      options.fadeIn = 500;
      options.fadeOut = 500;
      new NotificationMessage(options); //display the UI Notification
   });
}

The CustomEvent object takes two arguments:

  1. The ‘glide:ui_notification.‘ object. This object includes a mandatory property that defines its name. In our example we’ve used a variable to store the name, but it could also be added to the object as an explicit value. In that case, it would be written ‘glide:ui_notification.demo_notification’ (including the quotes).
  2. A function that defines the notification’s contents and display options. The display options determine how the notification will behave. The options should be defined as properties in their own options object within the function. Available options properties include:
    text: Required. The text of the message. You can include rich text formatting via standard HTML tags.
    sticky: Optional. If true, the notification persists until the user closes it by clicking the [x] icon. If false or omitted, the notification automatically closes after the specified closeDelay.
    closeDelay: Optional. Automatically closes the message after this number of milliseconds. If omitted, the message closes after about three seconds. If the sticky property is true, this option is ignored.
    fadeIn: Optional: Sets the fade-in time for the notification in milliseconds
    fadeOut: Optional: Sets the fade-out time for the notification in milliseconds if the sticky property is false/omitted. If the sticky property is true, this option is ignored.
Note that if fadeIn, fadeOut and closeDelay intervals are specified, they are additive. That is, the notification will be displayed for the total amount of time specified in all three properties.

The function uses the getAttribute() method to retrieve the information passed in from the server-side script which triggers the notification. If multiple attributes have been set in the server-side script, the UI Script will need additional getAttribute() method calls to retrieve each one.

Displaying the Notification

To display the notification, we simply instantiate, (create a new instance of) the UINotification object in a Business Rule (it may work in other server-side scripts but I haven’t tested that). For our example we’ll use a business rule that runs after the incident has been updated. Our script borrows code from a previous post about checking for modified fields on forms or records.

‘Changed Fields UI Notification’ Business Rule
Name: Changed Fields UI Notification
Table: Incident [incident]
Active: true
When: after
Update: true
Script:

//First, get an ArrayList of all fields changed on the record
if (typeof GlideScriptRecordUtil != 'undefined') {
   var gru = GlideScriptRecordUtil.get(current);
} else {
   var gru = Packages.com.glide.script.GlideRecordUtil.get(current);
}

var changedFields = gru.getChangedFields(); //Get changed fields with friendly names

//Next, pass the values into the UI Notification we defined in the UI Script
var notification;
if(typeof UINotification != 'undefined') {
   notification = new UINotification('demo_notification'); //Calgary and later releases use the UINotification object call
} else {
   notification = new Packages.com.glide.ui.UINotification('demo_notification'); //For pre-Calgary releases, use the Java Package call
}

//create the message to be displayed
var messageText = gs.getUser().getDisplayName();
messageText += ' modified the following fields on : ';
messageText += current.number;

/*
Assign the message text to the 'text1' attribute. Additional attributes can be passed into the UI notification. Just be sure each one is accounted for in the UI Script via getAttribute() method calls.
*/
notification.setAttribute('text1', messageText + changedFields);
notification.send();

The key items in the business rule’s script are:

  • The new UINotification object call that specifies the object we defined in the UI Script (‘demo_notification’)
  • The setAttribute() method that passes specific information into the notification
  • The send() method that triggers the actual display of the notification.

To see the notification, open any Incident and modify one or more fields, then Save or Update it.

Incident field changes

Once the UI Script is defined, it can be reused as many times as needed. Just call it from any business rule and pass information to it using the setAttribute() method.