GroupWise supports recurring appointments, notes, and tasks. Recurring items are created from one item that fans out into many items. For example, a manager wants to send out a team appointment. The appointment occurs every Monday morning at 9:00 a.m. The manager could send out one appointment for each occurrence, but that would be time-consuming and tedious. Using GroupWise, the manager can send out one appointment and specify the recurring dates for the appointment.
This section contains the following examples:
GroupWise Web Services defines recurring items on the CalendarItem element. The recurring elements are rdate, exdate, and rrule.
The rdate element specifies a list of days to include in the recurrence. The rrule specifies a rule that defines a list of days to include in the recurrence. The exdate specifies a list of days to exclude in the recurrence. All three elements (rdate, rrule, and exdate) can be used to build a list of recurring days.
The rrule element defines a rule that defines the number of occurrences for the calendar item. There are industry standards that deal with recurrence. You should be familiar with recurrence in RFC 2445. For more information, see 4.3.10 Recurrence Rule.
GroupWise supports a subset of the many definitions that are available in recurrence rules. For example, in rrule there is a frequency element defined in the GroupWise schemas. RFC 2445 defines Secondly, Minutely, Hourly, Daily, Weekly, Monthly, and Yearly. At this time, GroupWise doesn’t support Secondly, Minutely, or Hourly. Consult the GroupWise schemas and RFC 2445 to see what elements are supported.
For each recurring instance, GroupWise creates a new item in the user's database at send time. For example, suppose an application creates a recurring appointment by calling sendItemRequest. The appointment defines a recurrence rule. When the POA evaluates the item, it fans out or creates a new item for each instance defined in the recurrence rule. This fanning out of recurring items is different than some other collaboration products. Other collaboration products create one instance of the item and store the recurrence rule with the item.
When you get a list of calendar items, recurring items are grouped together with a recurrenceKey. If you want to accept, decline, delegate, or modify all recurring items, pass in the recurrenceKey to the appropriate method.
If your user base is used to seeing only one calendar item to represent a recurring calendar item, it is up to the application to collapse the fanned-out items into one item. The recurrenceKey is used to determine which items are a part of the recurrence group.
In the following example, three appointments are created in the recipient's mailbox by calling sendItemRequest. The startDate and endDate create one instance, while the rdate element defines two other instances. The startDate and endDate both have a time associated with the date. This time value is used to create the duration of the appointment. The rdate values have only a date with no associated time. The rdate elements use the time and duration specified in the startDate and endDate elements.
<sendItemRequest> <types:item type="Appointment"> ... <subject>Recurrence 1</subject> ... <startDate>20121012T180000Z</startDate> <endDate>20121012T190000Z</endDate> <rdate> <date>20121013</date> <date>20121016</date> </rdate> <alarm types:enabled="1">5</alarm> </types:item> </sendItemRequest>
In the following example, a recurring item is created on a startDate of 10/12/2012. The rrule element specifies to create an appointment daily until 10/20/2012.
<sendItemRequest> <types:item type="Appointment"> <subject>Recurrence 2</subject> <startDate>20121012T180000Z</startDate> <endDate>20121012T190000Z</endDate> <rrule> <frequency>Daily</frequency> <until>20121020</until> </rrule> <alarm types:enabled="1">5</alarm> </types:item> </sendItemRequest>
In the following example, recurring items are created using this rule:
startDate specifies October 12, 2012 at 7:00PM UTC as the start time.
endDate specifies October 12, 2012 at 8:00PM UTC as the end time.
frequency creates the appointments on a monthly basis.
until creates the monthly appointments until 2/28/2013.
day creates the appointments only on Mondays.
<startDate>20121012T190000Z</startDate> <endDate>20121012T200000Z</endDate> <rrule> <frequency>Monthly</frequency> <until>20070228</until> <interval>2</interval> <byDay> <day>Monday</day> </byDay> </rrule>