Create a UI action

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 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 Defines the text that appears on the button, link, or context menu item.
    Table Defines 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 Defines 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 Defines a name to use when referencing the UI action in scripts.
    Active Enables the UI action when selected. To disable a UI action, clear the check box.
    Show insert Shows a button on new records that have not been inserted.
    Show update Shows a button on existing records.
    Client The UI action executes its script in the user's browser, not on the server. When enabled, the Onclick field appears above the Condition field.
    List v2 Compatible Indicates that the UI action is compatible with v2 lists. This field must be enabled to display the UI action in a v2 list, but only if the List v3 Compatible field is enabled as well. If the List v3 Compatible field is not enabled, the UI action displays in v2 lists regardless of the List v2 Compatible field state.
    List v3 Compatible Indicates that the UI action is compatible with v3 lists. This field must be enabled to display the UI action in a v3 list.
    Form button Puts a button on a form.
    Form context menu Puts an item in a form context menu (right-click the form header).
    Form link Puts a link in the Related Links section of a form.
    List banner button Puts a button in the banner of a list.
    List bottom button Puts a button at the bottom of a list.
    List context menu Puts an item in a list field context menu (right-click a cell in a list).
    List choice Puts an item in the action choice list at the bottom of a list.
    List link Puts a link in the Related Links section at the bottom of a list.
    Overrides Specifies a UI action that this UI action overrides.
    Comments Provides descriptive content regarding this UI action.
    Hint Defines 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 Defines the conditions that restrict when a UI action appears. See Restricting UI actions based on conditions for examples.
    Script Defines the script to run when the UI action is executed.
    Related lists on the form view:
    UI Action Visibility Specifies other views of the form that the UI action applies to. Use this option to restrict the UI action to form views that you specify.
    Versions Shows 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 );

What to do next

Note: In UI11 only, you can control whether the UI action appears at the bottom of the form in addition to the top. Create the property propertyglide.ui.buttons_bottom and set it to true.

Restricting UI actions based on conditions

You can include scripts in the Condition field of the UI Action form. The condition must evaluate to true for the action to appear.

Using the UI action condition builder

If you leave the field empty, the condition defaults to true. For example, the following condition is configured for the Close Incident button:

Condition statement
For this action to appear on a form, these conditions must evaluate to true:
  • current.incident_state must equal 6: The incident must already be in a Resolved state.
  • gs.hasRole("itil_admin"): The current user must have the itil_admin role.
OR this condition must evaluate to true:
  • gs.GetUserID() == current.caller_id: The current user is the user who requested the change.
Note:
  • The current object is not available for conditions on a list context menu (the List context menu check box 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.

Restricting UI actions based on form views

You can restrict UI actions to appear only on specified form views.

Use the UI Action Visibility related list on the UI Action form to restrict a UI action by view. 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.
Example: Show an action everywhere except the Cost Management view
Add an exclude rule for the Cost management view.
Figure 1. Example exclusion UI action view
Example exclusion UI action view
Example: Show an action on the Routine and ITIL views, but nowhere else
Add include rules for the Routine and ITIL views.
Figure 2. Example inclusion UI action views
Example inclusion UI action views