
- Post History
- Subscribe to RSS Feed
- Mark as New
- Mark as Read
- Bookmark
- Subscribe
- Printer Friendly Page
- Report Inappropriate Content
10-14-2022 03:28 PM - edited 01-16-2024 01:52 PM
AMB Record Watcher Data Resource
Hello! There is a new, but not necessarily easy to find, feature in Tokyo that allows you to easily monitor a table and react to events in your UI Builder (UIB) application when a record changes in that table.
This is called an AMB Record Watcher, and is a websocket feature that supports the handy little green checkboxes you see on fields on a record form when someone else is editing it. Prior to Tokyo it was quite a bit of work to setup but thanks to a new Data Resource called Record Watcher it's pretty simple now!
When to use it
You want to use a Record Watcher whenever you need your UIB page to react to a record change in the database. E.g. if a record is inserted or a value changes you may need to respond or flag the change to the user.
How to use it
1. In the UIB add a new Data Resource to the page and find Record Watcher > Record Watcher.
2. This gives you a configurable data resource. Open the config for the data resource using the little database icon in the bottom left of the UIB and specify the table which you want to watch.
3. You will need to next specify a filter. For instance, if you wish to monitor a table and be notified whenever a record changes to state = "Ready" you specify that using "Edit filter conditions".
4. Turn on "Subscribe" to have it automatically start watching when the page loads.
5. Go the Scripts and create a new script to handle messages from the Record Watcher. For now just add the code "console.log(event);" to the script so that you may inspect the output and figure out what data is returned that you may wish to use.
6. Return to the Record Watcher data resource and under the "Events" tab add your script as an event handler for "Message Received".
7. Reload the page then go modify your table record and watch the event logged to the console.
How it works
Here's how it works (and this is important to understand)--you will receive an event every time a record "enters" a state that satisfies the condition and an "exit" event whenever a record no longer satisfies the condition.
For example if the condition you are monitoring for is "State=Ready", when a record moves to that state a message will be received. In the payload you will see that "data.action" is "entry", like this:
If the state changes to "Open" you will receive another message (but without the full record data) of action "exit" letting you know that it is no longer being watched. You will no longer receive messages until the record's state returns to "Ready".
You may use code similar to this in your UIB script to check the action and decide whether to act on it:
function handler({api, event, helpers, imports}) {
console.log("Request Record Changed!");
console.log(event);
const { action, sys_id : requestId } = event.payload.data;
if(action === 'entry'){
api.setState('requestId', requestId);
api.setState('snapRequested', Date.now());
}
}
Actions and Operations
The Action is the activity that occurred to engage the record watcher and fire the event. It is centered around the state of the condition in relation to the record watcher. Did it enter the state? Did it exit the state? Or did something on the record that already satisfied the state change?
Consider the following response for the "action" property for the condition watching all tasks "assigned to is me".
entry | A change happened to cause a record to satisfy the condition that did not formerly satisfy that condition. E.g. the assigned to field changes from blank to myself or a new record assigned to me is inserted. |
change | A record that already satisfies the condition changes. E.g. the description of the record changes. |
exit | A record that formerly satisfied the condition no longer does so, e.g. assigned to field changes to another person. |
The Operation is an old-fashioned GlideRecord operation--insert, update, delete. As you can see you could have a combination of actions and operations that aren't exactly 1:1. I.e. a "change" action and "update" operation may seem like the same thing, but in fact an update operation on a record may cause it to enter the condition's parameters (such as the example of a record updated to assigned to me, triggering an "entry/update" combination).
You can use these values in combination with the filter to make sure that you only respond on the specific situations that you want to and don't cause too much noise.
Pretty sweet, no?
Once you've got the result of the Record Watcher state-change you can kick off any activity that you wish. Dig in a bit more and you'll see how to explicitly subscribe or unsubscribe (e.g. if you don't care about events any more), and you can build specific conditions to make sure that you're only targeting precisely the activities that you want to trigger the events.
Note: This feature was introduced with the Tokyo release.
- 5,329 Views
- Mark as Read
- Mark as New
- Bookmark
- Permalink
- Report Inappropriate Content
Hi Jon - Thankyou for the detailed article. I was searching about the record watcher and only found your post about that. Unfortunately, this is not working for me.
My use case is to - Open the Interaction record in a tab in agent workspace as soon as the Interaction is created. I was planning to use this approach to trigger the UIB client script and use g_aw method to open the created Interaction. But I'm not seeing any payload for the created record in the console.
Not sure if I'm missing anything but yeah this is really a great idea for my requirement.
- Mark as Read
- Mark as New
- Bookmark
- Permalink
- Report Inappropriate Content
Thanks for the article. This data resource is really useful.
My case is that there is a Create Record Button and the user clicks on it and the record is created and I'm turning on the Subscription through the Client State parameter when the Create Record Operation Succeeds.
On record insertion, a flow is running and making a POST request and then stores the response in the same record string field, API Response.
I have the Record Watcher Data Resource but can't get the API response through it. I am trying API response is not empty and have tried API response is empty conditions, but none of them seems to working.
Maybe, I am doing something wrong with it, this part is I am not able to figure out for now.
UPDATE:
Fixed it
Just tried conditions: (API_Response Is not null) && (API_Response is notEmpty)
Thanks, @Jon G Lind for this article. Saved me.
- Mark as Read
- Mark as New
- Bookmark
- Permalink
- Report Inappropriate Content
@Jon ,Is "Record Watcher" data resource not available in Vancouver?
- Mark as Read
- Mark as New
- Bookmark
- Permalink
- Report Inappropriate Content
Thank you.
Record watcher not working in list view simplelist workspace servicenow.
I wanted to use this record watcher in My approval list on CSM workspace home page, and it worked. But when click on view all, record watcher is not refreshing the list view page. any help is appreciated. thank you.
- Mark as Read
- Mark as New
- Bookmark
- Permalink
- Report Inappropriate Content
This solution is hit and miss. It seems it works for explicit filters like state='xyz' but more dynamic queries like assignment_group is dynamic 'My Groups' does not process update the Record Watcher correctly.