1. Introduction to UI Actions
In ServiceNow, a UI Action is used to add buttons, links, or context menu options to a form or list. These actions help users perform tasks quickly without manually updating multiple fields.
For example, on an Incident form, we can create UI Actions to:
- Mark an incident as resolved.
- Display a confirmation message.
- Assign an incident to a specific group.
- Close an incident after validating its information.
UI Actions can execute client-side JavaScript, server-side JavaScript, or a combination of both.
2. Where Can We Use UI Actions?
A UI Action can appear in different places depending on its configuration.
- Form button: Displays a button on the form, such as Resolve.
- Form link: Displays a link on the form.
- Form context menu: Adds an option to the form’s context menu.
- List banner button: Displays a button above a list.
- List choice: Adds an option to a list context menu.
- List context menu: Adds an option to a list’s context menu.
These options are controlled by the UI Action record’s form and list configuration fields.
3. What Is a Client-Side UI Action?
A client-side UI Action runs JavaScript in the user’s browser. It is useful when you want to interact with the current form, validate information, display messages, or ask for confirmation before submitting a record.
Example: Show a Confirmation Message
Requirement: When a user clicks a custom button on an Incident form, display a confirmation message before continuing.
Step 1: Create a UI Action
Navigate to System Definition → UI Actions and create a new record.
Configure the following fields:
| Field | Value |
| Name | Confirm Incident |
| Table | Incident |
| Action name | confirm_incident |
| Client | Checked |
| Form button | Checked |
| Form link | Unchecked |
| List banner button | Unchecked |
Step 2: Add the Client Script
Enter the following code in the Script field:

Step 3: Test It
- Open an Incident record.
- Find the Confirm Incident button.
- Click it.
- A confirmation dialog appears.
- Click OK to display the information message, or Cancel to dismiss the dialog.
This example only demonstrates client-side interaction; it does not save or update the incident.
Important: When using return false, the UI Action stops its default submission behavior. If you want to submit the form after validation, you need to explicitly implement the appropriate submission logic.
4. What Is a Server-Side UI Action?
A server-side UI Action runs JavaScript on the ServiceNow server. It is useful for updating records, changing field values, performing database operations, and applying business logic.
Example: Set an Incident to In Progress
Requirement: When a user clicks a custom button, the incident state changes to In Progress and the record is saved.
Step 1: Create a UI Action
Navigate to System Definition → UI Actions and create a new record.
Configure the fields:
| Field | Value |
| Name | Mark In Progress |
| Table | Incident |
| Action name | mark_in_progress |
| Client | Unchecked |
| Form button | Checked |
| Form link | Unchecked |
| Active | Checked |
Step 2: Add the Server Script

Step 3: Test It
- Open an Incident record.
- Click Mark In Progress.
- The server updates the incident state and adds a work note.
- The record is saved, and the user is redirected to the incident.
Note: The numeric value 2 represents In Progress in the standard Incident state choices in many ServiceNow configurations. Verify the choice value in your instance, as state configurations can differ.
5. What Is a Client-Side and Server-Side UI Action?
Sometimes, you need both client-side validation and server-side processing in the same UI Action.
For example, before resolving an incident, you may want to check that the user has entered a resolution note. Once the validation succeeds, the server can update the record.
Example: Resolve an Incident After Validation
Requirement: When the user clicks Resolve, check that the Resolution notes field is not empty. If it contains a value, submit the form to the server to resolve the incident.
Step 1: Create the UI Action
Configure the following fields:
| Field | Value |
| Name | Resolve Incident |
| Table | Incident |
| Action name | resolve_incident |
| Client | Checked |
| Form button | Checked |
| Onclick | resolveIncident() |
| Active | Checked |
Step 2: Add the Script

Step 3: Test It
- Open an Incident that is not resolved.
- Click Resolve Incident without entering Resolution notes.
- The form displays an error message and does not submit.
- Enter Resolution notes.
- Click Resolve Incident again.
- The server-side portion runs, updates the state, saves the record, and redirects to it.
Important implementation details:
- gsftSubmit() submits the form to invoke the server-side part of the UI Action.
- The action name passed to gsftSubmit() must match the UI Action’s Action name field.
- The server-side code is distinguished from the client-side code using typeof window == ‘undefined’.
- In standard Incident configurations, state 6 commonly means Resolved. Verify the value in your instance.
- This example assumes the user has permission to update the incident and that no other required resolution fields are missing.
6. Difference Between Client-Side and Server-Side UI Actions
| Feature | Client-side | Server-side |
| Executes on | User’s browser | ServiceNow server |
| Common purpose | Validation and form interaction | Database updates and server logic |
| Can use g_form | Yes | No, not directly |
| Can use current | No, not as a server record object | Yes |
| Can use action.setRedirectURL() | No | Yes |
| Example | Check resolution notes | Update incident state |
7. Important UI Action Fields
- Name: The label displayed to the user.
- Action name: The unique identifier used to invoke the action.
- Client: Enables client-side scripting.
- Onclick: Specifies the client function to execute when the action is clicked.
- Form button: Displays the action as a form button.
- Form link: Displays the action as a form link.
- Condition: Controls when the UI Action is available.
- Active: Determines whether the UI Action is enabled.
- Roles: Restricts which roles can use the UI Action.
8. Best Practices
- Use client-side scripts for user interaction and immediate validation.
- Use server-side scripts for database updates and business logic.
- Do not rely only on client-side validation for important security or data-integrity rules.
- Configure conditions and roles to control when users can execute an action.
- Avoid unnecessary current.update() calls and ensure the action cannot cause unwanted repeated updates.
- Test the action with users who have different roles and permissions.
9. Conclusion
UI Actions make ServiceNow forms more interactive and efficient. Client-side UI Actions are useful for validation and user interaction, server-side UI Actions handle record processing, and combined UI Actions support workflows that require both.
Start by creating a simple client-side button, then create a server-side button that updates an incident. After understanding both, practice combining them to validate the form before submitting it to the server.
