Having introduced the basic elements of client-side scripting and how and where to use it, we can take a look at some examples of scripts to further our understanding.

We'll start by looking at some client script examples.

In this first example, we'll use an onLoad client script to show and hide form sections based on the logged-in users' roles. We'll only show the related records form section on the incident form if the logged-in user has the itil_admin role:

function onLoad() {
    if (g_user.hasRole('itil_admin')) {
        g_form.setSectionDisplay('related_records', false);
    }
}

As you can see in the example, we are using g_user's hasRole method to determine whether the logged-in user has the required role. If they don't, then we use the g_form setSectionDisplay method to hide the form section. Putting this client script as an onLoad type allows us to ensure that this form section is immediately hidden from the user.

I have often used this type of script before to hide sensitive data that appears on a form section. This can range from financial details to personal information held by HR.

We can see how this script would look in Figure 3.6:

Now let's have a look at an onChange client script example. Sometimes, we may want to increase the speed at which incidents for certain categories are looked into. Let's suppose that for this example, we want to set the urgency to high for all network incidents, medium for database ones, and low for all other users.

We need to make sure we set the Field name field value to Category for our onChange script. Let's look at the code we need:

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

    switch(newValue) {
        case 'network':
            g_form.setValue('urgency', 1);
            break;
        case 'database':
            g_form.setValue('urgency', 2);
            break;
        default:
            g_form.setValue('urgency', 3);
    }

}

In this example, we have used a switch case statement to perform different actions, based on the new value of the field. This JavaScript technique is more efficient than using multiple if statements. We have also used the newValue parameter that ServiceNow gives us to quickly decide on which value we should set the urgency to. 

When setting the value of the urgency in this example, the user is still able to amend the urgency field if they feel the urgency is not fitting for this particular incident. It is possible to lock down fields though which have been populated by scripts by making them read-only or setting security rules.

Let's take a look at how this client script looks in Figure 3.7:

Next, we'll have a look at an example using an onSubmit type client script. These are less used than some of the other types of client script, but it is good to see how to create one if necessary.

In this example, we'll look at making sure a user has filled in the description if they have the itil role. Sometimes you may want to ensure that users with more technical experience fill in further information on a form:

function onSubmit() {
    if (g_user.hasRole('itil') && g_form.getValue('description') == '') {
        g_form.addErrorMessage('Enter a description to save.');
        return false;
    }

}

In the preceding example, we use the g_form.addErrorMessage method to show a message at the top of the form if a user with the itil role tries to save the form with no description. This message will let the user know why they are not able to save the form. The code that stops the record from being saved is returning false from the onSubmit function. If at any point in the onSubmit script the function returns false, then the record will not be saved.

Being able to stop a form from being saved is an important aspect of the onSubmit type of client script, and arguably, its main use.

The example we have scripted can be seen in Figure 3.8:

Now let's see an example using the onCellEdit type of client script. Often, these types of script are used to validate the input that a user enters into a cell on the list view.

For this example, we will ensure that a user does not enter a high impact into a cell to force them to open up the form view to do this:

function onCellEdit(sysIDs, table, oldValues, newValue, callback) {
  var saveAndClose = true;
  if (newValue == 1) {
    alert('High Impact cannot be set on a list view.');
    saveAndClose = false;
  }
  
  callback(saveAndClose);
}

This example uses the newValue parameter to check the value the impact has been set to. If it has high or 1 as the value of the field, which we need to use in scripts rather than labels, then the user is alerted through a message. By setting the saveAndClose variable to false, we can also stop the field from being updated. This is because the callback is using this variable, and therefore also sets the callback to false.

Often, business rules can be used to fulfill a similar task to the onCellEdit scripts, but it is useful to see how they can be created.

We can also see how this script looks in ServiceNow in Figure 3.9:

These examples give us a good understanding of the different types of client script, and some uses for each. Now we'll take a look at UI policies.

As a UI policy is configured, we mainly only need to use script if we want to run scripts for the Execute if true and Execute if false fields we described earlier in the chapter.

For this example, we will change the short description when the UI policy condition matches and clear the value again if the condition does not match. Firstly, let's see the Execute if true script:

function onCondition() {
  g_form.setValue('short_description', 'Matched condition');
}

As the condition handles when we want the script to run, we simply need to perform the actions we want to take in the Execute if true script. This script will change the value in the short description field.

Now let's see the Execute if false script:

function onCondition() {
  g_form.setValue('short_description', '');
}

This second script will clear the Short description field if the condition does not match. In this example, the short description field would only ever contain no value or the Matched condition text. When writing scripts in UI policies, think carefully about all of the outcomes of your script. Writing scripts in these two separate scripts can be more difficult, which is why scripting is usually done in client scripts rather than UI policies.

We can see the UI policy containing the scripts we created in Figure 3.10: