ServiceNow Client-Side APIs: g_form, g_user, g_list — The Methods That Control the Form

Where these run

Client-side scripts run in the user's browser, not on the server. You cannot use GlideRecord here. The three objects available to you are:

• g_form — manipulates the current form (fields, labels, messages)
• g_user — information about the logged-in user
• g_list — manipulates list views (less common)

g_form — Form manipulation

Get and set field values

// Get the raw value (sys_id for reference fields, number for choice fields)
var callerId = g_form.getValue('caller_id');       // sys_id string
var priority = g_form.getValue('priority');         // '1'

// Get the display value (the text the user sees)
var callerName = g_form.getDisplayValue('caller_id'); // 'John Smith'

// Set a field value
g_form.setValue('priority', '2');
g_form.setValue('assignment_group', 'a1b2c3d4...');  // must be sys_id for reference fields

// Clear a field
g_form.clearValue('assigned_to');

Control field visibility and behavior

// Hide/show a field
g_form.setVisible('u_internal_notes', false);  // hide
g_form.setVisible('u_internal_notes', true);   // show

// Make a field mandatory
g_form.setMandatory('assignment_group', true);

// Make a field read-only
g_form.setReadOnly('short_description', true);

// Set a field label (useful for dynamic labels)
g_form.setLabelOf('u_custom_field', 'New Label Text');

Messages on the form

// Info message (blue banner at top)
g_form.addInfoMessage('This incident has been escalated.');

// Error message (red banner at top)
g_form.addErrorMessage('Missing required data.');

// Field-level message (appears under a specific field)
g_form.showFieldMsg('short_description', 'Must be at least 10 characters', 'error');
g_form.hideFieldMsg('short_description');

// Clear all messages
g_form.clearMessages();

Form state

// Check if the form is for a new record
if (g_form.isNewRecord()) {
    // This is an insert, not an update
}

// Get the table name
var table = g_form.getTableName();  // 'incident'

// Get the sys_id of the current record
var sysId = g_form.getUniqueValue();

// Check if a field value has changed (useful in onChange)
var changed = g_form.isFieldChanged('priority');  // only works in onChange context

// Submit the form programmatically
g_form.submit();

Reference field lookups (getReference)

// getReference is asynchronous — always use the callback form
g_form.getReference('caller_id', function(callerRecord) {
    // callerRecord is a GlideRecord-like object
    var dept = callerRecord.department.getDisplayValue();
    g_form.addInfoMessage('Caller department: ' + dept);
});

// NEVER use the synchronous form — it freezes the browser
// var ref = g_form.getReference('caller_id'); // BAD — blocks UI

g_user — Current user information

// Basic user info
var userName = g_user.userName;      // 'john.smith'
var fullName = g_user.getFullName(); // 'John Smith'
var userId   = g_user.userID;        // sys_id of the logged-in user

// Role checks
if (g_user.hasRole('admin')) {
    // user has admin role
}
if (g_user.hasRole('itil')) {
    // user has ITIL role
}
// hasRoleExactly checks the specific role, not inherited roles
if (g_user.hasRoleExactly('incident_manager')) {
    // user has incident_manager specifically, not just admin
}

// Client-side data from g_user.getClientData (set in Display Business Rule)
// In Display BR:  g_scratchpad.isVIP = true;
// In Client Script: var isVIP = g_scratchpad.isVIP;

g_scratchpad — Pass server data to client

g_scratchpad is an object populated by Display Business Rules on the server side, then available in Client Scripts. This is the correct way to pass server data to the client without making GlideAjax calls.

// === Display Business Rule (server-side, runs when form loads) ===
(function executeRule(current, previous) {
    g_scratchpad.callerIsVIP = current.caller_id.vip.toString();
    g_scratchpad.openP1Count = new GlideAggregate('incident');
    // ... calculate value ...
    g_scratchpad.openP1Count = '5';
})(current, previous);

// === Client Script (onLoad, runs in browser) ===
function onLoad() {
    if (g_scratchpad.callerIsVIP === 'true') {
        g_form.addInfoMessage('VIP caller — handle with priority.');
    }
}

g_list — List view manipulation

Available only in list context (not forms). Less commonly used but important for UI Actions on lists.

// Get selected sys_ids from a list (checkboxes)
var selectedIds = g_list.getChecked();  // comma-separated sys_ids

// Refresh the current list
g_list.refresh();

// Get the list's table name
var table = g_list.getTableName();

// Get the current list filter (encoded query)
var filter = g_list.getQuery();

Common traps

• Using GlideRecord in a Client Script: It does not exist on the client side. Use GlideAjax to call a Script Include on the server if you need database access.
• Synchronous getReference: The no-callback version of g_form.getReference() blocks the browser's main thread. Always pass a callback function.
• g_user.hasRole('admin') returns true for admins on everything: Admin role bypasses all role checks. If you want to check a specific role without admin bypass, use g_user.hasRoleExactly().
• setValue on reference fields: You must pass a sys_id, not a display name. To set by display name, use g_form.getReference() first or pass both: there is no two-arg version for setValue reference, so you need the sys_id.
• UI Policies override Client Scripts: If both control the same field, the UI Policy runs after the Client Script and wins. Do not use both on the same field unless you understand the execution order.