You can create a new UI action or edit an existing one.

Before you begin

Role required: ui_action_admin or admin

About this task

You can add UI actions to tables and database views that are in the same scope as the UI action and tables that allow UI actions from another application scope to run on them.

Procedure

  1. Navigate to All > System Definition > UI Actions.
  2. Click New or open an existing record.
  3. Define the UI action by completing the fields.
    You may need to configure the form to see all the fields.
    Table 1. UI action fields
    Field Description
    Name The text that appears on the button, link, or context menu item.
    Table The table on which the UI action is available. By default, the UI action also appears on tables that extend the selected table (for example, Task actions appear on the Incident table).

    Select Global to make the action available on all tables.
    Order The order in which the UI action appears. The order applies to buttons from left to right and to menu actions from top to bottom.
    Action name A unique name to use when referencing the UI action in scripts.
    Active An option to enable the UI action when selected. To disable a UI action, clear the check box.
    Show insert An option to show a button on new records that have not been inserted.
    Show update An option to show a button on existing records.
    Client An option for the UI action to execute its script in the user's browser, not on the server. When enabled, the Onclick field appears above the Condition field.
    Form button An option to put a button on a form.
    Form context menu An option to put an item in a form context menu (right-click the form header).
    Form link An option to put a link in the Related Links section of a form.
    Form style
    • Primary—Colors the UI Action blue.
    • Destructive—Colors the UI Action red.
    • Unstyled—Does not color the UI Action.
    List banner button An option to put a button in the banner of a list.
    Note: List banner buttons are not intended to support record-specific conditions, so only the first row is considered when the condition is evaluated to determine whether the button will show for the list. Do not use record-specific conditions (e.g., current.getValue('state') === 'closed') in list banner button UI Actions.
    List bottom button An option to put a button at the bottom of a list.
    Note: List bottom buttons show regardless of condition and are evaluated per record on execution.
    List context menu An option to put an item in a list field context menu (right-click a cell in a list).
    List choice An option to put an item in the action choice list at the bottom of a list.
    Note: List bottom buttons, like list choice actions, show regardless of condition and are evaluated per record on execution.
    List link An option to put a link in the Related Links section at the bottom of a list.
    List style
    • Primary—Colors the UI Action blue.
    • Destructive—Colors the UI Action red.
    • Unstyled—Does not color the UI Action.
    Overrides A UI action that this UI action overrides.
    Messages Text strings that the UI action can use as a key to look up a localized message alternative from the Message [sys_ui_message] table. Each message key is on a separate line in the Messages field.

    The instance looks for a localized message string anytime the UI action makes a getMessage(msg) call where the msg string matches a key in the Messages field.
    Comments Descriptive content regarding this UI action.
    Hint The text that appears when a user points to the UI action control.
    Onclick The name of the JavaScript function to run when the UI action is executed. The function is defined in the Script field.
    Condition A JavaScript conditional statement that restricts when a UI action appears. Conditions always run on the server.
    Note:
    • The current object is not available for conditions on a list context menu. If the List context menu option is selected, any use of current on these actions is ignored.
    • You can reference the parent record for the UI action conditions on a related list button. For example, to disable the New and Edit buttons on the Affected CIs related list for closed changes, copy the global m2m UI actions to the task_ci table and add a condition of parent.active.
    • If you leave one of the fields empty that you specify in your condition statement, that condition defaults to true.
    Script The script to run when the UI action is executed. Function names must be unique.
    Workspace
    Workspace Form Button An option to make the UI action appear on the list of UI actions in a workspace.
    Workspace Form Menu An option to make the UI action appear as a list item in the menu associated with UI actions in a workspace.
    Format for Configurable Workspace An option to use the UI action in a Configurable Workspace. If cleared, the UI action applies in Legacy Workspaces.
    Workspace Client Script A script to run when the UI action is executed in workspaces.
    Requires role
    Role The roles required for the UI action to apply. Users must have at least one of the roles for the UI action to apply.
    Related lists on the form view
    UI Action Visibility The views of the form that the UI action applies to. Use this option to restrict the UI action to form views that you specify. A UI action is available for the specified view according to the following rules:
    1. If there are no visibility rules, the action appears on all views.
    2. Any exclude rule on a given view means that the action does not appear on that view.
    3. If there is at least one include rule, then the action appears only on views that are specifically included.
    Versions All versions of the UI action. Use this list to compare versions or to revert to a previous version.
  4. Click Submit or Update.
    Note: If the UI action is enabled to run on the client side, wrap it in a function. Otherwise, the contents of the Script field runs when the page loads.

Example

As part of a UI action script, you can redirect a user to a URL. For example, you might add links to a form or open a new record after it is created from a UI action. To redirect a user to a URL from a UI action, use this syntax in the Script field to define the redirect link:
action.setRedirectURL ( 'http://www.mysite.com/mypage.htm' );
To direct a user to a record, use this syntax, where new_record is the variable name for the GlideRecord:
action.setRedirectURL (new_record );