Introduction
Special Handling Notes (SHNs) in ServiceNow are a powerful but often overlooked feature. They allow you to surface important context such warnings, alerts, or reminders directly on records like Cases or Accounts so fulfillers see them instantly.
But have you ever wondered how SHNs actually work under the hood? Or if you could extend their behaviour to suit specific use cases?
What Are SHNs (and Why They Matter)?
At their core, SHNs act like “sticky alerts” on records. They draw attention to something the fulfiller needs to know before taking action.
For example, you might display an SHN if:
- A customer has a special SLA agreement.
- A record has been flagged for review.
- Compliance rules require additional checks.
Unlike notifications or emails, SHNs live right on the record and stay visible until dismissed, making them hard to ignore.
The Use Case: Auto-Unflagging Records
I ran into a scenario where SHNs were an almost perfect fit:
Problem: When a non-fulfiller (say, via email) updates a record, the record gets flagged for review. The fulfiller must un-flag it manually.
Risk: Fulfillers often forget to un-flag the record, leading to inaccurate reporting.
Goal: Create an alert that forces fulfillers to act by either acknowledging and un-flagging, or snoozing the reminder.
In other words, I wanted SHNs to behave like:
- “X” button (top-right) → Remind me later.
- “Dismiss” button → Acknowledge and undo the condition that triggered the SHN.
This behaviour isn’t available out-of-the-box (OOTB), but SHNs gave me a strong foundation to build on.
How SHNs Work Behind the Scenes
At first, I assumed SHNs worked like most other ServiceNow features: with a Many-to-Many (M2M) table linking SHN records to users with some sort of "state". Surprisingly, that’s not the case.
When I inspected the table relationships, nothing showed up. After digging deeper, I discovered SHNs are powered by a Script Include called global.SHNProcessor.
This Script Include handles the core functionality of retrieving and storing SHNs via via getSession’s putClientData() / getClientData().
This means SHNs aren’t tracked in the database per user but instead rely on session-level data.
Customising SHN Behaviour
The key method we’re looking for is markAlertSeen(), which runs when the user clicks Dismiss. This is where you can inject custom logic.
Because it’s server-side, you can use the full ServiceNow API. A simple GlideRecord update might be all you need, or you can call your own Script Include for more complex behaviour.
To keep my customisation lightweight so upgrades won’t heavily impact it I:
- Built a custom Script Include to handle record updates.
- Modified SHNProcessor’s markAlertSeen function to call my Script Include when the Dismiss button was clicked.
This gave me the behaviour I wanted: “X” acts like snooze, while “Dismiss” acknowledges and updates the record.
// Custom Script Include: SHNHandler
var SHNHandler = Class.create();
SHNHandler.prototype = {
updateRecordOnDismiss: function(tableName, recordSysId) {
var gr = new GlideRecord(tableName);
if (gr.get(recordSysId)) {
// Example: auto-clear the "flagged" field
gr.flagged = false;
gr.update();
}
},
type: 'SHNHandler'
};// Modified markAlertSeen with custom logic
SHNProcessor.prototype.markAlertSeen = function(sysparm_id, sysparm_sys_id, sysparm_table) {
// Call OOTB behaviour
// Call custom handler for record updates
var handler = new SHNHandler();
handler.updateRecordOnDismiss(tableName, recordSysId);
// Continue OOTB behaviour
};
Potential Extensions
Once you understand SHNs, a lot of possibilities open up. For example you can implement:
- Lookup table for anti-conditions: For an SHN record, which triggers the alert on a condition, optionally create an anti-condition record so dismissing a note automatically applies that inverse condition.
- Automated workflows: Trigger follow-up tasks when an SHN is dismissed.
- Analytics: Track which SHNs are most often dismissed or snoozed, helping refine business rules.
Key Takeaways
- SHNs aren’t just simple alerts – they’re session-based notes managed by the SHNProcessor Script Include.
- By customising the markAlertSeen() method, you can change how SHNs behave when dismissed.
- With some creativity, SHNs can evolve into powerful workflow enforcers – not just reminders.
