Recurrence handling occurs as follows:
A recurring series of events or todos has a master entry plus entries for exceptions.
Changing the rrules of a single instance returns an error. When rrules are modified for a recurring series, the whole series is deleted and recreated.
Changing dtstart of a recurring series entry causes the whole series to be recreated with the new dtstart, thereby losing all exceptions.
Inserting a rid that was not part of the original rule is not supported.
Multiple rrules for any component are not supported.
The following parameters are used with the storeevents and storetodos commands to create and modify components:
rrules - Semicolon-separated list of quoted recurrence-rule strings for recurring events.
rdates– Semicolon-separated list of ISO 8601 date strings listing recurrence dates.
exrules– Semicolon-separated list of quoted recurrence-rule strings for dates to exclude.
exdates– Semicolon-separated list of ISO 8601 date strings listing dates to exclude.
rid– ISO 8601 Date-Time String giving the recurrence ID of an event.
mod– Modifier specifying whether the action pertains to all the events or to just this event.
rchange– A boolean specifying whether or not to replace the rrules parameter. If rchange=1, the store commands map all mod settings (2-4) are mapped to 4. This means that you can not change an rrules for only some of the components in a recurring series. To change the rrules parameter, all components in the recurring series must be changed.
excludedtstart– An integer specifying whether or not to include the dtstart date in a recurring series if the date does not follow the rrule.
The rrules, rdates, exrules, and exdates parameters always function in replace mode. That is, no matter what the replace parameter value is set to, the values passed in for the recurrence parameters always replace the old parameter values, rather being appended to them.
This means you can not have multiple rrules for the same component.
For more information on the replace parameter, see Updating Parameter Values in Calendar Server WCAP
The rrules parameter takes a semicolon-separated list of quoted recurrence rule strings. Each string represents a recurrence rule of the event. Each string must be enclosed in quotes. Many parameters are possible for recurrence rules. (See RFC 2445 for a complete description of the syntax.)
Three parameters used by Calendar Server for specifying recurrence are freq, count and until:
The freq parameter in a rule defines the periodicity of the event, and has the following possible values:
DAILY |
The event recurs daily. |
WEEKLY |
The event recurs weekly. |
MONTHLY |
The event recurs monthly. |
YEARLY |
The event recurs yearly. |
The count parameter in a rule defines how many times the meeting repeats. If you do not specify the count, the default is the maximum number of recurrences allowed. The default maximum is 60. To change the maximum number, set the server configuration preference calstore.recurrence.bound.
The until parameter in a rule specifies using an end date as opposed to using the count to limit the number of instances created. Instances are created up to the end date or until 60 instances are created, whichever occurs first.
In the event that neither the count nor the until parameter are specified, the default is 60 instances.
Using the storeevents.wcap command to create an event with only exdates or rdates values, without specifying an rrules results in no events being created. The same behavior can be observed with the storetodos.wcap command.
The following example shows an rrules parameter that specifies the event is to occur daily for 10 instances (COUNT=10;FREQ=DAILY):
rrules="count%3D10%3Bfreq%3Ddaily" |
The following example URL passes the example rrules parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rrules="count%3D10%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
The rdates parameter takes a semicolon-separated list of date-time specifications where each date-time gives a recurrence date of the event.
For example, the following rdates parameter specifies a recurring event with two recurrence dates (3/31/02 11:22:33 and 5/31/02 11:22:33):
rdates=20020331T112233;20020531T112233 |
The following example URL passes the rdates parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rdates=20020331T112233;20020531T112233 &dtend=20020301T112233 &summary=uuuu |
If you want to the change the recurrence rule after a certain date, you must set rchange to 1.
The exrules parameter takes a semicolon-separated list of quoted recurrence rule strings where each rule is an excluded recurrence of the event.
For example, the following exrules parameter specifies a recurring event that does not recur at the times specified by the two rules:
exrules="count%3D10%3Bfreq%3Ddaily";"freq%3Dweekly%3Bcount%3D4" |
The first rule is for the event not to occur daily for 10 instances. The second rule is for the event not to occur weekly for 4 instances (COUNT=10;FREQ=DAILY and FREQ=WEEEKLY;COUNT=4).
The following example URL passes the example exrules parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &exrules="count%3D10%3Bfreq%3Ddaily"; "freq%3Dweekly%3Bcount%3D4" &rrules="count%3D100%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
The exdates parameter takes a semicolon-separated list of date-time specifications. Each date-time represents an excluded date of the event.
For example, the following exdates parameter specifies a recurring event that does not occur on the two specified dates (3/31/02 11:22:33 and 5/31/02 11:22:33):
exdates=20020331T112233;20020531T112233 |
The following example URL passes the example exdates parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &exdates=20020331T112233;20020531T112233 &rrules="count%3D200%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
This parameter specifies a unique recurrence date of an event or todo. Use rid in conjunction with the mod parameter to specify a range of events and todos to be modified.
For example:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rid=20020331T112233 &dtend=20020301T112233 &summary=uuuu&mod=1 |
For a non-recurring event or todo, the rid is 0.
When modifying recurring components, this parameter specifies whether to apply the changes to one or more instances of the event or todo. The following settings are mapped, but currently only the values 1 and 4 are used.
Value |
Option |
1 |
This instance only. |
2 |
Unused. This has been deprecated. Specifying a value of 2 will cause unpredictable results. |
3 |
Unused. This has been deprecated. Specifying a value of 2 will cause unpredictable results. |
4 |
This and all instances. |
When creating or modifying a recurring component, if changing rrules is allowed (rchange is set to 1), the system assumes a setting of 4, which causes the entire series of events or todos to be deleted and rewritten. If 2 or 3 are specified when trying to change rules or start times, they are mapped to 4. If 2 or 3 is specified for changing a summary or description, the setting are honored, but no exceptions are created for errors.
The rchange parameter specifies whether recurrences are expanded in storeevents.wcap, and storetodos.wcap. Normally, events and todos calendar components are not expanded, so the parameter defaults to 0, which implies the series is recreated.
However, you might not want to expand recurrences when you are modifying multiple events. For example, suppose a meeting recurs every Friday starting Jan. 1, 2002. Use the following URL to change the summary of each event after Feb. 1, 2002 to changed-event.
The following example sets the rchange parameter to 0, to make the modification without adding additional events:
http://webcalendarserver/storeevents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=abcxyz &dtstart=20020201T112233Z &rrules="byday%3Dfr%3Bfreq%3Dweekly" &summary=changed-event &rid=20020201T112233Z &mod=4 &rchange=0 |
Note that when you are modifying a recurrence series, do not pass in rrules unless you are trying to recreate the series with a new rule.
When creating a recurring series according to the rrule, this integer specifies whether to include the dtstart date if the date does not follow the rrules. For example, if on a Monday, you were creating a recurring series of meetings that were to be held every Wednesday, the dtstart would be Monday, but that does not fit the set of dates (all Wednesdays) generated using the rrules. Therefore the server must decide whether to include the dtstart date or not based on the value of excludedtstart.
A value of 0 indicates the dtstart date is included in the recurring series and a value of 1 indicates the dtstart date is not included in the recurring series. The default is 0.
When you delete a recurring component, specify the recurrence ID and whether to delete the recurrences as well as the original event or todo.
Use the mod parameter to select which occurrences to delete:
Value |
Option |
1 |
Delete or modify this instance only. |
2 |
Unused. This has been deprecated. Specifying a value of 2 will cause unpredictable results. |
3 |
Unused. This has been deprecated. Specifying a value of 3 will cause unpredictable results. |
4 |
Delete or modify all instances. |
To delete just the single instance of the event, the mod parameter should be set to 1. For example, this URL would delete just the event that occurs on the date March 1, 2002 11:22:33 AM GMT.
http://webcalendarserver/deleteevents_by_id.wcap ?id=23423423434abc &calid=jdoe &uid=001 &rid=20020301T112233Z &mod=1 |
To delete all instances of the event, the mod parameter should be set to 4. For example, this URL would delete ALL instances of the event (uid 001).
http://webcalendarserver/deleteevents_by_id.wcap ?id=23423423434abc &calid=jdoe &uid=001 &rid=20020301T112233Z &mod=4 |
The following parameters are found in the fetchcomponents_by_* commands, and the fetchevents_by_id and fetchtodos_by_id commands:
compressed– A boolean specifying whether to return all of the recurring entry’s data, or to exclude the following parameters:rrules, rdates, exrules, exdates.
This parameter is deprecated in the current release, and is included only for backwards compatibility. It might be removed from future releases.
recurring– A boolean parameter specifying whether or not to return all components in compressed form (master entry and exceptions). This parameter is also present in the fetch_deletedcomponents command.