ServiceNow gs.eventQueue: A Guide to Event-Driven Automation

ServiceNow is built on an event-driven architecture that allows the platform to respond to changes and trigger actions asynchronously. In this context, gs.eventQueue is a crucial GlideSystem method that developers use to fire off events programmatically. Essentially, an event in ServiceNow is a special log record indicating that something notable happened, which the system can react to (for example, by sending a notification or running a script). The gs.eventQueue() method lets you insert a new event into ServiceNow’s event queue from your server-side scripts, enabling workflow automation and asynchronous processing of tasks. This means you can decouple heavy or conditional logic from the immediate user interaction – the main script continues running without waiting for the event to be handled, as the event is processed in the background by ServiceNow’s event engine.

At a high level, event processing in ServiceNow works like this:

1. When an event is queued (either by the platform or via gs.eventQueue), it gets recorded in the [sysevent] event queue table.

2. The system then picks up this event record and looks for any listeners or handlers associated with the event name – these could be email notifications, script actions, or Flow Designer triggers configured for that event.

3. If a matching handler is found, it executes (for example, sending an email or running a script) in a separate process.

This architecture is powerful for automating workflows because it allows actions to occur after the initial business logic finishes, ensuring a smooth user experience (no long waits) and reliable processing of follow-up tasks.

In summary, gs.eventQueue plays an important role in ServiceNow by enabling event-driven automation – it helps you trigger custom events that kick off notifications, subsequent scripts, or other processes without blocking the current transaction.

What is gs.eventQueue?

In ServiceNow, gs.eventQueue() is a server-side method (part of the global GlideSystem API) used to programmatically fire an event. Calling this method inserts a new event record into the event queue, which the system will process asynchronously. In practical terms, this means you can signal that “something happened” (defined by a custom event name) and have ServiceNow react to it through configured handlers. Because it’s asynchronous, gs.eventQueue allows your script to queue the event and then immediately continue with other operations – the event’s subsequent actions (like sending an email or running a script action) will happen in the background shortly after. This non-blocking behavior is essential for maintaining performance and a good user experience.

The events triggered by gs.eventQueue are typically defined in the Event Registry (sysevent_register table) for clarity and maintainability. By registering an event, you document its purpose and link it to a table, and you can associate it with notifications or script actions to respond when the event occurs. (Script actions are server-side scripts that execute only when a specific event is fired.) Events triggered by gs.eventQueue that aren't registered in the Event Registry are still queued by ServiceNow, but they won't be handled by built-in processes. Therefore, unregistered events will effectively be ignored by default unless you've specifically written custom code to handle them. Thus, while gs.eventQueue gives you the ability to fire events on the fly, it’s best used in tandem with properly registered event names and handlers.

To sum up, gs.eventQueue is the go-to mechanism for event-driven scripting in ServiceNow. It’s commonly used within Business Rules, Script Includes, or other server-side scripts to signal that a certain condition was met or an action occurred, so that other parts of the system (like notifications or background processes) can take appropriate action in an asynchronous way.

Parameters of gs.eventQueue

The gs.eventQueue() method requires a few parameters to define the event and its context. Its signature looks like:

gs.eventQueue(eventName, record, parm1, parm2, queue);

Below is a breakdown of each parameter and how they are used:

• Event Name (eventName) – A string specifying the name of the event to trigger. This should correspond to an event in the Event Registry (for example, "incident.updated" or a custom name like "task.closed"). The event name is typically namespaced by the table or application (e.g., "incident.commented" for an Incident-related event). Always enclose the name in quotes. This parameter is required.

• GlideRecord Object (record) – A GlideRecord object that the event is associated with, usually the current record in a Business Rule (denoted by current). This provides context about which record the event pertains to (and the event record will store that table and record information). While often you pass current, it can be any valid GlideRecord from the relevant table that the event is about. This parameter is required. (For example, if the event is incident-related, you should pass a GlideRecord from the Incident table.)

• Parameter 1 (parm1) – An optional value to pass additional data with the event. This can be any value that resolves to a string (a string literal, a variable, or even a method call that returns a string). Many notifications or scripts that handle the event can use this parameter to get extra information. For instance, you might pass the user ID or a short description as parm1. This parameter is optional, and if not needed you can pass an empty string or null.

• Parameter 2 (parm2) – A second optional value for extra data, similar to parm1. It’s often used to provide a second piece of context to the event handler (for example, passing the user’s name, or another identifier). This is also optional and can be left blank if not used.

• Queue Name (queue) – An optional string to specify a custom event queue. ServiceNow processes events in queues, and by default, if you don’t specify this, the event goes into the default event queue. In most cases you will not need to set a custom queue; the default is appropriate. However, advanced use cases might use named queues to segregate event processing (for example, handling certain events in a dedicated worker thread). If you use a custom queue, you should also define that in the Event Registry (the registry form has a “Queue” field) so that ServiceNow knows which queue handles that event. If left blank, it uses the default queue. (Note: custom queue names should be all lowercase and use underscores, per best practice.)

  
  

Example Usage: To illustrate, consider the out-of-box scenario of logging an “incident commented” event. In an after Business Rule on the Incident table, you might have a script like this:

// In an Incident business rule, after a comment is added
if (!current.isNewRecord() && current.comments.changes()) {  
    gs.eventQueue("incident.commented", current, gs.getUserID(), gs.getUserName());  
}

In this example, "incident.commented" is the Event Name, current (the Incident GlideRecord) is the record context, and we pass two parameters: the user’s ID and user’s name who made the comment. We did not specify a queue name, so the event goes to the default queue.

When this line executes, ServiceNow will insert a record into the event queue indicating that for the current incident, an "incident.commented" event happened, with parm1 =  and parm2 = . Shortly after, the system will process this event: any email notification or script action listening for "incident.commented" will fire (for example, sending a notification to stakeholders that a new comment was added).

This pattern is commonly used to decouple the notification logic from the form save operation – the user who added the comment can continue their work without waiting for emails to be sent synchronously.

Common Use Cases

Why and where do developers use gs.eventQueue?

Here are some common use cases and scenarios where this method is invaluable:

• Triggering Notifications: One of the primary uses of events is to drive email or SMS notifications. By firing a custom event, you can leverage ServiceNow’s notification engine to send messages to users. For example, when a high-priority incident is created, you might use gs.eventQueue("incident.high_priority", current, ..., ...) in a Business Rule. A corresponding email Notification can be set to send whenever that event occurs. This way, your notification logic is cleanly separated – the Business Rule just queues the event, and the Notification (configured in System Notification > Email > Notifications) takes care of the messaging. This is how many out-of-the-box notifications work as well (e.g., an "incident.commented" event triggers an email to watchers of the incident). Using events for notifications ensures they are sent asynchronously after the record action, and it allows multiple handlers to respond to the same event if needed (perhaps logging it or taking other actions too).

• Automating Workflows: Events can kick off more complex logic such as legacy Workflow activities or modern Flow Designer flows.

  In older workflows, there were activities that waited for or triggered on events; in Flow Designer, you can configure a Flow to start when a specific event is fired.

  This means a gs.eventQueue call can serve as a trigger to begin an automated workflow or flow. For instance, you might fire a "request.completed" event that a Flow Designer flow listens for to then perform downstream tasks (like updating related records or calling an integration). This event-driven approach makes your workflows more modular – one part of the system signals an event, and another part (the flow) picks it up and runs with it. (Note: Ensure the event name matches exactly what the Flow or Workflow is expecting. Also, flows triggered by events typically require the event to be registered. In some cases, additional configuration might be needed for Flow Designer to catch custom events.)

• Executing Scripts Asynchronously: Sometimes you have server-side logic that you want to run, but not in the current user’s transaction because it might be time-consuming or you want to execute it after a slight delay. gs.eventQueue is perfect for this scenario when used in combination with Script Actions (or even simply as a signal that a Scheduled Job could pick up). A Script Action is essentially a script that runs when a specific event is processed. Developers often use this to handle heavier tasks in the background. For example, suppose when a record is updated you need to make a call to an external system or do some complex calculations. Instead of doing it immediately (and making the user wait for the form save to complete), you can queue an event like "custom.integration.call" with the record and necessary info. A Script Action listening for that event will then execute the code to call the external system asynchronously. This pattern improves performance and user experience by offloading work to the event queue. The main rule of thumb: use gs.eventQueue to run non-critical or heavy processes asynchronously so that your users aren’t stuck waiting on them.

• Logging and Monitoring Changes: Events can also serve as a mechanism to log important system changes or to trigger monitoring tools. For instance, you might queue a custom event whenever a certain threshold is crossed (like a server goes down, or a financial approval is granted) so that it gets recorded in the Event Log for audit purposes, or so that an external monitoring system (integrated via an Event Integration) picks it up. ServiceNow’s Event Management (if enabled) deals with inbound events from external systems, but here we’re talking about outbound or internal events via gs.eventQueue that you define. By creating events for significant business events (e.g., "budget.exceeded", "security.incident.opened"), you not only create a log (in the Events table) of these occurrences, but you can also hook notifications or scripts to them as needed. This is a lightweight way to track certain actions without building a whole new logging mechanism – the event itself is the log record. Keep in mind, events in the [sysevent] table do get purged after a while (older events are rotated out), so they’re for short-to-mid term logging or triggering rather than permanent history.

Troubleshooting and Best Practices

Using gs.eventQueue is generally straightforward, but here are some tips to avoid common pitfalls and to use it effectively:

• Server-side Only: Remember that gs.eventQueue is a server-side API. It will not work in client-side scripts (like Client Scripts or the client portion of UI Actions). If you need to trigger an event from a client context (for example, when a user clicks a button), you must make a server call (such as using GlideAjax or a UI Action that runs on the server) to call gs.eventQueue. A common mistake is trying to use gs.eventQueue in a client script and wondering why nothing happens – the code simply won’t execute since gs (GlideSystem) isn’t available on the client side.

• Verify Event Firing: If your event-driven logic isn’t working, first verify that the event is actually getting queued. You can check System Logs > Events (which shows entries in the event queue). If you don’t see your event there, it means the gs.eventQueue call might not have run or the code path wasn’t hit. Add some gs.log() or gs.info() logging around your eventQueue call to ensure the code executes. If the event is in the queue but the expected action (notification or script) didn’t occur, double-check the event name and context.

• Event Name and Registration: Typos or case mismatches in the event name are a common issue. The event name in gs.eventQueue must exactly match the name defined in the Event Registry and used by any Notification or Script Action. For example, "Incident.High_Priority" is different from "incident.high_priority" – the latter might be the registered name, and a case difference or missing underscore will cause a no-op. Also, as mentioned earlier, if you fire an event that isn’t registered, ServiceNow will still create the event record but no built-in handler will respond. Always register your custom events (via System Policy > Events > Registry) and provide a description. Not only does this enable the platform to respond, but it also helps administrators see what custom events exist and what triggers them.

• Event Queue (Advanced): In normal use, you don’t need to specify the queue name in gs.eventQueue – just leave that parameter off and the default queue will be used. However, if you have set up a custom event queue for specialized processing (perhaps to handle a flood of a certain type of event separately), ensure that you pass the correct queue name as the fifth parameter and that the event’s registry entry is configured with that same queue name. If a custom queue is misconfigured, your event might sit unprocessed. By default, “default” is the queue used for events. ServiceNow also has an “email” queue for events that are specifically email sends, and other system queues, but those are generally managed by the platform itself. Use custom queues sparingly and only if you have a clear reason.

• Debugging Script Actions: If you’re using Script Actions to handle events (a common pattern), keep in mind that script actions run asynchronously and have no "current" or "previous" like business rules do. They receive the GlideRecord you passed (available via event.parm1, event.parm2 in the script action, and event.instance for the GlideRecord). If your script action isn’t running, check that it’s set to Active and that its conditions (if any) are met. You can add debug logging in the script action and watch the system log when the event fires. Also note that script actions, like email notifications, only run after the event is committed to the queue (which typically happens at the end of the transaction that queued the event).

• Performance Considerations: Firing events is generally lightweight, but be mindful of volume. If you have a loop that calls gs.eventQueue hundreds of times in a short period, you might overwhelm the event queue or cause a backlog. In such cases, consider if you truly need individual events or if a single event can indicate a batch of work. Also avoid using large data in parm1 and parm2 – if you need to pass a lot of information, it might be better to pass a record ID and have the handler script look up details, rather than stuffing a long string into the event parameters.

• Use After Business Rules for Events: As a best practice, trigger events in after Business Rules (or in scripts that run post-transaction) whenever possible, especially for events related to record changes. This ensures that the record has been written to the database and all fields (like sys_id) are finalized. While you can fire events in before rules or other places, doing so after the action guarantees that any handler will see the final state of the record. For instance, if you queue an event during a before insert, the record doesn’t technically exist in the database yet – if a script action for that event tries to query that record by sys_id, it might not find it. Therefore, after-commit is safer for most situations.

• Alternative Approaches: If gs.eventQueue doesn’t seem to fit a scenario, consider what you need.

  For immediate, synchronous logic, simply put the code in a Business Rule or Script Include and call it directly (no event needed). If you want to delay execution of some code by a specific time or interval, you might use gs.eventQueueScheduled() (which is a variant of eventQueue that allows scheduling an event for a future time) or use a Scheduled Job.

  If your goal is to trigger an action in an external system, you could also consider IntegrationHub or direct web service calls – though often you’d still use events to decouple the external call from the user action.

  And for cases where you want to respond to record changes within ServiceNow, also evaluate if Flow Designer can meet your needs with its triggers and actions (Flow Designer can respond to record changes without needing manual events). However, Flow Designer also supports an event trigger if you prefer using events. In short, use gs.eventQueue when you want a loosely coupled, asynchronous trigger – but if you need something immediate or strictly ordered, other techniques might be more appropriate.

In troubleshooting, a key resource is the Event Log (Event Registry) and System Logs. You can open an event in the Event log and even see a “Reprocess” option to manually re-fire it if needed, which is useful for testing your handlers. Always ensure that the "Fired by" field in the Event Registry is updated (this is a free text field where you list which script or Business Rule fires the event – helpful for future maintainers). And finally, document your events. Event-driven architecture is powerful but can become confusing if there are many custom events – maintaining clear names (using a <application>.<action> naming convention) and descriptions will help keep things understandable.

Conclusion

The gs.eventQueue method is a cornerstone of ServiceNow’s event-driven automation capabilities. By allowing developers to generate events on the fly, it enables asynchronous workflows and decoupled processing that make applications more robust and user-friendly. We’ve seen that with just a name and a record (and optional parameters), you can signal the system to handle something later – whether it’s sending out notifications, kicking off a workflow, or running custom cleanup scripts. This not only improves performance (since users aren’t waiting on these tasks) but also leads to cleaner separation of concerns in your code (the code that detects a condition is separate from the code that reacts to it).

As a developer or administrator, understanding gs.eventQueue means you can leverage ServiceNow’s powerful event engine to build scalable solutions. Key takeaways include: always register and name your events clearly so they can be managed and tracked, use the event parameters to pass just the necessary data, and ensure you handle events in script actions or notifications appropriately. By following best practices – such as triggering events in after business rules, keeping an eye on the event log for debugging, and avoiding unnecessary event floods – you can make the most of event-driven automation.

In essence, gs.eventQueue empowers you to automate and orchestrate complex processes in ServiceNow in a safe, efficient manner. Embrace this feature to create responsive notifications, streamlined workflows, and background processes that enhance your platform’s functionality. With the tips and insights provided above, you should be well-equipped to implement gs.eventQueue in your ServiceNow scripts effectively, optimizing your use of event-driven automation for better system design and performance.