Difficulty using custom events in UXA
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
an hour ago
I created a custom event using the snAnalytics API as recommended in the documentation, but I need to track clicks on UI actions and list actions. I understood that I could use this API, but it only works for the portal; I searched the documentation for custom events but didn't find information regarding this specific type of event.
I would like to understand how to create this event, given that the native "form action click" event is able to capture custom UI actions and some list actions.
All the actions I need to track are applied to the workspace, but none of them were created in UI Builder.
attempt used
try {
if (typeof snAnalytics !== 'undefined' && snAnalytics) {
var payload = {};
payload.name = "JEITTO CSM Click Tracking";
payload.data = {};
payload.data["Clicked Action"] = "Cancel Contract";
payload.data["Application"] = "CSM";
snAnalytics.addEvent(payload);
}
- Mark as New
- Bookmark
- Subscribe
- Mute
- Subscribe to RSS Feed
- Permalink
- Report Inappropriate Content
an hour ago
Hi @HEITORALEXANDRE ,
The main issue is that snAnalytics.addEvent() is not the best approach for this use case.
The SNAnalytics Client API example you are using is primarily documented for Service Portal/widget-based implementations. Your actions are running in a Configurable Workspace / Next Experience context, so snAnalytics may not be available in the same way.
Since your requirement is specifically to track clicks on existing UI Actions and List Actions, I would use the OOB Usage Insights instrumentation instead of adding tracking code to every action.
Recommended approach:
1. First check the existing OOB event
Since you mentioned that "form action click" already captures your custom actions, check the event properties in Usage Insights.
If the action name/label is available as an event property, you may not need a custom event at all.
You could use:
Form action click
+
Action = Cancel Contract
This is preferable because you keep the OOB instrumentation and avoid adding custom analytics code.
2. If you need a separate named event
On releases/Usage Insights versions that support Custom Event Instrumentation, open the Workspace and use the Usage Insights page overlay.
Go to the page containing the action and:
Usage Insights Overlay
-> Instrumentation
-> Start instrumentation
-> Select the UI Action/List Action
-> Add instrumentation
Create an event such as:
JEITTO CSM Click Tracking
Then configure properties that allow you to identify the action, for example:
Clicked Action = Cancel Contract
Application = CSM
This mechanism can instrument buttons, links, tabs, icons, and other clickable elements in Next Experience without requiring that the action was originally created in UI Builder.
So the fact that these actions were not created in UI Builder should not by itself prevent click instrumentation.
3. For Workspace actions, keep the action architecture OOB
If you need to customize the action behavior itself, use Declarative Actions.
For Configurable Workspace, ServiceNow supports:
Action Assignment
-> UX Add-on Event Mapping
-> Handled Event
-> UI Builder event handling
This is preferable to modifying OOB Workspace pages or injecting analytics JavaScript into UI Actions.
4. Important release consideration
The no-code custom event instrumentation capability is documented for the newer Usage Insights experience, including Australia.
If you are on Zurich or an earlier release, verify:
- ServiceNow release
- Installed Usage Insights Store application version
- Whether Custom Event Instrumentation is available in the page overlay
If the option is not available in your release/version, I would first use the existing OOB "form action click" event and its properties rather than creating a custom tracking framework.
I would therefore avoid this pattern for Workspace:
if (typeof snAnalytics !== 'undefined' && snAnalytics) {
snAnalytics.addEvent(payload);
}
unless you have verified that the API is supported and available in that specific Workspace execution context.
For your requirement, the preferred order would be:
OOB form/list action event
-> Filter by action property
If a dedicated event is required:
Usage Insights custom event instrumentation
Only if those options cannot meet the requirement:
Declarative Action / UX event architecture with supported analytics capability for your release.
ServiceNow Documentation:
Creating custom events in Usage Insights:
https://www.servicenow.com/docs/r/now-intelligence/usage-insights/tagged-events.html
Declarative Actions:
https://www.servicenow.com/docs/r/customer-service-management/migration-form-declarative-actions.htm...
Bind an event to a Declarative Action:
https://www.servicenow.com/docs/r/application-development/ui-builder/bind-event-declarative-action.h...
Community references with Accepted Solutions:
Custom events for User Experience Analytics:
https://www.servicenow.com/community/platform-analytics-forum/how-to-create-custom-events-for-user-e...
The accepted solution in this thread was provided by a ServiceNow employee and points to the supported analytics APIs.
Another accepted Community discussion covering custom User Experience Analytics events:
UI Builder custom component/event handling accepted solution:
So in your case, I would first inspect the properties of the existing "form action click" event. If it already identifies "Cancel Contract", use that. If you specifically need your own event name and your Usage Insights version supports instrumentation, use the page overlay rather than adding snAnalytics code to the Workspace action.
Hope this helps!
If this response helped, please mark it as Helpful.
If it resolves your issue, please Accept it as Solution.
Kind Regards,
Abhishek Pal
