Creating Interactions with UI Actions

An Introduction to scripting UI Actions

#UI Action , #Server Side Scripting , #Scripting

Ben Sweetser

8 minute read

We are experimenting with new training content delivery methods. This tutorial blog post is one of those experiments. We are very interested in your feedback. Please let us know what you think about this format and the content in the comments below.

Introduction

When I develop scripts to automate business logic, I try to automate how the logic triggers. If logic should run when a record is created or is set to a certain state, I use a Business Rule to automatically execute a script. Sometimes a user needs to initiate the work. UI Actions provide the interface elements for a user to take action from a form or list. Configure UI Actions as buttons or links to create interface elements with which users can interact.

Working with forms and lists, you have interacted with UI Actions.

UI Actions are buttons, Related Links, and context menu items.

In this post, you learn how to create your own UI Actions:

  • Creating UI Actions: How to create UI Actions for an application in Studio
  • Placing UI Actions: Where to put a UI Action and when to show a UI Action with conditions
  • Server or Client?: When to use server-side or client-side scripting in a UI Action
  • Redirecting After UI Actions: What page should open after UI Action logic executes

Each topic includes hands-on steps to practice creating a UI Action on a Personal Developer Instance. The hands-on steps build on concepts covered in the Scripting in ServiceNow training on the developer portal. To prepare your Personal Developer Instance with the NeedIt application, follow the steps in Exercise: Prepare Instance for Server-side Scripting.

In the hands-on steps, you create a UI Action that a user working on a NeedIt request can use to create an associated Incident record if the request is to restore service. The UI Action will only be visible for NeedIt requests with a Request type of Facilities.

NOTE: The exercises use demo data that may vary in your instance.

Creating UI Actions

In this section you create a UI Action for the NeedIt application used in training on the Developer Portal. You view the button on a form, but it does not yet do anything.

  1. Open the NeedIt application for editing in Studio if it is not already open.
    1. In the main ServiceNow browser window, use the Application Navigator to open System Applications > Studio.
    2. In the Load Application dialog, click the NeedIt application.
  2. Create the UI Action record.
    1. In Studio, click the Create Application File button.
    2. In the Filter… field, enter the text UI OR select Server Development from the categories in the left-hand pane.
    3. Select UI Action in the middle pane as the file type then click the Create button.
  3. Configure the UI Action.
    1. Name: Create Incident
    2. Table: NeedIt [x_58872_needit_needit]
    3. Show insert: deselected (unchecked)
    4. Form button: selected (checked)
  4. Click the Submit button.
  5. View the UI Action.
    1. In the main ServiceNow browser window (not Studio), use the Application Navigator to open NeedIt > Open.
    2. Click the Number for any NeedIt record.
    3. Find the Create Incident UI Action on the form.

      The Create Incident UI Action is a button at the top and bottom of the form.


Placing UI Actions

Great! Now you can create buttons for everything you want to let a user do, right??

The form with too many buttons.

Too many buttons can negatively impact the user experience. Fortunately, UI Actions can be configured in other places on a form or in the list. Developers need to determine which location makes the most sense for the action.

UI Action locations.

  • Form buttons are the most prominent and should be used sparingly. Use Form buttons for very common actions.
  • Form link puts the UI Action in the Related Links and is the next most visible location.
  • Form context menu is the most hidden of the form options and should be used when you do not need the actions directly visible on the form.

UI Actions can also be added to lists. See the UI actions documentation for more details about the list options.

Use the Order field on UI Actions to put the UI Actions in the order you want.

DEVELOPER TIP: To more easily order UI Actions, use the list of UI Actions for a table. From the form, open the Additional actions menu and select the Configure > UI Actions menu item. Edit the Order in the list to put UI Actions in the desired order.

Open the list of UI Actions and change the order in the list to more easily place UI Actions in the desired order.

Use the Condition field to set conditions on when the UI Action should be visible. The Create Incident UI Action should only be visible for Facilities requests. Set conditions that must evaluate to true for the UI Action to be visible.

  1. If not still open in Studio, use the Application Explorer to open Server Development > UI Actions > Create Incident
  2. Set the Condition value to current.u_request_type == ‘facilities’.
  3. Click the Update button.
  4. View the UI Action.
    1. In the main ServiceNow browser window (not Studio), use the Application Navigator to open NeedIt > Open.
    2. Click the Number for any NeedIt record.
    3. Review the Request type. If Request type is Facilities, the Create Incident UI Action should be visible. If Request type is not Facilities, the Create Incident UI Action should not be visible.
    4. Change the value of Request type and save the record to see the visibility of the Create Incident UI Action change.

Server or Client?

Though UI Actions are buttons, links, and context menu items in the user interface, UI Actions execute server-side code by default. This tutorial only covers server-side coding. The Client configuration option for a UI Action configures it to run client-side scripts instead.

In this section of the tutorial, you add the script to create an Incident record from the NeedIt record.

  1. If not still open in Studio, use the Application Explorer to open Server Development > UI Actions > Create Incident

  2. Copy the script and paste it into the Script field.

    
    createIncident();

    function createIncident() {
        // Create an Incident record 
        // Populate the Caller, Short description, and Description fields with details from the NeedIt record
        var grInc = new GlideRecord("incident");
        grInc.caller_id = current.u_requested_for;
        grInc.short_description = "Facilities work required for NeedIt " + current.number;
        grInc.description = "NeedIt request " + current.number + " requires some facilities work. " + current.short_description;
        grInc.insert();  // Add Incident to database

        // Add a Work note to the NeedIt record indicating an Incident was created
        // Include the Incident Number in the Work note
        current.work_notes = "Incident " + grInc.number + " created to address requirements";
        current.update();  // Update NeedIt record in database
    }

  3. Read through the script to be sure you understand what it does.

  4. Click the Update button.

  5. Execute the UI Action.

    1. In the main ServiceNow browser window (not Studio), use the Application Navigator to open NeedIt > Create New.
    2. Configure the NeedIt record.
      1. Requested for: Fred Luddy
      2. Request type: Facilities
      3. When needed: <select any date in the future>
      4. Short description: Projector needs a new lamp
    3. Open the Additional actions menu and select the Save menu item.
    4. Make note of the value of the Number field.
    5. Click the Create Incident button. After you click the Create Incident button, the complete NeedIt list opens.

  6. View the update to the NeedIt record and the new Incident record.

    1. Click the Number for the NeedIt record to open the record.

    2. A Work note in the Activies documents the Incident created. Make note of the INC number.

      A work note states Incident INC0010020 created to address requirements.

    3. Use the Application Navigator to open Incident > Open.

    4. Find the Incident record created by the UI Action and click the Number to open the record. What are the values of Caller Short description, and Description? These values should match the values set in the script.

Redirecting After UI Actions

The UI Action is working now, but after you click the Create Incident button, the user is redirected to the list or the page the user was on prior to the NeedIt record. The user then needs to navigate back to the NeedIt record or find the new Incident record.

Use the action.setRedirectURL() method to specify the page to open after the UI Action executes.

Use the action.setReturnURL() method to specify the page to open when the back button is pressed from the redirect page.

The action.setRedirectURL() and action.setReturnURL() methods require a GlideRecord or URL to open.

In the last bit of hands-on, you update the UI Action Script to open the new Incident record after execution. If the user presses the Back button on the Incident record, the NeedIt record opens.

  1. If not still open in Studio, use the Application Explorer to open Server Development > UI Actions > Create Incident

  2. Copy and paste these lines between the current.update(); line and the closing curly brace for the function.

    // Redirect to the Incident (grInc) after execution 
// and return to the NeedIt (current) record with the Incident's Back button 
action.setRedirectURL(grInc);
action.setReturnURL(current);

  3. Read through the script to be sure you understand what it does. How does the UI Action redirect to the Incident after execution?

  4. Click the Update button.

  5. Execute the UI Action.

    1. In the main ServiceNow browser window (not Studio), use the Application Navigator to open NeedIt > Create New.
    2. Configure the NeedIt record.
      1. Requested for: Beth Anglin
      2. Request type: Facilities
      3. When needed: <select any date in the future>
      4. Short description: Extension cord is frayed
    3. Open the Additional actions menu and select the Save menu item.
    4. Make note of the value of the Number field.

    5. Click the Create Incident button. After you click the Create Incident button, the Incident record opens.

      The back button for the Incident returns you to the NeedIt record.

    6. Click the Back button on the Incident form. The NeedIt record opens.

Did you do the hands-on exercise in this blog? Click here to let us know!

Closing Thoughts

UI Actions are interface elements with which users can interact with ServiceNow. Add UI Actions to an application to make your application more interactive, but be aware of the user experience as you configure when and where the UI Action is available. Use the action.setRedirectURL() method to redirect a user to the appropriate page after the UI Action executes.

This tutorial only covers a little of what you can do with UI Actions. Would you like to see more? Please let us know in the comments below.

Comments