Manage actions in UI Builder pages

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 16분

    • Learn how to work with events so that you can add actions to components, pages, data resources, and declarative actions in UI Builder.

    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:

    • User clicks a data visualization
    • Page successfully fetches data
    • User selects a radio button
    • Page loads

    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

    An event handler is an action performed when an event occurs. By mapping an event handler to an event, you are specifying which action or actions to take when the event occurs. Use an event handler to configure an action for your UI Builder page or the components on the page. For example:
    • Clicking a data visualization opens a list of records represented in the visualization
    • Fetching data successfully for a list opens an alert that indicates the data fetch was successful
    • Selecting a radio button adjusts the filter for a list on the page
    • Loading a page opens a modal to confirm acceptance of cookies before proceeding

    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.
      표 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.
      표 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.

    You can bind event mappings using the following methods:
    • 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. Add a handled event for an event that is exposed and available for use by other users.
    For more information, see Bind an event to a page.

    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.

    Configure the declarative action event mappings option in the Configure panel.

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