gs.getMessage() - The Second Parameter

[Chuck Tomasi]

I was working on something today and discovered something interesting. You know me, if I find something cool, I want to share it. I was going through some of the standard script includes that come with each instance when I noticed a gs.getMessage() statement with some intriguing characters and a second parameter. When I figured out what it did, I thought "Oh, how I wish I had this a year ago! It would have been so much cleaner than what I did." Hopefully this article will save you the same frustration.

Let's back up a bit and explain what gs.getMessage() is and why it is useful. gs.getMessage() is part of the GlideSystem, or gs for short. GlideSystem provides a number of useful methods (or functions) to get information about the system including the currently logged in user, dates and times, and output messages. It is the last part that we are interested in regarding gs.getMessage().

gs.getMessage() retrieves messages from the Messages (sys_ui_message) table based on the current user's language settings. In short, you can write language independent scripts provided the right messages are in the table. Consider the following script:

gs.addInfoMessage('Hello');

No matter what, this will always print "Hello". Now, let's go to System UI> Messages and enter the following record:

Let's modify that script slightly to use the message we just created.

var msg = gs.getMessage('Hello');
gs.addInfoMessage(msg);

The system retrieves the entry from the Messages table with the key 'Hello' and saves the 'Message' field value in our variable 'msg'. On the surface it appears to do the same thing, so why go through the extra trouble of creating a message and the extra line of code? (which could be consolidated to one, but let's not get carried away.)

There are two reasons for using gs.getMessage(). The first is for automatic translations of your output messages. When your boss says "We've just acquired a company in France and we want you to have a French version of ServiceNow" it is a simple matter to export a few tables, have them translated, re-import them and your work is done. No changes to the code!

The second reason is for centralized administration. This makes it easy to change the current messages without modifying code. Your boss says "We need to change all the places it says 'New' and make it say 'Create New'." You only need to update the entries in the Messages table and you're done. No searching, no replacing, nothing.

Now that you're familiar with the use and benefits of gs.getMessage(), what do you do when you run in to a situation where you need to translate a message with dynamic content such as the following?

Message sent to Chuck Tomasi regarding INC0010056

The "Chuck Tomasi" and incident number are going to change every time, but the "Message sent to" and "regarding" parts will be the same.

You COULD do what I did at first and break it in to two messages. For example:

key = 'im_notification_msg_1'
message = 'Message sent to'

key = 'im_notification_msg_2'
msg = 'regarding'

and string it together with code like this:

var msg = gs.getMessage('im_notification_msg_1') + ' ' +
                  current.caller_id.getDisplayValue() + ' ' +
                  gs.getMessage('im_notification_msg_2') + ' ' +
                  current.number;
gs.addInfoMessage(msg);

While that works, it makes two calls to gs.getMessage() - I hate duplicate/repetitive code. The main problem with this solution is that the syntax between languages isn't exactly these same as English and you could end up writing very bad grammar in Japanese, Russian, or another language. Of course, there's a better way. Otherwise, why would I be writing this?

If you've ever read the GlideSystem wiki page and noticed the syntax for the getMessage() method, there's a second parameter "object", but not much information on what it is or how to use it (at least not when I'm writing this.) What goes there? What is it and how is it used? Simple, we'll use an array for the above example. First, define your message this way:

key = 'im_notification_msg'
message = 'Message sent to {0} regarding {1}';

I'll explain the {0} and {1} in a bit. We'll make use of that special message with one call to gs.getMessage() using that second parameter like this:

var msgArray = [];

// Put the dynamic parts of the message in an array
msgArray.push(current.caller_id.getDisplayValue());
msgArray.push(current.number);

var msg = gs.getMessage('im_notification_msg', msgArray);

gs.addInfoMessage(msg);

The variable msgArray has two elements. Element '0' (the first one) is going to be the caller's name. Element '1' (the second one) is going to be the incident number. gs.getMessage() is smart enough to recognize the {0} and {1} in the message string and substitute the right elements of the array in to the message string to return the proper result.

Now you just need to translate one message and if the user name and/or incident number go in different places in the message, your translation will take care of that too!

Very flexible and easy to use.