Actions in UI Builder

UI actions tell UI Builder what to do when an event is triggered. An event is an action a user takes or occurrence that happens on a page. Use UI actions to create interactive, user-friendly interfaces that help your users complete tasks. Each component has its own events associated with it. Events include:

Events in UI Builder

Use an event to add actions to your components, pages, and data resources.

• A component event is an action that you set up for a component. You set up an event handler to configure that component action. For example, you can add a button component to your UI Builder page. Then, you can add an event handler to apply an action for that button, such as going to a web page.
• Page events perform actions for the entire page. You can configure the following page events:
  • Page event mappings. Add, remove, or clear alert notifications on your page.
  • Variant event mappings. Add, remove, or clear alert notifications on your page variant.
  • Dispatched events. Create dispatched events for your page to create relayed event mappings that model events after a parent event handler. Select a target parent event handler to model the payload fields after it.
  • Handled events. A handled event is an event that is exposed and available for use by other users. After you create a handled event, it is available under Page event mappings for other users to use. You can also set up payload fields that you create manually or choose a template for your handled event, such as an open or close a modal dialog.
• Data resources events map data resources to notify information about when data is fetched.
• Events for a page or component do nothing until the event is mapped to one or more event handlers.

Event mapping in UI Builder

Map actions to events such as clicking a button or filling in a field. An event mapping is the process that enables you to map an event's payload or contextual values to the object or handler that acts on that event.

For more information about event mapping, see Define map events.

Event handlers in UI Builder

When you add an event handler to a UI Builder page or component, you can choose different types of event handlers. For example, a Button component can have the following types of event handlers:

• Inherited event handlers. An inherited event handler is exposed from the page that you are working in. If you are in the parent UI Builder page, an inherited event handler could be exposed from the app shell. The following table lists the different types of inherited event handlers that you can use and what you can do with them.

  Table 1. Inherited event handlers

  Event handler	Description
  Breadcrumb URL changed
  Link to destination	Navigate to a destination. App routes: Link to another page within an app, like a home screen. External URL: Link to a website or any external URL. Sample script return { route: null, /* Page route, e.g. 'record' */ fields: null, /* Required params, e.g. {"table":"incident","sysId":"X"} */ params: null, /* Optional params, e.g. {"selectedIndex" : 1} */ ☑️redirect: null, /* ??? True/false? */ ☑️passiveNavigation: null, /* Load in background, e.g. 'false' */ title: null, multiInstField: null, ☑️targetRoute: null, /* ??? */ ☑️external: null /* ??? True/false? */ };
  Add parameters to URL	Add additional parameters to a URL. Sample script { “selectedTabIndex” : 0 }
  Open or close modal dialog	After you create a modal, use Open or close modal dialog to trigger the modal.

• Page-level event handlers. This type of event handler is common to all pages, and you would use this handler type when you want to add or clear page-level alert notifications. The following table lists the different types of page-level event handlers that you can use and what you can do with them.

  Table 2. Page-level event handlers

  Event handler	Description
  Add alert notifications	Add a code snippet to send an alert notification. For example: return { items: [{"type" : "info", "message" : "Info message", "id" : "optionalID"}] /* Types: info, warning, error */ };
  Remove alert notification	Add code to call alert notification IDs that you want to dismiss. For example, click a button to remove a page load alert notification.
  Clear alert notification	Add code to call all alert notification IDs that you want to dismiss. For example, click a button to remove all alert notifications.
  Set loading state	Toggle loading on or off. For example, you can toggle loading on to load the page when you click a button or toggle loading off to not load the page when a button is clicked.
  Update client state parameter	Declaratively set the client state parameter. Let's say that you have a client state parameter that you set up with a value. You can configure the Update client state parameter event handler to update the client state parameter with a new value. For example, you have a client state parameter that is called Greeting that is set up with Hello as the initial value. You can add an Update client state parameter event handler, select the Greeting client state parameter, and then enter a new value like Goodbye. When you click the button, Goodbye replaces Hello on the page.
  UXF macroponent viewport load requested	Add to a component, such as a button component, to open a viewport. For more information, see Add a viewport component to your page.

• Data resource handlers. This type of event handler triggers the fetching or writing of data to the server.
  You can refresh the app shell data source data on your UI Builder page by clicking a button. For example, with a data resource handler, you can do the following actions:

  • Bind data to the description of an incident record.
  • Change the value of the incident description.
  • Add a button component to your page.
  • Label the button as Refresh incident.
  • Add a Look Up Record event handler for the button.
  • Save your page.
  • If the description of the incident record changes, click Refresh to update the description on your page.
• Client scripts. Scripts that execute when an event is triggered on a component. You create these scripts in the Client scripts section in UI Builder. For more information, see Define and bind client scripts to components.

Binding events to components in UI Builder

Bind event handlers to the events on a component. When you add components to your UI Builder page, these components are not configured to perform any action on your page. For example, a button component is static and does not do anything until you bind an event action to it, such as deleting a record. Some components have several events where event handlers can be assigned. For example, on the list component, you can assign a navigation handler to the Row clicked event. You can also assign an open modal to the Data fetch failed event. For more information, see Bind an event to a component.

Binding events to UI Builder pages

Bind a page-level event to execute event handlers on the page. For example, use page-level events for page notifications, page load, or when a page property changes. The assignment of the event handler to the page-level event is similar to assigning handlers to events from components.

Binding events to data resources in UI Builder

Bind event handlers to individual data resources on your UI Builder page. For example, when a data resource successfully fetches new data, it executes an event handler, like navigation, to take a user to the next step in a flow. When a data resource successfully adds a record to a table, it shows a success modal that uses the show modal event handler. For more information, see Bind an event to a data resource.

Binding events to declarative actions in UI Builder

Bind data elements to add event actions to a declarative action definition in Actions & Components in the ServiceNow AI Platform®. For example, you could bind a data element to add an event action to complete work on a table.

If you add a component to your UI Builder page that has a declarative action, you must bind it to a handled event. The handled event creates an action that is performed when a user selects the component. By selecting Configure declarative action event mapping, you add a new event handler to define what the declarative action does on the page.

For more information, see Bind an event to a declarative action.