Example: Populating a ‘Description’ based on ‘Short Description’

Imagine you want to automatically populate the ‘Description’ field with the value of the ‘Short Description’ field when the latter is changed. This is a common requirement for Incident or Request items.

You would typically implement this in an onChange client script on the ‘Short Description’ field:

function onChange(control, oldValue, newValue, isLoading, isTemplate) {
    if (isLoading || newValue === '') {
        return;
    }
    // Get the value from the 'short_description' field
    var shortDescValue = g_form.getValue('short_description');

    // Set the value for the 'description' field
    g_form.setValue('description', shortDescValue);
}
        

Key Takeaway: getValue() is essential for reading data to use in further logic or to populate other fields.

Example: Setting a Reference Field and its Display Value

Let’s say you have a ‘Configuration Item’ (cmdb_ci) reference field and you want to set it based on a value retrieved from another field or a server call. You might also want to ensure the correct display name is shown.

function setConfigurationItem(ciSysId, ciDisplayName) {
    // Set the value (sys_id) for the 'cmdb_ci' field
    g_form.setValue('cmdb_ci', ciSysId);

    // Optionally, set the display value. This is often done automatically when setting the sys_id,
    // but explicit setting can be useful in complex scenarios or when you might not have the sys_id readily available.
    // For reference fields, the third parameter is the display value.
    g_form.setValue('cmdb_ci', ciSysId, ciDisplayName);
}

// Example usage (e.g., called from another script or event)
// Assuming you have the sys_id and display name from somewhere
// setConfigurationItem('a7e21b63db1234567890abcd12345678', 'My Server 01');
        

Important Note on setValue for Reference Fields: When setting a reference field using setValue(), the primary way is to pass the sys_id as the second argument. The third argument is for explicitly setting the display value, which is less commonly needed if the system can resolve it.

Server-Side Comparison: On the server-side, the current object is used. The equivalent of g_form.setValue() is current.field_name.setValue(value);. For reference fields, you’d set the sys_id.

// Server-side example
current.short_description.setValue("This is a critical incident.");
current.assigned_to.setValue("6816f79cc0a8016401c5a33be04be441"); // Setting sys_id for a reference field
        

Example: Setting a User Field by Name

Suppose you want to set the ‘Assigned To’ field to a specific user by their name. While setting by sys_id is generally preferred for accuracy, this method can be helpful.

// This is less common and might not always work reliably if names are not unique or have special characters.
// It's generally better to use sys_id if possible.
// g_form.setDisplayValue('assigned_to', 'Abel Tuter');
        

Real-world scenario: You might receive a user’s name from an external system and want to map it to a user record. setDisplayValue can attempt this mapping.

Caution: Using setDisplayValue for reference fields relies on the system’s ability to resolve the display value to a unique record. If multiple records share the same display value, the behavior can be unpredictable. Always prefer setting by sys_id when possible.

Example: Clearing a Field Based on a Choice

If a user selects “Other” in a choice list, you might want to make a corresponding “Other Specify” text field visible and clear its previous value.

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

    if (newValue === 'other') {
        g_form.setVisible('other_specify_field', true);
        g_form.clearValue('other_specify_field'); // Clear any previous entry
        g_form.setMandatory('other_specify_field', true);
    } else {
        g_form.setVisible('other_specify_field', false);
        g_form.clearValue('other_specify_field'); // Clear it when not visible
        g_form.setMandatory('other_specify_field', false);
    }
}
        

Example: Showing a Field Only for Specific Record Types

On an incident form, you might want to show a ‘SLA Due Date’ field only if the ‘Impact’ is ‘High’.

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

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

    if (impact === '1') { // Assuming '1' is the value for High Impact
        g_form.setVisible('u_sla_due_date', true);
    } else {
        g_form.setVisible('u_sla_due_date', false);
    }
}
        

Example: Making a Field Read-Only After Submission

Once an incident is resolved or closed, you might want to prevent users from changing certain fields like ‘Short Description’ or ‘Description’.

function onLoad(type) {
    var state = g_form.getValue('state'); // Assuming 'state' is the field for incident state

    // Common values for Resolved or Closed states
    var resolvedState = '6'; // Example sys_id or value for Resolved
    var closedState = '7'; // Example sys_id or value for Closed

    if (state === resolvedState || state === closedState) {
        g_form.setReadOnly('short_description', true);
        g_form.setReadOnly('description', true);
        // Make other fields read-only as needed
    }
}
        

Example: Making ‘Assignment Group’ Mandatory if ‘Assigned To’ is Empty

In a task-like table, if a user assigns the task to themselves, the ‘Assignment Group’ might become optional. If they leave ‘Assigned To’ blank, then ‘Assignment Group’ should be mandatory.

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

    var assignedToValue = g_form.getValue('assigned_to');

    if (assignedToValue === '') {
        g_form.setMandatory('assignment_group', true);
    } else {
        g_form.setMandatory('assignment_group', false);
    }
}
        

Example: Adding a Custom Priority Option Based on Category

If the ‘Category’ is ‘Network’, you might want to add a “Critical” priority option to the ‘Priority’ choice list.

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

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

    // Clear existing options related to custom priorities if needed, or handle carefully
    // This example assumes you want to ADD an option.
    if (category === 'network') {
        // Check if 'Critical' option already exists to avoid duplicates
        if (g_form.getOption('priority', 'critical')) {
            // Option already exists, do nothing or handle as needed
        } else {
            // Add the 'Critical' option with value 'critical' and label 'Critical - Network Issue'
            // Typically, values are numbers or short strings. Let's use a custom value.
            // You might need to ensure your backend field supports this custom value.
            g_form.addOption('priority', 'network_critical', 'Critical - Network Issue');
            g_form.setMandatory('priority', true); // Make priority mandatory if network is chosen
            g_form.setValue('priority', 'network_critical'); // Set it to the new option
        }
    } else {
        // If category is not network, you might want to remove the custom option or reset priority
        // Removing options can be tricky. Often easier to manage visibility/mandatory of default options.
        // For simplicity, let's just ensure it's not mandatory and set a default if applicable.
        g_form.setMandatory('priority', false); // Make it optional again if not network
        // If you need to remove it: g_form.removeOption('priority', 'network_critical');
        // Be cautious when removing options as it might affect other logic.
    }
}
        

Example: Removing ‘Not Applicable’ Option for Certain Situations

If a task is assigned to a specific user, you might remove the “Not Applicable” option from a “Reason for Delay” choice list.

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

    var assignedTo = g_form.getValue('assigned_to');

    if (assignedTo !== '') {
        // Remove 'Not Applicable' if assigned to someone
        g_form.removeOption('u_reason_for_delay', 'not_applicable'); // Assuming 'not_applicable' is the value
    } else {
        // Re-add it if needed, or ensure it's present if the assignment is cleared
        // Note: Re-adding is not directly supported by a simple addOption if it was removed.
        // Often, managing visibility/mandatory of choices is a better approach than removing.
        // If you must remove and re-add, you might need to refresh the choice list or use other methods.
        // A safer approach is often to manage visibility of the choice itself if possible, or use UI Policies.
    }
}
        

Troubleshooting Note: Removing and re-adding options can be complex. If you find issues, consider using UI Policies to control the visibility or mandatory status of default choices instead of manipulating the options themselves.

Example: Checking for an Existing Option Before Adding

As seen in the addOption example, it’s good practice to check if an option already exists to prevent duplicates.

if (g_form.getOption('priority', 'network_critical')) {
    gs.log("Custom priority already exists."); // This log would be server-side if used in a Business Rule. Client-side, use g_form.addInfoMessage or console.log.
    console.log("Custom priority already exists.");
} else {
    g_form.addOption('priority', 'network_critical', 'Critical - Network Issue');
}
        

Example: Setting Default Values on a New Incident

When a new incident is created, automatically set the ‘Caller’ to the currently logged-in user and set the ‘Impact’ and ‘Urgency’ to ‘Medium’ by default.

function onLoad(type) {
    // Set the caller to the current user
    g_form.setValue('caller_id', g_user.userID);

    // Set default impact and urgency
    g_form.setValue('impact', '2'); // Assuming '2' is the value for Medium Impact
    g_form.setValue('urgency', '2'); // Assuming '2' is the value for Medium Urgency

    // You might also want to set a default assignment group for certain categories
    var category = g_form.getValue('category');
    if (category === 'hardware') {
        // Set a default hardware assignment group (using sys_id)
        // g_form.setValue('assignment_group', 'sys_id_of_hardware_group');
    }

    // Example: Setting a default value for a field that is initially hidden
    // This is useful if you plan to reveal it later based on a condition.
    // g_form.setValue('u_internal_notes', 'Initial notes.');
}
        

Troubleshooting: If default values aren’t appearing, ensure your client script is correctly set to run onLoad and that it’s applied to the correct table and conditions. Also, check if other scripts (like Business Rules or UI Policies) might be overwriting these defaults.

Example: Setting ‘Company’ based on ‘User’

When a ‘User’ is selected, automatically populate the ‘Company’ field with the user’s company.

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

    var userID = g_form.getValue('caller_id'); // Assuming caller_id is the reference to sys_user

    if (userID) {
        // Use GlideAjax to efficiently get the user's company sys_id from the server
        var ga = new GlideAjax('com.glide.script.UserPreference'); // A common utility script, or create your own
        ga.addParam('sysparm_name', 'getUserInfo'); // A custom function in your script include
        ga.addParam('sysparm_user_id', userID);
        ga.getXMLAnswer(function(answer) {
            if (answer) {
                var userInfo = JSON.parse(answer);
                if (userInfo && userInfo.company) {
                    g_form.setValue('company', userInfo.company); // Set the company field
                } else {
                    g_form.clearValue('company'); // Clear company if user has no company
                }
            }
        });
    } else {
        g_form.clearValue('company');
    }
}
        

Note: The example above uses a placeholder for GlideAjax. In a real scenario, you’d create a Script Include that fetches the company sys_id from the sys_user record based on the provided userID.

Server-Side Equivalent for Reference fields:

// Server-side: setting the sys_id of a related user record
current.caller_id.setValue("a1b2c3d4e5f678901234567890abcdef");

// Server-side: setting the company based on caller_id
var userRecord = new GlideRecord('sys_user');
if (userRecord.get(current.caller_id)) {
    current.company.setValue(userRecord.company);
}
        

Example: Providing Feedback and Validation

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

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

    if (priorityValue === '1') { // Assuming '1' is Critical
        g_form.addInfoMessage("Critical priority selected. Please ensure all required fields are complete.");
        // Potentially make assignment group mandatory
        g_form.setMandatory('assignment_group', true);
    } else {
        g_form.addInfoMessage("Priority set to " + g_form.getDisplayBox('priority').value + ".");
        g_form.setMandatory('assignment_group', false);
    }

    // Example of validation that might prevent submission
    if (g_form.getValue('short_description').length < 5) {
        g_form.addErrorMessage("Short Description must be at least 5 characters long.");
        console.log("Short Description validation failed.");
        // The form might not submit if there are error messages and your script is designed to block it.
        // In some cases, you might need to return false from onSubmit scripts, but addErrorMessage is often sufficient for guidance.
    }
}