The GlideAjax class allows a client-side script to make an AJAX (Asynchronous JavaScript And XML) call to the server, execute a server-side script include, and even return a value. GlideAjax might be one of the least well understood client-side APIs in ServiceNow, in part because it has both a client-side, and a server-side component.

First, let's discuss the server-side component. A GlideAjax call from a client-side script will ultimately execute a script include (which as we learned in a previous chapter, is a server-side script), so let's create a script include for our GlideAjax script to talk to.

For our example, we're going to create a simple script include that'll return the value of a system property we specify, so we'll create a script include called GetPropertyAjax. Once we enter this name and then tab out of the Name field, the default scaffolding of the script include is populated into the Script field.

To make this script include accessible from client-side scripts through GlideAjax though, we need to check the Client callable tick-box. This will alter the contents of the Script field, so that our script include extends the AbstractAjaxProcessor class. It also removes the initialize method, since we won't be initializing this class from the server.

Next, we'll define a method of our GlideAjax script include that'll do the work of retrieving the value of the system properties and returning it to the client.

var GetPropertyAjax = Class.create();  
GetPropertyAjax.prototype = Object.extendsObject(AbstractAjaxProcessor, {  
    getProp: function() {  
        var propName = this.getParameter('sysparm_prop_name');  
        return(gs.getProperty(propName));  
    },   
    type: 'GetPropertyAjax'  
}); 

In the getProp method in the previous code, you'll notice that we're calling this.getParameter(). This is a method specific to the AbstractAjaxProcessor class, which we're extending. That means that all methods of the AbstractAjaxProcessor class are now also member methods of the GetPropertyAjax class we've created; so when we access methods of the this object inside our class, we're able to access those methods as well. This method in particular, retrieves the value of the sysparm we'll be sending over when we call this GlideAjax script include from our client-side script.

Speaking of our client-side script, let's build that out. For starters, we need to instantiate an instance of the GlideAjax class on the client, passing the GlideAjax script include name into the client-side constructor; after which, we need to use the addParam() method to specify two parameters: sysparm_name, and sysparm_prop_name. Here's what that might look like:

var ga = new GlideAjax('GetPropertyAjax');  
ga.addParam('sysparm_name', 'getProp');  
ga.addParam('sysparm_prop_name', 'glide.servlet.uri'); 

The sysparm_name parameter is mandatory whenever we use GlideAjax from the client: it tells the GlideAjax script on the server which method we want to run. The sysparm_prop_name parameter however, we've custom-defined. It's just the name of a parameter that we agree to expect on the server-side script include, and provide from the client-side script; just like a function parameter variable name, except that we have to manually retrieve it using this.getParameter() on the server.

There's more, though; when a GlideAjax script returns a value, it doesn't return it like a normal function. You can't for example, just do something like the following:

//The following will not work!
var answer = new GlideAjax('MyGlideAjax').myMethod(); 

Instead, after specifying all of the necessary parameters, we call another method of the GlideAjax class in our client-side script: getXMLAnswer(). This method accepts one argument: a callback function, as you can see in the following code:

var ga = new GlideAjax('GetPropertyAjax'); //Pass in Script Include name  
ga.addParam('sysparm_name', 'getProp'); //Method name
ga.addParam('sysparm_prop_name', 'glide.servlet.uri'); //Name of the property to retrieve
ga.getXMLAnswer(ajaxCallback); 
 
function ajaxCallback(answer) {  
    console.log('The base instance URI property is ' + answer);  
} 

In the preceding example, we're passing in a reference to the ajaxCallback function to the getXMLAnswer() method. After completion, the ajaxCallback function is called. The callback function is called on the client with one argument: the value that was returned from the method specified in the sysparm_name parameter, cast to a string. If an object is returned, then the argument passed into the callback function will be a JSON-formatted string. You could then use JSON.parse() to parse the string back into a JSON object.

One more thing to be aware of, is that the getXMLWait() method runs asynchronously. What this means, is that you cannot be certain of the order of execution (that is, when it will run with respect to the rest of your code). Consider the following example:

As you can see in the previous screenshot, the last line of code executes before the console.log() line in the callback function at the top.