SharePoint Calendar: Managing Exceptions in a Recurring Event Schedule

The object returned by the SharePoint JavaScript CSOM for a recurring event schedule is very intuitive. For example, an event which occurs every day for the next year (up until 2017-02-21) reads as follows in the RecurrenceData field of the SP.ListItem.fieldValuesAsText property:

RecurrenceData: "<recurrence><rule><firstDayOfWeek>su</firstDayOfWeek><repeat><daily dayFrequency="1" /></repeat><windowEnd>2017-02-21T01:00:00Z</windowEnd></rule></recurrence>"

I used something similar to the above schedule to start a daily timecard entry event in a SharePoint Calendar. The scenario is basically to track a daily task to submit a timecard, but there are a lot of exceptions. Take for example an employee named Karen. She has alternating Monday-Tuesday and then Thursday-Friday off and works weekends. Bob happens to be putting in a bit of overtime for the next week before going on vacation. Again, exceptions occur often, so we see variable schedules for Karen and Bob:

SharePoint Calendar
Schedules for Karen and Bob.

If we were to process the RecurrenceData XML rule above in order to build logic which triggers an e-mail or reminder to Bob/Karen to enter their timecard, we’d end up triggering the activity on dates when they were off (days like the exceptions above, holidays, sick days, and so on). Fortunately, the exceptions are also stored as list items in the SharePoint Calendar list item collection – they’re just not shown on the calendar view. In the above Calendar, we’ll get back 6 list items: the recurring event schedule for Karen, the recurring event schedule for Bob, and then the four exceptions to Karen’s schedule.

Calendar Objects in Debugger.
Calendar Objects in Debugger.

The first thing to do is to group the exceptions with their parent event. As noted, this is very intuitive:

  1. Group the list items on the UID property or match them by the MasterSeriesItemID property
  2. Then, sort the items in ascending order by the Order property or ID property
  3. There are even more creative ways to match and order and identify the exceptions you want to work with. See below for examples of use fields…SharePoint even prepends “Deleted: ” to the Title property of the exception

Finally, you can now use the EventDate or RecurrenceID property to identify the exact date of the exception to the schedule and prevent the e-mail or reminder from going out.

Useful Exception Item Properties
Useful Exception Item Properties

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s