Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 39 ยท Forms, Lists and UI Policies

UI Actions and Form Buttons

Add buttons, links and menu items with UI actions: form and list placements, conditions, client versus server scripts, onclick, current, action.setRedirectURL and good practice.

Buttons such as Resolve, Assign to me or Create Problem on a form are not hard-coded. Each one is a UI action: a record that says where to show an action, who may see it and what script to run. UI actions are the bridge between the forms you configured in this chapter and the scripting you will learn next.

What a UI action is

A UI action lives in the table sys_ui_action. Open System Definition > UI Actions and press New. Key fields:

Field Meaning
Name Text on the button or menu item
Table Where it applies (inherits to child tables)
Action name A stable identifier used in scripts
Order Left-to-right position of buttons
Condition A script expression deciding if it is shown
Show insert / Show update Whether it appears on new or existing records
Client If ticked, runs in the browser first
Onclick The client function to call, such as confirmIt()
Script The code to run
Roles Who sees it

Where it appears

Tick one or more placement checkboxes:

  • Form button: at the top of the form (the common choice).
  • Form context menu: in the header's right-click menu.
  • Form link: a link at the bottom of the form.
  • List banner button, List bottom button, List context menu, List choice, List link: placements on lists, where the action can work on one or many selected rows.
  • Form style / List action: for buttons that act on selections.

Pick placement with the audience in mind: frequent actions deserve a button, rare administrative ones belong in a context menu.

Server-side script

A UI action without Client runs on the server when pressed. The object current is the record, and action offers helper methods:

JavaScript
// "Assign to me" (read-only example)
current.assigned_to = gs.getUserID();
current.state = 2;                       // In Progress (choice value)
current.update();
gs.addInfoMessage('Assigned to you.');
action.setRedirectURL(current);          // reload the record

gs is the GlideSystem helper for messages, the current user and logging. current.update() saves, firing the same business rules as any other update. action.setRedirectURL(current) returns the user to the record instead of the list; passing nothing keeps default behavior.

Client-side and server-side together

When a UI action needs a confirmation or a prompt first, tick Client, set Onclick to a function name and write both parts in one script:

JavaScript
function confirmResolve() {
  if (!confirm('Resolve this incident?')) {
    return false;                         // stop; nothing is sent
  }
  gsftSubmit(null, g_form.getFormElement(), 'resolve_incident');  // run the server part
}

// Server part (runs only when the action name matches)
if (typeof window == 'undefined') {
  current.state = 6;
  current.update();
  action.setRedirectURL(current);
}

Here gsftSubmit re-submits the form with the UI action's Action name (resolve_incident), which is why that field must match. The typeof window == 'undefined' check ensures the server section runs only on the server.

Exact helper names and recommended patterns evolve between releases. Treat the snippets above as read-only illustrations of the structure, and check the current documentation when you build one.

Conditions

The Condition field is a short script expression returning true or false, evaluated on the server when the form loads. Examples:

  • current.state == 1 (only for New records)
  • gs.hasRole('itil') && current.canWrite()
  • !current.isNewRecord()

Keep conditions cheap and rely on Roles for permission. A hidden button is convenience, not security: also check permissions inside the script or with ACLs.

Python Which buttons does this user see? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Running a UI action simulation

The stand-in below mimics current, update() and a redirect so you can see how a server-side action changes a record.

Python A server-side UI action (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Good practice

  1. Search first: the out-of-the-box UI action you need may already exist. Copy rather than editing it so upgrades do not collide.
  2. Give an Action name that describes the purpose and do not reuse names.
  3. Use Roles and a cheap Condition, and re-check permissions in the script.
  4. Put reusable logic in a script include (later chapters) and call it, instead of long UI action scripts.
  5. Give feedback with gs.addInfoMessage or addErrorMessage so users know what happened.
  6. Keep the number of buttons small. Too many buttons confuse agents.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a UI action define?

    UI actions add buttons, links or menu items on forms and lists and run a script.
  2. 2. In a server-side UI action script, what is current?

    current is a GlideRecord of the record being edited or the selected record.
  3. 3. Is hiding a button with a role or condition enough to secure an action?

    A hidden button is convenience; a user could still reach the action another way, so enforce server-side.
  4. 4. Why copy an out-of-the-box UI action instead of editing it?

    Configuring a copy keeps the original intact so upgrades stay smoother.

Summary

  • A UI action is a button, menu item or link plus a script, stored in sys_ui_action.
  • Choose placements, roles and a cheap condition; use current and action on the server.
  • Add Client and Onclick when you need a browser-side confirmation.
  • Do not treat button visibility as security.

Next: Flow Designer: Low-Code Automation in ServiceNow