---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Client-side script use cases

# Client-side script use cases {#ariaid-title1}

* Release version: Xanadu
* 
* Updated February 4, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 9 minutes to read

Use cases for client-side scripts include displaying field messages, changing form colors, adding fields, and creating UI routing actions.

## Add a field to the service catalog checkout {#ariaid-title2}

This is an example of adding a Company field to the checkout
below the Requested for field using non-cart layout macros, that is,
glide.sc.use_cart_layouts is
<kbd class="ph userinput">false</kbd>.

### Before you begin

Role required: Admin

### About this task

Figure 1. Requested for field ![Requested for dialog box with "System Administrator" in the field.]()

This field passes a provided value to the Company field of the Service Catalog Request.

This example makes the following assumptions:  
* The instance using two-step checkout. If two-step checkout is not enabled, enable it before beginning. For more information, see [Service Catalog checkout models](https://www.servicenow.com/docs/access?context=c_EnableATwoStepCheckout&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US).
* This example populates the Company field on the Service Catalog Request form. If the field does not appear on the form, configure the form before beginning. For instructions, see [Personalize a form](https://www.servicenow.com/docs/access?context=t_PersonalizeAForm&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US).

### Procedure

1. Go to System UI \> UI Macros and select servicecatalog_cart_template.
2. Find where there are hidden variables declared and add the following line:  

       <input type="HIDDEN" name="cart_id" id="cart_id" value="$[sc_cart.sys_id]" />

3. Find the following code, which generates the Requested For code:  

       <tr class="header">
       <td width = "30%">
         ${gs.getMessage('Requested for')}:
         </td>
         <td width="70%">
           <label for="requestor_location">${gs.getMessage('Deliver to')}:</label>
         </td>
       </tr>
       <tr><td>$[SP]</td> 
       </tr>
         <tr><td valign="top">
           <j2:if test="$[jvar_can_delta_rf == false]">
             $[sc_cart.requested_for.getDisplayValue()]
           </j2:if>
           <j2:if test="$[jvar_can_delta_rf != false]">
             <g2:catalog_requested_for />
           </j2:if>
         </td>
         <td>
           <textarea id="requestor_location" style="width:100%" rows="4"
             name="requestor_location" wrap="soft" onChange="catDeliveryAddress('$[sc_cart.sys_id]', 'requestor_location');"> 
             $[sc_cart.delivery_address]
           </textarea>
         </td>
       </tr>
       <tr>
         <td>$[SP]</td>
       </tr>

4. Add the following code afterward:  

       <tr class="header">
         <td colspan="2">Company</td>
       </tr>
       <tr>
         <td>$[SP]</td>
       </tr>
       <tr>
         <td colspan="2">
           <g2:ui_reference name="core_company" table="core_company" onchange="setCartValue()"/>
         </td>
       </tr>
       <tr>
         <td>$[SP]</td>
       </tr>

   Note:  
   The `'ui_reference'` macro defines a reference field. There are several macros for different field types. You can see examples of these field types under System UI -\> UI Macros. These macros start with `'ui_'`. For this example, the reference field created is named core_company. For more information, see [UI macros](https://servicenow-prod.fluidtopics.net/~qIUyqeIRdrSnlC1RcqGNQ#c_UIMacros "UI macros are discrete scripted components administrators can add to the user interface.").
5. Now navigate to System UI \> UI Pages and select the servicecatalog_checkout_one UI Page.
6. Add the followings script to the Client script field.  

       function setCartValue() { 
         var newField = gel('core_company'); 
         var myCart = gel('cart_id'); 
         var cart_item = new GlideRecord('sc_cart_item');
         cart_item.addQuery('cart', myCart.value);
         cart_item.query(); 
         if(cart_item.next()) {
           cart_item.hints = "<hints><entry key='sysparm_processing_hint' value='setfield:request.company=" + newField.value + "'/></hints>";
           cart_item.update(); 
         } 
       }

   For this example, the reference field was called core_company, and the field being populated on the request is company. If different fields are used:
   * Find this line: `var company = gel('core_company');` and replace core_company with the name of the field in the checkout.
   * In the line that starts with `'cart_item.hints'` replace `'request.company'` with the name of the field to be populated on the request ticket where `'request'` is the request being generated and `'company'` is the name of the field.
   {#t_AddFldSrvcCatCkout__ul_llx_2ln_kyb}

### Result

When an item is ordered, the company field appears on the Catalog form:

## Add autofill functionality {#ariaid-title3}

Add autofill functionality is also called incident template, auto assignments, quick
calls, call script, or auto populate.  
To auto-fill a Short Description field based on the Subcategory selected:

1. Create a lookup table.
2. Populate the key field, Subcategory.
3. Populate the auto-filled field, Short Description.
{#c_AddAutofillFunctionality__ol_tfw_52y_q2c}  

    function onChange(control, oldValue, newValue, isLoading) { 
      if (isLoading) { return; } 
      var newrec = gel('sys_row');
      //Check if new record
      if (newrec.value == -1) { 
        var lookup = new GlideRecord('u_short_desc_lookup'); 
        lookup.addQuery('u_subcategory', g_form.getValue('subcategory'));
        lookup.query();
        var temp; //temp var - reusable
        if (lookup.next()) {
          temp = lookup.u_short_description;
            if (null != temp) { //Set the form value from lookup if there is a lookup value
              g_form.setValue('short_description', temp); } 
            else {
              g_form.setValue('short_description', "" ); } } 
       else { 
         //If a lookup record does not exist based on lookup.addQuery 
         //Then set to UNDEFINED or NULL depending on type
          g_form.setValue('short_description', ""); } } 
    }

You can populate many fields or pull in call script questions into the Comments field so call center personnel gather good information to pass on to a technician.

Setting a field to password reset
:
    Lookup table has a record with the following key and auto-fill settings:

    * Subcategory = Password
    * Short Description = Password Reset
    {#c_AddAutofillFunctionality__ul_dv3_phy_q2c}
:
    Client script settings:

    * Type = onChange
    * Table name = incident
    * Field name = Subcategory
    {#c_AddAutofillFunctionality__ul_rwq_vfy_q2c}

:   When the user selects the subcategory of Password on the Incident form, a client script looks up the matching record and sets the short description equal to Password Reset.

## Change form color on state change {#ariaid-title4}

Changes color of a form field of the form on state change. The script can easily be
changed to adjust any property of any object on the page accessible via the HTML DOM.  
Warning:  
The customization described here was developed for use in specific instances, and is not supported by Now Support. This method is provided as-is and should be tested thoroughly before implementation. Post all questions and comments regarding this customization to our community [forum](http://community.service-now.com/).

Name: Change Form Color on State Change

Type: Client script

Description: Changes color of a form field of the form on state change. The
script can easily be changed to adjust any property of any object on the page accessible via the
HTML DOM.  
Script:

    function onChange(control, oldValue, newValue, isLoading) { 
      var elementID = gel("incident.priority");
        switch(newValue) { 
          case "1": elementID.style.backgroundColor = "red"; break; 
          case "2": elementID.style.backgroundColor = "tomato"; break;
          case "3": elementID.style.backgroundColor = "orange"; break;
          case "4": elementID.style.backgroundColor = "yellow"; break;
          case "5": elementID.style.backgroundColor = "green"; break; 
          default: elementID.style.backgroundColor = "white"; break; } }

## Create a UI routing action {#ariaid-title5}

This solution enables you to create a record with the service desk without knowing
whether it is an incident or request item; the service desk can then route the record to the
appropriate table.

### Before you begin

Role required: Admin

### Procedure

1. Create a new table that extends the `task` table (for example, New Call).
2. Create a module to create a new New Call record.
3. Create any fields that you want on the New Call table.  
   The only fields you need are those fields necessary to determine whether the
   new call should route to an Incident or a Request Item. Ensure that the form
   contains any fields that you want to pass to the Incident or Request Item.
   In this example, the following are created on the form:
   * Requested for (reference)
   * Location (reference)
   * Call type (choice with two values--Incident and Request)
   * Request Item (reference to the `sc_cat_item` Item table)
4. Add some UI policies to set a couple of fields to mandatory and hide the Request item field based on the Call type selection.
5. Remove unnecessary buttons and functionality from the form.
6. Create a new UI Action button.  
   This button redirects the user to either an incident or a request. It also creates the incident record and copies values to the incident and the Request Item form.  

       var reqItem = current.u_item;
       var requestedFor = current.u_requested_for;
       var location = current.location;

       if(current.u_incident_request == 'Incident'){
         //Create a new incident record and redirect to the new incident
         var rec = new GlideRecord('incident');
         rec.initialize();
         rec.caller_id = requestedFor;
         rec.location = location;
         rec.insert();
         action.setRedirectURL(rec);
       }

       if(current.u_incident_request == 'Request'){
         //Build the url and route the user to the request item
         var url = '';
         if(current.u_item.sys_class_name == 'sc_cat_item_guide'){
           url = 'com.glideapp.servicecatalog_cat_item_guide_view.do?sysparm_initial=true&sysparm_guide=' + 
             reqItem + '&sysparm_user=' + requestedFor + '&sysparm_location=' + location;
         }
         else{
           url = 'com.glideapp.servicecatalog_cat_item_view.do?sysparm_id=' + reqItem + '&sysparm_user=' +  
             requestedFor + '&sysparm_location=' + location;
         }
         action.setRedirectURL(url);
       }

7. The Route button in the preceding example passes the Requested for and Location values in the URL to the Request Item form.  
   Ensure that you have variables called <var class="keyword varname">requested_for</var> and <var class="keyword varname">location</var> on your item, record producer, or order guide that map these values using the following client script. There is a limit as to how much information you can pass, as the URL has a restricted length. Avoid sending information from long text fields using this method.  

       function onLoad() {
         var url = document.location.toString();
         var userKey = 'sysparm_user=';
         var locKey = 'sysparm_location=';
         var userPosition = url.indexOf(userKey);
         var locPosition = url.indexOf(locKey)
         if (userPosition != -1) {
           var user = url.substr(userPosition+userKey.length, 32);
           g_form.setValue('requested_for', user);
         }
         if (locPosition != -1) {
           var loc = url.substr(locPosition+locKey.length, 32);
           g_form.setValue('location', loc);
         }
       }

## Display field messages {#ariaid-title6}

Rather than use JavaScript alert(), for a cleaner look, you can display an error on the form itself.
The methods showFieldMsg() and hideFieldMsg() can be used to display a message just below the field itself.
showFieldMsg and hideFieldMsg are methods that can be
used with the <var class="keyword varname">g_form</var> object.

These methods are used to change the form view of records (Incident, Problem, and Change
forms). These methods may also be available in other client scripts, but must be tested to
determine whether they work as expected.

When a field message is displayed on a form on load, the form scrolls to ensure that the
field message is visible. Ensuring that users do not miss a field message because it was off
the screen.

The global property <var class="keyword varname">glide.ui.scroll_to_message_field</var> controls automatic
message scrolling when the form field is offscreen (scrolls the form to the control or
field).
{#r_DisplayFieldMessages__table_bgp_bwq_bp__entry__3}

| Method Detail | Parameters | Example |
|-|-|-|
| showFieldMsg(input, message, type, \[scrollform\]) | * input --- name of the field or control * message --- message you would like to appear * type --- 'info', 'error', or 'warning'; defaults to info if not supplied * scroll form --- (optional) Set scrollForm to false to prevent scrolling to the field message offscreen | Error Message g_form.showFieldMsg('impact','Low impact not allowed with High priority','error'); ![Low impact not allowed with high priority message.]() Informational Message g_form.showFieldMsg('impact', 'Low impact response time can be one week','info'); //or this defaults to info type //g_form.showFieldMsg('impact', 'Low impact response time can be one week'); ![Low impact response time can be one week message.]() |
| hideFieldMsg(input) | * input --- name of the field or control * clearAll --- (optional) boolean parameter indicating whether to clear all messages. If true, all messages for the field are cleared. If false or empty, only the first message is removed | Removing a Message //this will clear the first message printed to the field g_form.hideFieldMsg('impact'); |
[Table 1. Method Detail]

{#r_DisplayFieldMessages__table_bgp_bwq_bp}

### Legacy support

The showErrorBox() and hideErrorBox() methods are not recommended.

## Using client and server code in a UI action {#ariaid-title7}

You can use a script to validate input upon a UI Action click on the client side before updating the record on the server side. The user will not have to click the button twice to validate the required fields and update the
record.
The script calls the client function for client-side validation, and the UI action completes the task if it passes. The `code that runs without onclick` statement ensures that the server-side function does not run
until the client function is no longer running. If successful, the server-side function runs and updates the record.

    // Client-side onclick function
    function resolveIncident() {
      // Set the 'Incident state' and 'State' values to 'Resolved', and display mandatory fields
      g_form.setValue('incident_state', 6);
      g_form.setValue('state', 6);
      g_form.setValue('resolved_by', g_user.userID);

      // Call the UI action and skip the 'onclick' function
      gsftSubmit(null, g_form.getFormElement(), 'resolve_incident'); //MUST call the 'Action name' set in this UI Action
    }

    // Code that runs without 'onclick'
    // Ensure call to server-side function with no browser errors
    if (typeof window == 'undefined')
      serverResolve();

    // Server-side function
    function serverResolve() {
      current.incident_state = IncidentState.RESOLVED;
      current.state = IncidentState.RESOLVED;
      current.resolved_by = gs.getUserID();
      current.update();
    }

### gsftSubmit(String control, Object form, String action_name) {#using-client-server-code-ui-action__section_rkc_v3f_lwb}

Submits a form as if the user had clicked a UI Action after checking for required fields and executing onSubmit() client scripts. Enables calling client-side code and server-side code and in a single UI
action.
{#using-client-server-code-ui-action__table_lmr_qwr_fz__entry__3}

| Name | Type | Description |
|-|-|-|
| control | String | Name of a form button on which you want to simulate a user click. Use `null` otherwise. |
| form | Object | Optional. The form element that contains the submitted input. You can retrieve this value by calling the g_form.getFormElement() method. |
| action_name | String | Action name. This value is provided in the record listed in the UI Actions \[sys_ui_action\] table. For example, `'resolve_incident'` is the action name of the Resolve button in the Incident \[incident\] table. |
[Table 2. Parameters]

{#using-client-server-code-ui-action__table_lmr_qwr_fz}
**Related concepts**   

* [GlideUser - Client](https://servicenow-prod.fluidtopics.net/9J_5TcrSQapaeWEwrxQqaQ#c_GlideUserAPI "The GlideUser API provides methods that access information about the current user and current user roles. Using this API avoids the need to use the slower GlideRecord queries to get user information.")  
**Related reference**   

* [GlideForm - getFormElement()](https://servicenow-prod.fluidtopics.net/D~Jz7pWgGiVdAfIZ~ZFj8Q#r_GlideFormGetFormElement "Returns the HTML element for the form.")
* [Scoped GlideSystem - eventQueue(String name, Object instance, String parm1, String parm2, String queue)](https://servicenow-prod.fluidtopics.net/3Hp1FQjMKidd9ATK9vFJrA#r_ScopedGlideSystemEventQueue_String_Object_String_String_String "Queues an event for the event manager.")  
**Related topics**   

* [UI actions](https://www.servicenow.com/docs/access?context=c_UIActions&version=xanadu&pubname=xanadu-platform-administration&ft:locale=en-US)