What are some of the available helper functions?

Available helper functions.

What are some of the available helper functions?

There is a global object that ServiceNow automatically creates called g_form that references the currently active form. You can use the g_form object in your scripts to simplify certain common programming tasks.

A second global object, called g_user, references the currently active user. Just like g_form, you can use g_user in your scripts to react based on the current user (and that user's roles).

Hide or show a field

While you can use client scripting to hide or show a field, you can usually accomplish the same thing without scripting via UI policies.
g_form.setVisible(<fieldname>, <value>);
function onChange(control, oldValue, newValue, isLoading) {
  var index = newValue.indexOf('Change');
  if(index == -1 ) { // hide it
    g_form.setVisible('field', false); }
  else { // unhide it
    g_form.setVisible('field', true); } }

Make a field mandatory

While you can use client scripting to make a field mandatory, you can usually accomplish the same thing without scripting via UI policies.
g_form.setMandatory(<fieldname>, <value>);
function onChange(control, oldValue, newValue, isLoading) {
  if(oldValue == newValue) return;
  g_form.setMandatory('short_description', true); }
function onChange(control, oldValue, newValue, isLoading) {
  if(isLoading) return;
 
  if(newValue == "Critical")
    g_form.setMandatory('u_due_date', true);
  else
    g_form.setMandatory('u_due_date', false); }

Make a field read-only

While you can use client scripting to make a field read-only, you can usually accomplish the same thing without scripting by using UI policies.

In order to make a field read-only, the field must be present on the form, though it may be hidden. The following example makes the incident_state field read-only on the Incident form upon load:
function onLoad() {
  g_form.setReadonly('incident_state', true); }
To do the same thing for a derived field (e.g., the Caller's phone number field if it has been added to the Incident form), you can use the following:
function onLoad() {
  g_form.setReadonly('caller_id.phone', true) }
Get a field value
g_form.getValue(<fieldName>);
function onChange(control, oldValue, newValue, isLoading) { 
  alert(g_form.getValue('short_description')); }
Set a field value
g_form.setValue(<fieldName>, <value>);
function onChange(control, oldValue, newValue, isLoading) {
  g_form.setValue('short_description', 'hello world'); }

Set a glide_list field value

You can pass one argument or two. For reference values, passing both the sys_id and the display value is more efficient because the client does not have to look up the display values for you. However, if you do not want to pass the display value, the client will do an AJAX call to find the value, which takes time.

Example: reset to no values.
g_form.setValue("watch_list", "" );
Example: Set to two references, passing the display values to avoid an AJAX call.
var valueArray = new Array("46d44a23a9fe19810012d100cca80666", "46c6f9efa9fe198101ddf5eed9adf6e7");
var labelArray = new Array("Beth Anglin", "Bud Richman");
g_form.setValue("watch_list", valueArray, labelArray);
Example: Set arbitrary email address (for a sys_user glide list).
g_form.setValue("watch_list", "", "you@you.com");
Example: Set references and emails, passing the display values to avoid an AJAX call.
var valueArray = new Array("46d44a23a9fe19810012d100cca80666", "", "46c6f9efa9fe198101ddf5eed9adf6e7");
var labelArray = new Array("Beth Anglin", "me@me.com", "Bud Richman");
g_form.setValue("watch_list", valueArray, labelArray);
Example: Set references and emails, but use AJAX to obtain display values for references (this is a bit less efficient as the server must be contacted for the display values).
var valueArray = new Array("46d44a23a9fe19810012d100cca80666", "me@me.com", "46c6f9efa9fe198101ddf5eed9adf6e7");
g_form.setValue("watch_list", valueArray);
Example: Set references and emails using a comma separated string, but use AJAX to obtain display values for references (this is a bit less efficient as the server must be contacted for the display values).
g_form.setValue("watch_list", "46d44a23a9fe19810012d100cca80666,me@me.com, "46c6f9efa9fe198101ddf5eed9adf6e7");
Add an Option to the end of a choice list
g_form.addOption(<fieldName>, <choiceValue>, <choiceLabel>);
function onChange(control, oldValue, newValue, isLoading) {
  g_form.addOption('priority', '6', '6 - Really Low'); }
Add an Option at a specific point on a choice list
g_form.addOption(<fieldName>, <choiceValue>, <choiceLabel>, <targetIndex>);
function onChange(control, oldValue, newValue, isLoading) {
  g_form.addOption('priority', '2.5', '2.5 - Really Low', 3); }

Note that an insert happens at the location you specify on a zero based array. Existing options will all shift up one level. For example:

[A, B, C, D]

Insert E at 0

[E, A, B, C, D]

Insert E at 2

[A, B, E, C, D]

Remove an option from a choice list
function onChange(control, oldValue, newValue, isLoading) {
  g_form.addOption('priority', '2.5', '2.5 - Really Low', 3); }
function onChange(control, oldValue, newValue, isLoading) {
  g_form.removeOption('priority', '1'); }
Remove the Closed state option if the user is not an admin:
function onLoad() { 
  var isAdmin = g_user.hasRole('admin');
  var state = g_form.getValue('state');
  if(!isAdmin && (state != 7)) { 
    alert('Current user is not an admin');
    g_form.removeOption('state', '7'); } }

Remove ALL options from a choice list

The Category choice list, for example:
g_form.getControl('category').options.length = 0;
Get the label for a choice list value
var choiceValue = g_form.getValue(<fieldName>);
 var choiceLabel = g_form.getOption(<fieldName>,choiceValue).text;
function onChange(control, oldValue, newValue, isLoading) {
  var choiceValue = g_form.getValue('category');
  var choiceLabel = g_form.getOption('category',choiceValue).text; }
Show or hide an action button depending on the form view
function onLoad() { 
  var objView = document.getElementById('sysparm_view');
  var strView = objView.getAttribute('value');
  if(strView == 'ess') { 
    var objCloseButton = document.getElementById('close_incident');
    objCloseButton.style.display = 'none'; } }
Look up the value of a reference field
var gr = g_form.getReference('fieldName');
function onChange(control, oldValue, newValue, isLoading) { 
  var caller = g_form.getReference('caller_id');
  if(caller.vip == 'true')
    alert('Caller is a VIP!'); }
Note: When setting values, use the storage value instead of the display value.
Get the current user name
var myVariable = g_user.userName;
function onLoad() { 
  var userName = g_user.userName;
  alert('Current user = ' + userName); }
Get the value of a parameter
var currentView = g_form.getParameter('view');
function onLoad() { 
  var view = g_form.getParameter('view'); 
  alert('Current view = ' + view); }
Test if the current user has a role
var myRole = g_user.hasRole(<role>);
function onLoad() {
  var isAdmin = g_user.hasRole('admin');
  if(isAdmin) 
    alert('Current user is an admin');
  else 
    alert('Current user is NOT an admin'); }
Determine what submit button was clicked
function onSubmit() {
  var action = g_form.getActionName();
  alert('You pressed ' + action); }
Determine if any fields on the form have changed
function onSubmit() { 
  var field1 = g_form.getControl('caller_id');
 
   //See if the 'changed' attribute is true 
  if(field1.changed) { 
    return confirm("The Caller field has changed.\n Do you really want to save this record?"); } }

Using GlideRecord query from client

There is a lightweight GlideRecord object on the client side that can be used to query the server from within client scripts. The following are some common methods that are available.
  • addQuery()
  • get()
  • hasNext()
  • next()
  • orderBy()
  • query()

For additional information, see GlideRecord() on the ServiceNow Developer Site.

One limitation is that the addOrCondition() method is not available. You can work around this by setting the GlideRecord encodedQuery property with an encoded query string.

Example:
var cat = g_form.getValue('category'); 
var subcat = g_form.getValue('subcategory');
var lookup = new GlideRecord('u_assignment_lookup');
strQuery = "u_type=Incident^ORu_type=All";
strQuery = strQuery + "^u_category=" + cat;
strQuery = strQuery + "^u_subcategory=" + subcat;
strQuery = strQuery + "^EQ";
lookup.encodedQuery = strQuery;
lookup.query();

Check if order guide is loaded for the first time

It can be helpful for a catalog client script to know whether the user has just started an order guide or is going back to the guide using the Describe Needs button from the item page.
// onload catalog script 
if(g_form.getParameter('cart_edit') != 'guide_serial') { 
  // this stuff only runs if the guide is reloaded after initial submit 
  // it will not run on initial load of the guide }