ServiceNow’s Service Portal allows businesses to interact with their users/customers with a catalog of various items, giving users easy access to services that help them conduct their business activities.
Recently, JDS was engaged to assist a customer with a Human Resources (HR) onboarding form that integrated with SAP. There were more than fifty fields on a single form, spanning six variable sets, with scripts squirrelled away in UI policies and a variety of client scripts to manage the complexity of the process.
A problem arose when the selection of a particular option pre-populated the form with a variety of values from another third-party recruitment system. If the user changed their mind and chose another option, fields were hidden that still retained values. This caused erroneous values to be posted to the backend.
As the form was large, scrolling well off the screen, it was difficult to troubleshoot problems, but JDS realised that the ability to reset the form to its default values whenever key choices changed or UI policies were switched would drastically simplify the form. Unfortunately, the g_form.clearValues() didn’t work quite as expected.
Behind the scenes, there are a number of special functions that allow these catalog items to respond to a user’s input. In this article, we’re going to examine the behaviour of the g_form.clearValue(), which is used to clear values when switching between options.
Depending on the requirements of a particular service catalog item, there can be a need to clear the values on a form and start again (such as when switching between users with different privileges, etc.), but this is where the g_form.clearValue() can be a little tricky.
Consider this: the code below seems simple enough—clear each value, but look at what happens when we try that…
The first two fields respond as you’d expect, clearing values from a reference field and a plain text field, but look at the colour option: it switches from pink to black, while the option of having 4G switches from no to yes.
The problem lies in how ServiceNow handles fields. A selection control, like the one used for cover colours, switches to ‘none,’ but as this particular list of choices doesn’t have ‘none’ as an option, ServiceNow takes the FIRST option, which in this case is black.
We could simply make sure all our selection controls have ‘none’ as an option, but in a large catalog with complex forms, there’s a good chance we’ll miss some of them. Besides, what we really need is a way to reset to our default values. Having ‘none’ as an option won’t solve that issue.
When it comes to Boolean fields, like our 4G field above, the clear values function switches options, reversing them!
On complex forms with lots of combinations, especially those that don’t fit on a single page, this can cause unpredictable behaviour that confuses users. The solution JDS developed is to introduce the ability to reset to default.
Rather than trying to guess which selection a user should have when there’s no option for ‘none,’ or simply flipping Boolean values, JDS recommends resetting the form to the values it had when it originally loaded. There’s no way to do this out-of-the-box, so we’re going to have to get a little creative. The actual code is quite small, but it has to be placed in a strategic location.
Step One: Build a Catalog Client Script Library
Behind the scenes, ServiceNow retains a large amount of information about the widgets on each portal page, including the value of various fields, so we’re going to tap into this to reset our form to the default values. To do this, we need to add a UI script that runs in the background whenever our catalog loads. We’ll use this as a way of adding a library of common functions that are accessible from any catalog item.
Note: this UI script is available as a download at the bottom of this page.
By default, ServiceNow does not allow access to components like the document object or the angular object from a catalog client script, so we’re going to sidestep this limitation by accessing these through our UI Script.
There’s a good reason ServiceNow doesn’t allow access to these components by default. The reason is that people tend to abuse these libraries and do all kinds of ridiculous things, like inserting values directly into forms instead of using the g_form libraries built into ServiceNow.
As the adage goes, “With great power comes great responsibility.” It’s fine to use components like the angular and the DOM, but they need to be used wisely. Don’t abuse them.
As you’ll see, we’ll use the angular object to get our values but NOT to set our values, as that’s where the danger lies. Instead, we’ll use the tried and tested g_form library to reset the defaults on our catalog item.
Our code is concise—only seven lines. The actions we’re undertaking are:
- Retrieve the field object from the widget’s angular scope
- Loop through that object to pick up each of the initial form values
- Store them in a session object so we can retrieve them later
If you haven’t used session storage before, it provides a convenient way of passing information between components/pages. HTML is inherently state-less, so session storage allows you to overcome this limitation and share information freely. Normally, session storage is used while switching between pages, but in this case, we’re using it as a global variable shared by client scripts on the same page.
When it comes to resetting the form, it’s simply a case of looping through our session storage variable.
Notice how we pass the g_form through to our script along with ignore, a comma-separated list of any fields we don’t want reset.
Step Two: Allow the catalog widget to access this library
You’ll find these within ServiceNow under SC Catalog Item in Widgets in the Portal.
Add a new Dependency called Catalog Client Script Library at the bottom of this widget record.
This new Dependency needs a JS Includes.
Which then refers to our UI Script.
All of these entries are simply a means of pointing to the UI Script we developed previously.
Step Three: Setting and Get Defaults
Our UI Script will automatically get the defaults for each catalog item when it loads, so there’s no need for an onLoad script. All we need to do is identify when and where we want to reset our form to its default values.
Once we’ve identified the trigger for resetting the form to its default state, we can add a Catalog Client Script to that onChange event.
By passing the g_form object through to our UI Script, we can use the default ServiceNow means of manipulating form elements rather than doing something risky that might backfire with an upgrade.
Also, notice we’ve passed a few fields we want to leave untouched.
In this way, we can develop a complex form catering for multiple scenarios, showing and hiding fields and resetting them at will.
ServiceNow’s g_form API provides a host of useful functions for managing catalog items, but its clear values function is a little overzealous. In light of that, we’ve developed a means of restoring the initial default values instead of blindly clearing values.
Going forward, you can add more and more common functions to this catalog script library and access them from your various catalog items.