How to display notifications using a script in UI Builder (example with explanation)

HonzaProkes
Tera Contributor

While working with UI Builder, sometimes you might need to show a message to a user. You can do it by simply using Add alert notifications handler. But sometimes it may be more convenient to add the notification through a script, though.  Sadly, the documentation on this is rather scattered. You can find a few examples of how to do this but there is not much explanation on how the whole thing works. This post seeks to fill this gap.

 

First, let´s see an example of a script displaying a notification:

 

*******************************************************************

api.emit("NOW_UXF_PAGE#ADD_NOTIFICATIONS", {

    items: [

        {

            id: "greeting_1",

            status: "moderate",

            icon: "info-circle-outline",

            content: "Hello, world!",

            action: {

                "type": "open",

                "label": "Explore",

                "href": "https://example.com"

            }

        }

    ]

});

*******************************************************************

 

So, what are we doing in this script? We call api.emit() function that takes two arguments:

  • the name of the event that we want to emit
    • in our case: NOW_UXF_PAGE#ADD_NOTIFICATIONS => this is the system name of the event for showing a message to the user
  • the object with attributes that will modify the properties of the event
    • in our case, we only have one such attribute: items => this is an array of objects representing the messages we want to show

 

Every such item-object has its own attributes that influence the content and form of the message. The main attributes are: id, status, icon, content, action. There are actually more of them but these are the most common ones.

 

Let´s take a closer look at each of these attributes:

  • id
    • a string that serves as unique identifier of the message
    • you can use any string you want (be it "alert1" or "mambo_jambo_93", it´s really up to you)
    • just remember: if a message is already being displayed on the page and you add a new message with the same id, then the old message will be overwritten by the new one
  • status
    • based on the value, the message will have a certain color
    • for example, if you choose "status": "moderate" => the message will be somewhat purplish
    • you can choose from these values:
      • critical (red)
      • high (orange)
      • moderate (purple)
      • warning (yellow)
      • info (blue; this one is the default value)
      • positive (green)
      • low (grey)
  • icon
    • determines what icon will be displayed at the left side of the message
    • the usual choice is "info-circle-outline" but you can choose based on your own preferences; the complete list of the icons and their names is to be found right here
  • content
    • string that will be shown to the user as the message
  • action
    • another object with a few attributes
    • in general, these control how the message should be closed and whether clicking the closing button will take the user to a link

 

Attributes of the action object:

  • type
    • determines the appearance of the closing button
    • you can choose from these values:
      • "dismiss"
        • the closing button will be a classical one ("X")
      • "acknowledge"
        • the closing button will read: "OK"
      • "open"
        • the closing button will read: "OPEN"
        • optionally, you can specify your own label (see bellow)
  • label
    • can be used only in combination with "open" type
    • if you specify a value, then the closing button will take the value as its label
  • href
    • can be used only in combination with "open" or "acknowledge" type
    • the value should be a URL; if you specify it, then clicking on the closing button will redirect the user to the link

 

 

Here is how the message would look like based on our example´s configuration:

 

HonzaProkes_0-1688198190258.png

 

5 REPLIES 5

 

Thanks Krishnak, unfortunately, the instance name is added at the beginning of the URL.

So if: links = '<a href="' + "www.google.com" + '">LINK TEXT HERE</a>';

The actual URL link is instance name + /www.google.com, in my PDI: "https://dev322772.service-now.com/www.google.com".

Could it be that there is a parameter to add, like "navigateExternal"?

Will continue to check.

The alternative would be to use a "LINK_TO_DESTINATION_RELAY" (where the above parameter exists), but I cannot find a decent example on how to use this.