3.5. Methods for VJOURNAL Components
This section defines the property set for the methods that are applicable to the "VJOURNAL" calendar component. The following summarizes the methods that are defined for the "VJOURNAL" calendar component.
+---------+---------------------------------------------------------+ | Method | Description | +---------+---------------------------------------------------------+ | PUBLISH | Post a journal entry. Used primarily as a method of | | | advertising the existence of a journal entry. | | | | | ADD | Add one or more instances to an existing journal entry. | | | | | CANCEL | Cancel one or more instances of an existing journal | | | entry. | +---------+---------------------------------------------------------+3.5.1. PUBLISH
The "PUBLISH" method in a "VJOURNAL" calendar component has no associated response. It is simply a posting of an iCalendar object that may be added to a calendar. It MUST have an "Organizer". It MUST NOT have "Attendees". The expected usage is for encapsulating an arbitrary journal entry as an iCalendar object. The "Organizer" MAY subsequently update (with another "PUBLISH" method) or cancel (with a "CANCEL" method) a previously published journal entry. This method type is an iCalendar object that conforms to the following property constraints: +------------------------------------------------+ | Constraints for a METHOD:PUBLISH of a VJOURNAL | +------------------------------------------------+ +--------------------+----------+-----------------------------------+ | Component/Property | Presence | Comment | +--------------------+----------+-----------------------------------+ | METHOD | 1 | MUST be PUBLISH. | | | | | | VJOURNAL | 1+ | | | DESCRIPTION | 1 | Can be null. | | DTSTAMP | 1 | | | DTSTART | 1 | | | ORGANIZER | 1 | | | UID | 1 | | | ATTACH | 0+ | | | CATEGORIES | 0+ | | | CLASS | 0 or 1 | | | COMMENT | 0+ | | | CONTACT | 0+ | | | CREATED | 0 or 1 | | | EXDATE | 0+ | | | LAST-MODIFIED | 0 or 1 | |
| RDATE | 0+ | | | RECURRENCE-ID | 0 or 1 | Only if referring to an instance | | | | of a recurring calendar | | | | component. Otherwise, it MUST | | | | NOT be present. | | RELATED-TO | 0+ | | | RRULE | 0 or 1 | | | SEQUENCE | 0 or 1 | MUST be present if non-zero. MAY | | | | be present if zero. | | STATUS | 0 or 1 | MAY be one of | | | | DRAFT/FINAL/CANCELLED. | | SUMMARY | 0 or 1 | Can be null. | | URL | 0 or 1 | | | IANA-PROPERTY | 0+ | | | X-PROPERTY | 0+ | | | ATTENDEE | 0 | | | REQUEST-STATUS | 0 | | | | | | | VALARM | 0+ | | | | | | | VTIMEZONE | 0+ | MUST be present if any date/time | | | | refers to a timezone. | | | | | | IANA-COMPONENT | 0+ | | | X-COMPONENT | 0+ | | | | | | | VEVENT | 0 | | | | | | | VFREEBUSY | 0 | | | | | | | VTODO | 0 | | +--------------------+----------+-----------------------------------+3.5.2. ADD
The "ADD" method allows the "Organizer" to add one or more new instances to an existing "VJOURNAL" using a single iTIP message without having to send the entire "VJOURNAL" with all the existing instance data, as it would have to do if the "REQUEST" method were used. The "UID" must be that of the existing journal entry. If the "UID" property value in the "ADD" is not found on the recipient's calendar, then the recipient MAY treat the "ADD" as a "PUBLISH". When handling an "ADD" message, the "Attendee" treats each component in the "ADD" message as if it were referenced via an "RDATE" in the main component. There is no response to the "Organizer".
This method type is an iCalendar object that conforms to the following property constraints: +--------------------------------------------+ | Constraints for a METHOD:ADD of a VJOURNAL | +--------------------------------------------+ +--------------------+----------+-----------------------------------+ | Component/Property | Presence | Comment | +--------------------+----------+-----------------------------------+ | METHOD | 1 | MUST be ADD. | | | | | | VJOURNAL | 1 | | | DESCRIPTION | 1 | Can be null. | | DTSTAMP | 1 | | | DTSTART | 1 | | | ORGANIZER | 1 | | | SEQUENCE | 1 | MUST be greater than 0. | | UID | 1 | MUST match that of the original | | | | journal. | | ATTACH | 0+ | | | CATEGORIES | 0+ | | | CLASS | 0 or 1 | | | COMMENT | 0+ | | | CONTACT | 0+ | | | CREATED | 0 or 1 | | | LAST-MODIFIED | 0 or 1 | | | RELATED-TO | 0+ | | | STATUS | 0 or 1 | MAY be one of | | | | DRAFT/FINAL/CANCELLED. | | SUMMARY | 0 or 1 | Can be null. | | URL | 0 or 1 | | | IANA-PROPERTY | 0+ | | | X-PROPERTY | 0+ | | | ATTENDEE | 0 | | | EXDATE | 0 | | | RECURRENCE-ID | 0 | | | REQUEST-STATUS | 0 | | | RDATE | 0 | | | RRULE | 0 | | | | | | | VALARM | 0+ | | | | | | | VTIMEZONE | 0 or 1 | MUST be present if any date/time | | | | refers to a timezone. | | | | | | IANA-COMPONENT | 0+ | | | X-COMPONENT | 0+ | |
| | | | | VEVENT | 0 | | | | | | | VFREEBUSY | 0 | | | | | | | VTODO | 0 | | +--------------------+----------+-----------------------------------+3.5.3. CANCEL
The "CANCEL" method in a "VJOURNAL" calendar component is used to send a cancellation notice of an existing journal entry. The message is sent by the "Organizer" of a journal entry. For a recurring journal entry, either the whole journal entry or instances of a journal entry may be cancelled. To cancel the complete range of a recurring journal entry, the "UID" property value for the journal entry MUST be specified and a "RECURRENCE-ID" property MUST NOT be specified in the "CANCEL" method. In order to cancel an individual instance of the journal entry, the "RECURRENCE-ID" property value for the journal entry MUST be specified in the "CANCEL" method. There are two options for canceling a sequence of instances of a recurring "VJOURNAL" calendar component: a. The "RECURRENCE-ID" property for an instance in the sequence MUST be specified with the "RANGE" property parameter value of "THISANDFUTURE" to indicate cancellation of the specified "VJOURNAL" calendar component and all instances after. b. Individual recurrence instances may be cancelled by specifying multiple "VJOURNAL" components each with a "RECURRENCE-ID" property corresponding to one of the instances to be cancelled. When a "VJOURNAL" is cancelled, the "SEQUENCE" property value MUST be incremented as described in Section 2.1.4. This method type is an iCalendar object that conforms to the following property constraints:
+-----------------------------------------------+ | Constraints for a METHOD:CANCEL of a VJOURNAL | +-----------------------------------------------+ +--------------------+----------+-----------------------------------+ | Component/Property | Presence | Comment | +--------------------+----------+-----------------------------------+ | METHOD | 1 | MUST be CANCEL. | | | | | | VJOURNAL | 1+ | All MUST have the same UID. | | DTSTAMP | 1 | | | ORGANIZER | 1 | | | SEQUENCE | 1 | | | UID | 1 | MUST be the UID of the original | | | | REQUEST. | | ATTACH | 0+ | | | ATTENDEE | 0 | | | CATEGORIES | 0+ | | | CLASS | 0 or 1 | | | COMMENT | 0+ | | | CONTACT | 0+ | | | CREATED | 0 or 1 | | | DESCRIPTION | 0 or 1 | | | DTSTART | 0 or 1 | | | EXDATE | 0+ | | | LAST-MODIFIED | 0 or 1 | | | RDATE | 0+ | | | RECURRENCE-ID | 0 or 1 | Only if referring to an instance | | | | of a recurring calendar | | | | component. Otherwise, it MUST | | | | NOT be present. | | RELATED-TO | 0+ | | | RRULE | 0 or 1 | | | STATUS | 0 or 1 | MAY be present; MUST be CANCELLED | | | | if present. | | SUMMARY | 0 or 1 | | | URL | 0 or 1 | | | IANA-PROPERTY | 0+ | | | X-PROPERTY | 0+ | | | REQUEST-STATUS | 0 | | | | | | | VALARM | 0 | | | | | | | VTIMEZONE | 0+ | MUST be present if any date/time | | | | refers to a timezone. | | | | | | IANA-COMPONENT | 0+ | | | X-COMPONENT | 0+ | |
| | | | | VEVENT | 0 | | | | | | | VFREEBUSY | 0 | | | | | | | VTODO | 0 | | +--------------------+----------+-----------------------------------+3.6. Status Replies
The "REQUEST-STATUS" property is used to convey status information about a "REPLY", "COUNTER", or "DECLINECOUNTER" iTIP message. The codes listed in the table below SHOULD be used. If the "REQUEST- STATUS" property is not present in one of these iTIP messages, then a status code of "2.0" (success) MUST be assumed. This specification adds a new IANA registry for "REQUEST-STATUS" property values, as defined in Section 7, which includes a new registration template for defining the specific components of the "REQUEST-STATUS" property value. Additional codes MAY be used, provided the process described in Section 8.2.1 of [RFC5545] is used to register them. This specification allows for multiple "REQUEST-STATUS" properties to be returned in iCalendar components in the appropriate iTIP messages. When multiple "REQUEST-STATUS" properties are present, the following restrictions apply: 1. Within any one component, the "top-level" numeric value of the "short return status code" MUST be the same for all "REQUEST- STATUS" properties, i.e., there cannot be a mixture of, e.g., 2.xx and 5.xx codes within a single component. 2. Across all components in the iTIP message, the following applies: A. If any one component would have a 5.xx code, then either all components MUST have a code in that range or "REQUEST-STATUS" MUST NOT be present in the other components if a 5.xx code is not appropriate for those components. B. Otherwise, if any one component would have a 3.xx code, then either all components MUST have a code in that range or "REQUEST-STATUS" MUST NOT be present in the other components if a 3.xx code is not appropriate for those components. C. 2.xx and 4.xx codes can be used in different components, provided that each component follows the restriction in (1) above.
The following "REQUEST-STATUS" codes are defined (any "Offending Data" MAY be specified in the "REQUEST-STATUS" value as the extdata field):3.6.1. Status Code 2.0
Status Code: 2.0 Status Description: Success. Status Exception Data: None. Description: iTIP operation succeeded.3.6.2. Status Code 2.1
Status Code: 2.1 Status Description: Success, but fallback taken on one or more property values. Status Exception Data: Property name and value MAY be specified. Description: iTIP operation succeeded with fallback on one or more property values.3.6.3. Status Code 2.2
Status Code: 2.2 Status Description: Success; invalid property ignored. Status Exception Data: Property name MAY be specified. Description: iTIP operation succeeded but a property was ignored.3.6.4. Status Code 2.3
Status Code: 2.3 Status Description: Success; invalid property parameter ignored. Status Exception Data: Property parameter name and value MAY be specified. Description: iTIP operation succeeded but a property parameter was ignored because it was invalid.
3.6.5. Status Code 2.4
Status Code: 2.4 Status Description: Success; unknown, non-standard property ignored. Status Exception Data: Non-standard property name MAY be specified. Description: iTIP operation succeeded but a property parameter was ignored because it was unknown.3.6.6. Status Code 2.5
Status Code: 2.5 Status Description: Success; unknown, non-standard property value ignored. Status Exception Data: Property and non-standard value MAY be specified. Description: iTIP operation succeeded but a property was ignored because its value was unknown.3.6.7. Status Code 2.6
Status Code: 2.6 Status Description: Success; invalid calendar component ignored. Status Exception Data: Calendar component sentinel (e.g., BEGIN: ALARM) MAY be specified. Description: iTIP operation succeeded but a component was ignored because it was invalid.3.6.8. Status Code 2.7
Status Code: 2.7 Status Description: Success; request forwarded to Calendar User. Status Exception Data: Original and forwarded calendar user addresses MAY be specified. Description: iTIP operation succeeded, and the request was forwarded to another Calendar User.
3.6.9. Status Code 2.8
Status Code: 2.8 Status Description: Success; repeating event ignored. Scheduled as a single component. Status Exception Data: RRULE or RDATE property name and value MAY be specified. Description: iTIP operation succeeded but a repeating event was truncated to a single instance.3.6.10. Status Code 2.9
Status Code: 2.9 Status Description: Success; truncated end date time to date boundary. Status Exception Data: DTEND property value MAY be specified. Description: iTIP operation succeeded but the end time was truncated to a date boundary.3.6.11. Status Code 2.10
Status Code: 2.10 Status Description: Success; repeating VTODO ignored. Scheduled as a single VTODO. Status Exception Data: RRULE or RDATE property name and value MAY be specified. Description: iTIP operation succeeded but a repeating to-do was truncated to a single instance.
3.6.12. Status Code 2.11
Status Code: 2.11 Status Description: Success; unbounded RRULE clipped at some finite number of instances. Status Exception Data: RRULE property name and value MAY be specified. Number of instances MAY also be specified. Description: iTIP operation succeeded but an unbounded repeating object was clipped to a finite number of instances.3.6.13. Status Code 3.0
Status Code: 3.0 Status Description: Invalid property name. Status Exception Data: Property name MAY be specified. Description: iTIP operation failed because of an invalid property name.3.6.14. Status Code 3.1
Status Code: 3.1 Status Description: Invalid property value. Status Exception Data: Property name and value MAY be specified. Description: iTIP operation failed because of an invalid property value.3.6.15. Status Code 3.2
Status Code: 3.2 Status Description: Invalid property parameter. Status Exception Data: Property parameter name and value MAY be specified. Description: iTIP operation failed because of an invalid property parameter.
3.6.16. Status Code 3.3
Status Code: 3.3 Status Description: Invalid property parameter value. Status Exception Data: Property parameter name and value MAY be specified. Description: iTIP operation failed because of an invalid property parameter value.3.6.17. Status Code 3.4
Status Code: 3.4 Status Description: Invalid calendar component sequence. Status Exception Data: Calendar component sentinel MAY be specified (e.g., BEGIN:VTIMEZONE). Description: iTIP operation failed because of an invalid component.3.6.18. Status Code 3.5
Status Code: 3.5 Status Description: Invalid date or time. Status Exception Data: Date/time value(s) MAY be specified. Description: iTIP operation failed because of an invalid date or time property.3.6.19. Status Code 3.6
Status Code: 3.6 Status Description: Invalid rule. Status Exception Data: RRULE property value MAY be specified. Description: iTIP operation failed because of an invalid rule property.
3.6.20. Status Code 3.7
Status Code: 3.7 Status Description: Invalid Calendar User. Status Exception Data: ATTENDEE property value MAY be specified. Description: iTIP operation failed because of an invalid ATTENDEE property.3.6.21. Status Code 3.8
Status Code: 3.8 Status Description: No authority. Status Exception Data: METHOD and ATTENDEE property values MAY be specified. Description: iTIP operation failed because an Attendee does not have suitable privileges for the operation.3.6.22. Status Code 3.9
Status Code: 3.9 Status Description: Unsupported version. Status Exception Data: VERSION property name and value MAY be specified. Description: iTIP operation failed because the calendar data version is not supported.3.6.23. Status Code 3.10
Status Code: 3.10 Status Description: Request entity too large. Status Exception Data: None. Description: iTIP operation failed because the calendar data was too large.
3.6.24. Status Code 3.11
Status Code: 3.11 Status Description: Required component or property missing. Status Exception Data: Component or property name MAY be specified. Description: iTIP operation failed because the calendar data did not contain a required property or component.3.6.25. Status Code 3.12
Status Code: 3.12 Status Description: Unknown component or property found. Status Exception Data: Component or property name MAY be specified. Description: iTIP operation failed because the calendar data contained an unknown property or component.3.6.26. Status Code 3.13
Status Code: 3.13 Status Description: Unsupported component or property found. Status Exception Data: Component or property name MAY be specified. Description: iTIP operation failed because the calendar data contained an unsupported property or component.3.6.27. Status Code 3.14
Status Code: 3.14 Status Description: Unsupported capability. Status Exception Data: METHOD or action MAY be specified. Description: iTIP operation failed because the operation is not supported.
3.6.28. Status Code 4.0
Status Code: 4.0 Status Description: Event conflict. Date/time is busy. Status Exception Data: DTSTART and DTEND property names and values MAY be specified. Description: iTIP operation failed because the event overlaps the date and time of another event.3.6.29. Status Code 5.0
Status Code: 5.0 Status Description: Request not supported. Status Exception Data: METHOD property value MAY be specified. Description: iTIP operation failed because the operation is not supported.3.6.30. Status Code 5.1
Status Code: 5.1 Status Description: Service unavailable. Status Exception Data: ATTENDEE property value MAY be specified. Description: iTIP operation failed because scheduling is not active.3.6.31. Status Code 5.2
Status Code: 5.2 Status Description: Invalid calendar service. Status Exception Data: ATTENDEE property value MAY be specified. Description: iTIP operation failed because there is no scheduling capability.
3.6.32. Status Code 5.3
Status Code: 5.3 Status Description: No scheduling support for user. Status Exception Data: ATTENDEE property value MAY be specified. Description: iTIP operation failed because scheduling is not enabled for an Attendee.3.7. Implementation Considerations
3.7.1. Working With Recurrence Instances
iCalendar includes a recurrence grammar to represent recurring events. The benefit of such a grammar is the ability to represent a number of events in a single object. However, while this simplifies creation of a recurring event, meeting instances still need to be referenced. For instance, an "Attendee" may decline the third instance of a recurring Friday event. Similarly, the "Organizer" may change the time or location to a single instance of the recurring event. Since implementations may elect to store recurring events as either a single event object or a collection of discrete, related event objects, the protocol is designed so that each recurring instance may be both referenced and versioned. Hence, implementations that choose to maintain per-instance properties (such as "ATTENDEE" property "PARTSTAT" parameter) may do so. However, the protocol does not require per-instance recognition unless the instance itself must be renegotiated. The scenarios for recurrence instance referencing are listed below. For purposes of simplification, a change to an event refers to a "trigger property." That is, a property that has a substantive effect on the meeting itself, such as start time, location, due date (for "VTODO" calendar components), and possibly description. "Organizer"-initiated actions: o deletes or changes a single instance of a recurring event o makes changes that affect all future instances o makes changes that affect all previous instances o deletes or modifies a previously changed instance
"Attendee"-initiated actions: o changes status for a particular recurrence instance o sends a "COUNTER" for a particular recurrence instance An instance of a recurring event is assigned a unique identification, "RECURRENCE-ID" property, when that instance is renegotiated. Negotiation may be necessary when a substantive change to the event or to-do has been made (such as changing the start time, end time, due date, or location). The "Organizer" can identify a specific recurrence instance using the "RECURRENCE-ID" property. The property value is equal to the date/time of the instance. If the "Organizer" wishes to change the "DTSTART", the original, unmodified "DTSTART" value of the instance is used as the value "RECURRENCE-ID" property, and the new "DTSTART" and "DTEND" values reflect the change.3.7.2. Attendee Property Considerations
The "ORGANIZER" property is required on published events, to-dos, and journal entries for two reasons. First, only the "Organizer" is allowed to update and redistribute an event or to-do component. It follows that the "ORGANIZER" property MUST be present in the event, to-do, or journal entry component so that the CUA has a basis for authorizing an update. Second, it is prudent to provide a point of contact for anyone who receives a published component, in case of problems. Email addresses that correspond to groups of "Calendar Users" could be specified as a mailto: URI [RFC2368] calendar user address. Sending email to such an address results in email being sent to multiple recipients. Such an address may be used as the value of an "ATTENDEE" property. Thus, it is possible that the recipient of a "REQUEST" does not appear explicitly in the list. It is recommended that the general approach to finding a "Calendar User" in an "Attendee" list be as follows: 1. Search for the "Calendar User" in the "Attendee" list where "CUTYPE=INDIVIDUAL" 2. Failing (1), look for "Attendees" where "CUTYPE=GROUP" or "CUTYPE=UNKNOWN". The CUA then determines if the "Calendar User" is a member of one of these groups. If so, the "REPLY" method sent to the "Organizer" MUST contain a new "ATTENDEE" property in which: * the "TYPE" property parameter is set to INDIVIDUAL
* the "MEMBER" property parameter is set to the name of the group 3. Failing (2), the CUA MAY ignore or accept the request as the "Calendar User" wishes.3.7.3. Extension Tokens
To make iCalendar objects extensible, new component, property, or property parameters can be used. Two types of extensions are defined by [RFC5545]: IANA-registered tokens ("iana-token") and experimental use tokens ("x-name"). A client SHOULD save "iana-token's" and MAY use them in replies. A client MAY save "x-name's" and MAY use them in replies. When delegating or forwarding messages to other CUs, a client SHOULD include "iana-token's" and "x-names's".4. Examples
4.1. Published Event Examples
In the calendaring and scheduling context, publication refers to the one-way transfer of event information. Consumers of published events simply incorporate the event into a calendar. No reply is expected. Individual "A" publishes an event. Individual "B" reads the event and incorporates it into their calendar. Events are published in several ways, including embedding the event as an object in a web page, emailing the event to a distribution list, or posting the event to a newsgroup. The table below illustrates the sequence of events between the publisher and the consumers of a published event. +----------------+-----------------------+--------------------------+ | Action | Organizer | Receiver | +----------------+-----------------------+--------------------------+ | Publish an | "A" sends or posts a | "B" reads a published | | event | PUBLISH message. | event. | | | | | | Publish an | "A" sends or posts a | "B" reads the updated | | updated event | PUBLISH message. | event. | | | | | | Cancel a | "A" sends or posts a | "B" reads the canceled | | published | CANCEL message. | event publication. | | event | | | +----------------+-----------------------+--------------------------+
4.1.1. A Minimal Published Event
The iCalendar object below describes a single event that begins on July 1, 1997 at 20:00 UTC. This event contains the minimum set of properties for a "PUBLISH" for a "VEVENT" calendar component. BEGIN:VCALENDAR METHOD:PUBLISH PRODID:-//Example/ExampleCalendarClient//EN VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com DTSTART:19970701T200000Z DTSTAMP:19970611T190000Z SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES UID:0981234-1234234-23@example.com END:VEVENT END:VCALENDAR4.1.2. Changing a Published Event
The iCalendar object below describes an update to the event described in Section 4.1.1; the time has been changed, an end time has been added, and the sequence number has been adjusted. BEGIN:VCALENDAR METHOD:PUBLISH VERSION:2.0 PRODID:-//Example/ExampleCalendarClient//EN BEGIN:VEVENT ORGANIZER:mailto:a@example.com DTSTAMP:19970612T190000Z DTSTART:19970701T210000Z DTEND:19970701T230000Z SEQUENCE:1 UID:0981234-1234234-23@example.com SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES END:VEVENT END:VCALENDAR The "UID" property is used by the client to identify the event. The "SEQUENCE" property indicates that this is a change to the event. The event with a matching "UID" and sequence number 0 is superseded by this event. The "SEQUENCE" property provides a reliable way to distinguish different versions of the same event. Each time an event is published, its sequence number is incremented. If a client receives
an event with a sequence number 5 and finds it has the same event with sequence number 2, the event SHOULD be updated. However, if the client received an event with sequence number 2 and finds it already has sequence number 5 of the same event, the event MUST NOT be updated.4.1.3. Canceling a Published Event
The iCalendar object below cancels the event described in Section 4.1.1. This cancels the event with "SEQUENCE" property of 0, 1, and 2. BEGIN:VCALENDAR METHOD:CANCEL VERSION:2.0 PRODID:-//Example/ExampleCalendarClient//EN BEGIN:VEVENT ORGANIZER:mailto:a@example.com COMMENT:DUKES forfeit the game SEQUENCE:2 UID:0981234-1234234-23@example.com DTSTAMP:19970613T190000Z END:VEVENT END:VCALENDAR4.1.4. A Rich Published Event
This example describes the same event as in Section 4.1.1, but in much greater detail. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:PUBLISH SCALE:GREGORIAN VERSION:2.0 BEGIN:VTIMEZONE TZID:America-Chicago TZURL:http://example.com/tz/America-Chicago BEGIN:STANDARD DTSTART:19671029T020000 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 TZOFFSETFROM:-0500 TZOFFSETTO:-0600 TZNAME:CST END:STANDARD BEGIN:DAYLIGHT DTSTART:19870405T020000 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
TZOFFSETFROM:-0600 TZOFFSETTO:-0500 TZNAME:CDT END:DAYLIGHT END:VTIMEZONE BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTACH:http://www.example.com/ CATEGORIES:SPORTS EVENT,ENTERTAINMENT CLASS:PRIVATE DESCRIPTION:MIDWAY STADIUM\n Big time game. MUST see.\n Expected duration:2 hours\n DTEND;TZID=America-Chicago:19970701T180000 DTSTART;TZID=America-Chicago:19970702T160000 DTSTAMP:19970614T190000Z STATUS:CONFIRMED LOCATION;VALUE=URI:http://stadium.example.com/ PRIORITY:2 RESOURCES:SCOREBOARD SEQUENCE:3 SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES UID:0981234-1234234-23@example.com RELATED-TO:0981234-1234234-14@example.com BEGIN:VALARM TRIGGER:-PT2H ACTION:DISPLAY DESCRIPTION:You should be leaving for the game now. END:VALARM BEGIN:VALARM TRIGGER:-PT30M ACTION:AUDIO END:VALARM END:VEVENT END:VCALENDAR The "RELATED-TO" field contains the "UID" property of a related calendar event. The "SEQUENCE" property 3 indicates that this event supersedes versions 0, 1, and 2.
4.1.5. Anniversaries or Events Attached to Entire Days
This example demonstrates the use of the "VALUE" parameter to tie a "VEVENT" to a day rather than a specific time. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:PUBLISH VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com DTSTAMP:19970614T190000Z UID:0981234-1234234-23@example.com DTSTART;VALUE=DATE:19970714 RRULE:FREQ=YEARLY;INTERVAL=1 SUMMARY: Bastille Day END:VEVENT END:VCALENDAR4.2. Group Event Examples
Group events are distinguished from published events in that they have "Attendees" and there is interaction between the "Attendees" and the "Organizer" with respect to the event. Individual "A" requests a meeting between individuals "A", "B", "C", and "D". Individual "B" confirms attendance to the meeting. Individual "C" declines attendance. Individual "D" tentatively confirms attendance. The following table illustrates the message flow between these individuals. "A", the CU scheduling the meeting, is referenced as the "Organizer".
+--------------+-----------------------+----------------------------+ | Action | "Organizer" | Attendee | +--------------+-----------------------+----------------------------+ | Initiate a | "A" sends a REQUEST | | | meeting | message to "B", "C", | | | request | and "D". | | | | | | | Accept the | | "B" sends a REPLY message | | meeting | | to "A" with its ATTENDEE | | request | | PARTSTAT parameter set to | | | | ACCEPTED. | | | | | | Decline the | | "C" sends a REPLY message | | meeting | | to "A" with its ATTENDEE | | request | | PARTSTAT parameter set to | | | | DECLINED. | | | | | | Tentatively | | "D" sends a REPLY message | | accept the | | to "A" with its ATTENDEE | | meeting | | PARTSTAT parameter set to | | request | | TENTATIVE. | | | | | | Confirm | "A" sends a REQUEST | | | meeting | message to "B" and | | | status with | "D" with updated | | | Attendees | information. | | +--------------+-----------------------+----------------------------+4.2.1. A Group Event Request
A sample meeting request is sent from "A" to "B", "C", and "D". "E" is also sent a copy of the request but is not expected to attend and need not reply. "E" illustrates how CUAs might implement an "FYI"- type feature. Note the use of the "ROLE" parameter. The default value for the "ROLE" parameter is "REQ-PARTICIPANT" and it need not be enumerated. In this case, we are using the value "NON- PARTICIPANT" to indicate "E" is a non-attending CU. The parameter is not needed on other "Attendees" since "PARTICIPANT" is the default value. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=A:mailto:a@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL;CN=B:mailto:b@example.com
ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL;CN=C:mailto:c@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL;CN=Hal:mailto:d@example.com ATTENDEE;RSVP=FALSE;CUTYPE=ROOM:conf_big@example.com ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:mailto:e@example.com DTSTAMP:19970611T190000Z DTSTART:19970701T200000Z DTEND:19970701T2100000Z SUMMARY:Conference UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 STATUS:CONFIRMED END:VEVENT END:VCALENDAR4.2.2. Reply to a Group Event Request
"Attendee" "B" accepts the meeting. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REPLY VERSION:2.0 BEGIN:VEVENT ATTENDEE;PARTSTAT=ACCEPTED:mailto:b@example.com ORGANIZER:mailto:a@example.com UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 REQUEST-STATUS:2.0;Success DTSTAMP:19970612T190000Z END:VEVENT END:VCALENDAR "B" could have declined the meeting or indicated tentative acceptance by setting the "ATTENDEE" "PARTSTAT" parameter to "DECLINED" or "TENTATIVE", respectively. Also, "REQUEST-STATUS" is not required in successful transactions.4.2.3. Update an Event
The event is moved to a different time. The combination of the "UID" property (unchanged) and the "SEQUENCE" (bumped to 1) properties indicate the update. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT
ORGANIZER:mailto:a@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:mailto:a@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:b@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:c@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL;CN=Hal:mailto:d@example.com ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE; CUTYPE=ROOM:mailto:conf@example.com ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:mailto:e@example.com DTSTART:19970701T180000Z DTEND:19970701T190000Z SUMMARY:Phone Conference UID:calsrv.example.com-873970198738777@example.com SEQUENCE:1 DTSTAMP:19970613T190000Z STATUS:CONFIRMED END:VEVENT END:VCALENDAR4.2.4. Countering an Event Proposal
"A" sends a "REQUEST" to "B" and "C". "B" makes a counter proposal to "A" to change the time and location. "A" sends the following "REQUEST": BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:mailto:a@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:b@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:c@example.com DTSTART:19970701T190000Z DTEND:19970701T200000Z SUMMARY:Discuss the Merits of the election results LOCATION:Green Conference Room UID:calsrv.example.com-873970198738777a@example.com SEQUENCE:0 DTSTAMP:19970611T190000Z STATUS:CONFIRMED END:VEVENT END:VCALENDAR
"B" sends "COUNTER" to "A", requesting changes to time and place. "B" uses the "COMMENT" property to communicate a rationale for the change. Note that the "SEQUENCE" property is not incremented on a "COUNTER". BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:COUNTER VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:mailto:a@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:b@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:c@example.com DTSTART:19970701T160000Z DTEND:19970701T170000Z DTSTAMP:19970612T190000Z SUMMARY:Discuss the Merits of the election results LOCATION:Blue Conference Room COMMENT:This time works much better and I think the big conference room is too big UID:calsrv.example.com-873970198738777a@example.com SEQUENCE:0 END:VEVENT END:VCALENDAR "A" accepts the changes from "B". To accept a counter proposal, the "Organizer" sends a new event "REQUEST" with an incremented sequence number. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:mailto:a@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:b@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:c@example.com DTSTAMP:19970613T190000Z DTSTART:19970701T160000Z DTEND:19970701T170000Z SUMMARY:Discuss the Merits of the election results - changed to meet B's schedule LOCATION:Blue Conference Room UID:calsrv.example.com-873970198738777@example.com SEQUENCE:1 STATUS:CONFIRMED
END:VEVENT END:VCALENDAR Instead, "A" rejects "B's" counter proposal. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:DECLINECOUNTER VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;RSVP=TRUE;CUTYPE=INDIVIDUAL:mailto:b@example.com COMMENT:Sorry, I cannot change this meeting time UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 DTSTAMP:19970614T190000Z END:VEVENT END:VCALENDAR4.2.5. Delegating an Event
When delegating an event request to another "Calendar User", the "Delegator" must both update the "Organizer" with a "REPLY" and send a request to the "Delegate". There is currently no protocol limitation to delegation depth. It is possible for the original delegate to delegate the meeting to someone else, and so on. When a request is delegated from one CUA to another, there are a number of responsibilities required of the "Delegator". The "Delegator" MUST: o Send a "REPLY" to the "Organizer" with the following updates: A. The "Delegator's" "ATTENDEE" property "PARTSTAT" parameter is set to "DELEGATED" and the "DELEGATED-TO" parameter is set to the address of the "Delegate". B. Add an additional "ATTENDEE" property for the "Delegate" with the "DELEGATED-FROM" property parameter set to the "Delegator". C. Indicate whether they want to continue to receive updates when the "Organizer" sends out updated versions of the event. Setting the "RSVP" property parameter to "TRUE" will cause the updates to be sent; setting it to "FALSE" causes no further updates to be sent. Note that in either case, if the "Delegate" declines the invitation, the "Delegator" will be notified.
o The "Delegator" MUST also send a copy of the original "REQUEST" method to the "Delegate", with changes (A) and (B), as detailed above applied. If the "Delegate" declines the meeting, the "Organizer" MUST send an update "REQUEST" to the "Delegator" so that the "Delegator" may elect to delegate the "REQUEST" to another CUA. +----------------+-----------------+--------------------------------+ | Action | "Organizer" | Attendee | +----------------+-----------------+--------------------------------+ | Initiate a | "A" sends a | | | meeting | REQUEST message | | | request | to "B" and "C". | | | | | | | Delegate: "C" | | "C" sends a REPLY to "A" with | | delegates to | | the ATTENDEE PARTSTAT | | "E" | | parameter set to DELEGATED and | | | | with a new ATTENDEE property | | | | for "E". "E's" ATTENDEE | | | | DELEGATED-FROM parameter is | | | | set to "C". "C's" ATTENDEE | | | | DELEGATED-TO parameter is set | | | | to "E". "C" sends REQUEST | | | | message to "E" with the | | | | original meeting request | | | | information. The PARTSTAT | | | | property parameter for "C" is | | | | set to DELEGATED and the | | | | DELEGATED-TO parameter is set | | | | to the address of "E". An | | | | ATTENDEE property is added for | | | | "E" and the DELEGATED-FROM | | | | parameter is set to the | | | | address of "C". | | | | | | Confirm | | "E" sends REPLY message to | | meeting | | "A", and optionally to "C", | | attendance | | with its PARTSTAT property | | | | parameter set to ACCEPTED. | | | | | | Optional: | "A" sends | | | Redistribute | REQUEST message | | | meeting to | to "B", "C", | | | Attendees | and "E". | | +----------------+-----------------+--------------------------------+
"C" responds to the "Organizer". BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REPLY VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;PARTSTAT=DELEGATED;DELEGATED- TO="mailto:e@example.com":mailto:c@example.com UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 REQUEST-STATUS:2.0;Success DTSTAMP:19970611T190000Z END:VEVENT END:VCALENDAR "Attendee" "C" delegates presence at the meeting to "E". BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;PARTSTAT=DELEGATED;DELEGATED- TO="mailto:e@example.com":mailto:c@example.com ATTENDEE;RSVP=TRUE; DELEGATED-FROM="mailto:c@example.com":mailto:e@example.com DTSTART:19970701T180000Z DTEND:19970701T200000Z SUMMARY:Phone Conference UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 STATUS:CONFIRMED DTSTAMP:19970611T190000Z END:VEVENT END:VCALENDAR4.2.6. Delegate Accepts the Meeting
To accept a delegated meeting, the delegate, "E", sends the following message to "A" and "C". BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REPLY VERSION:2.0
BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;PARTSTAT=ACCEPTED;DELEGATED- FROM="mailto:c@example.com":mailto:e@example.com ATTENDEE;PARTSTAT=DELEGATED; DELEGATED-TO="mailto:e@example.com":mailto:c@example.com UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 REQUEST-STATUS:2.0;Success DTSTAMP:19970614T190000Z END:VEVENT END:VCALENDAR4.2.7. Delegate Declines the Meeting
In this example, the "Delegate" declines the meeting request and sets the "ATTENDEE" property "PARTSTAT" parameter to "DECLINED". The "Organizer" SHOULD resend the "REQUEST" to "C" with the "PARTSTAT" parameter of the "Delegate" set to "DECLINED". This lets the "Delegator" know that the "Delegate" has declined and provides an opportunity to the "Delegator" to either accept the request or delegate it to another CU. "E" responds to "A" and "C". Note the use of the "COMMENT" property "E" uses to indicate why the delegation was declined. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REPLY VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;PARTSTAT=DELEGATED; DELEGATED-TO="mailto:e@example.com":mailto:c@example.com ATTENDEE;PARTSTAT=DECLINED; DELEGATED-FROM="mailto:c@example.com":mailto:e@example.com COMMENT:Sorry, I will be out of town at that time. UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 REQUEST-STATUS:2.0;Success DTSTAMP:19970614T190000Z END:VEVENT END:VCALENDAR "A" resends the "REQUEST" method to "C". "A" may also wish to express the fact that the item was delegated in the "COMMENT" property.
BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;PARTSTAT=DECLINED; DELEGATED-FROM="mailto:c@example.com":mailto:e@example.com ATTENDEE;RSVP=TRUE:mailto:c@example.com UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 SUMMARY:Phone Conference DTSTART:19970701T180000Z DTEND:19970701T200000Z DTSTAMP:19970614T200000Z COMMENT:DELEGATE (ATTENDEE mailto:e@example.com) DECLINED YOUR INVITATION END:VEVENT END:VCALENDAR4.2.8. Forwarding an Event Request
The protocol does not prevent an "Attendee" from "forwarding" a "VEVENT" calendar component to other "Calendar Users". Forwarding differs from delegation in that the forwarded "Calendar User" (often referred to as a "Party Crasher") does not replace the forwarding "Calendar User". Implementations are not required to add the "Party Crasher" to the "Attendee" list, and hence there is no guarantee that a "Party Crasher" will receive additional updates to the event. The forwarding "Calendar User" SHOULD NOT add the "Party Crasher" to the "Attendee" list. The "Organizer" MAY add the forwarded "Calendar User" to the "Attendee" list.4.2.9. Cancel a Group Event
Individual "A" requests a meeting between individuals "A", "B", "C", and "D". Individual "B" declines attendance to the meeting. Individual "A" decides to cancel the meeting. The following table illustrates the sequence of messages that would be exchanged between these individuals. Messages related to a previously canceled event ("SEQUENCE" property value is less than the "SEQUENCE" property value of the "CANCEL" message) MUST be ignored.
+-------------+---------------------+-------------------------------+ | Action | Organizer | Attendee | +-------------+---------------------+-------------------------------+ | Initiate a | "A" sends a REQUEST | | | meeting | message to "B", | | | request | "C", and "D". | | | | | | | Decline the | | "B" sends a REPLY message to | | meeting | | "A" with its PARTSTAT | | request | | parameter set to DECLINED. | | | | | | Cancel the | "A" sends a CANCEL | | | meeting | message to "B", | | | | "C", and "D". | | +-------------+---------------------+-------------------------------+ This example shows how "A" cancels the event. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:CANCEL VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;CUTYPE=INDIVIDUAL;mailto:a@example.com ATTENDEE;CUTYPE=INDIVIDUAL:mailto:b@example.com ATTENDEE;CUTYPE=INDIVIDUAL:mailto:c@example.com ATTENDEE;CUTYPE=INDIVIDUAL:mailto:d@example.com COMMENT:Mr. B cannot attend. It's raining. Lets cancel. UID:calsrv.example.com-873970198738777@example.com SEQUENCE:1 STATUS:CANCELLED DTSTAMP:19970613T190000Z END:VEVENT END:VCALENDAR4.2.10. Removing Attendees
"A" wants to remove "B" from a meeting. This is done by sending a "CANCEL" to "B" and removing "B" from the "Attendee" list in the master copy of the event.
+--------------------+-----------------------------------+----------+ | Action | Organizer | Attendee | +--------------------+-----------------------------------+----------+ | Remove "B" as an | "A" sends a CANCEL message to | | | Attendee | "B". | | | | | | | Update the master | "A" optionally sends the updated | | | copy of the event | event to the remaining Attendees. | | +--------------------+-----------------------------------+----------+ The original meeting includes "A", "B", "C", and "D". The example below shows the "CANCEL" that "A" sends to "B". Note that in the example below, the "STATUS" property is omitted. This is used when the meeting itself is cancelled and not when the intent is to remove an "Attendee" from the event. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:CANCEL VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE:mailto:b@example.com COMMENT:You're off the hook for this meeting UID:calsrv.example.com-873970198738777@example.com DTSTAMP:19970613T193000Z SEQUENCE:1 END:VEVENT END:VCALENDAR The updated master copy of the event is shown below. The "Organizer" MAY resend the updated event to the remaining "Attendees". Note that "B" has been removed. BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:mailto:a@example.com ATTENDEE;CUTYPE=INDIVIDUAL:mailto:c@example.com ATTENDEE;CUTYPE=INDIVIDUAL:mailto:d@example.com ATTENDEE;CUTYPE=ROOM:mailto:cr_big@example.com ATTENDEE;ROLE=NON-PARTICIPANT; RSVP=FALSE:mailto:e@example.com DTSTAMP:19970611T190000Z DTSTART:19970701T200000Z
DTEND:19970701T203000Z SUMMARY:Phone Conference UID:calsrv.example.com-873970198738777@example.com SEQUENCE:2 STATUS:CONFIRMED END:VEVENT END:VCALENDAR4.2.11. Replacing the Organizer
The scenario for this example begins with "A" as the "Organizer" for a recurring meeting with "B", "C", and "D". "A" receives a new job offer in another country and drops out of touch. "A" left no forwarding address or way to be reached. Using out-of-band communication, the other "Attendees" eventually learn what has happened and reach an agreement that "B" should become the new "Organizer" for the meeting. To do this, "B" sends out a new version of the event and the other "Attendees" agree to accept "B" as the new "Organizer". "B" also removes "A" from the event. When the "Organizer" is replaced, the "SEQUENCE" property value MUST be incremented. This is the message "B" sends to "C" and "D". BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REQUEST VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:b@example.com ATTENDEE;ROLE=CHAIR;STATUS=ACCEPTED:mailto:b@example.com ATTENDEE;CUTYPE=INDIVIDUAL:mailto:c@example.com ATTENDEE;CUTYPE=INDIVIDUAL:mailto:d@example.com DTSTAMP:19970611T190000Z DTSTART:19970701T200000Z DTEND:19970701T203000Z RRULE:FREQ=WEEKLY SUMMARY:Phone Conference UID:123456@example.com SEQUENCE:1 STATUS:CONFIRMED END:VEVENT END:VCALENDAR