How To Call A Script Include From A UI Action
Introduction
A UI Action allows you to add buttons, links, and context menu items on forms and lists, making it possible to create custom on-click actions. The UI Action Condition is an optional field used to define specific criteria determining when the UI Action is visible to the user, via server-side Javascript code.
A Script Include is a reusable piece of JavaScript code that can be called from anywhere in the ServiceNow platform.
Rather than defining condition criteria in an individual UI Action, it's possible to instead define the condition criteria on a Script Include, then call it from a UI Action.
If you're looking for how to call a script include from a Business Rule instead, check out our guide here.
Real-world Use Case
Below are a few examples of why a developer may need to call a Script Include from a UI Action:
- Lengthy Conditions: The UI Action Condition field is limited to 255 characters and its length cannot be modified. In some cases, a Condition may require Javascript code exceeding this limit
- Advanced Conditions: The Developer may need to use additional Javascript statements that are not usable in the UI Action Condition field, such as var, if, and else.
- Commonly-used Conditions: If numerous UI Actions require the exact same conditions, then it may be beneficial to control these conditions on a single Script Include instead of writing the condition code on each individual UI Action.
1) Create the Script Include
Before a Script Include can be called by a UI Action it must first exist, of course! To create the Script Include, perform the following procedure:
- Navigate to System Definition > Script Includes in your filter navigator
- Click the New button
The following fields are available to populate:
- Name: this is the name of the Script Include
- API Name: this field is a combination of the Application Scope and the Name of the script include. It auto-populates when the Name field is filled. Take note of this value, as it is used to call the Script Include from the UI Action
- Script: this field used to define the Javascript code utlized by the Script Include. In order for this Script Include to callable by a UI Action, the following Javascript code format must be used:
var <ScriptIncName> = Class.create();
<ScriptIncName>.prototype = {
\\ ScriptIncName should match the Name field of the Script Include
initialize: function() {},
<FunctionName>: function() {
\\ FunctionName can be any value, but take note of whatever it is because the Function Name
will be referenced in the UI Action condition
\\ **Insert function Javascript code here!**
},
\\ Closes the function
type: '<ScriptIncName>'
\\ the type should also match the Name field of the Script Include
2) Create the UI Action
To create the UI Action, perform the following procedure:
- Navigate to System UI > UI Actions.
- Click the New button.
The following fields are available to populate:
- Name: this is the display name of the UI Action
- Table: this field is for selecting the table where UI Action should appear on
- Action Name: This is the unique identifier of the UI Action
- Button: checking this box allows the UI Action to appear as a form button
- Insert, Delete, Update, Query: checking these boxes enables what server-side operations this UI Action can be used with
- Client: checking this box enables the use client-side code in the Script field
- Script: Javascript code that is executed when the UI Action is clicked
- Condition: this field used to define the conditions in which the UI Action appears. In order for this UI Action to call the script include created earlier, the following Javascript code format must be used:
new <Script-Include-API-Name>.<Function-Name>();
// the "Script-Include-API-Name" should match the API Name field found on the Script Include
// the "FunctionName" should match the name of the name given to the function in the Script
Include's Script field
Example Scenario
In the following situation, the client wishes to restrict a UI Action button called "ButtonX" (associated with a custom "Tickets" table) to become visible only to ten specific custom user roles.
Under normal circumstances UI Action role restrictions can be handle by specifying roles in the Requires role tab. However, this particular ServiceNow instance has 508 Compliance settings enabled, preventing the use of the "Insert new row" function in the Requires roles tab, and thus forcing the developer to write-out role restriction code in the Condition field.
current.state=='new'||
current.state=='in progress'||current.state=='pending'
&& gs.hasRole('x_custom_application.basic_user,
x_custom_application.business_user,
x_custom_application.program_manager,
x_custom_application.funding_manager,
x_custom_application.project_lead');
Script Include settings
Application (Scope): x_custom_application
Name: scriptIncButtonX
API Name: x_custom_application.scriptIncButtonX
Script: see the code below...
var ButtonX = Class.create();
ButtonX.prototype = {
initialize: function() {},
hasRequiredRole: function() {
return gs.hasRole('x_custom_application.basic_user,
x_custom_application.business_user,
x_custom_application.program_manager,
x_custom_application.funding_manager,
x_custom_application.project_lead');
},
type: 'ButtonX'
};
UI Action settings
Application (Scope): x_custom_application
Name: ButtonX
Table: Tickets [custom_tickets]
Form button: true (checked)
Condition: see the code below...
new x_custom_application.scriptIncButtonX.hasRequiredRole();
Conclusion
Calling a Script Include from a UI Action can offer more flexibility and capability with the UI Action Condition. A Script Include allows a developer to bypass the 255 character limit of the Conditon field, use conditional Javascript statements such as IF or use variables, and control the code from a single source instead of writing the condition code on each individual UI Action.
Looking for something else? Check out our other posts below!
