ServiceNow Scripting 101: Client-Server Communication

[Jake Gillespie]

As a ServiceNow Administrator, you will often be asked to find ways of improving efficiency within the IT Service Desk. While there are many ways to do this, a simple example would be retrieving and displaying related information for the Service Desk Analyst before they go looking for it. This could be information from the caller's User record, Location record or even a Configuration Item. Today we'll focus on the various options available for handling communication between the client and server when requesting related information.

Most ServiceNow Administrators would likely have used the GlideForm (g_form) API to manipulate field data within a table form. But did you also know that this API offers the ability to retrieve database records as JavaScript objects? The getReference() method allows us to retrieve a table record in the form of a JavaScript object. Only records populated in Reference fields on the current table form can be retrieved using this method. For an Incident record, this would include User records on the Caller, Opened By or Assigned To fields, or even records from the Location or Configuration Item fields.

Let's take a simple example:

Retrieve the Configuration Item record and display the IP Address values in a field message.

The getReference() method can be used to retrieve the selected Configuration Item record as a JavaScript object, and then we can access the object's properties (e.g. field values) to display the IP Address to the user. Let's take a look at the code.

The above code is contained with an onChange Client Script running on the Incident table. The script has been modified such that it will run when the form loads, as well as when the Configuration Item value changes. Since we're using a field level message, another g_form method called showFieldMsg() is being called to show the IP Address value. Although the above script will not attempt the getReference() call if the Configuration Item field is empty, we still check that the returned record object ciRec exists (line 😎 before attempting to access its ip_address property. Failing to do this could result in an error when processing the client side JavaScript. We also check that the selected Configuration Item has an IP Address value, and only show the message if it does. Let's take a look at the result.

As you can see, the IP Address value was retrieved for the selected Configuration Item, and displayed in the blue field message. The getReference() method is a very quick and easy way to achieve such a result, but it does have its limitations. Firstly, it provides no functionality to select which fields we want to retrieve from the selected record, and as such will retrieve the entire record from the database. In the case of a table with many fields, this increases the amount of data being transferred and therefore increases the time required to retrieve and process the values. Secondly, the record object only contains values stored on the selected record. This means that any populated Reference fields on the selected record will only contain the sys_id values of those referenced records. This means that no Display Values are accessible via the object, and the ability to dot-walk to other fields is also not available. Lastly, another limitation exists when accessing a referenced record from an extended table. The getReference() method will only retrieve the record via the base table. That means that any fields defined on the extended table and not on the base table, will be unavailable on the returned JavaScript object. An example of this would be the Business Criticality field on the Business Service class of Configuration Item.

To overcome the getReference() limitations described above, another solution can be used called GlideAjax. Although this process is more complex to use, it presents significant benefits regarding data efficiency and speed, as well as the ability to do a lot more than just retrieve table record data. By using the GlideAjax class, a Client Script can be used call the server and trigger a server-side script to run. Examples of this include accessing any of the GlideSystem methods (gs.getProperty() or gs.getUser() etc.), or updating a database record directly by using the GlideRecord class.

So how does it work I hear you ask? Well, within a Client Script an object is instantiated from the GlideAjax class. This class is available on any ServiceNow table form, and even on UI Pages. Parameters are then defined and posted to the server for processing. Then, a Script Include on the server is invoked, and this script determines if and what values should be returned to the client. One of these parameters must be the name of a function defined in the extended GlideAjax class. Before we take a look at the code, let's define a new example:

Retrieve and display the name of the user who Manages the selected Configuration Item.

As we saw earlier, we'll need an onChange Client Script running on the Incident table, which is triggered when the Configuration Item value changes. But first, let's take a look at the Script Include and define what we want the server side script to actually do.

In my last post we discussed Class Vs Classless Script Includes. In this example we will define a class in a Script Include, however it is considered an extended class as it builds on the existing functionality provided by ServiceNow. In technical terms this is called Prototyping. The class definition is slightly different to the default stub provided after entering the script name, however the content where functions/methods and properties are defined is still the same. In the above code extract, you will see that we've defined a function stub called getManagedBy(). This will be the function we call from our Client Script. As this function can be called from any table form, we will need to pass the sys_id value of the Configuration Item record we want to retrieve data from. Then, after retrieving the sys_id value the function should run a GlideRecord query to obtain the Configuration Item record as an object. From here we can return the Display Value of the managed_by field. Let's look at the updated code below.

As you can see, we've added some code to use the sys_id value to retrieve the GlideRecord object, and then call a method called getDisplayValue() to retrieve the Display Value of the managed_by field. Since this field is a reference to the User table, the Display Value is the value from the name field (e.g. the user's full name). This value will be passed back to the client when requested. Now let's look at the Client Script.

Like the onChange Client Script we used earlier in the getReference() example, this script is triggered when the Configuration Item field is populated. If the value is cleared, it will clear any field level messages that may have been previously displayed. We've also defined 2 local functions (meaning they are only available within the scope of this onChange function). The first is called getConfigManagedBy() and is invoked directly by the onChange function. The second function is called getConfigManagedByCallBack() and it is called indirectly when a response is received from the server (this is known as a Callback). As you can see, in the first function we instantiate an object from the GlideAjax class, and in doing so we pass the name of the Script Include we defined - ConfigurationItemAjax. Then, we use a method called addParam() to add some name/value pairs. The first parameter name is sysparm_name, and its value refers to the name of the we want to call within our Script Include (e.g. getManagedBy()). The next parameter name is sysparm_ciSysId, and its value is the sys_id of the selected Configuration Item. Finally, we call a method called getXML() and pass to it the name of the Callback function. When this method is called, the parameters are sent to the server, and there our Script Include function will be invoked. Once processed, the server script will return a value to the client, and in doing so will invoke the nominated Callback function - getConfigManagedByCallBack(). This function receives the server's payload in the form of an object called response. Although it may look tricky, line 18 simply dot-walks along some object properties to get an attribute named answer. This value is then assigned to a local variable of the same name. Because we only want to show our message when the value is not empty, we first check if the returned value is empty. If the value is not empty, we call the g_form method showFieldMsg() and show a field level message with the name of the user who currently manages the selected Configuration Item. Let's take a look at the result.

As you can see, Roger Rasmussen manages the selected Configuration Item called Client Services. While this example of GlideAjax is fairly simple, I'm sure you have realised its potential for retrieving a great deal of useful information for the user. For further information on the topics covered in this article, please see the following pages on the ServiceNow Wiki:

• GlideAjax
• GlideForm
• Client Script Best Practices

NOTE: MY POSTINGS REFLECT MY OWN VIEWS AND DO NOT NECESSARILY REPRESENT THE VIEWS OF MY EMPLOYER.