Originally from earlduque/ServiceNow-Developer-Training. Thanks Earl!

ServiceNow GlideAjax #

This tutorial will teach the fundamentals of GlideAjax and how to use it inside of ServiceNow. The purpose of GlideAjax is to allow for the scripts on the client-side to send and receive information to and from the server. An example of its uses is when we need to make a GlideRecord call in a client script.

*Note: GlideAjax requires prior knowledge of JavaScript*

Overview and Brief Explanation #

  • It has both client side and server side components. The GlideAjax class enables a client script to call server side code in a script includes.
  • The GlideAjax API itself is a client side API, but is used to call server side in a script-includes
  • It has both client side and server side components and is similar to jQuery's AJAX method.
  • AJAX stands for "Asynchronous Javascript And XML"
  • Used to make client side requests to the server-side without requiring a "page reload", ServiceNow utilizes a browser API called XMLHttpRequest to make AJAX calls (GlideAjax calls this API to make requests, but uses a layer of abstraction)

Stages of GlideAjax #

  1. Client side code calls the GlideAjax API, which is making an XMLHttpRequest behind the scenes to the server
  2. Server side processes the request and returns a response
  3. The client side processes the response (we have to tell the browser what to do with the information in the response from the server)

Scripting Locations #

There are two scripting locations to GlideAjax: Server side and client side.

While GlideAjax API is a client side API, we are still accessing server side code. Client script which contains GlideAjax API and methods. often times stored in client scripts or UI pages.

Server side code is stored in a script include

GlideAjax Process #

Here is an example of the GlideAjax process:

When we're on a task record like an incident, after the form loads, we want to make an AJAX request to the server side, which will update the location of the current user, leveraging the browser's geolocation API.
Once the page loads, the browser pulls in the current user's location, makes a request in the background via GlideAjax, to the server side to save that to the record

  1. Client makes a request for a page that contains a client script with GlideAjax.
  2. Server processes the request from the client, it sends client task form along with client script.
  3. After the onLoad event occurs, the client side script is executed which calls the GlideAjax API.
  4. GlideAjax accesses browser's XMLHttpRequest API and generates a request.
  5. Browser's XMLHttpRequest API sends data back to ServiceNow in the background.
  6. A request from the client invokes a Script include, where request data is used to call certain methods with arguments. The data is packaged up in the form of a response.
  7. Browser receives response from the server side
  8. Client Script callback processes returned data and updates location field on task

GlideAjax Example #

In order to help remember the differences between the Client and Server elements of a GlideAjax call, here is a simple example:

*Tip: Client callable must be checked in the 'script include' in order for this to work*

Note: Github Markup does not support colored/highlighted test, so we will use blocks of color to differentiate between the different pieces.

Red: The name of the class you create, which is generally the same name of the Script Include.

Orange: The name of the function used in a script include. A single script is able to include multiple functions that accept and return different parameters. For example, one could create a single script include for retrieving data related to users and continue adding functions to it (as needed).

Yellow: The parameter that is passed through the URL of the AJAX call, to which you may add more than one parameter. Generally this is information used to create a GlideRecord call in the script include.

Green: The function that asynchronously awaits a response. Any code that needs to wait for a response needs to go in the function that is called inside the getXML() function. Code that does not need to wait should go directly after the getXML() call within the main client script function and will not await a response before executing.

Blue: This is the data you will need from the server. The pieces of data are added to an object in the script include and then passed back to the client script. Once these are returned, you can choose what to do with them. In this particular example they are being used to set a value on a form.

Code Reference Chart:

Type Properties
ucd_GetLocationData
getCampus
sysparm_buildingid
updateCampus
updateCampus

Client Script: #

function onChange(control, oldValue, newValue, isLoading) {
if (isLoading || newValue == "") {
return;
}

var ga = new GlideAjax("ucd_GetLocationData");
ga.addParam("sysparm_name", "getCampus");
ga.addParam("sysparm_buildingid", g_form.getValue("u_building"));
ga.getXML(updateCampus);
}

function updateCampus(response) {
var answer = response.responseXML.documentElement.getAttribute("answer");
var clearvalue; // Stays Undefined

if (answer) {
var returneddata = JSON.stringify(answer);
g_form.setValue("campus", returneddata.sys_id, returneddata.name);
} else {
g_form.setValue("campus", clearvalue);
}
}

Server Script (Script Include): #

var ucd_GetLocationData = Class.create();

ucd_GetLocationData.prototype = Object.extendsObject(AbstractAjaxProcessor, {
getCampus: function() {
var buildingid = this.getParameter("sysparm_buildingid");
var loc = new GlideRecord("cmn_location");
if (loc.get(buildingid)) {
var campus = new GlideRecord("cmn_location");
if (campus.get(loc.parent)) {
var json = new JSON();
var results = {
sys_id: campus.getValue("sys_id"),
name: campus.getValue("name")
};

return json.parse(results);
}
} else {
return null;
}
}
});

Tutorial #

We want to: update the short description of an incident to Hello World! when the incident form loads.

Log into your personal developer instance.

  1. Go to the navigator and head to System Definition > Script Includes.

    screen shot 2019-02-21 at 3 33 41 pm
  2. Click New.
  3. Name the new Script Include "ServiceNowGlideAjaxTutorial". We will need to remember the exact name later.

screen shot 2019-02-21 at 3 52 58 pm

  1. Select "Client Callable"

  2. The Script field auto populates after naming the Script Include. We are then going to create a method called "sayHello" and return a "Hello World!" string. Update the code so that it looks like this:

    screen shot 2019-02-21 at 3 54 02 pm

  3. Click Submit.

  4. Be sure to copy the name of your Script Include (i.g. ServiceNowGlideAjaxTutorial)

  5. In the navigator head to Client Scripts.

    screen shot 2019-02-21 at 4 00 18 pm

  6. Create a new Client Script called "OnLoadHello"

  7. We are going to create a new GlideAjax object within our onLoad() function with the same name as our Script Include.

  8. We'll add the name of the method we want to call and pass in the keyword sysparm_name and then the name of the method we created in our Script Include, sayHello.

  9. Then we want to use getXML() and pass in the name of our callback function.

  10. then we create the callback function and pass in response as an argument

  11. We then need to create a variable called answer and assign it to the attribute we want from response.

  12. Then we need to update our incident description field with the "Hello world!" text by using g_form.setValue(). Your code should now look like this:

    screen shot 2019-02-21 at 4 06 49 pm

  13. Hit Submit.

  14. Navigate to Incidents and click on any incident. You should see that the short description to the incident has been changed to "Hello World!".

    screen shot 2019-02-21 at 4 52 31 pm

    screen shot 2019-02-21 at 4 52 41 pm

Conclusion #

This tutorial has covered the fundamentals of GlideAjax and how to go about using it. The example provided is rather basic, but covers the basis of its functionality. GlideAjax is a powerful tool and is often times one of the few ways to accomplish a task.

Congrats! You've just completed your first GlideAjax tutorial.