Client scripts

  • 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 Client scripts

    Client scripts in ServiceNow enable JavaScript execution within the web browser in response to client-side events such as form loading, field value changes, and form submission. They are designed to enhance the user experience by dynamically configuring forms and fields during user interaction, but they are not intended to secure data access. Data protection should be managed with Access Control Lists (ACLs) or data policies.

    Show full answer Show less

    Key Features

    • Form and field manipulation: Show/hide fields, make fields read-only or writable, and set fields as mandatory or optional based on user roles.
    • Field value automation: Automatically set or modify field values and choice list options according to other field values or user roles.
    • Message display: Show messages to users based on field values.
    • Multiple script types:
      • onLoad(): Runs when the form loads, typically to set default values or modify the form UI.
      • onSubmit(): Runs on form submission to validate data and can cancel submission if needed.
      • onChange(): Runs when a specific field value changes, enabling dynamic form behavior.
      • onCellEdit(): Runs when list editor cells are edited, allowing validation and control of list data changes.

    Important Considerations

    • Client scripts primarily apply to forms and search pages; they do not control list editing except through onCellEdit() scripts or other server-side controls such as ACLs, business rules, or data policies.
    • Client scripts are not supported in ServiceNow mobile applications.
    • For security, sensitive fields must be controlled through ACLs or data policies, not client scripts.
    • New client scripts run in strict mode with restricted DOM and global object access; this isolation can be optionally disabled per script or globally via system properties.

    Practical Use for ServiceNow Customers

    ServiceNow customers can use client scripts to create responsive, user-friendly forms that adapt dynamically to user input and roles, helping to streamline workflows and improve data quality at the point of entry. Understanding the types of client scripts and their parameters enables precise control over form behavior. Customers should complement client scripts with ACLs and data policies to secure data properly.

    The client script form contains configurable fields such as script name, target table, UI type, script type, field name (for onChange/onCellEdit), application scope, active status, inheritance, and view scope. Descriptions and localized messages can be added to aid maintenance and clarity.

    Client scripts allow the system to run JavaScript on the client (web browser) when client-based events occur, such as when a form loads, after form submission, or when a field changes value.

    Use client scripts to configure forms, form fields, and field values while the user is using the form. Client scripts can:

    • make fields hidden or visible
    • make fields read only or writable
    • make fields optional or mandatory based on the user's role
    • set the value in one field based on the value in other fields
    • modify the options in a choice list based on a user's role
    • display messages based on a value in a field
    Warning:

    Client scripts are intended to optimize the user experience on a form. Client scripts are not meant to protect unwanted access to data.

    To prevent unwanted access to data, ensure that sensitive fields are hidden or read-only through ACLs or data policies.

    For more information, see Access Control List Rules or Data policy.

    Where client scripts run

    With the exception of onCellEdit() client scripts, client scripts only apply to forms and search pages. If you create a client script to control field values on a form, you must use one of these other methods to control field values when on a list.
    • Create an access control to restrict who can edit field values.
    • Create a business rule to validate content.
    • Create a data policy to validate content.
    • Create an onCellEdit() client script to validate content.
    • Disable list editing for the table.
    Note:
    Client scripts are not supported on ServiceNow mobile applications.

    Client script form

    Field Description
    Name Name of the client script.
    Table Table to which the client script applies.
    UI Type Target user interface to which the client script applies.
    Type

    onLoad() — runs when the system first renders the form and before users can enter data. Typically, onLoad() client scripts perform client-side-manipulation of the current form or set default record values.

    onSubmit() — runs when a form is submitted. Typically, onSubmit() scripts validate things on the form and ensure that the submission makes sense. An onSubmit() client script can cancel form submission by returning a value of false.

    onChange() — runs when a particular field value changes on the form. The onChange() client script must specify these parameters.
    • control: the DHTML widget whose value changed.
      Note:
      control is not accessible in mobile and service portal.
    • oldValue: the value the widget had when the record was loaded.
      Note:
      Old values aren't returned for the HTML field type.
    • newValue: the value the widget has after the change.
    • isLoading: identifies whether the change occurs as part of a form load.
    • isTemplate: identifies whether the change occurs as part of a template load.
    onCellEdit() — runs when the list editor changes a cell value. The onCellEdit() client script must specify these parameters.
    • sysIDs: an array of the sys_ids for all items being edited.
    • table: the table of the items being edited.
    • oldValues: the old values of the cells being edited.
    • newValue: the new value for the cells being edited.
    • callback: a callback that continues the execution of any other related cell edit scripts. If true is passed as a parameter, the other scripts are executed or the change is committed if there are no more scripts. If false is passed as a parameter, any further scripts are not executed and the change is not committed.
    Field Name Name of the field to which the script applies. Available only if the script responds to a field value change (onChange or onCellEdit script types).
    Application Application where this client script resides.
    Active Enables the client script when selected. Unselect this field to disable the client script.
    Inherited Indicates whether the client script applies to extended tables.
    Global If true, the client script runs on all views of the table.
    View Only visible when Global is unselected. Views on which the client script will run.
    Description Content describing the functionality and purpose of the client script.
    Messages Text string (one per line) available to the client script as localized messages using getmessage('[message]'). For additional information, see Translate a client script message.
    Script Contains the client script.
    Isolate script New client scripts are run in strict mode, with direct DOM access disabled. Access to jQuery, prototype, and the window object are also disabled. To disable this on a per-script basis, configure this form and select the Isolate script check box. To disable this feature for all new globally-scoped client-side scripts set the system property glide.script.block.client.globals to false.