Next Experience - Alert notifications

[AttilaVarga]

UI Builder in ServiceNow gives developers many tools to create modern and user-friendly pages. One important and frequently used component is the Alert, which helps inform users about what happens in the system.

This post is not meant to introduce the component itself, because there are several resources available, that show how the notifications can be handled on a page, like THIS and THIS. 

I would rather focus on and explain the possibilities of how a notification message can be shown and hidden on a page. Let's look at the details.

Display an alert message, that can be hidden

Let's have a quick look at how a notification can be displayed on a page. There are two main methods:

 

No-code

1. Select an event and attach the Add alert notification handler to it.
   
2. Configure the Alert component
   
   

  Low-code

1. Create a client script, which emits a specific event to display the notification
   

   /**
   *  {params} params
   *  {api} params.api
   *  {any} params.event
   *  {any} params.imports
   *  {ApiHelpers} params.helpers
   */
   function handler({api, event, helpers, imports}) {
   
       api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
           items: [{
               id: 'abc123',
               status: 'info',
               icon: 'check-circle-outline',
               header: 'Heads up',
               content: 'This needs your attention'
           }]
       });
   
   }​

2. Attach the script to an event
   

Both solutions have the same result: the message appears on the top of the screen.

There are several configuration possibilities regarding the look&feel and behaviour, described on the previously mentioned pages. Now I would like to focus on how the notification can be hidden.

Hide the alert notification

The first and simplest one is that the component has a configuration option to enable the dismiss button.

The event handler configuration contains a section, called Action. The type: dismiss option has to be added to this part, clicking the Edit button:

As a result, the dismiss (X) button appears on the right side of the notification component.

There are some cases when the notification has to be hidden automatically or programmatically. I am going to show some possibilities in the next part of the document. Let's take a look at them.

1. The generic one (no-code)

The simplest method is to use the OOTB event handler, called Remove alert notification.

The event handler can be attached to any event. The component ID is important in this case, which has to be provided as an action parameter. This ID was defined in the Add alert notification event handler.

Once an event is triggered where this handler is attached to, the notification panel disappears.

2. The generic, but scripted one (low-code)

Once someone clicks the dismiss button on the right side of alert layout, a specific event is executed, called 

NOW_UXF_PAGE#REMOVE_NOTIFICATIONS.

When this event is fired with the alert ID as an action parameter, the notification pane disappears if it is visible on the page.

The script below represents a usage sample code.

/**
*  {params} params
*  {api} params.api
*  {any} params.event
*  {any} params.imports
*  {ApiHelpers} params.helpers
*/
function handler({api, event, helpers, imports}) { 
    api.emit('NOW_UXF_PAGE#REMOVE_NOTIFICATIONS', {
        items: [
            {id: 'abc123'}
        ]
    });
}

3. The new one (no-code)

There is a new cool feature in the Zurich release, which can be used to enable an auto-hide behavior for the alert component. It can be set up on the main configuration page of experience:

The auto-dismiss feature can be defined on action status level (Low, Positive, Info, etc.). When the checkbox is checked an additional configuration option appears where the time (in second) can be set for the component to hide automatically:

This configuration is an experience level setting, which means that regardless of which page you add this status notification to, it will be disappear after the specified time.

There may be cases when we need more flexibility, so we need to set up different durations on different pages. The solution is described in the next chapter.

4. The new, but scripted one (low-code)

So, how can we add the auto-hide behavior to an alert component using JavaScript?

/**
*  {params} params
*  {api} params.api
*  {any} params.event
*  {any} params.imports
*  {ApiHelpers} params.helpers
*/
function handler({api, event, helpers, imports}) {

    api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        items: [{
            id: 'alert_unique_id',
            status: 'info',
            icon: 'check-circle-outline',
            header: 'Heads up',
            content: 'This needs your attention',
            autoDismissConfig: {
                enableAutoDismiss: true,
                duration: 4000,
                showTimer: true
            }
        }]
    });

}

As can be seen above in the code snippet, there is an additional configuration object, called autoDismissConfig, which has to be added to the script. Three main options can be set up:

1. Enable or disable the feature (enableAutoDismiss)
2. Set the duration for how long the message is visible in seconds (duration)
3. Show or hide the countdown timer (showTimer)

Closure

Based on my experience, the notifications are used quite frequently on pages. There are now several possibilities to show or hide a notification, based on user activities, automated event triggers, or even using a countdown.

I hope this summary will help make your work easier, at least in the area of handling alert components in the world of UI Builder.