Define map events

  • Release version: Yokohama
  • Updated January 30, 2025
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Define map events

    Event mapping in UI Builder enables ServiceNow customers to connect events triggered by components, pages, data resources, or declarative actions to the appropriate handlers that perform desired actions. This process is essential to making components responsive to user interactions, such as clicking a button or loading data, by defining how events propagate and are handled within a page.

    Show full answer Show less

    Event Types and Their Uses

    UI Builder supports four event types, each tailored to different scopes and purposes:

    • Component events: Trigger actions specific to individual components (e.g., a button click that navigates to a web page). Event handlers are configured directly on the component.
    • Page events: Apply actions at the entire page level. These include:
      • Page event mappings: Defined on the page record, triggered by events like Page ready or Page property changes. Handlers include user session events, page-level events, client scripts, and data resource operations.
      • Variant event mappings: Relay component-dispatched events to user session handlers, created automatically when mapping component events to session handlers.
      • Dispatched events: Custom events created and saved to facilitate relay mappings, allowing payloads to be modeled after existing events or manually defined.
      • Handled events: Events that serve as sources for page event mappings, created manually with customizable payloads.
    • Data resource events: Notify users or trigger actions related to data fetch status, including:
      • Data Fetch Initiated
      • Data Fetch Succeeded
      • Data Fetch Failed
    • Declarative action events: Bind data elements within UI Builder to declarative actions configured in the ServiceNow AI Platform. These enable event-driven automation linked to declarative action assignments.

    Practical Benefits for ServiceNow Customers

    • Enable interactive and dynamic pages by mapping user interactions and data changes to specific handlers.
    • Customize page behavior at both component and page levels, providing fine-grained control over user experience.
    • Leverage data resource event mapping to enhance user notifications and automate responses to data fetch operations.
    • Integrate declarative actions with UI Builder events to extend automation and AI-driven processes.
    • Utilize automatic variant event relay mappings to streamline event propagation across page components and user sessions.

    Next Steps

    To implement event mappings, customers should:

    • Identify the appropriate event type based on the scope (component, page, data resource, or declarative action).
    • Configure event handlers following UI Builder best practices, such as binding component events to handlers or setting up page event mappings.
    • Use the ServiceNow tables [sysuxmacroponent], [sysuxscreen], and [sysuxevent] to manage event definitions and mappings as needed.
    • Refer to UI Builder documentation for detailed guidance on binding events to components, pages, data resources, and declarative actions.

    An event mapping in UI Builder 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. The four event types are: component, page, data resource, and declarative action.

    Event mapping is an important process within UI Builder. When you build pages with components, you need those components to perform actions for users. For example, if you add a button component to the page, a button-clicked event must be mapped to an event handler. The event handler performs a button-clicked action when it is selected by a user. An example is when you add a data resource, such as a form, and have an event handler notify the user when the form successfully loads.

    Event types

    The event types that are available are based on the component. For example, declarative action events are available for specific components, such as the Action bar and List components.

    You choose a type of event based on what action you want to perform on your page. For example, if you want to bind an action to a component, such as a button loading a web page, you would use a component event. If you want an event to apply to your whole page, such as adding an alert notification to a page, you use a page event. The following table describes each event type that is available in UI Builder and provides some examples on how you can use the events.

    Table 1. Event types and descriptions
    Event type Description
    Component events Action that you set up for a component. You set up an event handler to configure that component action. For example, add an event handler to apply an action for a button, such as going to a web page. For more information on binding events to components, see Bind an event to a component.
    Page events Page event that performs an action for the entire page. You can configure the following page events:
    • Page event mappings.
      • These event mappings are saved on the page definition record, which can be found in the [sys_ux_macroponent] table.
      • The source events for these event mappings are Page ready and Page property. They are defined for your page.
      • The available handlers for these event mappings are:
        • User session events
        • Page-level events
        • UXR App Shell Data Source
        • Client scripts that are defined on the page
        • Operations from local and inherited data resources
    • Variant event mappings.
      • These event mappings are saved on the variant record, which you can find in the [sys_ux_screen] table.
      • The source events for these event mappings are any dispatched events that are defined for your page.
      • The available handlers for these event mappings are canvas-level events, the UXR App Shell Data Source, and operations from the inherited data resources.
      • Variant event mappings are used as relays so that the events that are dispatched from components on your page can be relayed up to user session event handlers.
      • Mappings are created automatically on a page save when you have mapped a component's dispatched event to a user session handler. For example, by mapping a Button clicked event to the canvas-level Link to destination event, the event creates a dispatched relay event and a variant event mapping when the page is saved.
    • Dispatched events.

      • These events are saved in the [sys_ux_event] table. The page definition record contains references to the [sys_ux_event] record.

      • These events serve as source events for variant event mappings.

      • You can select +Add to create new dispatched events for your page. Configure the event label to auto-populate the event name and payload fields for your new sys_ux_event.

      • These events are used to create relay event mappings. You can select a Target parent event handler to model the payload fields after the selected event. You can also manually create payload fields for your dispatched event.

    • Handled events.

      • These events are saved in the [sys_ux_event] table. The page definition record contains references to the [sys_ux_event] record.

      • These events serve as source events for page event mappings.

      • You can select +Add to create new dispatched events for your page. Handled events are not modeled after parent event handlers. Payload fields for handled events are created manually. To use an existing handler's payload fields as a template, select a template and edit the fields as necessary.

    Page-level events pane that shows the page, variant, dispatched, and handled events add options.

    For more information on binding an event to a page, see Bind an event to a page.
    Data resource events Events that are mapped to data resources to provide notifications about when data is fetched.
    • Data Fetch Initiated. When a data resource event is triggered, the event handler executes the data fetch process.
    • Data Fetch Succeeded. When a data resource event is triggered, the event handler executes the process to notify a user when the data fetch completed successfully.
    • Data Fetch Failed. When a data resource event is triggered, the event handler executes the process to notify a user if the data fetch was unsuccessful.

    Event options for a data resource.

    For more information on binding an event to a data resource, see Bind an event to a data resource.
    Declarative action events

    Bind data elements within UI Builder to add event actions to a declarative action.

    You configure a declarative action event mapping in the ServiceNow AI Platform® declarative action assignment table. For an example, navigate to Filter navigator > sys_declarative_action_assignment.list and then search for and open an existing declarative action.

    In UI Builder, you bind an event to the declarative action. For more information on how to use declarative action events, see Bind an event to a declarative action.