Mobile client GlideForm (g form) scripting and migration

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Mobile client GlideForm (gform) scripting and migration

    This guide details the requirements and best practices for scripting on the ServiceNow mobile platform using GlideForm (gform). While mobile client scripting closely resembles web scripting, there are important differences and restrictions to ensure compatibility and performance on mobile devices. The document provides critical guidance for migrating existing scripts and developing new scripts tailored for mobile.

    Show full answer Show less

    Key Requirements for Mobile Client Scripts

    • Use new mobile-specific GlideForm methods: Replace all deprecated methods such as gform.getControl() with mobile-compatible methods designed for form field manipulation without direct HTML access.
    • Avoid deprecated methods: Methods like gform.getControl(), gform.getFormElement(), and gform.getElement() are not supported. Remove these from existing scripts and do not use them in new scripts.
    • Do not reference unsupported browser objects: Avoid using objects like window, document, and libraries such as jQuery or Prototype in mobile scripts. Instead, use GlideForm methods like setLabel(), addDecoration(), and hasField() for equivalent functionality.
    • Eliminate synchronous calls: The mobile platform disallows synchronous JavaScript, GlideAjax, and GlideRecord calls. Ensure all gform.getReference() calls include a callback function, and GlideAjax calls do not use getXMLWait(). Similarly, GlideRecord queries must be performed asynchronously with callbacks.
    • Avoid unsupported methods on mobile: Some methods (e.g., showRelatedList(), hideRelatedList(), flash(), enableAttachments()) are not available on mobile and will have no effect if called.
    • Enable scripts for mobile platform: Scripts must be explicitly enabled to run on mobile. Note that focusing elements programmatically is not supported on mobile forms.

    UI Policies, Navigator Modules, and UI Actions

    • UI Policies: Use the Run scripts in UI type field to specify whether the policy runs on mobile, desktop, or both. Update existing UI policies accordingly and ensure new policies are enabled for mobile or both platforms.
    • Navigator Modules: Existing modules must be migrated to the sysuiapplication or sysuimodule tables to be accessible on mobile. New modules should be created in these tables for mobile compatibility.
    • UI Actions: UI actions must reside in the sysuingaction table to appear on mobile. Scripts for UI actions do not require changes if they avoid deprecated methods. New UI actions for mobile must be created in this table.

    Practical Impact for ServiceNow Customers

    By following these guidelines, ServiceNow customers can ensure that their client-side scripts, UI policies, navigator modules, and UI actions function correctly and efficiently on mobile devices. This allows for a consistent user experience across web and mobile interfaces while respecting the technical limitations and optimized performance requirements of the mobile platform. Proper migration and development practices reduce errors, improve maintainability, and prepare scripts for future platform updates.

    Client scripting for mobile is identical to scripting for the web, with some exceptions. All new scripts must conform to certain guidelines. The following items are affected on the mobile platform: client scripts, UI policies, navigator modules, and UI actions.

    Client scripts

    For new or existing scripts to be valid for mobile, they must conform to the following requirements:
    • Use the new mobile methods in place of g_form.getControl().
    • Do not use deprecated methods.
    • Do not reference unsupported browser objects.
    • Do not make synchronous JavaScript, GlideAjax, and GlideRecord calls.
    • Do not call methods that are not available for mobile.
    • Enable scripts to run on the mobile UI.
    Table 1. Requirements
    Use the new mobile methods Several new methods are available for modifying form fields instead of directly manipulating the HTML. These methods replace previous usages of g_form.getControl(), which is deprecated for the mobile platform. In your existing scripts, ensure that the new methods are used in place of methods that are not valid on the mobile platform. For information on these new methods, refer to Mobile GlideForm() API.
    Do not use deprecated methods

    The following methods have been deprecated for the mobile platform because direct access to HTML elements is not allowed:

    • g_form.getControl()
    • g_form.getFormElement()
    • g_form.getElement()

    To ensure that existing scripts are compatible, remove all calls to deprecated methods from your code. For new scripts, do not use deprecated methods if you want the script to be valid for mobile.

    For g_form.getControl(), some of the functionality previously included with this method has been extracted to individual methods. Instead of g_form.getControl(), use the new methods described on the developer site.
    Do not reference unsupported browser objects

    The following browser objects are not supported in mobile scripts:

    • Window
    • jQuery or Prototype ($, $j, or $$)
    • Document

    Make sure that new scripts do not use these objects, and remove any usage of these objects from your existing scripts. Use GlideForm (g_form) instead, which provides methods such as setLabel(), addDecoration(), and hasField() for accomplishing the same tasks.
    Do not make synchronous JavaScript calls

    The mobile platform does not allow synchronous JavaScript calls. The g_form.getReference() method must now have the callback parameter defined. For example:

     g_form.getReference(fieldName, callback)

    Be sure that all g_form.getReference() calls include the callback parameter. For example, the following script does not include a callback and is incompatible with the mobile platform:

     var userName = g_form.getReference('assigned_to').user_name;
 g_form.setValue('u_assigned_user_name', userName);

    The following script has been updated to include the callback and is compatible with the mobile platform:

     g_form.getReference('assigned_to', function(now_GR) {
     g_form.setValue('u_assigned_user_name', gr.user_name);
 });
    Do not make synchronous Ajax calls The mobile platform does not allow synchronous GlideAjax calls. Any use of getXMLWait() in a GlideAjax call will not work on the mobile platform. Be sure that all GlideAjax calls are asynchronous. For more on synchronous versus asynchronous GlideAjax calls and getXMLWait(), see AJAX. For information on the available GlideAjax methods, refer to the GlideAjax API.
    Do not make synchronous GlideRecord calls

    The mobile platform does not allow synchronous GlideRecord calls. Make sure that any existing GlideRecord calls include a callback. For example, the following script does not include a callback and is incompatible with the mobile platform:

     var now_GR = new GlideRecord('incident');
 gr.addQuery('number', g_form.getValue('related_incident'));
 gr.query();
 gr.next();
 g_form.setValue('u_related_incident_description', gr.short_description);

    The following script has been updated to include the callback, and is compatible with the mobile platform:

     var now_GR = new GlideRecord('incident');
 gr.addQuery('number', g_form.getValue('related_incident'));
 gr.query(function(now_GR) {
     gr.next();
     g_form.setValue('u_related_incident_description', gr.short_description);
 });
    Do not use methods unavailable on the mobile platform
    Due to the limitations and reduced functionality that is imposed by the mobile platform, the following methods are not deprecated but are not available on the mobile platform. If these run on the mobile platform, no action occurs:
    • showRelatedList ()
    • hideRelatedList ()
    • showRelatedLists ()
    • hideRelatedLists()
    • flash()
    • getSections()
    • enableAttachments()
    • disableAttachments()
    • setReadonly() (Note that setReadOnly() is available)
    • getParameter()
    Enable scripts for mobile

    Scripts must be enabled for the mobile platform.
    Note:
    Focusing an element on a mobile form is not supported.

    UI policies

    Use the Run scripts in UI type field to determine whether scripts run on the mobile platform, the desktop, or both. Update existing policies so that they apply to either the mobile platform or both. For new scripts, also ensure that the mobile option or both is selected.

    Navigator modules

    For existing code, modules must be transferred to either the sys_ui_application or sys_ui_module tables to be available on the mobile platform. When developing new code, be sure that all modules are created in the sys_ui_application or sys_ui_module tables.

    UI actions

    UI actions must be transferred to the sys_ui_ng_action table to appear on the mobile platform. UI action scripts that do not use deprecated methods do not require changes to the script itself. For new UI actions, be sure that they are created in the sys_ui_ng_action table.