Recurring Components– Creating, Modifying

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 telling which instances of the event to store.

• 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

rrules

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:

• 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

rdates

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.

exrules

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

exdates

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

rid

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.

mod

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 honored. If 2 or 3 are specified, in certain cases they are mapped to 4.

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.

rchange

The rchange parameter specifies whether recurrences are expanded in Command: storeevents, and Command: storetodos. 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=2
              &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.

excludedtstart

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.