How BusinessCalendar functions AddDays() and AddTime() treat holidays, weekends, and time zones
Using functions in the BusinessCalendar library to process values that extend beyond normal business hours and across time zones can lead to unexpected results. For best results, review how the addTime() and addDays() functions work.
These functions are called in service level computations that compute deadlines and goals and by other work object processing computations.
Prerequisite: Ensure that all calendar calculations are performed using the same time zone. This condition will be met if all users use the same calendar.
PRPC 6.x and subsequent releases
If the time specified is after the end of the business day, the calendar rolls forward to the start time of the next business day.
PRPC 5.5.x and prior releases
The addTime() and addDays() functions evaluate input and calculate results in three steps:
- Evaluate a DateTime value for the starting date.
- The date you specify is evaluated to determine if the date is a business day. (The time of day is not evaluated.)
- If the specified day is a business day, then that date is used for the calculation.
- If the specified day is not a business day, then the date is rolled forward, using the calendar provided, to the next business day.
- If the date has rolled forward in this step, then the time portion of the DateTime that is passed to the next step (Step 2) will be whatever the start of the business day is in the calendar, and not the time value that was specified initially for this step (Step 1).
- Evaluate DateTime for the time.
- If the time specified is prior to the start of the business day, the calendar rolls forward to the start time on the same day (the result of Step 1).
- If the time specified is after the start of the business day, the calendar rolls back to the end time on the same day (the result of Step 1).
- If the time is within the range of hours that defines the business day, that value will be used.
- Add the specified number of days, followed by units of time.
- If the number of days added returns a value that is not a business day, the calendar rolls forward to the next business day.
- If the units of time added (hours, minutes, seconds) are within the given day, they are added to the day (the result of Step 1).
- If the units of time added (hours, minutes, seconds) exceed the limits of the business day, they roll forward to the next business day and are added to the starting time of that day.
Examples for PRPC 5.5.x and prior releases
Some examples illustrate the values returned by addTime() when you add one day to the CurrentDateTime(), and the CurrentDateTime() is beyond the range of business days and business hours.
Assume that a business day is any day from Monday through Friday, inclusive, and that the range of hours in a business day is 8:00 a.m. to 4:00 p.m. in the Eastern Daylight Time (EDT) or Eastern Standard Time (EST) zones. (Process Commander identifies the EDT/EST time zone as America/New_York, following the CDLR standards.)
The following examples show how the BusinessCalendar functions work when the CurrentDateTime() is within any of the following time periods:
- From 4:00 p.m. to 11:59 p.m. today
- From 12.01 a.m. to 7:59 a.m. the next day
- From any hour on weekend days and holidays
Example 1: Work Object Created After the Close of the Business Day
A work object is created on August 4, 2009 at 5:30 p.m. EDT, after the specified close of business (4:00 p.m.). Because August 4, 2009 is Tuesday, a business day, this date is used. The time (5:30 p.m.) rolls back to 4:00 p.m. If you add three days to the processing timeline of the work object, the deadline is August 7, 2009 4:00 p.m. EDT.
Example 2: Work Object Created Before the Start of the Business Day
A work object is created on August 5, 2009 at 7:47 a.m. EDT, before the specified start of business (8:00 a.m.). Because August 5, 2009 is Wednesday, a business day, this date is used. The time (7:47 a.m.) rolls forward to 8:00 a.m. If you add three days to the processing timeline of the work object, the deadline is August 9. Because August 9, 2009 is a Sunday, the date rolls forward to the next business day, which is August 10, Monday. The processing deadline is August 10, 2009 at 8:00 a.m.
Example 3: Work Object Created Shortly Before the Close of the Business Day
The start time for a work object is set at 3:50 p.m. EDT on a Tuesday, ten minutes before the close of business (4:00 p.m.). For this example, the Service Level Agreement (SLA) is set to 30 minutes after creation time. If you add ten minutes to the start time, the work object advances to the close of business and rolls forward to 8:00 a.m. EDT, Wednesday, the next business day. Add twenty minutes to set a processing deadline of 8:20 a.m. EDT Wednesday, when the work object must be completed.
Example 4: CurrentDateTime() function returns GMT values
This example shows how the CurrentDateTime() function gets the current data and time and returns Greenwich Mean Time (GMT) values. Ensure that you specify a valid calendar for the addTime function to use when calculating the resulting date and time.
From this starting date and time stamp 20090811T225534.851 GMT to this resulting date and time stamp 20090814T210000.851 GMT, here’s what happens:
A work object is created on August 11, 2009 at 10:55:34 p.m. GMT. This is 6:55:34 EDT, which is after the close of business on August 11, a business day. In this example, the close of business is 5:00 p.m. EDT. The time rolls back to 5:00 p.m. on August 11. If you add three business days to the processing timeline, the deadline is August 14 at 5:00 p.m. EDT or 9:00 p.m. GMT.