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

If you're working with ServiceNow, you've likely encountered the powerful method gs.eventQueue() for automating notifications based on specific events. This functionality is essential for creating responsive workflows and keeping users informed about important changes, such as updates to planned resource hours. However, a common challenge arises when parameter values (parm1, parm2) successfully appear in the event log but fail to display correctly in email notifications. This article explores why this happens and how to resolve it effectively.

Understanding the Issue

When using gs.eventQueue() to fire custom events, parameters parm1 and parm2 allow passing specific data into event logs. A typical scenario involves notifying users when the "planned hours" value changes, displaying both previous and updated values. The event gets queued correctly, and parameters appear as expected in the event log. However, users may face difficulty accessing these parameters in their email notification scripts, often seeing unexpected outputs, such as a record sys_id instead of the actual parameter values.

Common Causes of This Issue:

• Notification conditions conflicting with event-based triggers.

• Misuse of direct object references (current, previous) instead of string values.

• Incorrect referencing of event parameters within the notification template or email script.

Verified Troubleshooting Solutions

Step 1: Adjusting Notification Triggers

One critical insight is that when using gs.eventQueue(), your notifications should directly trigger from these events. Avoid combining event-based notifications with additional condition checks (like "field changes" criteria).

• Correct Practice: Set the notification to trigger explicitly when your custom event fires.

  • Navigate to your notification configuration.

  • Set the "When to send" field explicitly to "Event is fired" and select your event name (e.g., req_allocation.req_hours.changed).

    
    

Step 2: Properly Passing String Values to gs.eventQueue()

Avoid directly passing current and previous object references to the event queue, as this can result in displaying object IDs rather than readable values.

• Recommended practice:

  (function executeRule(current, previous) { var currentHours = current.requested_hours.toString(); var previousHours = previous.requested_hours.toString(); gs.eventQueue("req_allocation.req_hours.changed", current, currentHours, previousHours); })(current, previous);

  
  

Step 3: Referencing Parameters Correctly in Mail Scripts

In your email script, reference event parameters through the event object provided in the email notification context.

• Example mail script:

  (function runMailScript(current, template, email, email_action, event) { var gdt = new GlideDateTime(current.sys_updated_on); email.setSubject("Planned Hours Change " + current.resource_plan.number + " " + gdt.getDate()); template.print("Previous Hours: " + event.parm2); template.print("<br>"); template.print("Current Hours: " + event.parm1); })(current, template, email, email_action, event);

This approach ensures correct and readable values in the final email notification.

Practical Example

For instance, if a user's "requested hours" change from 40 to 32, after correctly applying these fixes, your email notification would clearly state:

Previous Hours: 40
Current Hours: 32

Alternative Solution

If your notification is simple and does not require additional scripting logic, you can directly insert parameters using the email notification's "pill picker" interface.

• Navigate to your notification message body.

• Use the "pill picker" on the right sidebar to select parm1 and parm2 directly from the event table.

• Preview the notification to ensure the correct parameters display as expected.

Conclusion

Effectively using gs.eventQueue() for email notifications in ServiceNow requires setting up event triggers correctly, passing values as strings, and accurately referencing parameters in your scripts. Adopting these practices ensures your notifications provide clear, precise information, enhancing the usability and responsiveness of your ServiceNow implementations.