changes() and journal fields

[SNAdmin47]

We were troubleshooting a failing business rule and whilst the cause turned out to be unrelated to this topic we noticed this statement in the ServiceNow documentation:

=========================

GlideElement - changes()

Determines if the current field has been modified. This functionality is available for all available data types, except Journal fields.

=========================

Taken from the following location: https://www.servicenow.com/docs/r/api-reference/server-api-reference/c_GlideElementAPI.html

The thing is, we have numerous usages of comments.changes() in use on BRs and they work fine whether in a scripted condition or within the BR script itself. We tested again just to be sure that nothing has changed recently (although we noticed that this statement is in use on product documentation dating back to Washington), and whether on our company instance or the PDI our testing confirmed this works as intended with comments.changes() being effective.  

We considered that maybe this is saying that this method doesn't work with 'Journal' field types (i.e. notes, etc.) as opposed to 'Journal Input' field types (i.e. comments/work_note), but when we tested with a notes field which is a Journal type, then this worked as intended too. We also double checked and found multiple OOTB BRs using comments.changes().

I can't find anything online which indicates that comments.changes() is unsafe or considered as inadvisable for evaluating field changes (other than the above link). Can anybody explain why the documentation states this and/or give an insight into our perception of this statement?

More than anything, we'd like to ensure that our usage of this won't come back to haunt us with a later patch/version update and force us to find an alternative and frantically update essential BRs. I'm currently putting this down to an oversight on the documentation but thought it prudent to check. 

Many thanks in advance for any input you guys can provide! 😁

[Naveen20]

Usage of comments.changes() is safe, and this is almost certainly a documentation inaccuracy (or at best, a misleading oversimplification) rather than a signal of future deprecation.

Here's the fuller picture:

Why it works despite what the docs say. Journal fields like comments and work_notes are stored in sys_journal_field rather than directly on the task table. When a Business Rule fires, the GlideRecord in context has the journal entry data available within the transaction. The changes() method on journal fields doesn't compare an old value to a new value the way it does for a string or reference field — since journals are append-only, changes() is effectively detecting whether a new entry was appended during that transaction. It works, but it works differently under the hood than it does for conventional field types, which is likely the origin of that documentation statement.

Why the docs probably say this. A few plausible explanations, and they aren't mutually exclusive:

The documentation may be trying to convey that changes() doesn't behave identically for journal fields — there's no traditional old-value-to-new-value comparison happening — and someone generalized that into "doesn't work for Journal fields," which is inaccurate. It's also possible this was true in much older platform versions and the docs were never corrected when the behavior stabilized. That documentation statement has been carried forward across multiple release versions essentially unchanged, which is a classic pattern for a stale doc entry.

Why you shouldn't worry about future breakage. The fact that ServiceNow's own OOTB Business Rules use comments.changes() is the strongest evidence you have. ServiceNow treats OOTB configurations as part of their platform contract — they aren't going to break their own shipped logic. If they ever changed the behavior of changes() on journal fields, it would break a massive amount of both OOTB and customer customization across the entire install base. That's not something that happens without an explicit deprecation notice, a KB article, and typically a multi-release migration path.

One genuine edge case worth knowing about. Where changes() on journal fields can behave unexpectedly is in async Business Rules or contexts where the journal write has already been committed to sys_journal_field and the in-memory transaction state is no longer available. If all your usage is in synchronous before/after BRs and scripted conditions, you're in well-trodden, safe territory.

So your conclusion is right — this reads as a documentation oversight. These BRs are fine.