How to Return Multiple Values from a GlideAjax (with JSON)
With Sheikh Kamarah
In this article, you will learn about GlideAjax. GlideAjax allows you to execute server-side code while calling it from the client-side. In the example you're going to see today, what’s particularly useful is when you need to pre-populate or auto populate fields based on data you enter in a form. There are times you will need to return more than one value from a GlideAjax, and ServiceNow has documentation here on just how to do that. They talk about using XML nodes and attributes to create a data structure that you can return to the client side and deconstruct and use to populate multiple values. XML is not the most friendly to work with, so today we want to show you a more friendly way to go about this when using JSON instead of XML.
What is JSON?
JSON is a JavaScript object notation; it's essentially a string of key value pairs that you can really put together simply in code. Now we're going to jump into ServiceNow. Here we have a standard catalog item. In this common use case, there is an onboarding form and the manager is entering employee data. Somewhere down the line, work email and the full name need to be generated based on the data that was entered. Specifically, the work email needed to be unique, so we needed to check on the serverside to make sure that what we created didn't exist, and if so, we needed to add more parameters to make sure that it was unique.
For instance, if you populate the Legal first name field with “Fred” and populate the Legal last name field with “Luddy”, you’ll see that you get back the User full name based on the first name and last name populated along with an email address. You'll see the User email field populated “Fred.Luddy1@example.com” because “Fred.Luddy@example.com” already existed in the instance, so that was some server-side processing that was done to make sure that the email was unique. You'll see that we have both the User full name and User email fields being populated at the same time — this is because we are using a GlideAjax call that is returning multiple values, but we're doing it with JSON.
Let's dig a little deeper into this and take a look at the code, starting with the client-side. This runs whenever one of those field changes. Whether it be legal first name, last name, preferred first or last or middle name, this piece of code is going to make that Ajax call. You'll see here we are setting up the Ajax and feeding it parameters from this form, and when you get it back, you'll get the XML response.
Extracting Data
We'll talk a little bit about what we’re doing here to parse that out and extract the data. Notice we see just a few lines of code here, unlike the previous Ajax response shown. Here we have a pretty simple client script. Now let’s take a look at the script include, the GlideAjax itself.
Here we have a client callable script include. This is essentially the GlideAjax; this is what gets called from the client-side to execute the server code. You see we have a function called create email. The first thing we're going to do is to get all our variables. We're going to get our parameters from the form — the legal first and last, preferred first and last, and middle initial. Then we're going to set up some of our variables that we'll use to send back, mainly the email and full name. We can send as many values back as we want to, but to keep it simple, we're just sending back two.
Shown here is the JSON object that's getting initialized here. Notice the curly brackets; unlike an array with the straight braces, you get curly brackets here to initialize a JSON object. We are going to step through the code at a high-level. The first thing you’re going to do (note: these are the parameters similar to the real-world use case) is to check if there's a preferred first name. If that is the case, then that's what we're going to use as the first name in the email and for the full name. If that preferred first name does not exist, we're going to use that legal first name, which must exist.We will do a similar thing for preferred last name. So basically, if you have a preferred first and last name that's what we'll use; if not then we're going to use either a combination of what is there or the legal information. At this point, we've constructed a full name and a full email, so now we do the checking; we're going to check if this email is unique.
Earlier “Fred Luddy” was entered into the system and that was not unique. Basically there is a simple script here to check the unique email based on the sys_user record that will return as true or false. If it's true, that means that another email was found, so we have to make some modifications. We will need to do a little bit of splicing here to insert a number or the middle name, if it exists, based on what you’re finding and getting back from the unique email check. The end goal is to eventually find a unique email, even if you must continue to add numbers to find it. Once we have our data — and again, you can reach out to as many tables as you need and harness as much data as you need — this is when we build our JSON object.
Building a JSON Object and Accessing the Values
To do this, you take your JSON object, you give it a name to the key, and you assign it your value. Now you have a simple JSON object with two keys of email and name; you'll access the values through these keys. Then you assign the data values that you've processed above — the unique email and the full name that you generated.
Now you have your JSON object. Shown on the screen is the key line, beginning with “return new”. The JSON object highlighted is a ServiceNow JSON object; this is not the JavaScript JSON object that is used with ES5. This is an older deprecated version of the JSON object. You can use the more modern version, shown in the example, to return the object. The unfortunate thing here with script includes is that, for some reason, it does not recognize a more modern line of code. What you had to do is go back and use this older version (the ServiceNow provided API of JSON and used the encode function) to basically take your JSON object and turn it into a string that can be returned through Ajax to the client-side. You have to do a little bit of manipulation here in this line (refer to the video at 8:08). You must use global within a scoped application, and you must use new to establish a new instance of this JSON API. One day hopefully the JSON stringify line will work; it essentially does the same thing as turning an object to a string, so on the other side we can parse it out and use these keys.
Parsing Out
So let’s get into parsing out. Going back to our client-script, once we send our data off and we get the response, you'll see that you’re collecting it in this answer variable. Then you’re using the JSON.parse function, which is the JavaScript provided JSON API, the ES5 API. This works just fine on the client-side and most other places in ServiceNow. There are some issues using it with the script include, so we had to use the older version of the JSON API provided by ServiceNow.
Here we are using the modern version, the JavaScript provided version, to parse your answer. For the string version that was sent over, we are parsing it back into a JSON object, so we can easily do a dot walk to the keys mentioned (email and name). You can just set the values on your form, and as you see in the demo, it works. If you change the Preferred first name or Preferred last name field, that will update your User full name and User email with those values. And that concludes our demo on returning multiple values from a GlideAjax call using JSON. This is much simpler than XML, super powerful, and will make your life a lot easier!
Did you find this How to Return Multiple Values from a GlideAjax (with JSON) in ServiceNow article helpful? Are you ready to start your journey with ServiceNow? If you want to find out more information about GlideFast Consulting and our ServiceNow implementation services, you can reach out to us here.
About GlideFast Consulting
GlideFast is a ServiceNow Elite Partner and professional services firm that provides tailored solutions and professional services for ServiceNow implementations, integrations, managed support services, application development, and training. Reach out to our team here.