Help
Join the Community
-
Documentation
Find detailed info about ServiceNow products, apps, features, and releases.
-
Impact
Drive a faster ROI and amplify your expertise with ServiceNow Impact.
-
Partner
Grow your business with promotions, news, and marketing tools for partners.
-
Store
Download certified apps and integrations that complement ServiceNow.
on - edited on by
MGOPW
Event Mapping |
An event mapping in Next® Experience UI Builder is the process of mapping an event's payload or contextual values to the object or handler that acts on that event. There are four event types: 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 selected by a user. Another example could be adding a data resource such as a form, and having 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 Action bar or List components. The following event types are used in UI Builder.
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. But 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 available in UI Builder and some examples of how to use the events.
Component Events
A component event is an action you set up for a component. You set up an event handler to configure that component action. The following example shows the process of adding an event handler to apply an action for a button, such as going to a specific web page.
- Add a button component to your page.
- Select Events in configuration.
- Select Link to destination under Inherited event handlers. Inherited event handlers come from the parent page or pages that surround your current page.
- Select Select destination.
- Select External URL under Select destination.
Type the URL in the Chosen route > External URL field and click OK. The URL must be a fully qualified URL. For example: https://www...
- Save the page.
- Open your page and click the button on your page. You go to the web page that you specified in the URL.
Page Events
A page event 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 defined on the page
- Operations from local and inherited data resources
- Variant Event mappings.
- These event mappings are saved on the variant record, which can be found in the sys_ux_screen table.
- The source events for these event mappings are any dispatched events defined for your page.
- The available handlers for these event mappings are canvas-level events, UXR App Shell Data Source, and operations from inherited data resources.
- Variant event mappings are used as relays so that events dispatched from components on your page can be relayed up to user session event handlers.
- Mappings are created automatically on page save when you have mapped a component's dispatched event to a user session handler. For example, map 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.
- Dispatched events are saved in the sys_ux_event table. The page definition record contains references to the sys_ux_event record.
- Dispatched 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.
- Dispatched events are most frequently 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.
- Handled events are saved in the sys_ux_event table. The page definition record contains references to the sys_ux_event record.
- Handled 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.
Work with Data Resources |
Bind data to your page using data resources to dynamically expose your data from tables and records on your page. You then bind these data properties to components on your page. Data enables you to reuse your components in Next® Experience UI Builder.
What are data resources?
A data resource in UI Builder is the data that a page fetches to display content in components. Components use data resources as a way to reuse data and configurations across different experiences, and make the components dynamic on a page. You do not need to build a component from scratch for every page.
You can bind the configuration properties for components, other data resources, client scripts, client state, and events to these data resources.
How are data resources used?
Data resources fetch data from Glide, GraphQL, as well as REST API. Data resources then update the data it fetches and transforms it for use in a component on a page.
Both inherited data resource instances and local data resource instances are used in components. Inherited data resources are automatically brought in through your page. Use local data resource instances to add and configure additional data resources. You can specify when the resource gets evaluated, as well as supply input values so the data resource knows how to get the right data.
Local data resources
You choose local data resources to bring your own data to your page in UI Builder. These data resources can be server data, operations, transforms, or client data like the gForm API. Data resources are organized by the application that owns them. They are further organized by the data resource type like Server data or Transform. For example, there are several data resources in the Global application but only a few in the CSM Workspace application.
You see different data resources depending on the application you are in. If you choose the Global application, you see different data resources under Server data than if you choose CSM Configurable Workspace application and Server data. The following table shows the data resources available for the Global application.
Data Resource |
Definition |
| Server data |
The server data resources grab data from a server. They include the following:
|
| Operations |
The Operations data resources let you perform actions. They include the following:
|
| Transform |
The Transform data resources let you perform transforms. They include the following:
|
| Client data |
The Client data resources include the following:
|
What is data binding
Use data binding to bind properties to static components to make a dynamic page. When you first add a component to a page, it is static, meaning it does not perform any action. Add data resources to fetch data from the back end of your instance to connect a component to data. For example, a Content tree component doesn't show any data until you bind it to a data resource that pulls in content. You use field parameters to get data resource properties from the URL, like table name or sysID.
You can bind data to a component in the following ways.
- Context binding. Use required or optional URL parameters to bind context property fields in the URL. For example, like binding the table name from the URL into your component using @context syntax, such as @context.props.table.
For example, say that your page has a required field on it called table. The URL that resolves to your page would then be something like /demo/page/<table-name>. The <table-name> could be incident. Data could also come from the parent data resources, or be local page properties that don’t map to anything. You bind component properties, other data resource properties, or event payload properties to the page property with a @context.props.table context binding. If you are using a context binding, make sure that you have supplied a test value on the URL, or a static value for that property in the body configuration of your page.
- Data resource binding. Add data resources to fetch data from the back end of your instance, such as Client state, GraphQL, or a REST API. Data resources expose properties that you can bind to components and elements on a page.
For example, say that you have a Lookup Record data resource. In a button component, you could use a data expression in the label prop like @Data.lookup_record_1.result.number.displayValue.
- Component binding. Use component binding to bind one component to another. Say that you have a List Menucomponent on the page. It exposes the currently selected list to other components on the page. Other components could get the data by binding to it with an expression such as @elements.list_menu_1.selectedListId.
- Client state parameter binding. Use @STate syntax to bind a state property to a client state parameter.
Types of data sources available in UI Builder
You can use the following data resource types in UI Builder.
|
Data Resource Type |
Description |
| GraphQL | Executes GraphQL queries and mutations. |
| Transform | A script transforms input data into another format. |
| Client state | Client-side data resources. Includes client information, domain-specific state or logic, user preferences, and so on. |
| Composite | Compose multiple data resources into a single reusable data resource. |
| REST | Data resources made through REST API requests. |
Inherited versus local data resources
Inherited data resources come from the parent page or pages that surround your current page. For example, there may be data resources coming from the application shell of your UX application, or data resources from the page surrounding a tab set. Inherited data resources are available for you to use and expose to your page by binding to them in the body properties for your page and mapping them to local page (context) properties. You do not need to add your own data resource if the data you need is already being supplied through inheritance.
Local data resource instances are data resources that you add to the page. Think of local data resources as specific data resources you add yourself. You expose local data resources to a component on a page.
For example, if you are creating a travel request page, you can expose employee records to a list component. Employees can then create travel requests associated with their own employee data.
You can add a data resource from an application. Or, you can create a local data resource in ServiceNow platform Lists and Forms. You then use UI Builder to expose that data in UI Builder for components on your page.
Once the data is available to your page, bind the data to your component so the component can use the data. For example, you can create a data resource for a set of records. You then expose that set of records in UI Builder. Finally, you bind that set of records to a component. You then configure the component to perform an action on that data, such as save a new record.
Data resource properties
Data resource properties can be thought of as how the data resource fetches the data. The properties of a data resource get exposed when you add the data resource to UI Builder. The properties define everything about the data resource. For example, tables, conditions, how to order them, and so on.
Data resource scripts
When you add a data resource to your page, you see a preview of the outputs of that data resource if all the required properties have been configured. The output preview is a good way of seeing how the data gets retrieved so you can quickly determine if the data you need is present.
