ServiceNow Client Script Explained

What Is a Client Script?

A Client Script is a piece of JavaScript code that runs in the browser on the user’s machine while they interact with a ServiceNow form. Unlike server-side code that processes data on the platform, Client Scripts execute locally and affect the user interface in real time. They can show or hide fields, populate fields based on user input, validate data before submission, or change form behaviour dynamically.

Client Scripts improve user experience by providing immediate feedback. When a user selects a value from a dropdown, a Client Script can instantly populate related fields instead of requiring a page refresh. When validating a phone number, a Client Script can check the format immediately instead of waiting for server validation. This responsiveness makes forms faster and more intuitive to use.

Where Client Scripts Live in the Platform

Client Scripts are created from the System Definition menu, under Client Scripts. Each Client Script is associated with a specific table and type: onLoad (when the form opens), onChange (when a field value changes), onSubmit (before the form is saved), or onCellEdit (for list edits). The platform provides hooks into these form lifecycle points.

Client Scripts are managed like other platform configuration. They have names, descriptions and can be enabled or disabled. Multiple Client Scripts can run on the same form, and the platform controls their order of execution. Organisations typically maintain a library of common Client Scripts and reuse them across similar forms.

A Worked Example

Consider a form where a user selects a location from a dropdown. When the location changes, the user should see available departments for that location. A Client Script attached to the location field’s onChange event can query available departments and populate a dropdown immediately. Without the Client Script, the user would have to save the form and reload to see updated department options.

Another common example: when a user requests hardware, they must provide a cost centre. A Client Script can validate that the cost centre they entered exists, showing an error message immediately if it doesn’t. This immediate feedback prevents errors from being discovered only after form submission, which disrupts the user workflow.

Common Misunderstandings

One frequent mistake is over-relying on Client Scripts for validation. Client Scripts run on the user’s browser, which means a sophisticated attacker could modify them or bypass them entirely. Critical validation—especially for data security—must happen on the server. Client Scripts provide user experience benefits, not security.

Another misunderstanding involves performance. Client Scripts are code: if poorly written, they can make forms slow or unresponsive. Complex queries or loops in Client Scripts can freeze the browser. Good Client Scripts are simple and fast. If you need complex logic, move it to the server where you can cache data and optimise queries.

Related Concepts

UI Scripts are similar to Client Scripts but run globally rather than on specific forms. They provide utility functions that many forms might use. UI Policies are a visual alternative to Client Scripts: you can hide or show fields and make them mandatory without writing code. Business Rules are server-side equivalents that execute when data changes on the server.

Catalog Client Scripts are a variant used specifically in the Service Catalog, handling dynamism in request forms. Script Includes are reusable server-side code libraries. Understanding these different options helps you choose the right tool for each situation.

Performance Considerations

Client Scripts run every time a user interacts with a form, so performance matters. Long-running Client Scripts make forms feel sluggish and frustrate users. Best practice is to keep Client Scripts short and fast. If you need to query large amounts of data, consider pre-loading data or using client-side caching to avoid repeated queries.

Complex validations that require external lookups are often better placed on the server as Business Rules. The server can cache data more efficiently and the user doesn’t experience delays. Reserve Client Scripts for form behaviour that needs immediate feedback: showing or hiding fields, formatting input, or simple local validation.

Debugging and Troubleshooting

Client Scripts can be difficult to debug because they’re not always obvious why they’re not working. Browser developer tools help: you can inspect the DOM, watch variables and step through code. ServiceNow also provides debugging options in the form footer that show Client Script execution. Common issues include typos in field names, missing null checks on optional fields, or Client Scripts running in the wrong order.

Testing Client Scripts requires access to a test form and understanding the data flow. Many organisations maintain a test table with sample data for validating Client Scripts before deploying to production. This prevents surprises when new Client Scripts behave unexpectedly on real data.

Keeping form scripts out of the critical path

Client scripts shape how a form feels, and a form that stutters on every keystroke can drive users to the service desk faster than a missing feature. The first design question is therefore not what the script should do but how often it will run and how much work each run triggers. A script that fires on every change to a field and makes a server call each time will be felt by every user of that form. A script that reads values already on the page costs almost nothing. Choose the lightest event that meets the requirement, and reserve expensive lookups for the moments when the user has committed to a value.

The second question is what happens on a slow connection or when the lookup fails. A script that blocks the form until a lookup returns can freeze the page for users on poor networks. Decide in advance what the user sees while waiting and what the form does if the answer never arrives.

Choosing the event and the mechanism

Need	Better fit	Why
Show or hide a field based on a choice	UI policy	Declarative, and easier for others to review
Fill a field from a value already on the form	Client script on change	Runs locally with no server round trip
Check a value against a reference table	Server-side check, with a client script only for the message	The server holds the authoritative data
Confirm a form before save	Client script on submit, with a server rule behind it	The browser check improves the experience; the server enforces the rule

Some scripts exist only because the author did not know a UI policy could do the job. Before writing a script that shows, hides or requires a field, check whether the behavior can be declared instead. Declarative logic is easier to audit and less likely to break when the form layout changes.

A review checklist before a client script goes live

1. Confirm the event is the lightest one that does the job, and that the script does not run on every form load for no reason.
2. Check that every field the script reads is present on the form for every view and every role that uses it.
3. Guard against empty values in each read, so a missing choice does not throw an error that stops the rest of the script.
4. Remove any server call that could be replaced by a value already held on the form.
5. Test the form in each role and each view, including the mobile layout where the form is used there.
6. Record why the script exists, which requirement it serves, and who will maintain it after the author has moved on.

Symptoms that point to a client script problem

• The form pauses noticeably after a selection, and removing a single script restores the speed.
• A field changes value unexpectedly because two scripts set it in an order nobody intended.
• Validation appears to work in the browser, but a record created through an integration contains the invalid value, since the check never ran there.
• Users report that a dropdown resets after saving, often because a script on load and a script on change disagree about the default.

Use the browser’s developer tools to see which script ran and when. Adding temporary messages to the console at the start and end of each function shows the order quickly, and removing them afterwards keeps the production form clean.

When a client script is not the right answer

A client script cannot be trusted to enforce anything. Users can bypass it, integrations never run it, and it runs in the browser of whoever happens to open the form. Use it for experience and put the rule itself on the server. Also avoid building long chains of client scripts that reproduce a business process; that logic belongs in a flow or a server-side library where its order and its audit trail are visible.

How many client scripts is too many on one form?

There is no fixed number. The question is whether a new developer can tell which script runs at each event and why. When that becomes hard to answer, consolidate the logic or move part of it to the server.

Can a client script call a server script directly?

It can, through the asynchronous request mechanism. Keep those calls rare and small, and make sure the form still works when the response is slow or does not arrive.

Should catalog forms use the same approach?

Catalog forms have their own script type, but the same principles apply. Check each script against the request’s variables and keep the logic that determines fulfillment on the server side.

What is the safest way to change an existing script?

Copy the original to a test form, change the copy, and compare the behavior on realistic data. Only then replace the production version, and keep the previous text so the change can be reversed quickly.

Next step

If forms feel slow or behave differently for different users, a review of the scripts and the events they use can find the cause quickly. For the trade-offs, see the article on client scripts and UI policies, and for the declarative alternative, see the UI policy guide.

Client script fields, UI types and g_form method names to check on your instance

A ServiceNow client script is a browser-side script defined on one table. Its Type sets when it fires (onLoad, onChange, onSubmit or onCellEdit) and its UI Type sets which interface runs it. Form values are read and written through g_form, and details of the signed-in user come from g_user.

These are common out-of-box names. Labels, choice lists and defaults shift between releases, so check each one on your own instance and release before building on it.

Item	Common out-of-box value	What it controls
Type	onLoad, onChange, onSubmit, onCellEdit	When the script fires
UI Type	Desktop, Mobile / Service Portal, All	Which interface runs it
onChange arguments	control, oldValue, newValue, isLoading, isTemplate	What the platform passes in
g_form methods	getValue, setValue, setMandatory, setReadOnly, setDisplay, setVisible	Reading and changing the form
g_user	userID, userName, hasRole	Who is signed in

UI Type is an easy setting to miss. In a standard setup, a script set to Desktop does not run in Service Portal, and one set to Mobile / Service Portal does not run on the classic form. When a script works for the service desk but does nothing for requesters in the portal, look here first. A script that needs server data typically asks a script include for it.

An onChange script also runs while the form loads with its saved values, and isLoading is true on that pass, so most onChange scripts return early when isLoading is true or newValue is empty. An onSubmit script stops the save when it returns false.

Example (hypothetical): a team wants a custom asset tag field required only when the Category choice is hardware. They write an onChange script on the category field, set UI Type to All because requesters use the portal, and return early on isLoading. For hardware they call g_form.setMandatory on the asset tag field with true, otherwise with false. A server-side rule enforces the same requirement,. Slow forms often trace back to heavy scripts, which the platform performance guide covers.

Which UI Type should a new client script use?

Choose the interface the form is used in. Desktop suits classic forms, Mobile / Service Portal suits portal and mobile use, and All covers both. Pick All only after testing in each interface.

Why does my onChange script run when the form opens?

The platform fires onChange as saved values load, with isLoading set to true. To react only to a user’s edit, return at the top when isLoading is true.

When is a UI policy better than a client script?

Use a UI policy when the rule is a plain condition that shows, hides, requires or locks a field. It is declared rather than coded, so reviewers can read it. Write a script when the logic needs calculation or several steps.