ClientScript

Creates a Client Script (sys_script_client) that runs JavaScript in the browser on form events (onLoad, onChange, onSubmit, onCellEdit) to dynamically configure forms, fields, and field values.

Signature

ClientScript(properties)

Parameters

properties

ClientScriptProps<keyof Tables, client_script_events, G>

Properties:

• $id (required): string | number | ExplicitKey<string>

• name (required): string Name of the client script

• order (optional): number The execution order of the client script (lower numbers execute first)

• table (required): keyof Tables Name of the table on which the client script runs

• $meta (optional): object

  • installMethod: 'first install' | 'demo' | 'once' Map a record to an output folder that loads only in specific circumstances. 'first install' - > 'unload', 'demo' -> 'unload.demo'

• active (optional): boolean Whether the record is enabled

• appliesExtended (optional): boolean Indicates whether the client script applies to tables extended from the specified table

• description (optional): string Description of the functionality and purpose of the client script

• field (optional): keyof Tables[T] | string Field on the table that the client script applies to. Takes effect only when type is set to onChange or onCellEdit; a warning is emitted at build time if set with other event types.

• global (optional): G Indicates which views of the table the client script runs.

  • true: the script runs on all views
  • false: the script runs only on specified views

• isolateScript (optional): boolean Indicates whether scripts run in strict mode, with access to direct DOM, jQuery, prototype, and the window object turned off

• messages (optional): string Strings that are available to the client script as localized messages using getmessage('[message]').

• protectionPolicy (optional): 'read' | 'protected' Controls edit/view access for other developers after the application is installed.

  • read: Others can see the script logic but not change it.
  • protected: Others cannot change this client script.
  • Omit to allow other developers to customize this client script.

• script (optional): string Script to be executed when the client script runs

• type (optional): client_script_events Type of client script, which defines when it runs

• uiType (optional): 'desktop' | 'all' | 'mobile_or_service_portal' User interface to which the client script applies

• view (optional): string Views of the table on which the client script runs. This property applies only when the global property is set to false

See

• https://docs.servicenow.com/csh?topicname=client-script-api-now-ts.html&version=latest

Examples

OnLoad Client Script with Inline Script

Create an onLoad client script with inline JavaScript code

/**
 * @title OnLoad Client Script with Inline Script
 * @description Create an onLoad client script with inline JavaScript code
 */
import { ClientScript } from '@servicenow/sdk/core'
ClientScript({
    $id: Now.ID['cs0'],
    name: 'my_client_script',
    table: 'incident',
    appliesExtended: false,
    global: true,
    uiType: 'all',
    description: 'Custom client script generated by Now SDK',
    messages: '',
    isolateScript: false,
    type: 'onLoad',
    script: `function onLoad() {
        g_form.addInfoMessage("Table loaded successfully!!")
    }`,
})

OnChange Client Script

Create a client script that triggers when a field value changes

/**
 * @title OnChange Client Script
 * @description Create a client script that triggers when a field value changes
 */
import { ClientScript } from '@servicenow/sdk/core'
ClientScript({
    $id: Now.ID['onchange_script'],
    name: 'field_change_handler',
    table: 'incident',
    type: 'onChange',
    field: 'priority',
    uiType: 'desktop',
    description: 'Handles priority field changes',
    script: `function onChange(control, oldValue, newValue, isLoading) {
        if (isLoading) return;
        if (newValue === '1') {
            g_form.addWarningMessage('High priority incident - please add urgency details');
        }
    }`,
})

OnLoad Client Script with External File

Create an onLoad client script that uses an external JavaScript file

/**
 * @title OnLoad Client Script with External File
 * @description Create an onLoad client script that uses an external JavaScript file
 */
import { ClientScript } from '@servicenow/sdk/core'

export default ClientScript({
    $id: Now.ID['sample1'],
    type: 'onLoad',
    uiType: 'all',
    table: 'incident',
    global: true,
    name: 'sample_client_script',
    appliesExtended: false,
    description: 'sample client script',
    isolateScript: false,
    script: Now.include('../../server/ClientScript/clientscript-onload.client.js'),
})

clientscript-onload.client.js

function onLoad() {
    g_form.addInfoMessage('Hello from Fluent Client Script')
}

For guidance on client script types, form events, and common patterns, see the client-script-guide topic.