Back to Topics

Client-Side JavaScript - Topic 4

g_form & g_user APIs

What is g_form?

g_form is the primary client-side API for interacting with forms. It provides methods to get/set values, control field behavior, display messages, and manipulate form elements.

Critical for Exams

g_form is heavily tested in CSA and CAD exams. Master getValue(), setValue(), setMandatory(), setDisplay(), addInfoMessage(), and clearValue().

Getting and Setting Field Values

getValue() and setValue() 
// Get field value
var priority = g_form.getValue('priority');
var state = g_form.getValue('state');

// Get display value (for reference fields)
var assignedToName = g_form.getDisplayValue('assigned_to');
var groupName = g_form.getDisplayValue('assignment_group');

// Set field value
g_form.setValue('priority', '1');
g_form.setValue('short_description', 'Email server down');

// Set reference field (pass sys_id)
g_form.setValue('assigned_to', 'user_sys_id_here');
g_form.setValue('assignment_group', 'group_sys_id_here');

// Set value with display value
g_form.setValue('assigned_to', 'user_sys_id', 'John Doe');

// Clear field value
g_form.clearValue('assignment_group');
g_form.clearValue('assigned_to');

// Example: Copy caller to assigned user
var caller = g_form.getValue('caller_id');
if (caller) {
    g_form.setValue('assigned_to', caller);
}

Field Visibility and Display

Show/Hide Fields and Sections 
// Hide field
g_form.setDisplay('assigned_to', false);

// Show field
g_form.setDisplay('assignment_group', true);

// Hide multiple fields
g_form.setDisplay('caller_id', false);
g_form.setDisplay('contact_type', false);

// Show/hide section
g_form.setSectionDisplay('resolution_info', true);
g_form.setSectionDisplay('closure_information', false);

// Example: Show resolution fields only when resolved
function onChange(control, oldValue, newValue, isLoading, isTemplate) {
    if (isLoading || isTemplate) return;
    
    if (newValue == '6') {  // Resolved
        g_form.setSectionDisplay('resolution_info', true);
        g_form.setMandatory('close_notes', true);
    } else {
        g_form.setSectionDisplay('resolution_info', false);
        g_form.setMandatory('close_notes', false);
    }
}

Mandatory and Read-Only Fields

Field Requirements and Editability 
// Make field mandatory
g_form.setMandatory('assignment_group', true);

// Remove mandatory requirement
g_form.setMandatory('assigned_to', false);

// Check if field is mandatory
var isMandatory = g_form.isMandatory('priority');

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

// Make field editable
g_form.setReadOnly('short_description', false);

// Disable field (similar to read-only)
g_form.setDisabled('state', true);

// Enable field
g_form.setDisabled('priority', false);

// Example: Critical incidents require assignment
if (g_form.getValue('priority') == '1') {
    g_form.setMandatory('assignment_group', true);
    g_form.setMandatory('assigned_to', true);
} else {
    g_form.setMandatory('assignment_group', false);
    g_form.setMandatory('assigned_to', false);
}

User Messages and Field Messages

Display Messages to Users 
// Info message (blue banner)
g_form.addInfoMessage('Record updated successfully');

// Error message (red banner)
g_form.addErrorMessage('Please fill in all required fields');

// Warning message (yellow banner)  
g_form.addWarningMessage('This action cannot be undone');

// Clear all messages
g_form.clearMessages();

// Field-specific message
g_form.showFieldMsg('priority', 'Critical priority requires immediate attention', 'info');
g_form.showFieldMsg('assignment_group', 'Required for P1 incidents', 'error');
g_form.showFieldMsg('assigned_to', 'Assign to available team member', 'warning');

// Hide field message
g_form.hideFieldMsg('priority');
g_form.hideFieldMsg('assignment_group', false);  // Don't clear other messages

// Example: Validation with messages
function onSubmit() {
    if (g_form.getValue('priority') == '1' && 
        g_form.getValue('assignment_group') == '') {
        g_form.addErrorMessage('Critical incidents must have an assignment group');
        g_form.showFieldMsg('assignment_group', 'This field is required', 'error');
        return false;
    }
    return true;
}

Form Submission and Actions

Control Form Submission 
// Submit form
g_form.submit();

// Submit form with action name
g_form.submit('insert_and_stay');
g_form.submit('update');

// Disable form submit button
g_form.disableButton('submit');
g_form.disableButton('insert');

// Enable form submit button
g_form.enableButton('submit');

// Example: Validate and submit
function validateAndSubmit() {
    if (g_form.getValue('short_description') == '') {
        g_form.addErrorMessage('Description is required');
        return;
    }
    g_form.submit();
}

// Save form (same as submit but returns to list)
g_form.save();

Reference Field Methods

Working with Reference Fields 
// Get reference sys_id
var assignedToID = g_form.getValue('assigned_to');

// Get reference display value
var assignedToName = g_form.getDisplayValue('assigned_to');

// Get reference field object
var refField = g_form.getReference('assigned_to', function(ref) {
    if (ref) {
        var email = ref.email;
        var phone = ref.phone;
        alert('User: ' + ref.name + ', Email: ' + email);
    }
});

// Add filter to reference field
g_form.addFilter('assigned_to', 'active', true);
g_form.addFilter('assignment_group', 'type', 'support');

// Example: Filter users by selected group
function onChange(control, oldValue, newValue, isLoading, isTemplate) {
    if (isLoading || isTemplate) return;
    
    // Clear assigned user when group changes
    g_form.clearValue('assigned_to');
    
    // Filter assigned_to by selected group
    if (newValue) {
        g_form.addFilter('assigned_to', 'member_of', newValue);
    }
}

Form Utility Methods

Additional g_form Methods 
// Check if form is new
var isNew = g_form.isNewRecord();

// Get form's sys_id
var sysID = g_form.getUniqueValue();

// Get table name
var tableName = g_form.getTableName();

// Get section names
var sections = g_form.getSections();

// Flash field (highlight briefly)
g_form.flash('priority', '#FF0000', 0);  // Red flash

// Add option to choice list
g_form.addOption('state', '10', 'Custom State');

// Clear options from choice list
g_form.clearOptions('category');

// Remove option from choice list
g_form.removeOption('priority', '5');

// Hide all field messages
g_form.hideAllFieldMsgs();

// Hide related lists
g_form.hideRelatedList('incident_task');

// Show related lists
g_form.showRelatedList('incident_task');

// Example: New record setup
function onLoad() {
    if (g_form.isNewRecord()) {
        g_form.setValue('caller_id', g_user.userID);
        g_form.setValue('opened_by', g_user.userID);
        g_form.addInfoMessage('Creating new incident for ' + g_user.firstName);
    }
}

What is g_user?

g_user provides information about the currently logged-in user in client scripts. It's a client-side object containing user properties.

g_user Properties and Methods 
// User properties
var userID = g_user.userID;              // sys_id
var userName = g_user.userName;          // username (e.g., 'john.doe')
var firstName = g_user.firstName;        // First name
var lastName = g_user.lastName;          // Last name
var fullName = g_user.firstName + ' ' + g_user.lastName;

// Check if user has role
var hasAdmin = g_user.hasRole('admin');
var hasITIL = g_user.hasRole('itil');

// Check multiple roles (OR logic)
var hasCriticalRole = g_user.hasRole('admin,itil');

// Client data (custom user properties)
var clientData = g_user.getClientData('custom_property');

// Example: Auto-assign new records to current user
function onLoad() {
    if (g_form.isNewRecord()) {
        g_form.setValue('opened_by', g_user.userID);
        g_form.setValue('caller_id', g_user.userID);
        
        if (g_user.hasRole('itil')) {
            g_form.setValue('contact_type', 'self-service');
        }
    }
}

// Example: Role-based field control
function onLoad() {
    if (!g_user.hasRole('admin')) {
        g_form.setReadOnly('state', true);
        g_form.setReadOnly('priority', true);
    }
}

Common g_form Patterns

Real-World Examples 
// Pattern 1: Conditional mandatory fields
function onChange(control, oldValue, newValue, isLoading, isTemplate) {
    if (isLoading || isTemplate) return;
    
    if (newValue == '1') {  // Critical priority
        g_form.setMandatory('assignment_group', true);
        g_form.setMandatory('assigned_to', true);
        g_form.showFieldMsg('priority', 'Immediate response required', 'error');
    } else {
        g_form.setMandatory('assignment_group', false);
        g_form.setMandatory('assigned_to', false);
        g_form.hideFieldMsg('priority');
    }
}

// Pattern 2: Cascading field updates
function onChange(control, oldValue, newValue, isLoading, isTemplate) {
    if (isLoading || isTemplate) return;
    
    // Clear dependent field
    g_form.clearValue('subcategory');
    
    // Add filter for dependent field
    if (newValue) {
        g_form.addFilter('subcategory', 'parent', newValue);
    }
}

// Pattern 3: Form validation
function onSubmit() {
    var priority = g_form.getValue('priority');
    var group = g_form.getValue('assignment_group');
    
    if (priority == '1' && group == '') {
        g_form.addErrorMessage('Critical incidents require an assignment group');
        g_form.showFieldMsg('assignment_group', 'Required', 'error');
        return false;
    }
    
    return true;
}

// Pattern 4: Dynamic field visibility
function onLoad() {
    var state = g_form.getValue('state');
    
    if (state == '6' || state == '7') {  // Resolved or Closed
        g_form.setSectionDisplay('resolution_info', true);
        g_form.setMandatory('close_notes', true);
    } else {
        g_form.setSectionDisplay('resolution_info', false);
    }
}

// Pattern 5: User-specific defaults
function onLoad() {
    if (g_form.isNewRecord()) {
        g_form.setValue('opened_by', g_user.userID);
        g_form.setValue('caller_id', g_user.userID);
        
        if (g_user.hasRole('vip')) {
            g_form.setValue('priority', '2');
            g_form.addInfoMessage('VIP user - High priority assigned');
        }
    }
}

CSA & CAD Exam Questions (18 Questions)

How do you get a field value in a client script? Q1
CSA
  • A) g_form.getFieldValue('field')
  • B) g_form.getValue('field')
  • C) g_form.get('field')
  • D) g_form.field.value
Show Answer
Correct Answer: B
g_form.getValue('field_name') retrieves the value of a form field. For reference fields, it returns the sys_id. Use getDisplayValue() to get the display name of reference fields.
How do you make a field mandatory using g_form? Q2
CSA
  • A) g_form.setRequired('field', true)
  • B) g_form.setMandatory('field', true)
  • C) g_form.mandatory('field')
  • D) g_form.require('field', true)
Show Answer
Correct Answer: B
g_form.setMandatory('field_name', true) makes a field required. Use false to remove the requirement. This is one of the most common g_form methods in exams.
What does g_form.getDisplayValue() return for reference fields? Q3
CSA
  • A) The sys_id of the referenced record
  • B) The display value/name of the referenced record
  • C) The entire record object
  • D) A JSON string
Show Answer
Correct Answer: B
getDisplayValue() returns the display value (name) of reference fields. getValue() returns the sys_id. Example: getValue('assigned_to') returns sys_id, getDisplayValue('assigned_to') returns "John Doe".
How do you hide a field using g_form? Q4
CSA
  • A) g_form.hideField('field')
  • B) g_form.setVisible('field', false)
  • C) g_form.setDisplay('field', false)
  • D) g_form.hide('field')
Show Answer
Correct Answer: C
g_form.setDisplay('field_name', false) hides a field. Use true to show it. To hide entire sections, use g_form.setSectionDisplay('section_name', false).
How do you display an error message to the user? Q5
CSA
  • A) g_form.showError('message')
  • B) g_form.addErrorMessage('message')
  • C) g_form.errorMessage('message')
  • D) g_form.displayError('message')
Show Answer
Correct Answer: B
g_form.addErrorMessage('text') displays a red error banner. Also available: addInfoMessage() for blue info banner, addWarningMessage() for yellow warning banner.
What does g_form.clearValue() do? Q6
CSA
  • A) Clears all form fields
  • B) Removes a specific field from the form
  • C) Clears the value of a specific field
  • D) Validates the field value
Show Answer
Correct Answer: C
g_form.clearValue('field_name') sets a field's value to empty. Commonly used when clearing dependent fields, like clearing subcategory when category changes.
How do you submit a form using g_form? Q7
CSA
  • A) g_form.save()
  • B) g_form.submit()
  • C) g_form.update()
  • D) g_form.send()
Show Answer
Correct Answer: B
g_form.submit() submits the form. Can pass action name: g_form.submit('insert_and_stay'). g_form.save() also works but returns to list view.
How do you make a field read-only? Q8
CSA
  • A) g_form.setReadOnly('field', true)
  • B) g_form.readOnly('field')
  • C) g_form.setEditable('field', false)
  • D) g_form.lock('field')
Show Answer
Correct Answer: A
g_form.setReadOnly('field_name', true) makes a field read-only (non-editable). Use false to make it editable again. Also available: setDisabled() which is similar.
What does g_user.userID contain? Q9
CSA
  • A) The username (login name)
  • B) The user's full name
  • C) The user's sys_id
  • D) The user's email
Show Answer
Correct Answer: C
g_user.userID contains the current user's sys_id. g_user.userName contains the login name (e.g., 'john.doe'). g_user.firstName and lastName contain name parts.
How do you check if a user has a specific role using g_user? Q10
CSA
  • A) g_user.checkRole('admin')
  • B) g_user.hasRole('admin')
  • C) g_user.isRole('admin')
  • D) g_user.validateRole('admin')
Show Answer
Correct Answer: B
g_user.hasRole('role_name') returns true if the user has that role. Can check multiple roles with OR logic: g_user.hasRole('admin,itil') returns true if user has admin OR itil.
How do you show a field-specific message? Q11
CAD
  • A) g_form.addFieldMessage('field', 'text')
  • B) g_form.showFieldMsg('field', 'text', 'info')
  • C) g_form.fieldMessage('field', 'text')
  • D) g_form.setFieldMsg('field', 'text')
Show Answer
Correct Answer: B
g_form.showFieldMsg('field', 'message', 'type') displays a message under a specific field. Types: 'info' (blue), 'error' (red), 'warning' (yellow). Use hideFieldMsg() to remove.
What does g_form.isNewRecord() return? Q12
CSA
  • A) The record's sys_id
  • B) True if the form is creating a new record
  • C) The record number
  • D) True if the record was recently created
Show Answer
Correct Answer: B
g_form.isNewRecord() returns true if the form is for a new record (not yet saved), false for existing records. Commonly used in onLoad to set default values only for new records.
How do you get the sys_id of the current record? Q13
CAD
  • A) g_form.getSysID()
  • B) g_form.getUniqueValue()
  • C) g_form.getId()
  • D) g_form.recordID
Show Answer
Correct Answer: B
g_form.getUniqueValue() returns the sys_id of the current record. Returns null for new records that haven't been saved yet.
How do you add a filter to a reference field? Q14
CAD
  • A) g_form.setFilter('field', 'condition', 'value')
  • B) g_form.addFilter('field', 'condition', 'value')
  • C) g_form.filter('field', 'condition', 'value')
  • D) g_form.applyFilter('field', 'condition', 'value')
Show Answer
Correct Answer: B
g_form.addFilter('field_name', 'condition_field', 'value') filters reference field choices. Example: g_form.addFilter('assigned_to', 'active', true) shows only active users.
What does g_form.clearMessages() do? Q15
CSA
  • A) Clears all form field values
  • B) Removes all banner messages (info, error, warning)
  • C) Clears the form history
  • D) Deletes the form
Show Answer
Correct Answer: B
g_form.clearMessages() removes all banner messages (info, error, warning) from the top of the form. Field-specific messages are cleared with hideFieldMsg().
How do you hide a section on the form? Q16
CAD
  • A) g_form.hideSection('section_name')
  • B) g_form.setSectionDisplay('section_name', false)
  • C) g_form.setDisplay('section_name', false)
  • D) g_form.sectionVisible('section_name', false)
Show Answer
Correct Answer: B
g_form.setSectionDisplay('section_name', false) hides an entire form section. Use true to show it. setDisplay() is for individual fields, not sections.
Can you use g_form in Business Rules? Q17
CAD
  • A) Yes, in all business rules
  • B) Only in display business rules
  • C) No, g_form is client-side only
  • D) Only in before business rules
Show Answer
Correct Answer: B
g_form is primarily client-side, but can be used in Display Business Rules which run after the form loads. For other business rules, use GlideRecord and the 'current' object instead.
What's the difference between setDisplay and setVisible? Q18
CAD
  • A) No difference, they're aliases
  • B) setDisplay exists, setVisible doesn't exist in g_form
  • C) setVisible is faster
  • D) setDisplay is for fields, setVisible for sections
Show Answer
Correct Answer: B
setVisible() is not a valid g_form method. Always use setDisplay() to show/hide fields and setSectionDisplay() for sections.

Navigation

Previous: UI Policies & Actions Next: GlideAjax

g_form Quick Reference

  • getValue('field')
  • setValue('field', value)
  • getDisplayValue('field')
  • setMandatory('field', bool)
  • setDisplay('field', bool)
  • setReadOnly('field', bool)
  • addErrorMessage(text)
  • clearValue('field')
  • submit()
  • isNewRecord()

g_user Properties

  • g_user.userID
  • g_user.userName
  • g_user.firstName
  • g_user.hasRole('role')