GlideForm (g_form) API

GlideForm (g_form) API – Complete Guide for ServiceNow CAD Exam

Why is the GlideForm (g_form) API Important?

The GlideForm API, commonly referenced as g_form, is one of the most critical client-side APIs in ServiceNow. It is the primary mechanism through which developers interact with and manipulate forms displayed to users in the browser. Whether you are setting field values, making fields mandatory, showing or hiding sections, or displaying messages to users, g_form is the tool you use. For the ServiceNow Certified Application Developer (CAD) exam, a strong understanding of g_form is absolutely essential, as it appears across multiple question domains including Client Scripts, UI Policies, and general application user interface topics.

What is the GlideForm (g_form) API?

The GlideForm API is a client-side JavaScript API that provides methods to interact with forms and form fields in the ServiceNow platform. The global object g_form is automatically available in the following client-side scripting contexts:

• Client Scripts (onLoad, onChange, onSubmit, onCellEdit)
• UI Policy Scripts (Run Scripts section)
• Catalog Client Scripts (for Service Catalog items)

It is not available in server-side scripts such as Business Rules, Script Includes, or Scheduled Jobs. This distinction is commonly tested on the exam.

How Does the GlideForm API Work?

When a form loads in the browser, ServiceNow creates a g_form object that represents the current form. This object exposes a wide range of methods that allow you to read and modify the form's behavior and appearance without requiring a server round-trip (in most cases).

Key Categories of g_form Methods:

1. Getting and Setting Field Values

• g_form.getValue('field_name') – Returns the value of a field as a string. For reference fields, this returns the sys_id.
• g_form.setValue('field_name', value) – Sets the value of a field. For reference fields, you can pass a sys_id and optionally a display value as a third parameter: g_form.setValue('field_name', sys_id, display_value).
• g_form.getDisplayValue('field_name') – Returns the display value of a field. Especially useful for reference fields where you want the human-readable name instead of the sys_id.
• g_form.clearValue('field_name') – Clears the value of a field.

2. Controlling Field Visibility

• g_form.setVisible('field_name', true/false) – Shows or hides a field on the form.
• g_form.setSectionDisplay('section_name', true/false) – Shows or hides an entire form section.

3. Controlling Field Properties

• g_form.setMandatory('field_name', true/false) – Makes a field mandatory or not mandatory.
• g_form.setReadOnly('field_name', true/false) – Makes a field read-only or editable. (Also known as setDisabled in some legacy references.)
• g_form.setDisplay('field_name', true/false) – Similar to setVisible but also removes the field from the form layout space entirely when set to false.

4. Displaying Messages

• g_form.addInfoMessage('message') – Displays a blue informational message at the top of the form.
• g_form.addErrorMessage('message') – Displays a red error message at the top of the form.
• g_form.showFieldMsg('field_name', 'message', 'type') – Displays a message directly below a specific field. The type can be 'info' or 'error'.
• g_form.hideFieldMsg('field_name') – Hides a previously shown field message.
• g_form.clearMessages() – Clears all messages displayed on the form.

5. Option List Manipulation (Choice Fields)

• g_form.getOption('field_name', 'value') – Returns a specific option object from a choice list.
• g_form.addOption('field_name', value, label) – Adds an option to a choice list. An optional fourth parameter (index) specifies the position.
• g_form.removeOption('field_name', value) – Removes an option from a choice list.
• g_form.clearOptions('field_name') – Removes all options from a choice list.

6. Reference Field Interaction

• g_form.getReference('field_name', callback) – Retrieves the full GlideRecord object for a reference field. Important: This method makes an asynchronous server call. Best practice is to always use the callback function parameter to handle the returned record. Using it synchronously (without a callback) is deprecated and can cause performance issues.

Example with callback:
g_form.getReference('caller_id', function(ref) {
    g_form.setValue('caller_phone', ref.phone);
});

7. Form Submission Control

• g_form.submit() – Submits the form programmatically.
• g_form.save() – Saves the form without leaving the current view.
• In onSubmit Client Scripts, returning false will prevent the form from being submitted. This is a common exam scenario.

8. Other Useful Methods

• g_form.getTableName() – Returns the name of the table associated with the current form.
• g_form.getSysId() – Returns the sys_id of the current record. (Not available for new records.)
• g_form.isNewRecord() – Returns true if the current record is new (has not been saved).
• g_form.addDecoration('field_name', 'icon', 'title') – Adds an icon decoration next to a field label.
• g_form.removeDecoration('field_name', 'icon', 'title') – Removes a previously added decoration.
• g_form.getLabelOf('field_name') – Returns the label of a field.
• g_form.setLabelOf('field_name', 'new_label') – Changes the label of a field on the form.

Understanding Client Script Types and g_form:

• onLoad – Runs when a form is first loaded. Use g_form to set initial values, hide fields, or show messages. The function signature is: function onLoad() { }
• onChange – Runs when a specific field value changes. The function signature is: function onChange(control, oldValue, newValue, isLoading, isTemplate) { }. A common best practice is to check if (isLoading || newValue === '') return; at the beginning to avoid unnecessary execution during form load.
• onSubmit – Runs when the form is submitted. Return false to abort submission. The function signature is: function onSubmit() { }
• onCellEdit – Runs when a cell in a list is edited.

g_form vs. UI Policies (No Script):

UI Policies can achieve many g_form operations without scripting—specifically making fields mandatory, read-only, or visible. ServiceNow recommends using UI Policies without scripts whenever possible, resorting to Client Scripts with g_form only when more complex logic is needed. The exam may test this best practice.

Key Distinctions to Remember:

• g_form is client-side only. Do not confuse it with GlideRecord, which can be used both client-side and server-side (though client-side GlideRecord via GlideAjax is preferred).
• g_form.getValue() always returns a string, even for numeric or boolean fields.
• g_form.getReference() should always use a callback function for asynchronous processing.
• g_form methods affect only the current user's view of the form—they do not change database values until the form is submitted.
• g_form.setValue() on a reference field should include the display value as the third parameter to avoid an unnecessary server lookup.

---

Exam Tips: Answering Questions on GlideForm (g_form) API

Tip 1: Know the Scope
If a question asks about manipulating a form field in a Business Rule or Script Include, the answer is not g_form. g_form is exclusively client-side. Business Rules use current and previous objects, not g_form.

Tip 2: getValue() Returns a String
Many exam questions test whether you know that g_form.getValue() returns a string. If you need to compare a numeric field, you may need to use parseInt() or simply compare with a string value like '1' instead of the number 1.

Tip 3: getReference() Requires a Callback
If a question provides code using g_form.getReference() without a callback, it may be flagged as incorrect or poor practice. Always look for the callback pattern in answer choices.

Tip 4: onChange Best Practice
In onChange Client Scripts, always look for the isLoading guard clause. Questions may present scripts that behave unexpectedly on form load because they lack this check.

Tip 5: onSubmit Return False
Know that returning false in an onSubmit Client Script prevents form submission. This is a frequently tested pattern for form validation scenarios.

Tip 6: UI Policies vs. Client Scripts
If a question asks for the simplest or best practice way to make a field mandatory, visible, or read-only based on a condition, the preferred answer is typically a UI Policy (no script), not a Client Script using g_form.

Tip 7: setValue on Reference Fields
Remember that g_form.setValue() on a reference field accepts three parameters: field name, sys_id, and display value. Providing the display value as the third argument is best practice because it prevents an extra AJAX call to the server to resolve the display value.

Tip 8: addInfoMessage vs. showFieldMsg
Know the difference: addInfoMessage and addErrorMessage display messages at the top of the form, while showFieldMsg displays a message below a specific field. Questions may test which method is appropriate for a given scenario.

Tip 9: addOption / removeOption
Questions about dynamically modifying choice list options will reference addOption and removeOption. Remember that clearOptions removes all options—it is commonly used before repopulating a choice list.

Tip 10: isNewRecord()
If a question involves logic that should only execute on new records (or only on existing records), look for g_form.isNewRecord() in the answer choices. This is a common exam pattern for onLoad Client Scripts.

Tip 11: Distinguish Between setVisible and setDisplay
setVisible hides the field but may leave the space on the form, while setDisplay removes the field and its space from the form layout. However, in modern ServiceNow versions, the behavior is very similar. The exam may still test awareness of both methods.

Tip 12: Practice Reading Code Snippets
Many CAD exam questions present short code snippets and ask what the result will be. Practice reading g_form method calls quickly and predicting outcomes. Pay attention to parameter order, return types, and whether the code is in the correct script type (onLoad, onChange, or onSubmit).

Summary: The GlideForm (g_form) API is fundamental to client-side development in ServiceNow. Mastering its methods, understanding when and where to use them, and knowing best practices will prepare you to confidently answer a significant number of CAD exam questions related to the application user interface domain.