GlideForm (Next Experience) - Client

The GlideForm API provides methods to customize forms in the Next Experience UI Framework.

Only use GlideForm methods on the client. You can use these methods to make custom changes to the form view of records. All validation of examples was done using client scripts.

You can also use some of these methods in other client scripts (such as Catalog Client Scripts or Wizard Client Scripts), but you must first test this to determine whether they will work as expected.

Note: The methods getControl(), getHelpTextControl(), getElement(), and getFormElement() are deprecated for mobile devices. For information on using GlideForm for mobile, see Mobile Client GlideForm (g_form) Scripting and Migration.

There is no constructor for the GlideForm class. Access GlideForm methods using the g_form global object.

Parent Topic:Client Next Experience API reference

GlideForm (Next Experience) - addAdditionalParams(String parameterName, String value)

Adds a hidden input with given name and value parameter to the form.

The following example customizes the behavior of the Update button on the Incident form so that users are redirected back to the list view in the default view, but remain on the record in the Advanced View after saving.

// Create an onLoad client script for the incident table with the following script.

function onLoad() {
   g_form.addAdditionalParam('view_name', g_form.getViewName());
}

Edit the global sysverb_update UI action and add the following script.

current.update();
if (RP.getParameterValue("view_name") == "advanced") {
  // Keep the record open if saving from the advanced view
  action.openGlideRecord(current);

// To test:
// Open the incident list and edit an incident. Click Update to be redirected to the list.
// Open /incident_list.do?sysparm_view=advanced and edit an incident. Click Update to be redirected back to the edited incident.

GlideForm (Next Experience) - addChoice(String fieldName, String choiceValue, String choiceLabel)

Adds a choice to the end of a specified choice list field.

g_form.addChoice('priority', '6', '6 - Really Low');

GlideForm (Next Experience) - addDecoration(String fieldName, String icon, String title)

Adds an icon on a field's label.

Adding the same item twice is prevented; however, you can add the same icon with a different title.

Note: This method is not supported by Service Catalog.

g_form.addDecoration('caller_id', 'icon-star', 'preferred member');

GlideForm (Next Experience) - addDecoration(String fieldName, String icon, String title, String color)

Adds an icon on a field's label.

Adding the same item twice is prevented; however, you can add the same icon with a different title.

Note: This method is not supported by Service Catalog.

g_form.addDecoration('caller_id', 'icon-star', 'Mark as Favorite', 'color-green');

GlideForm (Next Experience) - addErrorMessage(String message)

Displays the specified error message at the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

g_form.addErrorMessage('This is an error');

GlideForm (Next Experience) - addFormMessage(String message, String type, Object options)

Displays a floating form message at the top of the form detail section. The message doesn't cover UI actions.

See also:

• clearAllFormMessages()
• clearFormMessages()

{
  buttons: [Array],
  meta: {Object}
}

buttons: [
  {
    actionName: "String",
    label: "String"
  }
]

The following example shows how to add form messages of each type.

g_form.addFormMessage('info message','info');
g_form.addFormMessage('warning message','warning');
g_form.addFormMessage('error message','error');
g_form.addFormMessage('info2 message','info');
g_form.addFormMessage('warning2 message','warning');
g_form.addFormMessage('error2 message','error');
g_form.addFormMessage('Would you like to reassign this to yourself?', 'info', {buttons: [{label: "Assign to me", actionName: "assign_to_me"}], meta: {'userId': '46d44a23a9fe19810012d100cca80666'}});

GlideForm (Next Experience) - addInfoMessage(String message)

Adds the specified informational message to the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

g_form.addInfoMessage('The top five fields in this form are mandatory');

GlideForm (Next Experience) - addHighMessage(String message)

Displays a high priority message at the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

The following example shows how to display a high priority message at the top of the form.

g_form.addHighMessage(“This is a high priority message");

GlideForm (Next Experience) - addLowMessage(String message)

Displays a low priority message at the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

The following example shows how to display a low priority message at the top of the form.

g_form.addLowMessage(“This is a low priority message "); 

GlideForm (Next Experience) - addModerateMessage(String message)

Displays a moderate priority message at the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

The following example shows how to display a moderate priority message at the top of the form.

g_form.addModerateMessage(“This is a moderate priority message");

GlideForm (Next Experience) - addOption(String fieldName, String choiceValue, String choiceLabel)

Adds a choice to the end of a specified choice list field.

g_form.addOption('priority', '6', '6 - Really Low');

GlideForm (Next Experience) - addOption(String fieldName, String choiceValue, String choiceLabel, Number choiceIndex)

Adds a choice to the list field at the position specified.

Note: Duplicate list labels are not supported in Service Portal. For example, items with label text matching another label are ignored and not added to the list.

g_form.addOption('priority', '2.5', '2.5 - Moderately High', 3);

GlideForm (Next Experience) - addSuccessMessage(String message)

Displays a message confirming a successful action at the top of the form.

This message appears for approximately four seconds and then disappears. This timeout is not configurable at this time.

The following example shows how to display a message confirming a success message at the top of the form.

g_form.addSuccessMessage(“This is a success message");

GlideForm (Next Experience) - clearAllFormMessages()

Removes all form messages of any type.

See also:

• GlideForm (Next Experience) - addFormMessage(String message, String type, Object options)
• GlideForm (Next Experience) - clearMessages()
• clearFormMessages()

The following example shows how to clear all messages from the form.

g_form.clearAllFormMessages();

GlideForm (Next Experience) - clearChoices(String fieldName)

Removes all choices in a specified choice list field.

g_form.clearChoices('priority');

GlideForm (Next Experience) - clearFormMessages(String type)

Removes all form messages of a specified type.

See also:

• GlideForm (Next Experience) - addFormMessage(String message, String type, Object options)
• GlideForm (Next Experience) - clearMessages()
• GlideForm (Next Experience) - clearAllFormMessages()

The following example shows how to clear all error messages from the form.

g_form.clearFormMessages('error');

GlideForm (Next Experience) - clearMessages()

Removes all informational and error messages from the top of the form.

Removes informational and error messages added with g_form.addInfoMessage() and g_form.addErrorMessage().

g_form.clearMessages();

GlideForm (Next Experience) - clearOptions(String fieldName)

Removes all options from the specified choice list.

g_form.clearOptions('priority');

GlideForm (Next Experience) - clearValue(String fieldName)

Removes any value(s) from the specified field.

Note: This method can't be used to update fields set to strict read only. If this method is called on strict read only fields, the field isn't updated and a warning is logged in the browser console. For more information, see Configuring read-only security options.

GlideForm (Next Experience) - disableAttachments()

Prevents file attachments from being added to the form.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

GlideForm (Next Experience) - disableChoice(String fieldName, String choiceValue)

Programmatically disables a specific choice in the drop-down field, if the choice exists. No changes are made if the choice is already disabled.

The following example calls disableChoice() to disables the loading_dock choice in the delivery_location form field.

if (g_form.getValue('address_type') == 'home') {
    g_form.disableChoice('delivery_location', 'loading_dock');
}

// Only itil_admin users can select the "Closed" option  

function onLoad() {
    if (g_user.hasRole('itil_admin')) return;

    if (g_form.getValue('incident_state') != '7')
        g_form.disableChoice('incident_state', 7);

    if (g_form.getValue('state') != '7') {
        g_form.disableChoice('state', 7);
    }

}

GlideForm (Next Experience) - enableAttachments()

Allows file attachments to be added to the form. Shows the paper clip icon.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

GlideForm (Next Experience) - enableChoice(String fieldName, String choiceValue)

Programmatically enables a specific choice in the drop-down field, if the choice exists. No changes are made if the option is already enabled.

The following example calls enable() to enable a new drop-down choice, 1, in the priority form field.

var shortDescription = g_form.getValue('shortDescription');

// Allow priority 1 selection if short description mentions security 
if (shortDescription.includes('security')) {
    var p1Choice = g_form.getChoice('priority', '1');
    g_form.enableChoice('priority', '1');
}

GlideForm (Next Experience) - flash(String fieldName, String color, Number count)

Use to draw attention to a field. Flashes the specified color for a specified duration of time in the specified field.

This method is not supported by Service Catalog.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

g_form.flash("incident.number", "#FFFACD", 0);

GlideForm (Next Experience) - getActionName()

Returns the most recent action name, or, for a client script, the sys_id of the UI action clicked.

Note: Not available in Wizard client scripts.

function onSubmit() {
   var action = g_form.getActionName();
   alert('You pressed ' + action);
}

GlideForm (Next Experience) - getAnnotations()

Returns a list of all annotations on a form.

Annotations are visual separators between form elements, or blocks of colored text used to highlight form elements. Use GlideForm (Next Experience) - getAnnotationByName(String name) to return a specific annotation by its name.

[{content: "String", name: "String", visible: Boolean}]

The following example first calls getAnnotations() to return all annotations in a form, and then calls hideAnnotation() to hide all annotations in the form.

const annotations = getAnnotations();

/* returns:  
[ 
    { 
        "name": "test-annotation-msg-1", 
        "visible": true, 
        "content": "Test<input id=\"make_spacing_ok\" style=\"visibility:hidden; width:0px;\">" 
    }, 
    { 
        "name": "test-annotation-msg-2", 
        "visible": true, 
        "content": "Test 2<input id=\"make_spacing_ok\" style=\"visibility:hidden; width:0px;\">" 
    } 

]*/
annotations.forEach(function(annotation) {
    g_form.hideAnnotation(annotation.name);
});

// this script hides all annotations on the form. 

GlideForm (Next Experience) - getAnnotationByName(String name)

Returns a form annotation of a given name.

Annotations are visual separators between form elements, or blocks of colored text used to highlight form elements. Use GlideForm (Next Experience) - getAnnotations() to return all annotations in a form.

[{content: "String", name: "String", visible: Boolean}]

The following example demonstrates how to use the getAnnotationByName() method to retrieve a form annotation according to its given name, test-annotation-msg-1.

   var sampleAnnotation = g_form.getAnnotationByName("test-annotation-msg-1");

   /* returns:  
   { 
       "name": "test-annotation-msg-1", 
       "visible": true, 
       "content": "Test<input id=\"make_spacing_ok\" style=\"visibility:hidden; width:0px;\">" 
   }
   */

GlideForm (Next Experience) - getBooleanValue(String fieldName)

Returns a Boolean value for the specified field.

GlideForm (Next Experience) - getChoice(String fieldName, String choiceValue)

Returns an object with properties representing a given field and choice value.

("label", "value", "disabled", "index")

The following example demonstrates how to call g_form.getChoice() to return information about the priority field choices.

var priority = g_form.getValue('priority'); 

var priorityLabel = g_form.getChoice('priority', priority).label;

GlideForm (Next Experience) - getControl(String fieldName)

Returns the HTML element for the specified field.

Compound fields may contain several HTML elements. This method is generally not necessary as there are built-in methods that use the fields on a form.

If the field is a reference field and the control is a choice list, getControl() may not return a control as expected. In this case, use sys_select.<table name>.<field name>.

This method is not available in mobile scripts or Service Portal scripts.

GlideForm (Next Experience) - getDecimalValue(String fieldName)

Returns the decimal value of the specified field.

function onChange(control, oldValue, newValue, isLoading) {
   alert(g_form.getDecimalValue('percent_complete'));
}

GlideForm (Next Experience) - getDisplayValue(String fieldName)

Returns the display value from a form in Service Portal.

See also:

• getValue()
• Get the display value of a reference variable

Note: In the core UI, calling this method as g_form.getDisplayValue() without an argument returns the record display value rather than the display value of an individual field.

The following example shows how to get the display value of a reference variable in the core UI or Service Portal. The use case for this example is on the community site.

function onChange(control, oldValue, newValue, isLoading) {
     if (isLoading || newValue == '') {
          return;
     }
     if(window == null){
          var valuePortal = g_form.getDisplayValue('requester');
          alert('Portal->' + valuePortal);
     }
     else{
          var valueNative = g_form.getDisplayBox('requester').value;     
          alert('CoreUI->' + valueCoreUI);
     }
     //Type appropriate comment here, and begin script below
}

GlideForm (Next Experience) - getElement(String id)

Returns the HTML element specified by the parameter.

Compound fields may contain several HTML elements. This method is generally not necessary as there are built-in methods that use the fields on a form.

This method is not available in mobile scripts or Service Portal scripts.

GlideForm (Next Experience) - getFormElement()

Returns the HTML element for the form.

This method is not available in mobile scripts or Service Portal scripts.

GlideForm (Next Experience) - getIntValue(String fieldName)

Returns the integer value for the specified field.

GlideForm (Next Experience) - getLabelOf(String fieldName)

Returns the plain text value of the field label.

if (g_user.hasRole('itil')) {
    var oldLabel = g_form.getLabelOf('comments');
    g_form.setLabelOf('comments', oldLabel + ' (Customer visible)');
}

GlideForm (Next Experience) - getOptions(String fieldName)

Returns the available and selected options for a choice or reference field on the form. This method is useful for dynamic forms, catalog variables and variable sets, and integrations needing to inspect or filter field options at runtime.

For example, you can use the g_form.getOptions() to:

• Get and set the name-value pairs in a watch_list field type.
• Search or filter available options by a search term.
• Enable access to the same auto-complete results via a callback.
• Get and set options on choice fields, reference fields, and advanced field types such as watch_list, glide_list, field_list, and slushbucket.

[{value: "String", displayValue: "String"}]

[{value: "String", displayValue: "String"}]

The following example calls g_form.getOptions() to return all available choices for specified form fields, like state, work_notes_list, and others.

g_form.getOptions("state"); //table: incident, field: state, type: integer, choice: Dropdown without --None--
/*
returns [{"value":"1","displayValue":"New"},{"value":"2","displayValue":"In Progress"},{"value":"3","displayValue":"On Hold"},{"value":"6","displayValue":"Resolved"},{"value":"7","displayValue":"Closed"},{"value":"8","displayValue":"Canceled"}]
*/

g_form.getOptions("category"); //table: incident, field: category, type: string, choice: Dropdown with --None--
/*
returns [{"value":"","displayValue":"-- None --"},{"value":"inquiry","displayValue":"Inquiry / Help"},{"value":"software","displayValue":"Software"},{"value":"hardware","displayValue":"Hardware"},{"value":"network","displayValue":"Network"},{"value":"database","displayValue":"Database"}]
*/

g_form.getOptions("work_notes_list") //table: incident, field: work_notes_list, type: glide_list
/*
returns [{"value":"62826bf03710200044e0bfc8bcbe5df1","displayValue":"Abel Tuter"},{"value":"a8f98bb0eb32010045e1a5115206fe3a","displayValue":"Abraham Lincoln"},{"value":"5137153cc611227c000bbd1bd8cd2005","displayValue":"Fred Luddy"},{"value":"6a826bf03710200044e0bfc8bcbe5dec","displayValue":"Alissa Mountjoy"}]
*/

g_form.getOptions("restricted_fields") //table: std_change_properties, field: restricted_fields, type: field_list
/*
[{"value":"activity_due","displayValue":"Activity due"},{"value":"additional_assignee_list","displayValue":"Additional assignee list"},{"value":"comments","displayValue":"Additional comments"},{"value":"assignment_group","displayValue":"Assignment group"},{"value":"backout_plan","displayValue":"Backout plan"},{"value":"business_duration","displayValue":"Business duration"},{"value":"cab_delegate","displayValue":"CAB delegate"},...]
*/

g_form.getOptions('table') //table: sys_script_client, field: table, type: table_name
/*
[{"value":"","displayValue":"-- None --"},{"value":"cmdb_ci_appl_dot_net","displayValue":".NET Application [cmdb_ci_appl_dot_net]"},{"value":"evaluation","displayValue":"A/B Testing Evaluation [evaluation]"},{"value":"evaluation_execution","displayValue":"A/B Testing Evaluation Execution [evaluation_execution]"},{"value":"evaluation_parameter","displayValue":"A/B Testing Evaluation Parameter [evaluation_parameter]"},{"value":"sn_access_analyzer_request","displayValue":"Access Analyzer Query [sn_access_analyzer_request]"},{"value":"sn_access_analyzer_access_comparison_request","displayValue":"Access Comparison Request [sn_access_analyzer_access_comparison_request]"},{"value":"sys_security_acl","displayValue":"Access Control [sys_security_acl]"},...]
*/

g_form.getOptions('mandatory_fields'); //table: kb_knowledge_base, field: mandatory_fields, type: slushbucket
/*
[{"value":"active","displayValue":"Active"},{"value":"article_id","displayValue":"Article ID"},{"value":"displayValue","displayValue":"Article body"},{"value":"article_type","displayValue":"Article type"},{"value":"direct","displayValue":"Attachment link"},{"value":"author","displayValue":"Author"},{"value":"base_version","displayValue":"Base Version"},...]
*/

The following example script demonstrates how to call g_form.getOptions() with getAvailable() function.

const options = g_form.getOptions('priority');
if (options) {
  console.log('Selected:', options.selected);
  options.getAvailable('high').then(available => {
    console.log('Available matching "high":', available);
  });
}

GlideForm (Next Experience) - getReference(String fieldName, Function callBack)

Returns the GlideRecord for a specified field.

If a callback function is present, this routine runs asynchronously. The browser (and script) processing continues normally until the server returns the reference value, at which time, the callback function is invoked. If a callback function is not present, this routine runs synchronously and processing halts (causing the browser to appear to hang) while waiting on a server response.

Important: It is strongly recommended that you use a callback function.

Callback function support for ServiceCatalogForm.getReference is available.

Note: Using this method requires a call to the server which requires additional time and may introduce latency to your page. Use this method with caution. For additional information, see Client script design and processing.

function onChange(control, oldValue, newValue, isLoading) {
    g_form.getReference('caller_id', doAlert); // doAlert is our callback function
}

function doAlert(caller) { // reference is passed into callback as first arguments
   if (caller.getValue('vip') == 'true') {
      alert('Caller is a VIP!');
   }
}

GlideForm (Next Experience) - getRelatedListNames()

Returns an array of related list names from the current form.

var listNames = g_form.getRelatedListNames();

for (var i = 0; i < listNames.length; i++) {  
  this.showRelatedList(listNames[i]);
 }

GlideForm (Next Experience) - getSectionNames()

Returns all section names, whether visible or not.

GlideForm (Next Experience) - getSections()

Returns an array of the form's sections.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

function onChange(control, oldValue, newValue, isLoading) {
   //this example was run on a form divided into sections (Change form)
   // and hid a section when the "state" field was changed
   var sections = g_form.getSections();
   if (newValue == '2') {
      g_form.setSectionDisplay(sections[1], false);
   } else {
      g_form.setSectionDisplay(sections[1], true);
   }
}

GlideForm (Next Experience) - getTableName()

Returns the name of the table to which this record belongs.

On the server side, the table for the current record can be retrieved with current.sys_class_name or current.getTableName().

function onLoad() {
    if (g_form.isNewRecord()) {
        var tableName = g_form.getTableName(); //Get the table name
    }
}

GlideForm (Next Experience) - getUniqueValue()

Returns the sys_id of the record displayed in the form.

function onLoad() {
   var incSysid = g_form.getUniqueValue();
   alert(incSysid);
}

GlideForm (Next Experience) - getValue(String fieldName)

Returns the value of the specified form field.

This method also supports getting values from a multi-row variable set (MRVS). To obtain data from fields within an MRVS, you must first use JSON.parse(getValue('<mrvs_field_name>') || '[]') to obtain the MRVS array, and then use indexing to access the fields within the row objects. For more details, see the code example below.

The following example shows how to get the short description from the current form.

function onChange(control, oldValue, newValue, isLoading) {
   alert(g_form.getValue('short_description'));
}

The following example shows how to get values from an MRVS. In this example, salaries are being managed through the Service Catalog. The client script searches all rows within the MRVS for the value entered in the Job title and then updates the matching entries within the MRVS with what is entered in the Salary field. The MRVS is named "variable_set_1" and contains the following fields within each row object: Employee name [employee_name], Job title [employee_job_title], and Salary [employee_salary]. In addition, the Catalog Item contains: Job title [job_title] and Salary [salary].

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

// Get the MRVS
var vs1 = g_form.getValue('variable_set_1') || '[]';
var multiRowVariableSet = JSON.parse(vs1);

for (var i = 0; i < multiRowVariableSet.length; i++) {
// Check if the entered job title matches the title in the current MRVS row
  if (multiRowVariableSet[i].employee_job_title == g_form.getValue("job_title")){
    // Update the value of a matching field with the new salary
    multiRowVariableSet[i].employee_salary = newValue;
  }
}

// Update the MRVS
g_form.setValue('variable_set_1', JSON.stringify(multiRowVariableSet));
}

GlideForm (Next Experience) - hideAllFieldMsgs()

Hides all field messages.

GlideForm (Next Experience) - hideAllFieldMsgs(String type)

Hides all field messages of the specified type.

GlideForm (Next Experience) - hideAnnotation(String name)

Hides an annotation with a given name on the form UI.

Annotations are visual separators between form elements, or blocks of colored text used to highlight form elements. See also:

• GlideForm (Next Experience) - showAnnotation(String name) to display a specific annotation on the form.
• GlideForm (Next Experience) - toggleAnnotations() to toggle annotations on and off with greater flexibility.

The following example demonstrates how to programmatically hide the annotation named test-annotation-msg-1 on the form field using the hideAnnotation() method.

g_form.hideAnnotation('test-annotation-msg-1');

GlideForm (Next Experience) - hideErrorBox(String fieldName)

Hides the error message placed by showErrorBox().

Whenever possible, use hideFieldMsg() rather than this method whenever possible.

GlideForm (Next Experience) - hideFieldMsg(String fieldName, Boolean clearAll)

Hides the first message that appears in the specified field on the current form.

Use the showFieldMsg(String field, String message, String type) or showFieldMsg(String field, String message, String type, Boolean scrollForm) methods to display messages on a form.

For example, the following code snippet shows how to display two messages on the work_notes field of a form and then hide the first message:

g_form.showFieldMsg('work_notes', 'First message', "error");
g_form.showFieldMsg('work_notes', 'Second message', "error");
g_form.hideFieldMsg('work_notes', false); // This call hides the 'First message'

The following example shows how to clear all messages for a specified form field and then display an encryption error message.

function submitEncryptedInputs() {
  return processEncryptedInputs(function(inputName, fieldName) {
    if (!checkEncryptedFieldValue(fieldName)) {
      g_form.hideFieldMsg(fieldName, true); // Hide all messages for the specified field
      g_form.showFieldMsg(fieldName, "Your activity requires an encrypted input.", "error");
      return false;
    }
    return true;
  });
}

GlideForm (Next Experience) - hideRelatedList(String listTableName)

Hides the specified related list on the form.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

GlideForm (Next Experience) - hideRelatedLists()

Hides all related lists on the form.

This method is not available on the mobile platform. If this method is run on a mobile platform, no action occurs.

GlideForm (Next Experience) - isMandatory(String fieldName)

Returns true if the field is mandatory.

Mandatory fields are visually distinguished by an asterisk next to the field label. The asterisk is red if the field is empty, and black if the field is not empty. The system displays a validation message if a user attempts to save or submit the form without completing those fields. For more information, see Form fields.

GlideForm (Next Experience) - isNewRecord()

Returns true if the record has never been saved.

function onLoad() {
   if(g_form.isNewRecord()){
      alert('New Record!');
   }
}

GlideForm (Next Experience) - isVisible(String fieldName)

Determines whether the field associated with the passed-in field name is visible on the current form.

The following code example shows how to check if the user_address field is visible on the current form.

if(g_form.isVisible('user_address')) {
    alert('is visible');
}
else {
    alert('is hidden');
}

GlideForm (Next Experience) - onUserChangeValue(Function fn)

Registers a custom event listener that detects when any field in the current form is modified by a user.

When a form field is modified, the event listener calls the function that is passed in when the listener is initially registered. This listener is only triggered when a user makes a change to a field on the form. Changes from client scripts, UI policies, or any other non-user interactions, do not trigger the listener.

Note: This method does not work for journal fields or Service Catalog items in the classic environment.

var handler = function(fieldname, originalValue, newValue) {
  console.log('The field ('+ fieldname + ') has a new value of: ' + newValue); // function code
}

var unregister = g_form.onUserChangeValue(handler);

// To unregister the event listener
unregister();

GlideForm (Next Experience) - removeChoice(String fieldName, String choiceValue)

Removes the specified choice from the specified choice list field.

g_form.removeChoice('priority', '1');

GlideForm (Next Experience) - removeDecoration(String fieldname, String icon, String title)

Removes the icon from the specified field that matches the specified icon and title.

Note: This method isn't supported by Service Catalog.

function onChange(control, oldValue, newValue, isLoading) {
    // if the caller_id field is not present, then we can't add an icon anywhere
    if (!g_form.hasField('caller_id'))
        return;

    if (!newValue)
        return;

    g_form.getReference('caller_id', function(ref) {
        g_form.removeDecoration('caller_id', 'icon-star', 'VIP');

        if (ref.getValue('vip') == 'true')
            g_form.addDecoration('caller_id', 'icon-star', 'VIP');          
    });
}

GlideForm (Next Experience) - removeDecoration(String fieldname, String icon, String title, String color)

Removes the icon from the specified field that matches the specified icon, title, and color.

Note: This method isn't supported by Service Catalog.

g_form.removeDecoration('caller_id', 'icon-star', 'VIP', 'blue');

GlideForm (Next Experience) - removeOption(String fieldName, String choiceValue)

Removes the specified option from the specified choice list.

g_form.removeOption('priority', '1');

GlideForm (Next Experience) - save()

Saves the record without navigating away (update and stay).

GlideForm (Next Experience) - setChoiceLabel(String fieldName, String choiceValue, String newLabel)

Updates the label of a specific choice in the drop-down field.

When calling this method, the index position of the updated option in the drop-down remains unchanged. The enabled or disabled state of the option is preserved.

The following example calls setChoiceLabel() to update the 'bonus' field choices (10, 20, and 30) to new values.

// Show the calculated bonus next to the percentage label
var salary = parseInt(g_form.getValue('salary'), 10); 
g_form.setChoiceLabel('bonus', '10', '10% ($'+ (salary * .10) +')'); 
g_form.setChoiceLabel('bonus', '20', '20% ($'+ (salary * .20) +')'); 
g_form.setChoiceLabel('bonus', '30', '30% ($'+ (salary * .30) +')');

GlideForm (Next Experience) - setDisabled(String fieldName, Boolean disable)

Makes the specified field available or unavailable.

GlideForm (Next Experience) - setDisplay(String fieldName, Boolean display)

Displays or hides a specified field on the form.

This method can't hide a mandatory field with no value. If the field is hidden, the space is used to display other items. Whenever possible, use a UI policy instead of this method.

function onChange(control, oldValue, newValue, isLoading, isTemplate) {
   //If the page isn't loading
   if (!isLoading) {
      //If the new value isn't blank
      if (newValue != '') {
         g_form.setDisplay('priority', false);   
      }
      else 
         g_form.setDisplay('priority', true);
      }
   }

GlideForm (Next Experience) - setLabelOf(String fieldName, String label)

Sets the plain text value of the specified field label.

Note: This method isn't supported by Service Catalog.

if (g_user.hasRole('itil')) {
    var oldLabel = g_form.getLabelOf('comments');
    g_form.setLabelOf('comments', oldLabel + ' (Customer visible)');
}

GlideForm (Next Experience) - setMandatory(String fieldName, Boolean mandatory)

Makes the specified field mandatory.

Mandatory fields are visually distinguished by an asterisk next to the field label. The asterisk is red if the field is empty, and black if the field is not empty. The system displays a validation message if a user attempts to save or submit the form without completing those fields. For more information, see Form fields.

Note: Whenever possible, use a UI policy rather than this method.

GlideForm (Next Experience) - setReadOnly(String fieldName, Boolean readOnly)

Makes the specified field read-only or editable.

Whenever possible, use a UI policy instead of this method.

To make a mandatory field read-only, you must first remove the mandatory requirement for that field by using the setMandatory() method.

Once you set a field to read-only, you cannot use the setValue() method to update the value of that field. If you need to set the value in this way, you must set the readOnly value to false.

The following example shows how set the Variable Editor to read only. To do this in Service Catalog tables, use setVariablesReadOnly().

// Create a Client Script on a table (e.g., incident) and paste this script
// Uncheck (set to false) the "isolate script" checkbox (not available by default)
// To add the isolate script checkbox to the form, configure form layout to add the checkbox
function onLoad() { 
  $("variable_map").querySelectorAll("item").forEach(function(item){
    var variable = item.getAttribute("qname"); 
    g_form.setReadOnly("variables."+ variable, true); 
  }); 
}

GlideForm (Next Experience) - setSectionDisplay(String sectionName, Boolean display)

Shows or hides a specified section in the form.

GlideForm (Next Experience) - setValue(String fieldName, String value, String displayValue)

Sets the value of a specified form field to the specified value or the value of a specified display value in a reference record.

To improve performance by preventing a round trip when setting the value for a reference field, use this method, not setValue(fieldName, value). When setting multiple reference values for a list collector field, pass arrays in the value and displayValue parameters.

This method also supports setting values in a multi-row variable set (MRVS). You must first use JSON.parse(getValue('<mrvs_field_name>')) to obtain the MRVS array and then use indexing to update the fields within the row objects. Once all values are updated in the MRVS, use the setValue() method to save the updated MRVS array. For more details, see the code example below.

Note: This method can't be used to update fields set to strict read only. If this method is called on strict read only fields, the field isn't updated and a warning is logged in the browser console. For more information, see Configuring read-only security options.

Note: The method setValue() can cause a stack overflow when used in an onchange client script. This is because every time the value is set, it will register as a change, which may re-trigger the OnChange client script. To prevent this, perform a check that will validate that the new value will be different from the old value. For example, before performing setValue(shortDesc, newValue.toUpperCase());, validate that the short description is not already uppercase. This will prevent the client script from applying the toUpperCase() more than once.

The following example shows how to set the short description in the current form.

g_form.setValue('short_description', 'replace this with appropriate text');

The following example shows how to set values in an MRVS. In this example, salaries are being managed through the Service Catalog. The client script searches all rows within the MRVS for the value entered in the Job title and then updates the matching entries within the MRVS with what is entered in the Salary field. The MRVS is named "variable_set_1" and contains the following fields within each row object: Employee name [employee_name], Job title [employee_job_title], and Salary [employee_salary]. In addition, the Catalog Item contains: Job title [job_title] and Salary [salary].

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

// Get the MRVS
var multiRowVariableSet = JSON.parse(g_form.getValue('variable_set_1'));

for (var i = 0; i < multiRowVariableSet.length; i++) {
// Check if the entered job title matches the title in the current MRVS row
  if (multiRowVariableSet[i].employee_job_title == g_form.getValue("job_title")){
    // Update the value of a matching field with the new salary
    multiRowVariableSet[i].employee_salary = newValue;
  }
}

// Update the MRVS
g_form.setValue('variable_set_1', JSON.stringify(multiRowVariableSet));
}

This example shows passing the sys_id of the reference record that contains the userName field to use to update the assigned_to form field.

g_form.setValue('assigned_to', userSysID, userName);

This example shows passing an array of reference record sys_ids and an array of corresponding display value names to use to update the form fields in the GlideList glide-list_field_name.

g_form.setValue('glide-list_field_name', sysIDArray, displayNameArray);

GlideForm (Next Experience) - setVariablesReadOnly(Boolean isReadOnly)

Makes a Service Catalog variable editor read only.

Note: This method is only applicable to Service Catalog variable editors in the core UI. This method is not supported in the Service Catalog form.

The method must be placed in the client script of the table in which the variable editor is added, such as Requested Item [sc_req_item], Incident [incident], and so on. To set variables to read only in other tables, use the setReadOnly() method.

See also: Service Catalog variable editors

Adding the following line to a client script sets the variable editor to read only.

g_form.setVariablesReadOnly(true);

GlideForm (Next Experience) - setVisible(String fieldName, Boolean display)

Displays or hides the specified field.

On desktop UI, the space is left blank when hidden. On Mobile or Service Portal UI, the space is filled in my other fields when hidden. This method can't hide mandatory fields with no value.

Use UI Policy rather than this method whenever possible.

function onChange(control, oldValue, newValue, isLoading, isTemplate) {
   //If the page isn't loading
   if (!isLoading) {
      //If the new value isn't blank
      if(newValue != '') {
         g_form.setVisible('priority', false); 
      }
      else
         g_form.setVisible('priority', true); 
      }
   }

GlideForm (Next Experience) - showAnnotation(String name)

Shows an annotation with a given name on the form UI.

Annotations are visual separators between form elements, or blocks of colored text used to highlight form elements. See also:

• GlideForm (Next Experience) - hideAnnotation(String name) to hide a specific annotation on the form.
• GlideForm (Next Experience) - toggleAnnotations() to toggle annotations on and off with greater flexibility.

The following example demonstrates how to programmatically show the annotation named test-annotation-msg on the form field using the showAnnotation() method.

g_form.showAnnotation('test-annotation-msg');

GlideForm (Next Experience) - showErrorBox(String name, String message)

Displays an error message under the specified form field (either a control object or the name of the field). If the control or field is currently off the screen, the form automatically scrolls to the control or field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field). The showFieldMsg() method is a similar method that requires a type parameter.

GlideForm (Next Experience) - showErrorBox(String name, String message, Boolean scrollForm)

Displays an error message under the specified form field (either a control object or the name of the field). If the control or field is currently off the screen and the scrollForm parameter is true, the form scrolls to the control or field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field). The showFieldMsg() method is a similar method that requires a type parameter.

GlideForm (Next Experience) - showFieldMsg(String field, String message, String type)

Displays a message under the specified form field (either a control object or the name of the field). If the control or field is off the screen, the method automatically scrolls the form to that field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field).

The showErrorBox() method is a shorthand method that does not require the type parameter.

Note: This method does not work with the journal_field type field in Core UI.

g_form.showFieldMsg('impact','Low impact response time can be one week','info');

GlideForm (Next Experience) - showFieldMsg(String field, String message, String type, Boolean scrollForm)

Displays a message under the specified form field (either a control object or the name of the field). If the control or field is currently off the screen and scrollForm is true, the method scrolls the form to that field.

A global property (glide.ui.scroll_to_message_field) is available that controls automatic message scrolling when the form field is off screen (scrolls the form to the control or field).

The showErrorBox() method is a shorthand method that does not require the type parameter.

Note: This method does not work with the journal_field type field in Core UI.

g_form.showFieldMsg('impact','Low impact not allowed with High priority','error',false);

GlideForm (Next Experience) - showRelatedList(String listTableName)

Displays the specified related list on the form.

This method isn't available on the mobile platform. If this method is run on a mobile platform, no action occurs.

GlideForm (Next Experience) - showRelatedLists()

Displays all the form's related lists.

This method isn't available on the mobile platform. If this method is run on a mobile platform, no action occurs.

GlideForm (Next Experience) - submit()

Saves the record.

The user is taken away from the form, returning them to where they were.

GlideForm (Next Experience) - submit(String verb)

Performs the specified UI action.

GlideForm (Next Experience) - toggleAnnotations()

Hides or shows all annotations on the form.

Annotations are visual separators between form elements, or blocks of colored text used to highlight form elements. If annotations are visible on the form, calling toggleAnnotations() hides them. Similarly if annotations are hidden on the form, calling this method displays them. See also:

• GlideForm (Next Experience) - hideAnnotation(String name)
• GlideForm (Next Experience) - showAnnotation(String name)

The following example shows how to call toggleAnnotations() to show or hide form annotations. As a result, annotations are hidden or shown depending on their previous state.

g_form.toggleAnnotations();