UI actions are the buttons, context menu selections, links, and list selections that you find throughout ServiceNow. Because you can make UI actions appear in different areas of the platform, they can be incredibly handy to add your script to.

I tend to find that the form buttons are most used for UI actions. These can be added as helpful additional buttons to add functionality or ways to move records through different states of a process.

A UI action normally runs on the server side; however, we can run them on the client side, too, as we explored in the client-side chapters. By using the tick boxes, we can run UI actions on an insert when the record is created or on an update once the record already exists.

First, let's take a look at the different ways you can display a UI action to the user. By ticking the relevant checkboxes, a UI action you create can be displayed in one or multiple ways. Let's have a look at these options:

• Form button: This displays the the UI action as a button on the form, similar to the Update button
• Form context menu: Displays the UI action in the context menu, the menu that appears when you right-click the header bar of the form
• Form link: Displays the UI action as a link in the related links section, which appears between the form sections and related lists
• List banner button: Displays the UI action as a button at the top of a list view, next to the table label
• List bottom button: Shows the UI action at the bottom of a list as a button
• List context menu: Displays the UI action in the list context menu, accessed by right-clicking in a list of records
• List choice: The UI actions appear in the choices of actions on selected rows at the bottom of the list
• List link: Shows the UI action in the related links section at the bottom of a list

In a similar way to business rules, we also get a condition and script field for UI actions. However, the script field starts blank on a UI action, so the developer must provide all of the code.

We'll take a look at scripting a basic UI action. For our example, we'll build a form button to change an incident state to In progress. Let's take a look at the code we need:

//Moves the incident state to In progress
current.state = 2; //In progress
current.update();

action.setRedirectURL(current);

In the preceding code, we set the state to the value of 2, which corresponds to the In progress state for incidents. Once this value has been set, all we need to do is update the record using current.update.

The action.setRedirectURL line is used in UI actions to redirect to the current record once the server-side script has run. If no redirection code is used when a UI action is pressed on a form, it will move back to the previous screen, usually the list view the record was selected from.

In our script, this redirection line is saying that once the code has run, redirect the page to somewhere different; in our example, we use current as the current record. This then redirects back to the record we are on. This is helpful if we want to keep the user on the same record and show them the changes our UI action has made. In this case, the user should be able to see the state change.

We can see the UI action in Figure 5.2:

Here, we are only using our UI action as a form button, but we could also display it in other ways by using the tick boxes on the right. This UI action will appear on new and existing incident forms with the Show insert and Show update tick boxes checked.