An Examination of gs.eventQueue

[Alexander Grisb]

While I was working with notifications, I realized that there are some incredibly useful and neglected parts of ServiceNow that sometimes aren’t used to their fullest potential. I’d like to go over one of them right now, gs.eventQueue.

One thing seems to trip up a lot more people on first go than usual. This is gs.eventQueue. Let’s go over the syntax first. 

gs.eventQueue('event_name', gliderecord_object, 'string_parm1', 'string_param2', 'string_queue')

In order to use gs.eventQueue, it requires a minimum of two parameters passed to it: an event name and an object instance.

The first thing is the event name. An important thing to remember is that the event name must be an exact match for this to work. I would usually suggest making a custom event for this, as using an OOB event may trigger something that you may not want to trigger. However, it’s helpful to know that you CAN trigger OOB events to do what you need them to do. I personally have not run into a situation where I would need to trigger an OOB event. 

Secondly, an GlideRecord object instance. If you aren’t sure what to pass here, current is always an option. You can actually pass any GlideRecord object here. This can lead to some interesting interactions, such as triggering a query and sending the GlideRecord with the event. If you would like to find out what current is, it’s pretty easy. Navigate to the sys_event table and current will be the URI that is passed in. This is also any GlideRecord that is passed, and you can directly get to it by appending it to the end of your instance URL.

Thirdly, the two parameters, parm1 and parm2. These are optional, but are incredibly useful. These can be accessed in some places with event.parm1 and event.parm2. These parameters both take strings as input. However, you can pass in data gathered from methods in these parameters. For example, you can use gs.getUserName() and pass that in as an event parameter. You can also pass in either a sys_id or an email address and use this to send a notification, instead of having the recipient hard-coded. You can also construct an object, JSON.stringify it, and then send that as an event param and parse it when it gets to its destination.

Easy enough to follow, right?

There’s another event method that is almost the same. Scheduled event queue. This is extremely useful as well, but lacks any documentation on it. Let’s go over the differences between the two functions.

gs.eventQueueScheduled('String event name', Object instance, 'String parm1', 'String parm2', Object expiration)

This is the exact same as gs.eventQueue, except for one neglected feature. The event queue has been replaced with something called an expiration. Long story short, this is a GlideDateTime. You would manipulate the GlideDateTime and whatever you put in there will be the time and date the event would be triggered. This is extremely useful if you’re sending reminders, sending the same notification on different days, etc. This is a lot easier than making a notification with another event and a scheduled job, and requires less scripting and moving parts than other methods.

If you have any questions, let me know below and I'll do my best to answer them. Join me next time as we dive through more of ServiceNow's underutilized methods!

[jazz20]

Thanks for sharing this article. Can you pls provide some example/usage of using eventQueueScheduled for sending same reminders on different days etc...

[iamkurt]

Small correction - its the "sysevent" table and not "sys_event" table