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!

Improved CAML IntelliSense

Don’t know why I missed this but its an essential add-in for Visual Studio 2005/2008. This guy has taken the core SharePoint schema files and extended them to add all that information from the SDK that is notoriously difficult to find. He’s done this by getting as much information as possible and sticking it in xs:annotation elements, and replacing as many xs:string types with enumerated types as possible so that we get the possible valid values.

A couple of examples that will make you go and download this straightaway:

  • When selecting a true/false type, he pops up an annotation that lets you know what type of true/false value you need, either TRUE, True, true etc etc
  • When you are creating a ListInstance and start typing the TemplateType, not only does it give you an enumeration of the various integer values that you can enter but it pops up an annotation describing what each one is

I honestly think that if you are doing SharePoint development this could easily save you a couple of hours a week!

Here’s a link to his post that describes it in more detail and where you can download the files : CAML.Net IntelliSense