calDateDiff - Calendars are now legacy

[Michael273]

A question came up about a business rule customization that was made by a contractor that set the duration field when a record (task) is changed to active = false.  This business rule was setup to always run last.  That ended up opening up a can-o-worms with the business today, after it was allowed to run for a couple of months.

The question was about the duration and business_duration fields and which should be used for what purpose.  I think I am clear on that point, given what I see in the out of the box business rules for the incident records.  However, what I am not clear on is this little gem of a note in the API for Orlando for the calDateDiff method.

Calculate the difference between two dates using the default calendar.

Calendars are now legacy. If Schedules are being used, see the topic Calculate Duration Given a Schedule.

Irony here is that the topic "Calculate Duration Given a Schedule" is something I can't even find.

https://developer.servicenow.com/dev.do#!/reference/api/madrid/server_legacy/c_GlideSystemAPI#r_GS-c...

So, if the calDateDiff is a method which appears to is being depreciated, what is the preferred method getting a 'real' business duration for a task?  I also know, based upon searching that "using the default calendar" is a lie, it will find the 'first one' and use that.

Anyway, I would love to hear opinions and insights into this topic.  I'll admit I'm rather new to ServiceNow - been at for only 2 months - but I am a seasoned (20+ years) developer.

[Michael273 · Accepted solution]

Since posting this I've done considerable research into this topic and wanted to share with you my observations.

The method calDateDiff calculates the difference (duration) between two arbitrary dates using a SLA calendar setting in your instance.  Which one?  It uses the one found under System Policy -> SLA -> Calendars.

What if my calendar_duration is 0 (or smaller than I expected it to be), yet the opened/closed or created/closed dates are minutes or hours apart from each other on the same day?  Check the Calendars under the menu item above - it typically means that that these date/times in the fields started and ended after or before the times outlined in that calendar.

The calendar_duration isn't adding up right when it spans multiple days?  Well that's an interesting topic and difficult to describe.  Let's say your calendar in the menu item above is set to "9am to 5pm" Monday through Friday.  Meaning there is only 8 hours in a business day.  If you created/opened something on Monday at 9am and closed it on Thursday at 5pm you'd expect the calendar_duration be '4 four days' - but that's not what you'll get.  You'll get 8 hours on Monday, 8 hours on Tuesday, 8 hours on Wednesday, and 8 hours on Thursday - a total of 32 hours or 1.33 days.  The trick here is that calendar_duration still takes into account that there are '24 hours' in a day, despite how long the business day length is setup in the SLA Calendar.

[Natalie H]

Helpful, thank you. 

Interestingly, an OOTB Business rule 'mark_resolved' on Incident is still using gs.calDateDiff(), which is odd if calendars are legacy. We are having to write our own version to avoid business duration being updated based on default calendar.