SharePoint recurrence data schema


I have been hunting high and low for some definition of the schema used to populate the RecurrenceData field of an event in a SharePoint calendar. It seems to be one of life’s great mysteries…

Today, I finally stumbled across an msdn blog post that explains how to export SharePoint calendar events to iCal format files. I’m sure that this is the only post in the entire Internet (except for mine now of course…) that contains some really useful nuggets about what you need to set on your SPListItem when creating an event through code. I’ve included a link to the article at the end of this post, but just in case I’ve also copied a bit of it here…

<Updated> I’ve just added a section about deleting individual events from a recurring series. This took a bit of figuring out! </Updated>

Distinguishing between calendar item types

Calendar items in SharePoint fall into several categories. Single events are those which don’t repeat and only appear once on the calendar, while recurring events may show up any number of times depending on the recurrence pattern selected by a user. Either type of event may have a defined start and end time, or it may be an all-day event which lasts from midnight to 11:59 PM.

Furthermore, individual instances of a recurring event may be deleted or edited, creating a new event which takes its place. The event created by a deleted instance instructs the calendar not to render that day’s instance of the recurring event.

Calendar events can be distinguished by looking at the fRecurrence, fAllDayEvent, and EventType field values:

Type Description fRecurrence fAllDayEvent EventType
Single event An event created with the All Day Event and Recurrence checkboxes unselected. False False 0
All-day event An event created with the All Day Event checkbox selected. False True 0
Recurring event An event created with the Recurrence checkbox selected. Has a recurrence icon in the All Events view. Appears as a single master event on the All Events view, but as recurring instances on the Current Events and Calendar views. True False 1
Recurring all-day event Same as above, but with the All Day Event checkbox selected at creation time. True True 1
Recurrence exception Created by editing an instance of a recurring event. Has a strikethrough recurrence icon in the All Events view. True False 4
All-day recurrence exception Same as above, but created by editing an instance of an all-day recurring event. True True 4
Deleted instance of a recurring event Created by deleting a instance of a recurring event. Title is prefixed with “Deleted:” in the All Events view, and is hidden in the Current Events and Calendar views. True False 3
Deleted instance of an all-day recurring event Same as above, but created by deleting an instance of an all-day recurring event. True True 3

Understanding recurring events

Recurring events have a number of subtleties not found in single events. Most importantly, one recurring event item expands into any number of recurring event instances when it is rendered in the calendar view. Recurring events also make use of fields left empty in single events.

Certain fields are interpreted differently depending on whether the item in question is a recurring event or a single event:

Field Value for single event Value for recurring event
EventDate Start date and time Start date and time set for the recurring event when it was created, which may be an earlier date than the first instance of the recurring event.
EndDate End date and time End date and time for the last instance of the recurring event. For recurring events with no end date, this is a computed date several years in the future.
Duration The time in seconds between EventDate and EndDate. The duration in seconds of an individual instance of the recurring event.

Recurrence patterns and expanding events

Recurring events store the pattern used to display instances of the recurring event as XML in the RecurrenceData field. While this data is best used in a read-only fashion, the following are examples of the patterns you may encounter:

Recurrence type RecurrenceData field value
Daily every 1 days, no end date <recurrence><rule><firstDayOfWeek>su</firstDayOfWeek><repeat><daily dayFrequency=”1″ /></repeat>

<repeatForever>FALSE</repeatForever>

</rule></recurrence>

Weekly every Monday, Tuesday, and Wednesday, end by 5/31/2007 <recurrence><rule><firstDayOfWeek>su</firstDayOfWeek><repeat><weekly mo=”TRUE” tu=”TRUE” we=”TRUE” weekFrequency=”1″ /></repeat>

<windowEnd>2007-05-31T22:00:00Z</windowEnd>

</rule></recurrence>

Monthly the third Wednesday of every 2 months, no end date <recurrence><rule><firstDayOfWeek>su</firstDayOfWeek><repeat><monthlyByDay we=”TRUE” weekdayOfMonth=”third” monthFrequency=”2″ /></repeat>

<repeatForever>FALSE</repeatForever>

</rule></recurrence>

Yearly every May 18, end after 10 instances <recurrence><rule><firstDayOfWeek>su</firstDayOfWeek><repeat><yearly yearFrequency=”1″ month=”5″ day=”18″ /></repeat>

<repeatInstances>10</repeatInstances>

</rule></recurrence>

Deleting individual events from a recurring series

In order to delete an individual event from a recurring series, you actually need to create a new event and set a few properties on it to link it up to a specific instance from the ‘owning’ series. You will need to set the following properties (You need all of them!):

  • MasterSeriesItemID
    • Set this to the ID of the owning calendar list item
  • UID
    • Set this to the UID of the ownding calendar list item. If you haven’t populated this column in your owning list item, you’ll be having all sorts of problems already…
  • EventType
    • Set this to 3 to mark it as a deleted record
  • fRecurrence
    • Set this to 1
  • fAllDayEvent
    • Set this to the fAllDayEvent property of the owner calendar list item
  • EventDate
    • Set this to the date of the event instance you want to delete
  • EndDate
    • Set this to the date of the event instance you want to delete
  • RecurrenceID
    • Set this to the date of the event instance you want to delete. (Yep, this is the one that caught me out…has to be set to a datetime and NOT an ID)
  • Title
    • Set this to the title of the owner calendar event, but prefixed with Deleted:

When you have done this, you should now see an additional event in the All Events view of the calendar with a title of “Deleted: Name of your event” and the date of the specific instance. In the Calendar view, the specific instance should be invisible. This means that if you want to undo your deleted instance, you simply delete the extra list item that you have created and it will reappear!

Advertisements

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