Network Working Group E. York Internet-Draft Intended status: Standards Track M. Douglass Expires: 6 September 2022 5 March 2022 VPOLL: Consensus Scheduling Component for iCalendar draft-ietf-calext-vpoll-03 Abstract This specification introduces a new RFC5545 iCalendar component which allows for consensus scheduling, that is, voting on a number of alternative meeting or task alternatives. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 6 September 2022. Copyright Notice Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. York & Douglass Expires 6 September 2022 [Page 1] Internet-Draft VPOLL March 2022 Table of Contents 1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Terms and definitions . . . . . . . . . . . . . . . . . . . . 4 3.1. consensus scheduling . . . . . . . . . . . . . . . . . . 4 3.2. active Vpoll . . . . . . . . . . . . . . . . . . . . . . 5 3.3. voter . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Simple Consensus Scheduling . . . . . . . . . . . . . . . . . 5 4.1. The VPOLL Component: An Overview . . . . . . . . . . . . 5 4.2. The VPOLL Alternative Choices: An Overview . . . . . . . 7 4.3. VPOLL responses . . . . . . . . . . . . . . . . . . . . . 8 4.4. VPOLL updates . . . . . . . . . . . . . . . . . . . . . . 9 4.5. VPOLL Completion . . . . . . . . . . . . . . . . . . . . 11 4.6. Other Responses . . . . . . . . . . . . . . . . . . . . . 11 5. iCalendar Extensions . . . . . . . . . . . . . . . . . . . . 12 5.1. Updated Participant Type Value . . . . . . . . . . . . . 12 5.2. Updated Relation Type Value . . . . . . . . . . . . . . . 12 5.3. Updated Status Value . . . . . . . . . . . . . . . . . . 13 5.4. New Property Parameters . . . . . . . . . . . . . . . . . 13 5.4.1. Required . . . . . . . . . . . . . . . . . . . . . . 13 5.4.2. Stay-Informed . . . . . . . . . . . . . . . . . . . . 14 5.5. New Properties . . . . . . . . . . . . . . . . . . . . . 14 5.5.1. Accept-Response . . . . . . . . . . . . . . . . . . . 14 5.5.2. Poll-Completion . . . . . . . . . . . . . . . . . . . 15 5.5.3. Poll-Item-Id . . . . . . . . . . . . . . . . . . . . 16 5.5.4. Poll-Mode . . . . . . . . . . . . . . . . . . . . . . 16 5.5.5. Poll-properties . . . . . . . . . . . . . . . . . . . 17 5.5.6. Poll-Winner . . . . . . . . . . . . . . . . . . . . . 17 5.5.7. Reply-URL . . . . . . . . . . . . . . . . . . . . . . 18 5.5.8. Response . . . . . . . . . . . . . . . . . . . . . . 19 5.6. New Components . . . . . . . . . . . . . . . . . . . . . 19 5.6.1. VPOLL Component . . . . . . . . . . . . . . . . . . . 19 5.6.2. VOTE Component . . . . . . . . . . . . . . . . . . . 22 6. Poll Modes . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.1. POLL-MODE:BASIC . . . . . . . . . . . . . . . . . . . . . 24 6.1.1. Property restrictions . . . . . . . . . . . . . . . . 24 6.1.2. Outcome reporting . . . . . . . . . . . . . . . . . . 24 7. iTIP Extensions . . . . . . . . . . . . . . . . . . . . . . . 24 7.1. Methods . . . . . . . . . . . . . . . . . . . . . . . . . 24 7.2. Interoperability Models . . . . . . . . . . . . . . . . . 26 7.2.1. Delegation . . . . . . . . . . . . . . . . . . . . . 26 7.2.2. Acting on Behalf of Other Calendar Users . . . . . . 26 7.2.3. Component Revisions . . . . . . . . . . . . . . . . . 26 7.2.4. Message Sequencing . . . . . . . . . . . . . . . . . 26 7.3. Application Protocol Elements . . . . . . . . . . . . . . 26 7.3.1. Methods for VPOLL Calendar Components . . . . . . . . 26 7.3.2. Method: PUBLISH . . . . . . . . . . . . . . . . . . . 28 York & Douglass Expires 6 September 2022 [Page 2] Internet-Draft VPOLL March 2022 7.3.3. Method: REQUEST . . . . . . . . . . . . . . . . . . . 31 7.3.4. Method: REPLY . . . . . . . . . . . . . . . . . . . . 37 7.3.5. Method: CANCEL . . . . . . . . . . . . . . . . . . . 40 7.3.6. Method: REFRESH . . . . . . . . . . . . . . . . . . . 43 7.3.7. Method: POLLSTATUS . . . . . . . . . . . . . . . . . 45 8. CalDAV Extensions . . . . . . . . . . . . . . . . . . . . . . 47 8.1. Calendar Collection Properties . . . . . . . . . . . . . 47 8.1.1. CALDAV:supported-vpoll-component-sets . . . . . . . . 47 8.1.2. CALDAV:vpoll-max-items . . . . . . . . . . . . . . . 49 8.1.3. CALDAV:vpoll-max-active . . . . . . . . . . . . . . . 50 8.1.4. CALDAV:vpoll-max-voters . . . . . . . . . . . . . . . 50 8.1.5. CalDAV:even-more-properties . . . . . . . . . . . . . 51 8.1.6. Extensions to CalDAV scheduling . . . . . . . . . . . 51 8.2. Additional Preconditions for PUT, COPY, and MOVE . . . . 52 8.3. CalDAV:calendar-query Report . . . . . . . . . . . . . . 52 8.3.1. Example: Partial Retrieval of VPOLL . . . . . . . . . 53 8.4. CalDAV time ranges . . . . . . . . . . . . . . . . . . . 55 9. Security Considerations . . . . . . . . . . . . . . . . . . . 56 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 10.1. Parameter Registrations . . . . . . . . . . . . . . . . 56 10.2. Property Registrations . . . . . . . . . . . . . . . . . 57 10.3. POLL-MODE Registration Template . . . . . . . . . . . . 57 10.4. POLL-MODE Registrations . . . . . . . . . . . . . . . . 57 11. Normative References . . . . . . . . . . . . . . . . . . . . 58 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 59 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 60 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 61 1. Acknowledgements The authors would like to thank the members of the Calendaring and Scheduling Consortium (CalConnect) for contributing their ideas and support, in particular Cyrus Daboo for his help with the specification and implementations. 2. Introduction The currently existing approach to agreeing on meeting times using iTip [RFC5546] and/or iMip [RFC6047] has some significant failings. There is no useful bargaining or suggestion mechanism in iTip, only the ability for a potential attendee to accept or refuse or to counter with a time of their own choosing. York & Douglass Expires 6 September 2022 [Page 3] Internet-Draft VPOLL March 2022 Part of the problem is that for many potential attendees, their freebusy is not an accurate representation of their availability. In fact, when trying to schedule conference calls across different organizations, attendees may not be allowed to provide freebusy information or availability as this may reveal something of the organizations internal activities. A number of studies have shown that large amounts of time are spent trying to come to an agreement - up to and beyond 20 working hours per meeting. Many organizers fall back on other approaches such as phone calls and email to determine a suitable time. Online services have appeared as a result and these allow participants to vote on a number of alternatives without revealing or using freebusy or availability. When agreement is reached a conventional scheduling message may be sent to the attendees. This approach appears to reach consensus fairly rapidly. Peer pressure may have some bearing on this as all voters are usually able to see the current state of the voting and may adjust their own meeting schedules to make themselves available for a popular choice. The component and properties defined in this specification provide a standardized structure for this process and allow calendar clients and servers and web based services to interact. These structures also have uses beyond the relatively simple needs of most meeting organizers. The process of coming to consensus can also be viewed as a bidding process. 3. Terms and definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. The notation used in this memo to (re-)define iCalendar elements is the ABNF notation of [RFC5234] as used by [RFC5545]. Any syntax elements shown below that are not explicitly defined in this specification come from iCalendar [RFC5545]. Additionally the following terms are used: 3.1. consensus scheduling The process whereby users come to some agreement on meeting or task alternatives and then book that meeting or task. York & Douglass Expires 6 September 2022 [Page 4] Internet-Draft VPOLL March 2022 3.2. active Vpoll A VPoll may have a DTSTART, DTEND and DURATION which may define the start and end of the active voting period 3.3. voter A participant who votes on the alternatives. A voter need not be an attendee of any of the alternatives presented. 4. Simple Consensus Scheduling This specification defines components and properties which can be used for simple consensus scheduling but also have the generality to handle more complex cases. To provide an easy (and for many a sufficient) introduction to consensus scheduling and VPOLL we will outline the flow of information for the simple case of voting on a number of meeting alternatives which differ only in time of the meeting. In addition the voters will all be potential attendees. This specification not only defines data structures but adds new iTip methods, one used when consensus has been reached and one to distribute the current status of the poll. This document will show how a VPOLL object is used to inform voters of the state of a simple vote on some alternatives. 4.1. The VPOLL Component: An Overview The VPOLL component acts as a wrapper for a number of alternatives to be voted on, together with some properties and a new component used to maintain the state of the voting. For our simple example the following VPOLL properties and sub-components are either required or appropriate: DTSTAMP The usual [RFC5545] property. SEQUENCE The usual [RFC5545] property. See below for SEQUENCE behavior. UID The usual [RFC5545] property. ORGANIZER The usual [RFC5545] property. In general this need not be an organizer of any of the alternatives. In this simple outline we assume it is the same. SUMMARY The usual [RFC5545] property. This optional but recommended property provides the a short title to the poll. York & Douglass Expires 6 September 2022 [Page 5] Internet-Draft VPOLL March 2022 DESCRIPTION The usual [RFC5545] property. This optional property provides more details. DTEND The usual [RFC5545] property. This optional property provides a poll closing time and date after which the VPOLL is no longer active. POLL-MODE A new property which defines how the votes are used to obtain a result. For our use case it will take the value "BASIC" meaning one event will be chosen from the alternatives. POLL-COMPLETION A new property which defines who (server or client) chooses and/or submits the winning choice. In our example the value is "SERVER-SUBMIT" which means the client chooses the winner but the server will submit the winning choice. POLL-PROPERTIES A new property which defines which icalendar properties are being voted on. For our use case it will take the value "DTSTART, LOCATION" meaning only those properties are significant for voting. Other properties in the events may differ but are not considered significant for the voting process. PARTICIPANT There is one of these components for each voter with the PARTICIPANT-TYPE set to "VOTER". The CALENDAR-ADDRESS property identifies the voter and this component will contain one VOTE component for each item being voted on. VOTE A new component. There is one of these for each voter and choice. It usually contains at least a POLL-ITEM-ID property to identify the choice and a RESPONSE property to provide a vote. For more complex poll modes it may contain other information such as cost or estimated duration. VEVENT In our simple use case there will be multiple VEVENT sub- components defining the alternatives. Each will have a different date and or time for the meeting. EXAMPLE VPOLL with 3 voters and 3 alternative meetings: York & Douglass Expires 6 September 2022 [Page 6] Internet-Draft VPOLL March 2022 BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example//Example METHOD:REQUEST BEGIN:VPOLL POLL-MODE:BASIC POLL-COMPLETION:SERVER-SUBMIT POLL-PROPERTIES:DTSTART,LOCATION ORGANIZER:mailto:mike@example.com UID:sched01-1234567890 DTSTAMP:20120101T000000Z SUMMARY:What to do this week DTEND:20120101T000000Z BEGIN:PARTICIPANT PARTICIPANT-TYPE: VOTER CALENDAR-ADDRESS:mailto:cyrus@example.com END:PARTICIPANT BEGIN:PARTICIPANT PARTICIPANT-TYPE: VOTER CALENDAR-ADDRESS:mailto:eric@example.com END:PARTICIPANT BEGIN:PARTICIPANT PARTICIPANT-TYPE: VOTER CALENDAR-ADDRESS:mailto:mike@example.com END:PARTICIPANT BEGIN:VEVENT.......(with a poll-item-id=1) END:VEVENT BEGIN:VEVENT.......(with a poll-item-id=2) END:VEVENT BEGIN:VEVENT.......(with a poll-item-id=3) END:VEVENT END:VPOLL END:VCALENDAR As can be seen in the example above, there is an iTip METHOD property with the value REQUEST. The VPOLL object will be distributed to all the voters, either through iMip or through some VPOLL enabled service. 4.2. The VPOLL Alternative Choices: An Overview Within the VPOLL component we have the alternatives to vote on. In many respects these are standard [RFC5545] components. For our simple use case they are all VEVENT components. In addition to the usual [RFC5545] properties some extra properties are used for a VPOLL. POLL-ITEM-ID This provides a unique reference to the sub-component York & Douglass Expires 6 September 2022 [Page 7] Internet-Draft VPOLL March 2022 within the VPOLL. It's value SHOULD be a small integer. 4.3. VPOLL responses Upon receipt of a VPOLL REQUEST the voter will reply with a VPOLL component containing their vote. In our simple case it will have the following properties and components: DTSTAMP The usual [RFC5545] property. SEQUENCE The usual [RFC5545] property. See below for SEQUENCE behavior. UID Same as the request. ORGANIZER Same as the request. SUMMARY Same as the request. PARTICIPANT One only with a CALENDAR-ADDRESS identifying the voter replying. VOTE One per item being voted on. POLL-ITEM-ID One inside each VOTE component to identify the choice. RESPONSE One inside each VOTE component to specify the vote. Note that a voter can send a number of REPLYs for each REQUEST sent by the organizer. in BASIC mode each REPLY completely replaces the voting record for that voter for all components being voted on. In our example, if Eric responds and votes for items 1 and 2 and then responds again with a vote for only item 3, the final outcome is one vote on item 3. NOTE This is poll-mode specific behavior. EXAMPLE REPLY VPOLL from Cyrus: York & Douglass Expires 6 September 2022 [Page 8] Internet-Draft VPOLL March 2022 BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example//Example METHOD: REPLY BEGIN:VPOLL ORGANIZER:mailto:mike@example.com UID:sched01-1234567890 DTSTAMP:20120101T010000Z SUMMARY:What to do this week BEGIN:PARTICIPANT PARTICIPANT-TYPE: VOTER CALENDAR-ADDRESS:mailto:cyrus@example.com BEGIN:VOTE POLL-ITEM-ID:1 RESPONSE:50 COMMENT:Work on iTIP END:VOTE BEGIN:VOTE POLL-ITEM-ID:2 RESPONSE:100 COMMENT:Work on WebDAV END:VOTE BEGIN:VOTE POLL-ITEM-ID:3 RESPONSE:0 END:VOTE END:PARTICIPANT END:VPOLL END:VCALENDAR 4.4. VPOLL updates When the organizer receives a response from one or more voters the current state of the poll is sent to all voters. The new iTip method POLLSTATUS is used. The VPOLL can contain a reduced set of properties but MUST contain DTSTAMP, SEQUENCE (if not 0), UID, ORGANIZER and one or more PARTICIPANT components each populated with zero or more VOTE components. EXAMPLE York & Douglass Expires 6 September 2022 [Page 9] Internet-Draft VPOLL March 2022 BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example//Example METHOD: POLLSTATUS BEGIN:VPOLL ORGANIZER:mailto:mike@example.com UID:sched01-1234567890 DTSTAMP:20120101T020000Z SEQUENCE:0 SUMMARY:What to do this week BEGIN:PARTICIPANT PARTICIPANT-TYPE: VOTER CALENDAR-ADDRESS:mailto:cyrus@example.com BEGIN: VOTE POLL-ITEM-ID:1 RESPONSE:50 COMMENT:Work on iTIP END:VOTE BEGIN:VOTE POLL-ITEM-ID:2 RESPONSE:100 COMMENT:Work on WebDAV END:VOTE BEGIN:VOTE POLL-ITEM-ID:3 RESPONSE:0 END:VOTE END:PARTICIPANT BEGIN:PARTICIPANT PARTICIPANT-TYPE: VOTER CALENDAR-ADDRESS:mailto:eric@example.com BEGIN:VOTE POLL-ITEM-ID:1 RESPONSE:100 END:VOTE BEGIN:VOTE POLL-ITEM-ID:2 RESPONSE:100 END:VOTE BEGIN:VOTE POLL-ITEM-ID:3 RESPONSE:0 END:VOTE END:PARTICIPANT END:VPOLL END:VCALENDAR York & Douglass Expires 6 September 2022 [Page 10] Internet-Draft VPOLL March 2022 4.5. VPOLL Completion After a number of REPLY messages have been received the poll will be considered complete. If there is a DTEND on the poll the system may automatically close the poll, or the organizer may, at any time, consider the poll complete. A VPOLL can be completed (and effectively closed for voting) by sending an iTip REQUEST message with the VPOLL STATUS property set to COMPLETED. The poll winner is confirmed by sending a final iTip REQUEST message with the VPOLL STATUS property set to CONFIRMED. In this case the VPOLL component contains all the events being voted on along with a POLL-WINNER property to identify the winning event. As the POLL- COMPLETION property is set to SERVER-SUBMIT the server will submit the winning choice and when it has done so set the STATUS to "SUBMITTED". EXAMPLE VPOLL confirmation: BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example//Example METHOD: REQUEST BEGIN:VPOLL ORGANIZER:mailto:douglm@example.com UID:sched01-1234567890 DTSTAMP:20120101T030000Z COMPLETED:20120101T030000Z POLL-COMPLETION:SERVER-SUBMIT SEQUENCE:0 SUMMARY:What to do this week STATUS:CONFIRMED POLL-WINNER:3 BEGIN:VEVENT.......(with a poll-item-id=1) END:VEVENT BEGIN:VEVENT.......(with a poll-item-id=2) END:VEVENT BEGIN:VEVENT.......(with a poll-item-id=3) END:VEVENT END:VPOLL END:VCALENDAR 4.6. Other Responses A voter being asked to choose between a number of ORGANIZER supplied alternatives may find none of them acceptable or may simply not care. York & Douglass Expires 6 September 2022 [Page 11] Internet-Draft VPOLL March 2022 An alternative response, which may be disallowed by the ORGANIZER, is to send back the respondees availability or freebusy or even one or more new, alternative choices. This is accomplished by responding with a VOTE component which has no POLL-ITEM-ID property. In this case it MUST contain some alternative information. What form this takes depends on the poll mode in effect. 5. iCalendar Extensions 5.1. Updated Participant Type Value Participant type property values are defined in section 11.2.1. of [RFC9073]. This specification updates that type to include the new participant type VOTER to provide information about the voter and to contain their votes. Format Definition This property parameter is redefined by the following notation: partvalue /= "VOTER" Description The new property value indicates that the associated PARTICIPANT component identifies a voter in a VPOLL. 5.2. Updated Relation Type Value Relationship parameter type values are defined in section 3.2.15. of [RFC5545]. This specification updates that type to include the new relationship value POLL to provide a link to the VPOLL component in which the current component appears. Format Definition This property parameter is redefined by the following notation: reltypeparam /= "RELTYPE" "=" "POLL" ; Property value is a VPOLL uid Description This parameter can be specified on a property that references another related calendar component. The new parameter value indicates that the associated property references a VPOLL component which contains the current component. York & Douglass Expires 6 September 2022 [Page 12] Internet-Draft VPOLL March 2022 5.3. Updated Status Value Status property values are defined in section 3.8.1.11. of [RFC5545]. This specification updates that type to define valid VPOLL status values. Format Definition This property parameter is redefined by the following notation: statvalue /= statvalue-poll ; Status values for "VPOLL". statvalue-poll = "IN-PROCESS" / "COMPLETED" ; Poll has closed, ; nothing has been chosen yet / "CONFIRMED" ; Poll has closed and ; winning items confirmed / "SUBMITTED" ; The winning item has been ; submitted / "CANCELLED" Description These values allow clients and servers to handle the choosing and submission of winning choices. If the client is choosing and the server submitting then the client should set the POLL-WINNER property, set the status to CONFIRMED and save the poll. When the server submits the winning choice it will set the status to SUBMITTED. Figure 1 5.4. New Property Parameters 5.4.1. Required Parameter name REQUIRED Purpose To specify whether the associated property is required in the current context. Format Definition This parameter is defined by the following notation: requirededparam = "REQUIRED" "=" ("TRUE" / "FALSE") ; Default is FALSE Description This parameter MAY be specified on REPLY-URL and, if the value is TRUE, indicates the organizer requires all replies to be made via the specified service rather than iTip replies. York & Douglass Expires 6 September 2022 [Page 13] Internet-Draft VPOLL March 2022 5.4.2. Stay-Informed Parameter name STAY-INFORMED Purpose To specify the voter also wants to be added as an ATTENDEE when the poll is confirmed. Format Definition This parameter is defined by the following notation: stayinformedparam = "STAY-INFORMED" "=" ("TRUE" / "FALSE") ; Default is FALSE Description This parameter MAY be specified on the CALENDAR-ADDRESS property in the PARTICIPANT component and, if the value is TRUE, indicates the voter wishes to be added to the final choice as a non participant. 5.5. New Properties 5.5.1. Accept-Response Property name ACCEPT-RESPONSE Purpose This property is used in VPOLL to indicate the types of component that may be supplied in a response. Property Parameters Non-standard or iana parameters can be specified on this property. Conformance This property MAY be specified in a VPOLL component. Description When used in a VPOLL this property indicates what allowable component types may be returned in a reply. Typically this would allow a voter to respond with their freebusy or availability rather than choosing one of the presented alternatives. If this property is not present voters are only allowed to respond to the choices in the request. Format Definition This property is defined by the following notation: acceptresponse = "ACCEPT-RESPONSE" acceptresponseparams ":" iana-token ("," iana-token) CRLF acceptresponseparams = *(";" other-param) York & Douglass Expires 6 September 2022 [Page 14] Internet-Draft VPOLL March 2022 5.5.2. Poll-Completion Property name POLL-COMPLETION Purpose This property is used in VPOLL to indicate whether the client or server is responsible for choosing and/or submitting the winner(s). Description When a VPOLL is stored on a server which is capable of handling choosing and submission of winning choices a value of SERVER indicates that the server should close the poll, choose the winner and submit whenever it is appropriate to do so. For example, in BASIC poll-mode, reaching the DTEND of the poll could trigger this server side action. Server initiated submission requires that the submitted choice MUST be a valid calendaring component. POLL-COMPLETION=SERVER-SUBMIT allows the client to set the poll- winner, set the status to CONFIRMED and then store the poll on the server. The server will then submit the winning choice and set the status to SUBMITTED. Format Definition This property is defined by the following notation: poll-completion = "POLL-COMPLETION" pcparam ":" pcvalue CRLF pcparam = *(";" other-param) pcvalue = "SERVER" ; The server is responsible for both choosing and ; submitting the winner(s) / "SERVER-SUBMIT" ; The server is responsible for ; submitting the winner(s). The client chooses. / "SERVER-CHOICE" ; The server is responsible for ; choosing the winner(s). The client will submit. / "CLIENT" ; The client is responsible for both choosing and ; submitting the winner(s) / iana-token / x-name ;Default is CLIENT Example The following is an example of this property: POLL-COMPLETION: SERVER-SUBMIT York & Douglass Expires 6 September 2022 [Page 15] Internet-Draft VPOLL March 2022 5.5.3. Poll-Item-Id Property name POLL-ITEM-ID Purpose This property is used in VPOLL child components as an identifier. Value type INTEGER Property Parameters Non-standard parameters can be specified on this property. Conformance This property MUST be specified in a VOTE component and in VPOLL choice items. Description In a METHOD:REQUEST each choice component MUST have a POLL-ITEM-ID property. Each set of components with the same POLL- ITEM-ID value represents one overall set of items to be voted on. POLL-ITEM-ID SHOULD be a unique small integer for each component or set of components. If it remains the same between REQUESTs then the previous response for that component MAY be re-used. To force a re-vote on a component due to a significant change, the POLL-ITEM-ID MUST change. Format Definition This property is defined by the following notation: pollitemid = "POLL-ITEM-ID" pollitemdparams ":" integer CRLF pollitemidparams = *( (";" other-param) ) 5.5.4. Poll-Mode Property name POLL-MODE Purpose This property is used in VPOLL to indicate what voting mode is to be applied. Property Parameters Non-standard or iana parameters can be specified on this property. Conformance This property MAY be specified in a VPOLL component or its sub-components. York & Douglass Expires 6 September 2022 [Page 16] Internet-Draft VPOLL March 2022 Description The poll mode defines how the votes are applied to obtain a result. BASIC mode, the default, means that the voters are selecting one component (or group of components) with a given POLL=ITEM-ID. Other polling modes may be defined in updates to this specification. These may allow for such modes as ranking or task assignment. Format Definition This property is defined by the following notation: pollmode = "POLL-MODE" pollmodeparams ":" ("BASIC" / iana-token / other-token) CRLF pollmodeparams = *(";" other-param) 5.5.5. Poll-properties Property name POLL-PROPERTIES Purpose This property is used in VPOLL to define which icalendar properties are being voted on. Property Parameters Non-standard or iana parameters can be specified on this property. Conformance This property MAY be specified in a VPOLL component. Description This property defines which icalendar properties are significant in the voting process. It may not be clear to voters which properties are varying in a significant manner. Clients may use this property to highlight those listed properties. Format Definition This property is defined by the following notation: pollproperties = "POLL-PROPERTIES" pollpropparams ":" text *("," text) CRLF pollpropparams = *(";" other-param) 5.5.6. Poll-Winner Property name POLL-WINNER Purpose This property is used in a basic mode VPOLL to indicate which of the VPOLL sub-components won. York & Douglass Expires 6 September 2022 [Page 17] Internet-Draft VPOLL March 2022 Value type INTEGER Property Parameters Non-standard parameters can be specified on this property. Conformance This property MAY be specified in a VPOLL component. Description For poll confirmation each child component MUST have a POLL-ITEM-ID property. For basic mode the VPOLL component SHOULD have a POLL-WINNER property which MUST correspond to one of the POLL-ITEM-ID properties and indicates which sub-component was the winner. Format Definition This property is defined by the following notation: pollwinner = "POLL-WINNER" pollwinnerparams ":" integer CRLF pollwinnerparams = *(";" other-param) ; Used with a STATUS:CONFIRMED VPOLL to indicate which ; components have been confirmed 5.5.7. Reply-URL Property name REPLY-URL Purpose This property may be used in scheduling messages to indicate additional reply methods, for example a web-service. Value type URI Property Parameters Non-standard, required or iana parameters can be specified on this property. Conformance This property MAY be specified in a VPOLL component. Description When used in a scheduling message this property indicates additional or required services that can be used to reply. Typically this would be a web service of some form. Format Definition This property is defined by the following notation: York & Douglass Expires 6 September 2022 [Page 18] Internet-Draft VPOLL March 2022 reply-url = "REPLY-URL" reply-urlparams ":" uri CRLF reply-urlparams = *( (";" requiredparam) / (";" other-param) ) 5.5.8. Response Property name RESPONSE Purpose To specify a response vote. Value type INTEGER Format Definition This property is defined by the following notation: response = "RESPONSE" response-params ":" integer CRLF ; integer value 0..100 responseparams = *(";" other-param) Description This parameter can be specified on the POLL-ITEM-ID property to provide the value of the voters response. This parameter allows for fine grained responses which are appropriate to some applications. For the case of individuals voting for a choice of events, client applications SHOULD conform to the following convention: * 0 - 39 A "NO vote" * 40 - 79 A "MAYBE" vote * 80 - 89 A "YES - but not preferred vote" * 90-100 A "YES" vote. Clients MUST preserve the response value when there is no change from the user even if they have a UI with fixed states (e.g. yes/no/maybe). 5.6. New Components 5.6.1. VPOLL Component Component name VPOLL York & Douglass Expires 6 September 2022 [Page 19] Internet-Draft VPOLL March 2022 Purpose This component provides a mechanism by which voters can vote on provided choices. Format Definition This property is defined by the following notation: York & Douglass Expires 6 September 2022 [Page 20] Internet-Draft VPOLL March 2022 pollc = "BEGIN" ":" "VPOLL" CRLF pollprop *participantc *eventc *todoc *journalc *freebusyc *availabilityc *alarmc *iana-comp *x-comp "END" ":" "VPOLL" CRLF pollprop = *( ; ; The following are REQUIRED, ; but MUST NOT occur more than once. ; dtstamp / uid / organizer / ; ; The following are OPTIONAL, ; but MUST NOT occur more than once. ; acceptresponse / class / created / completed / description / dtstart / last-mod / pollmode / pollproperties / priority / seq / status / summary / url / ; ; Either 'dtend' or 'duration' MAY appear in ; a 'pollprop', but 'dtend' and 'duration' ; MUST NOT occur in the same 'pollprop'. ; 'duration' MUST only occur when 'dtstart' ; is present ; dtend / duration / ; ; The following are OPTIONAL, ; and MAY occur more than once. ; attach / categories / comment / contact / rstatus / related / resources / x-prop / iana-prop ; ; The following is OPTIONAL, it SHOULD appear ; once for the confirmation of a BASIC mode ; VPOLL. Other modes may define differing ; requirements. ; pollwinner / ; ) Description This component provides a mechanism by which voters can vote on provided choices. The outcome depends upon the POLL-MODE in effect. York & Douglass Expires 6 September 2022 [Page 21] Internet-Draft VPOLL March 2022 The PARTICIPANT components in VPOLL requests provide information on each recipient who will be voting - both their identity through the CALENDAR-ADDRESS property and their votes through the VOTE components. If specified, the "DTSTART" property defines the start or opening of the poll active period. If absent the poll is presumed to have started when created. If "DTSTART" is present "DURATION" MAY be specified and indicates the duration, and hence the ending, of the poll. The value of the property MUST be a positive duration. "DTEND" MAY be specified with or without "DTSTART" and indicates the ending of the poll. If DTEND is specified it MUST be later than the DTSTART or CREATED property. If one or more VALARM components are included in the VPOLL they are not components to be voted on and MUST NOT contain a POLL- ITEM-ID property. VALARM sub-components may be used to provide warnings to the user when polls are due to start or end. 5.6.2. VOTE Component Component name VOTE Purpose This component provides a mechanism by which voters can vote on provided choices. Conformance This component may be specified zero or more times in a PARTICIPANT component which identifies the voter. Format Definition This property is defined by the following notation: York & Douglass Expires 6 September 2022 [Page 22] Internet-Draft VPOLL March 2022 votec = "BEGIN" ":" "VOTE" CRLF voteprop *eventc *todoc *journalc *freebusyc *availabilityc *alarmc *iana-comp *x-comp "END" ":" "VOTE" CRLF voteprop = *( ; ; The following are REQUIRED, ; but MUST NOT occur more than once. ; pollitemid / response / ; ; The following are OPTIONAL, ; and MAY occur more than once. ; comment / x-prop / iana-prop ; ) Description This component appears inside the PARTICIPANT component with a PARTICIPANT-TYPE of VOTER to identify the voter. This component contains that participants responses. The required and optional properties and their meanings will depend upon the POLL-MODE in effect. For any POLL-MODE, POLL-ITEM-ID is used to associate the information to a choice supplied by the organizer. This means that each VOTE component only provides information about that choice. If allowed by the POLL-MODE a VOTE component without a POLL-ITEM- ID may be provided in a REPLY to indicate a possible new choice or to provide information to the ORGANIZER - such as the respondees availability. 6. Poll Modes The VPOLL component is intended to allow for various forms of polling. The particular form in efffect is indicated by the POLL- MODE property. New poll modes can be registered by including a completed POLL-MODE Registration Template (see Section 10.3) in a published RFC. York & Douglass Expires 6 September 2022 [Page 23] Internet-Draft VPOLL March 2022 6.1. POLL-MODE:BASIC BASIC poll mode is the form of voting in which one possible outcome is chosen from a set of possibilities. Usually this will be represented as a number of possible event objects one of which will be selected. 6.1.1. Property restrictions This poll mode has the following property requirements: POLL-ITEM-ID Each contained sub-component that is being voted upon MUST contain a POLL-ITEM_ID property which is unique within the context of the POLL. The value MUST NOT be reused when events are removed and/or added to the poll. POLL-WINNER On confirmation of the poll this property MUST be present and identifies the winning component. 6.1.2. Outcome reporting To confirm the winner the POLL-WINNER property MUST be present and the STATUS MUST be set to CONFIRMED. When the winning VEVENT or VTODO is not a scheduled entity, that is, it has no ORGANIZER or ATTENDEES it MUST be assigned an ORGANIZER property and a list of non-participating ATTENDEEs. This allows the winning entity to be distributed to the participants through iTip or some other protocol. 7. iTIP Extensions This specification introduces a number of extensions to [RFC5546]. In group scheduling the parties involved are organizer and attendees. In VPOLL the parties are organizer and voters. For many of the iTip processing rules the voters take the place of attendees. 7.1. Methods There are some extensions to the behavior of iTip methods for a VPOLL object and two new methods are defined. York & Douglass Expires 6 September 2022 [Page 24] Internet-Draft VPOLL March 2022 +================+================================================+ | Method | Description | +================+================================================+ | PUBLISH | No changes (yet) | +----------------+------------------------------------------------+ | REQUEST | Each child component MUST have a POLL-ITEM-ID | | | property. Each set of components with the | | | same POLL-ITEM-ID value represents one overall | | | set of items to be voted on. | +----------------+------------------------------------------------+ | REPLY | There MUST be a single VPOLL component which | | | MUST have: either one or more POLL-ITEM-ID | | | properties with a RESPONSE param matching that | | | from a REQUEST or a VFREEBUSY or VAVAILABILITY | | | child component showing overall busy/available | | | time. The VPOLL MUST have one voter only. | +----------------+------------------------------------------------+ | ADD | Not supported for VPOLL. | +----------------+------------------------------------------------+ | CANCEL | There MUST be a single VPOLL component with | | | UID | +----------------+------------------------------------------------+ | | matching that of the poll being cancelled. | +----------------+------------------------------------------------+ | REFRESH | The organizer returns a METHOD:REQUEST with | | | the current full state, or a METHOD:CANCEL or | | | an error if no matching poll is found. | +----------------+------------------------------------------------+ | COUNTER | Not supported for VPOLL. | +----------------+------------------------------------------------+ | DECLINECOUNTER | Not supported for VPOLL. | +----------------+------------------------------------------------+ | POLLSTATUS | Used to send the current state of the poll to | | | all voters. The VPOLL can contain a reduced | | | set of properties but MUST contain DTSTAMP, | | | SEQUENCE (if not 0), UID, ORGANIZER and | | | PARTICIPANTS. | +----------------+------------------------------------------------+ Table 1 The following table shows the above methods broken down by who can send them with VPOLL components. York & Douglass Expires 6 September 2022 [Page 25] Internet-Draft VPOLL March 2022 +============+================================================+ | Originator | Methods | +============+================================================+ | Organizer | CANCEL, PUBLISH, REQUEST, POLLSTATUS | +------------+------------------------------------------------+ | Voter | REPLY, REFRESH, REQUEST (only when delegating) | +------------+------------------------------------------------+ Table 2 7.2. Interoperability Models Most of the standard iTip specification applies with respect to organizer and voters. 7.2.1. Delegation TBD 7.2.2. Acting on Behalf of Other Calendar Users TBD 7.2.3. Component Revisions * Need to talk about what a change in SEQUENCE means * Sequence change forces a revote. * New voter - no sequence change * Add another poll set or change poll item ids or any change to a child * component - bump sequence 7.2.4. Message Sequencing TBD 7.3. Application Protocol Elements 7.3.1. Methods for VPOLL Calendar Components This section defines the property set restrictions for the method types that are applicable to the "VPOLL" calendar component. Each method is defined using a table that clarifies the property constraints that define the particular method. York & Douglass Expires 6 September 2022 [Page 26] Internet-Draft VPOLL March 2022 The presence column uses the following values to assert whether a property is required or optional, and the number of times it may appear in the iCalendar object. +================+=================================================+ | Presence Value | Description | +================+=================================================+ | 1 | One instance MUST be present. | +----------------+-------------------------------------------------+ | 1+ | At least one instance MUST be present. | +----------------+-------------------------------------------------+ | 0 | Instances of this property MUST NOT be present. | +----------------+-------------------------------------------------+ | 0+ | Multiple instances MAY be present. | +----------------+-------------------------------------------------+ | 0 or 1 | Up to 1 instance of this property MAY be | | | present. | +----------------+-------------------------------------------------+ Table 3 The following summarizes the methods that are defined for the "VPOLL" calendar component. York & Douglass Expires 6 September 2022 [Page 27] Internet-Draft VPOLL March 2022 +============+======================================================+ | Method | Description | +============+======================================================+ | PUBLISH | Post notification of an poll. Used primarily | | | as a method of advertising the existence of a | | | poll. | +------------+------------------------------------------------------+ | REQUEST | To make a request for a poll. This is an | | | explicit invitation to one or more voters. | | | Poll requests are also used to update, change | | | or confirm an existing poll. Clients that | | | cannot handle REQUEST MAY degrade the poll to | | | view it as a PUBLISH. REQUEST SHOULD NOT be | | | used just to set the status of the poll - | | | POLLSTATUS provides a more compact approach. | +------------+------------------------------------------------------+ | REPLY | Reply to a poll request. Voters may set | | | their RESPONSE parameter to supply the | | | current vote in the range 0 to 100. | +------------+------------------------------------------------------+ | CANCEL | Cancel a poll. | +------------+------------------------------------------------------+ | REFRESH | A request is sent to an Organizer by a Voter | | | asking for the latest version of a poll to be | | | resent to the requester. | +------------+------------------------------------------------------+ | POLLSTATUS | Used to send the current state of the poll to | | | all voters. The VPOLL can contain a reduced | | | set of properties but MUST contain DTSTAMP, | | | SEQUENCE (if not 0), UID, ORGANIZER and | | | PARTICIPANT. | +------------+------------------------------------------------------+ Table 4 7.3.2. Method: PUBLISH The "PUBLISH" method in a "VPOLL" calendar component is an unsolicited posting of an iCalendar object. Any CU may add published components to their calendar. The "Organizer" MUST be present in a published iCalendar component. "Voters" MUST NOT be present. Its expected usage is for encapsulating an arbitrary poll as an iCalendar object. The "Organizer" may subsequently update (with another "PUBLISH" method) or cancel (with a "CANCEL" method) a previously published "VPOLL" calendar component. Note Not clear how useful this is but needs some work on transmitting the current vote without any voter identification. York & Douglass Expires 6 September 2022 [Page 28] Internet-Draft VPOLL March 2022 This method type is an iCalendar object that conforms to the following property constraints: +=================+==========+=====================================+ | Component/ | Presence | Comment | | Property | | | +=================+==========+=====================================+ | METHOD | 1 | MUST equal PUBLISH. | +-----------------+----------+-------------------------------------+ | VPOLL | 1+ | | +-----------------+----------+-------------------------------------+ | DTSTAMP | 1 | | +-----------------+----------+-------------------------------------+ | DTSTART | 0 or 1 | If present defines the start of the | | | | poll. Otherwise the poll starts | | | | when it is created and distributed. | +-----------------+----------+-------------------------------------+ | ORGANIZER | 1 | | +-----------------+----------+-------------------------------------+ | SUMMARY | 1 | Can be null. | +-----------------+----------+-------------------------------------+ | UID | 1 | | +-----------------+----------+-------------------------------------+ | SEQUENCE | 0 or 1 | MUST be present if value is greater | | | | than 0; MAY be present if 0. | +-----------------+----------+-------------------------------------+ | ACCEPT-RESPONSE | 0 or 1 | | +-----------------+----------+-------------------------------------+ | ATTACH | 0+ | | +-----------------+----------+-------------------------------------+ | CATEGORIES | 0+ | | +-----------------+----------+-------------------------------------+ | CLASS | 0 or 1 | | +-----------------+----------+-------------------------------------+ | COMMENT | 0+ | | +-----------------+----------+-------------------------------------+ | COMPLETED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | CONTACT | 0 or 1 | | +-----------------+----------+-------------------------------------+ | CREATED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | DESCRIPTION | 0 or 1 | Can be null. | +-----------------+----------+-------------------------------------+ | DTEND | 0 or 1 | If present, DURATION MUST NOT be | | | | present. | +-----------------+----------+-------------------------------------+ | DURATION | 0 or 1 | If present, DTEND MUST NOT be | York & Douglass Expires 6 September 2022 [Page 29] Internet-Draft VPOLL March 2022 | | | present. | +-----------------+----------+-------------------------------------+ | LAST-MODIFIED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | POLL-ITEM-ID | 0 | | +-----------------+----------+-------------------------------------+ | POLL-MODE | 0 or 1 | | +-----------------+----------+-------------------------------------+ | POLL-PROPERTIES | 0 or 1 | | +-----------------+----------+-------------------------------------+ | PRIORITY | 0 or 1 | | +-----------------+----------+-------------------------------------+ | RELATED-TO | 0+ | | +-----------------+----------+-------------------------------------+ | RESOURCES | 0+ | | +-----------------+----------+-------------------------------------+ | STATUS | 0 or 1 | MAY be one of COMPLETED/CONFIRMED/ | | | | CANCELLED. | +-----------------+----------+-------------------------------------+ | URL | 0 or 1 | | +-----------------+----------+-------------------------------------+ | IANA-PROPERTY | 0+ | | +-----------------+----------+-------------------------------------+ | X-PROPERTY | 0+ | | +-----------------+----------+-------------------------------------+ | PARTICIPANT | 0+ | Only PARTICIPANT components with | | | | PARTICIPANT-TYPE not equal to | | | | "VOTER" - that is, no voters | +-----------------+----------+-------------------------------------+ | REQUEST-STATUS | 0 | | +-----------------+----------+-------------------------------------+ | VALARM | 0+ | | +-----------------+----------+-------------------------------------+ | VEVENT | 0+ | Depending upon the poll mode in | | | | effect there MAY be candidate | | | | components included in the poll | | | | component. | +-----------------+----------+-------------------------------------+ | VFREEBUSY | 0 | | +-----------------+----------+-------------------------------------+ | VJOURNAL | 0+ | Depending upon the poll mode in | | | | effect there MAY be candidate | | | | components included in the poll | | | | component. | +-----------------+----------+-------------------------------------+ | VTODO | 0+ | Depending upon the poll mode in | | | | effect there MAY be candidate | | | | components included in the poll | York & Douglass Expires 6 September 2022 [Page 30] Internet-Draft VPOLL March 2022 | | | component. | +-----------------+----------+-------------------------------------+ | VTIMEZONE | 0+ | MUST be present if any date/time | | | | refers to a timezone. | +-----------------+----------+-------------------------------------+ | IANA-COMPONENT | 0+ | | +-----------------+----------+-------------------------------------+ | X-COMPONENT | 0+ | | +-----------------+----------+-------------------------------------+ Table 5: Constraints for a METHOD:PUBLISH of a VPOLL 7.3.3. Method: REQUEST The "REQUEST" method in a "VPOLL" component provides the following scheduling functions: * Invite "Voters" to respond to the poll. * Change the items being voted upon. * Complete or confirm the poll. * Response to a "REFRESH" request. * Update the details of an existing vpoll. * Update the status of "Voters". * Forward a "VPOLL" to another uninvited CU. * For an existing "VPOLL" calendar component, delegate the role of "Voter" to another CU. * For an existing "VPOLL" calendar component, change the role of "Organizer" to another CU. The "Organizer" originates the "REQUEST". The recipients of the "REQUEST" method are the CUs voting in the poll, the "Voters". "Voters" use the "REPLY" method to convey votes to the "Organizer". The "UID" and "SEQUENCE" properties are used to distinguish the various uses of the "REQUEST" method. If the "UID" property value in the "REQUEST" is not found on the recipient's calendar, then the "REQUEST" is for a new "VPOLL" calendar component. If the "UID" property value is found on the recipient's calendar, then the "REQUEST" is for an update, or a reconfirmation of the "VPOLL" calendar component. York & Douglass Expires 6 September 2022 [Page 31] Internet-Draft VPOLL March 2022 For the "REQUEST" method only a single iCalendar object is permitted. This method type is an iCalendar object that conforms to the following property constraints: +=================+==========+=====================================+ | Component/ | Presence | Comment | | Property | | | +=================+==========+=====================================+ | METHOD | 1 | MUST be REQUEST. | +-----------------+----------+-------------------------------------+ | VPOLL | 1 | | +-----------------+----------+-------------------------------------+ | PARTICIPANT | 1+ | Identified as voters with the | | | | PARTICIPANT-TYPE=VOTER | +-----------------+----------+-------------------------------------+ | DTSTAMP | 1 | | +-----------------+----------+-------------------------------------+ | DTSTART | 0 or 1 | If present defines the start of the | | | | poll. Otherwise the poll starts | | | | when it is created and distributed. | +-----------------+----------+-------------------------------------+ | ORGANIZER | 1 | | +-----------------+----------+-------------------------------------+ | SEQUENCE | 0 or 1 | MUST be present if value is greater | | | | than 0; MAY be present if 0. | +-----------------+----------+-------------------------------------+ | SUMMARY | 1 | Can be null. | +-----------------+----------+-------------------------------------+ | UID | 1 | | +-----------------+----------+-------------------------------------+ | ACCEPT-RESPONSE | 0 or 1 | | +-----------------+----------+-------------------------------------+ | ATTACH | 0+ | | +-----------------+----------+-------------------------------------+ | CATEGORIES | 0+ | | +-----------------+----------+-------------------------------------+ | CLASS | 0 or 1 | | +-----------------+----------+-------------------------------------+ | COMMENT | 0+ | | +-----------------+----------+-------------------------------------+ | COMPLETED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | CONTACT | 0+ | | +-----------------+----------+-------------------------------------+ | CREATED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | DESCRIPTION | 0 or 1 | Can be null. | York & Douglass Expires 6 September 2022 [Page 32] Internet-Draft VPOLL March 2022 +-----------------+----------+-------------------------------------+ | DTEND | 0 or 1 | If present, DURATION MUST NOT be | | | | present. | +-----------------+----------+-------------------------------------+ | DURATION | 0 or 1 | If present, DTEND MUST NOT be | | | | present. | +-----------------+----------+-------------------------------------+ | GEO | 0 or 1 | | +-----------------+----------+-------------------------------------+ | LAST-MODIFIED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | LOCATION | 0 or 1 | | +-----------------+----------+-------------------------------------+ | POLL-ITEM-ID | 0 | | +-----------------+----------+-------------------------------------+ | POLL-MODE | 0 or 1 | | +-----------------+----------+-------------------------------------+ | POLL-PROPERTIES | 0 or 1 | | +-----------------+----------+-------------------------------------+ | PRIORITY | 0 or 1 | | +-----------------+----------+-------------------------------------+ | RELATED-TO | 0+ | | +-----------------+----------+-------------------------------------+ | REQUEST-STATUS | 0 | | +-----------------+----------+-------------------------------------+ | RESOURCES | 0+ | | +-----------------+----------+-------------------------------------+ | STATUS | 0 or 1 | MAY be one of COMPLETED/CONFIRMED/ | | | | CANCELLED. | +-----------------+----------+-------------------------------------+ | TRANSP | 0 or 1 | | +-----------------+----------+-------------------------------------+ | URL | 0 or 1 | | +-----------------+----------+-------------------------------------+ | IANA-PROPERTY | 0+ | | +-----------------+----------+-------------------------------------+ | X-PROPERTY | 0+ | | +-----------------+----------+-------------------------------------+ | VALARM | 0+ | | +-----------------+----------+-------------------------------------+ | VTIMEZONE | 0+ | MUST be present if any date/time | | | | refers to a timezone. | +-----------------+----------+-------------------------------------+ | IANA-COMPONENT | 0+ | | +-----------------+----------+-------------------------------------+ | X-COMPONENT | 0+ | | +-----------------+----------+-------------------------------------+ | VEVENT | 0+ | Depending upon the poll mode in | York & Douglass Expires 6 September 2022 [Page 33] Internet-Draft VPOLL March 2022 | | | effect there MAY be candidate | | | | components included in the poll | | | | component. | +-----------------+----------+-------------------------------------+ | VFREEBUSY | 0 | | +-----------------+----------+-------------------------------------+ | VJOURNAL | 0+ | Depending upon the poll mode in | | | | effect there MAY be candidate | | | | components included in the poll | | | | component. | +-----------------+----------+-------------------------------------+ | VTODO | 0+ | Depending upon the poll mode in | | | | effect there MAY be candidate | | | | components included in the poll | | | | component. | +-----------------+----------+-------------------------------------+ Table 6: Constraints for a METHOD:REQUEST of a VPOLL 7.3.3.1. Rescheduling a poll The "REQUEST" method may be used to reschedule a poll, that is force a revote. A rescheduled poll involves a change to the existing poll in terms of its time the components being voted on may have changed. If the recipient CUA of a "REQUEST" method finds that the "UID" property value already exists on the calendar but that the "SEQUENCE" (or "DTSTAMP") property value in the "REQUEST" method is greater than the value for the existing poll, then the "REQUEST" method describes a rescheduling of the poll. 7.3.3.2. Updating or Reconfirmation of a Poll The "REQUEST" method may be used to update or reconfirm a poll. An update to an existing poll does not involve changes to the time or candidates, and might not involve a change to the location or description for the poll. If the recipient CUA of a "REQUEST" method finds that the "UID" property value already exists on the calendar and that the "SEQUENCE" property value in the "REQUEST" is the same as the value for the existing poll, then the "REQUEST" method describes an update of the poll details, but not a rescheduling of the POLL. The update "REQUEST" method is the appropriate response to a "REFRESH" method sent from a "Voter" to the "Organizer" of a poll. York & Douglass Expires 6 September 2022 [Page 34] Internet-Draft VPOLL March 2022 The "Organizer" of a poll may also send unsolicited "REQUEST" methods. The unsolicited "REQUEST" methods may be used to update the details of the poll without rescheduling it, to update the "RESPONSE" parameter of "Voters", or to reconfirm the poll. 7.3.3.3. Confirmation of a Poll The "REQUEST" method may be used to confirm a poll, that is announce the winner in BASIC mode. The STATUS MUST be set to CONFIRMED and for BASIC mode a VPOLL POLL-WINNER property must be provided with the poll-id of the winning component. 7.3.3.4. Closing a Poll The "REQUEST" method may be used to close a poll, that is indicate voting is completed. The STATUS MUST be set to COMPLETED. 7.3.3.5. Delegating a Poll to Another CU Some calendar and scheduling systems allow "Voters" to delegate the vote to another "Calendar User". iTIP supports this concept using the following workflow. Any "Voter" may delegate their right to vote in a poll to another CU. The implication is that the delegate participates in lieu of the original "Voter", NOT in addition to the "Voter". The delegator MUST notify the "Organizer" of this action using the steps outlined below. Implementations may support or restrict delegation as they see fit. For instance, some implementations may restrict a delegate from delegating a "REQUEST" to another CU. The "Delegator" of a poll forwards the existing "REQUEST" to the "Delegate". The "REQUEST" method MUST include a "Voter" property with the calendar address of the "Delegate". The "Delegator" MUST also send a "REPLY" method to the "Organizer" with the "Delegator's" "Voter" property "DELEGATED-TO" parameter set to the calendar address of the "Delegate". Also, a new "Voter" property for the "Delegate" MUST be included and must specify the calendar user address set in the "DELEGATED-TO" parameter, as above. In response to the request, the "Delegate" MUST send a "REPLY" method to the "Organizer", and optionally to the "Delegator". The "REPLY" method SHOULD include the "Voter" property with the "DELEGATED-FROM" parameter value of the "Delegator's" calendar address. York & Douglass Expires 6 September 2022 [Page 35] Internet-Draft VPOLL March 2022 The "Delegator" may continue to receive updates to the poll even though they will not be attending. This is accomplished by the "Delegator" setting their "role" attribute to "NON-PARTICIPANT" in the "REPLY" to the "Organizer". 7.3.3.6. Changing the Organizer The situation may arise where the "Organizer" of a "VPOLL" is no longer able to perform the "Organizer" role and abdicates without passing on the "Organizer" role to someone else. When this occurs, the "Voters" of the "VPOLL" may use out-of-band mechanisms to communicate the situation and agree upon a new "Organizer". The new "Organizer" should then send out a new "REQUEST" with a modified version of the "VPOLL" in which the "SEQUENCE" number has been incremented and the "ORGANIZER" property has been changed to the new "Organizer". 7.3.3.7. Sending on Behalf of the Organizer There are a number of scenarios that support the need for a "Calendar User" to act on behalf of the "Organizer" without explicit role changing. This might be the case if the CU designated as "Organizer" is sick or unable to perform duties associated with that function. In these cases, iTIP supports the notion of one CU acting on behalf of another. Using the "SENT-BY" parameter, a "Calendar User" could send an updated "VPOLL" "REQUEST". In the case where one CU sends on behalf of another CU, the "Voter" responses are still directed back towards the CU designated as "Organizer". 7.3.3.8. Forwarding to an Uninvited CU A "Voter" invited to a "VPOLL" calendar component may send the "VPOLL" calendar component to another new CU not previously associated with the "VPOLL" calendar component. The current "Voter" participating in the "VPOLL" calendar component does this by forwarding the original "REQUEST" method to the new CU. The new CU can send a "REPLY" to the "Organizer" of the "VPOLL" calendar component. The reply contains a "Voter" property for the new CU. The "Organizer" ultimately decides whether or not the new CU becomes part of the poll and is not obligated to do anything with a "REPLY" from a new (uninvited) CU. If the "Organizer" does not want the new CU to be part of the poll, the new "Voter" property is not added to the "VPOLL" calendar component. The "Organizer" MAY send the CU a "CANCEL" message to indicate that they will not be added to the poll. York & Douglass Expires 6 September 2022 [Page 36] Internet-Draft VPOLL March 2022 If the "Organizer" decides to add the new CU, the new "Voter" property is added to the "VPOLL" calendar component. Furthermore, the "Organizer" is free to change any "Voter" property parameter from the values supplied by the new CU to something the "Organizer" considers appropriate. The "Organizer" SHOULD send the new CU a "REQUEST" message to inform them that they have been added. When forwarding a "REQUEST" to another CU, the forwarding "Voter" MUST NOT make changes to the original message. 7.3.3.9. Updating Voter Status The "Organizer" of an poll may also request updated status from one or more "Voters". The "Organizer" sends a "REQUEST" method to the "Voter" and sets the "RSVP=TRUE" property parameter on the PARTICIPANT CALENDAR-ADDRESS. The "SEQUENCE" property for the poll is not changed from its previous value. A recipient will determine that the only change in the "REQUEST" is that their "RSVP" property parameter indicates a request for updated status. The recipient SHOULD respond with a "REPLY" method indicating their current vote with respect to the "REQUEST". 7.3.4. Method: REPLY The "REPLY" method in a "VPOLL" calendar component is used to respond (e.g., accept or decline) to a "REQUEST" or to reply to a delegation "REQUEST". When used to provide a delegation response, the "Delegator" SHOULD include the calendar address of the "Delegate" on the "DELEGATED-TO" property parameter of the "Delegator's" "CALENDAR- ADDRESS" property. The "Delegate" SHOULD include the calendar address of the "Delegator" on the "DELEGATED-FROM" property parameter of the "Delegate's" "CALENDAR-ADDRESS" property. The "REPLY" method is also used when processing of a "REQUEST" fails. Depending on the value of the "REQUEST-STATUS" property, no action may have been performed. The "Organizer" of a poll may receive the "REPLY" method from a CU not in the original "REQUEST". For example, a "REPLY" may be received from a "Delegate" to a poll. In addition, the "REPLY" method may be received from an unknown CU (a "Party Crasher"). This uninvited "Voter" may be accepted, or the "Organizer" may cancel the poll for the uninvited "Voter" by sending a "CANCEL" method to the uninvited "Voter". York & Douglass Expires 6 September 2022 [Page 37] Internet-Draft VPOLL March 2022 A "Voter" MAY include a message to the "Organizer" using the "COMMENT" property. For example, if the user indicates a low interest and wants to let the "Organizer" know why, the reason can be expressed in the "COMMENT" property value. The "Organizer" may also receive a "REPLY" from one CU on behalf of another. Like the scenario enumerated above for the "Organizer", "Voters" may have another CU respond on their behalf. This is done using the "SENT-BY" parameter. The optional properties listed in the table below (those listed as "0+" or "0 or 1") MUST NOT be changed from those of the original request. (But see comments on VFREEBUSY and VAVAILABILITY) This method type is an iCalendar object that conforms to the following property constraints: +=================+==========+=====================================+ | Component/ | Presence | Comment | | Property | | | +=================+==========+=====================================+ | METHOD | 1 | MUST be REPLY. | +-----------------+----------+-------------------------------------+ | VPOLL | 1+ | All components MUST have the same | +-----------------+----------+-------------------------------------+ | | | UID. | +-----------------+----------+-------------------------------------+ | PARTICIPANT | 1 | Identifies the Voter replying. | +-----------------+----------+-------------------------------------+ | DTSTAMP | 1 | | +-----------------+----------+-------------------------------------+ | ORGANIZER | 1 | | +-----------------+----------+-------------------------------------+ | UID | 1 | MUST be the UID of the original | +-----------------+----------+-------------------------------------+ | | | REQUEST. | +-----------------+----------+-------------------------------------+ | SEQUENCE | 0 or 1 | If non-zero, MUST be the sequence | | | | number of the original REQUEST. | | | | MAY be present if 0. | +-----------------+----------+-------------------------------------+ | ACCEPT-RESPONSE | 0 or 1 | | +-----------------+----------+-------------------------------------+ | ATTACH | 0+ | | +-----------------+----------+-------------------------------------+ | CATEGORIES | 0+ | | +-----------------+----------+-------------------------------------+ | CLASS | 0 or 1 | | York & Douglass Expires 6 September 2022 [Page 38] Internet-Draft VPOLL March 2022 +-----------------+----------+-------------------------------------+ | COMMENT | 0+ | | +-----------------+----------+-------------------------------------+ | COMPLETED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | CONTACT | 0+ | | +-----------------+----------+-------------------------------------+ | CREATED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | DESCRIPTION | 0 or 1 | | +-----------------+----------+-------------------------------------+ | DTEND | 0 or 1 | If present, DURATION MUST NOT be | | | | present. | +-----------------+----------+-------------------------------------+ | DTSTART | 0 or 1 | | +-----------------+----------+-------------------------------------+ | DURATION | 0 or 1 | If present, DTEND MUST NOT be | | | | present. | +-----------------+----------+-------------------------------------+ | GEO | 0 or 1 | | +-----------------+----------+-------------------------------------+ | LAST-MODIFIED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | LOCATION | 0 or 1 | | +-----------------+----------+-------------------------------------+ | POLL-ITEM-ID | 1+ | One per item being voted on. | +-----------------+----------+-------------------------------------+ | POLL-MODE | 0 | | +-----------------+----------+-------------------------------------+ | POLL-PROPERTIES | 0 | | +-----------------+----------+-------------------------------------+ | PRIORITY | 0 or 1 | | +-----------------+----------+-------------------------------------+ | RELATED-TO | 0+ | | +-----------------+----------+-------------------------------------+ | RESOURCES | 0+ | | +-----------------+----------+-------------------------------------+ | REQUEST-STATUS | 0+ | | +-----------------+----------+-------------------------------------+ | STATUS | 0 or 1 | | +-----------------+----------+-------------------------------------+ | SUMMARY | 0 or 1 | | +-----------------+----------+-------------------------------------+ | TRANSP | 0 or 1 | | +-----------------+----------+-------------------------------------+ | URL | 0 or 1 | | +-----------------+----------+-------------------------------------+ | IANA-PROPERTY | 0+ | | York & Douglass Expires 6 September 2022 [Page 39] Internet-Draft VPOLL March 2022 +-----------------+----------+-------------------------------------+ | X-PROPERTY | 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 or 1 | A voter may respond with a | | | | VFREEBUSY component indicating that | | | | the ORGANIZER may select some other | | | | time which is not marked as busy. | +-----------------+----------+-------------------------------------+ | VAVAILABILITY | 0 | A voter may respond with a | | | | VAVAILABILITY component indicating | | | | that the ORGANIZER may select some | | | | other time which is shown as | | | | available. | +-----------------+----------+-------------------------------------+ | VJOURNAL | 0 | | +-----------------+----------+-------------------------------------+ | VTODO | 0 | | +-----------------+----------+-------------------------------------+ Table 7: Constraints for a METHOD:REPLY of a VPOLL 7.3.5. Method: CANCEL The "CANCEL" method in a "VPOLL" calendar component is used to send a cancellation notice of an existing poll request to the affected "Voters". The message is sent by the "Organizer" of the poll. The "Organizer" MUST send a "CANCEL" message to each "Voter" affected by the cancellation. This can be done using a single "CANCEL" message for all "Voters" or by using multiple messages with different subsets of the affected "Voters" in each. When a "VPOLL" is cancelled, the "SEQUENCE" property value MUST be incremented as described in Section 7.2.3. Once a CANCEL message has been sent to all voters no further voting may take place. The poll is considered closed. York & Douglass Expires 6 September 2022 [Page 40] Internet-Draft VPOLL March 2022 This method type is an iCalendar object that conforms to the following property constraints: +=================+==========+==================================+ | Component/ | Presence | Comment | | Property | | | +=================+==========+==================================+ | METHOD | 1 | MUST be CANCEL. | +-----------------+----------+----------------------------------+ | VPOLL | 1+ | All must have the same UID. | +-----------------+----------+----------------------------------+ | PARTICIPANT | 0+ | MUST include some or all Voters | | | | being removed from the poll. | | | | MUST include some or all Voters | | | | if the entire poll is cancelled. | +-----------------+----------+----------------------------------+ | UID | 1 | MUST be the UID of the original | | | | REQUEST. | +-----------------+----------+----------------------------------+ | DTSTAMP | 1 | | +-----------------+----------+----------------------------------+ | ORGANIZER | 1 | | +-----------------+----------+----------------------------------+ | SEQUENCE | 1 | | +-----------------+----------+----------------------------------+ | ATTACH | 0+ | | +-----------------+----------+----------------------------------+ | ACCEPT-RESPONSE | 0 | | +-----------------+----------+----------------------------------+ | COMMENT | 0+ | | +-----------------+----------+----------------------------------+ | COMPLETED | 0 or 1 | | +-----------------+----------+----------------------------------+ | CATEGORIES | 0+ | | +-----------------+----------+----------------------------------+ | CLASS | 0 or 1 | | +-----------------+----------+----------------------------------+ | CONTACT | 0+ | | +-----------------+----------+----------------------------------+ | CREATED | 0 or 1 | | +-----------------+----------+----------------------------------+ | DESCRIPTION | 0 or 1 | | +-----------------+----------+----------------------------------+ | DTEND | 0 or 1 | If present, DURATION MUST NOT be | | | | present. | +-----------------+----------+----------------------------------+ | DTSTART | 0 or 1 | | +-----------------+----------+----------------------------------+ York & Douglass Expires 6 September 2022 [Page 41] Internet-Draft VPOLL March 2022 | DURATION | 0 or 1 | If present, DTEND MUST NOT be | | | | present. | +-----------------+----------+----------------------------------+ | GEO | 0 or 1 | | +-----------------+----------+----------------------------------+ | LAST-MODIFIED | 0 or 1 | | +-----------------+----------+----------------------------------+ | LOCATION | 0 or 1 | | +-----------------+----------+----------------------------------+ | POLL-ITEM-ID | 0 | | +-----------------+----------+----------------------------------+ | POLL-MODE | 0 | | +-----------------+----------+----------------------------------+ | POLL-PROPERTIES | 0 | | +-----------------+----------+----------------------------------+ | PRIORITY | 0 or 1 | | +-----------------+----------+----------------------------------+ | RELATED-TO | 0+ | | +-----------------+----------+----------------------------------+ | RESOURCES | 0+ | | +-----------------+----------+----------------------------------+ | STATUS | 0 or 1 | MUST be set to CANCELLED to | | | | cancel the entire event. If | | | | uninviting specific Attendees, | | | | then MUST NOT be included. | +-----------------+----------+----------------------------------+ | SUMMARY | 0 or 1 | | +-----------------+----------+----------------------------------+ | TRANSP | 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+ | | +-----------------+----------+----------------------------------+ | VTODO | 0 | | York & Douglass Expires 6 September 2022 [Page 42] Internet-Draft VPOLL March 2022 +-----------------+----------+----------------------------------+ | VJOURNAL | 0 | | +-----------------+----------+----------------------------------+ | VEVENT | 0 | | +-----------------+----------+----------------------------------+ | VFREEBUSY | 0 | | +-----------------+----------+----------------------------------+ Table 8: Constraints for a METHOD:CANCEL of a VPOLL 7.3.6. Method: REFRESH The "REFRESH" method in a "VPOLL" calendar component is used by "Voters" of an existing event to request an updated description from the poll "Organizer". The "REFRESH" method must specify the "UID" property of the poll to update. The "Organizer" responds with the latest description and version of the poll. This method type is an iCalendar object that conforms to the following property constraints: +====================+==========+============================+ | Component/Property | Presence | Comment | +====================+==========+============================+ | METHOD | 1 | MUST be REFRESH. | +--------------------+----------+----------------------------+ | VPOLL | 1 | | +--------------------+----------+----------------------------+ | PARTICIPANT | 1 | MUST identify the | | | | requester as a voter. | +--------------------+----------+----------------------------+ | DTSTAMP | 1 | | +--------------------+----------+----------------------------+ | ORGANIZER | 1 | | +--------------------+----------+----------------------------+ | UID | 1 | MUST be the UID associated | | | | with original REQUEST. | +--------------------+----------+----------------------------+ | COMMENT | 0+ | | +--------------------+----------+----------------------------+ | COMPLETED | 0 | | +--------------------+----------+----------------------------+ | IANA-PROPERTY | 0+ | | +--------------------+----------+----------------------------+ | X-PROPERTY | 0+ | | +--------------------+----------+----------------------------+ | ACCEPT-RESPONSE | 0 | | +--------------------+----------+----------------------------+ York & Douglass Expires 6 September 2022 [Page 43] Internet-Draft VPOLL March 2022 | ATTACH | 0 | | +--------------------+----------+----------------------------+ | CATEGORIES | 0 | | +--------------------+----------+----------------------------+ | CLASS | 0 | | +--------------------+----------+----------------------------+ | CONTACT | 0 | | +--------------------+----------+----------------------------+ | CREATED | 0 | | +--------------------+----------+----------------------------+ | DESCRIPTION | 0 | | +--------------------+----------+----------------------------+ | DTEND | 0 | | +--------------------+----------+----------------------------+ | DTSTART | 0 | | +--------------------+----------+----------------------------+ | DURATION | 0 | | +--------------------+----------+----------------------------+ | GEO | 0 | | +--------------------+----------+----------------------------+ | LAST-MODIFIED | 0 | | +--------------------+----------+----------------------------+ | LOCATION | 0 | | +--------------------+----------+----------------------------+ | POLL-ITEM-ID | 0 | | +--------------------+----------+----------------------------+ | POLL-MODE | 0 | | +--------------------+----------+----------------------------+ | POLL-PROPERTIES | 0 | | +--------------------+----------+----------------------------+ | PRIORITY | 0 | | +--------------------+----------+----------------------------+ | RELATED-TO | 0 | | +--------------------+----------+----------------------------+ | REQUEST-STATUS | 0 | | +--------------------+----------+----------------------------+ | RESOURCES | 0 | | +--------------------+----------+----------------------------+ | SEQUENCE | 0 | | +--------------------+----------+----------------------------+ | STATUS | 0 | | +--------------------+----------+----------------------------+ | SUMMARY | 0 | | +--------------------+----------+----------------------------+ | URL | 0 | | +--------------------+----------+----------------------------+ | VALARM | 0 | | +--------------------+----------+----------------------------+ York & Douglass Expires 6 September 2022 [Page 44] Internet-Draft VPOLL March 2022 | VTIMEZONE | 0+ | | +--------------------+----------+----------------------------+ | IANA-COMPONENT | 0+ | | +--------------------+----------+----------------------------+ | X-COMPONENT | 0+ | | +--------------------+----------+----------------------------+ | VTODO | 0 | | +--------------------+----------+----------------------------+ | VJOURNAL | 0 | | +--------------------+----------+----------------------------+ | VEVENT | 0 | | +--------------------+----------+----------------------------+ | VFREEBUSY | 0 | | +--------------------+----------+----------------------------+ Table 9: Constraints for a METHOD:REFRESH of a VPOLL 7.3.7. Method: POLLSTATUS The "POLLSTATUS" method in a "VPOLL" calendar component is used to inform recipients of the current status of the poll in a compact manner. The "Organizer" MUST be present in the confirmed poll component. All "Voters" MUST be present. The selected component(s) according to the poll mode SHOULD NOT be present in the poll component. Clients receiving this message may store the confirmed items in their calendars. This method type is an iCalendar object that conforms to the following property constraints: +=================+==========+=====================================+ | Component/ | Presence | Comment | | Property | | | +=================+==========+=====================================+ | METHOD | 1 | MUST equal POLLSTATUS. | +-----------------+----------+-------------------------------------+ | VPOLL | 1+ | | +-----------------+----------+-------------------------------------+ | PARTICIPANT | 1+ | The voters containing their current | | | | vote | +-----------------+----------+-------------------------------------+ | COMPLETED | 0 or 1 | Only present for a completed poll | +-----------------+----------+-------------------------------------+ | DTSTAMP | 1 | | +-----------------+----------+-------------------------------------+ | DTSTART | 0 or 1 | | +-----------------+----------+-------------------------------------+ | ORGANIZER | 1 | | York & Douglass Expires 6 September 2022 [Page 45] Internet-Draft VPOLL March 2022 +-----------------+----------+-------------------------------------+ | SUMMARY | 1 | Can be null. | +-----------------+----------+-------------------------------------+ | UID | 1 | | +-----------------+----------+-------------------------------------+ | SEQUENCE | 0 or 1 | MUST be present if value is greater | | | | than 0; MAY be present if 0. | +-----------------+----------+-------------------------------------+ | ACCEPT-RESPONSE | 0 | | +-----------------+----------+-------------------------------------+ | ATTACH | 0 | | +-----------------+----------+-------------------------------------+ | CATEGORIES | 0 | | +-----------------+----------+-------------------------------------+ | CLASS | 0 | | +-----------------+----------+-------------------------------------+ | COMMENT | 0+ | | +-----------------+----------+-------------------------------------+ | CONTACT | 0 | | +-----------------+----------+-------------------------------------+ | CREATED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | DESCRIPTION | 0 or 1 | Can be null. | +-----------------+----------+-------------------------------------+ | DTEND | 0 or 1 | If present, DURATION MUST NOT be | | | | present. | +-----------------+----------+-------------------------------------+ | DURATION | 0 or 1 | If present, DTEND MUST NOT be | | | | present. | +-----------------+----------+-------------------------------------+ | LAST-MODIFIED | 0 or 1 | | +-----------------+----------+-------------------------------------+ | POLL-ITEM-ID | 0 | | +-----------------+----------+-------------------------------------+ | POLL-MODE | 0 or 1 | | +-----------------+----------+-------------------------------------+ | POLL-PROPERTIES | 0 | | +-----------------+----------+-------------------------------------+ | PRIORITY | 0 or 1 | | +-----------------+----------+-------------------------------------+ | RELATED-TO | 0+ | | +-----------------+----------+-------------------------------------+ | RESOURCES | 0+ | | +-----------------+----------+-------------------------------------+ | STATUS | 0 or 1 | MAY be one of TENTATIVE/CONFIRMED/ | | | | CANCELLED. | +-----------------+----------+-------------------------------------+ | URL | 0 or 1 | | York & Douglass Expires 6 September 2022 [Page 46] Internet-Draft VPOLL March 2022 +-----------------+----------+-------------------------------------+ | IANA-PROPERTY | 0+ | | +-----------------+----------+-------------------------------------+ | X-PROPERTY | 0+ | | +-----------------+----------+-------------------------------------+ | REQUEST-STATUS | 0 | | +-----------------+----------+-------------------------------------+ | VALARM | 0+ | | +-----------------+----------+-------------------------------------+ | VEVENT | 0 | All candidate components SHOULD NOT | | | | be present. | +-----------------+----------+-------------------------------------+ | VFREEBUSY | 0 | | +-----------------+----------+-------------------------------------+ | VJOURNAL | 0 | All candidate components SHOULD NOT | | | | be present. | +-----------------+----------+-------------------------------------+ | VTODO | 0 | All candidate components SHOULD NOT | | | | be present. | +-----------------+----------+-------------------------------------+ | VTIMEZONE | 0+ | MUST be present if any date/time | | | | refers to a timezone. | +-----------------+----------+-------------------------------------+ | IANA-COMPONENT | 0+ | | +-----------------+----------+-------------------------------------+ | X-COMPONENT | 0+ | | +-----------------+----------+-------------------------------------+ Table 10: Constraints for a METHOD:POLLSTATUS of a VPOLL 8. CalDAV Extensions This specification extends [RFC4791] in that it defines a new component and new iCalendar properties to be supported and requires extra definitions related to time-ranges and reports. Additionally, it extends [RFC6638] as it a VPOLL component is a schedulable entity. 8.1. Calendar Collection Properties This section defines new CalDAV properties for calendar collections. 8.1.1. CALDAV:supported-vpoll-component-sets Name supported-vpoll-component-sets Namespace urn:ietf:params:xml:ns:caldav York & Douglass Expires 6 September 2022 [Page 47] Internet-Draft VPOLL March 2022 Purpose Specifies the calendar component types (e.g., VEVENT, VTODO, etc.) and combination of types that may be included in a VPOLL component. Conformance This property MAY be defined on any calendar collection. If defined, it MUST be protected and SHOULD NOT be returned by a PROPFIND DAV:allprop request (as defined in Section 12.14.1 of [RFC2518]). Description The CALDAV:supported-vpoll-component-sets property is used to specify restrictions on the calendar component types that VPOLL components may contain in a calendar collection. It also specifies the combination of allowed component types. Any attempt by the client to store VPOLL components with component types or combinations of types not listed in this property, if it exists, MUST result in an error, with the CALDAV:supported-vpoll- component-sets precondition Section 8.2 being violated. Since this property is protected, it cannot be changed by clients using a PROPPATCH request. However, clients can initialize the value of this property when creating a new calendar collection with MKCALENDAR. In the absence of this property, the server MUST accept all component types, and the client can assume that all component types are accepted. Definition York & Douglass Expires 6 September 2022 [Page 48] Internet-Draft VPOLL March 2022 8.1.2. CALDAV:vpoll-max-items Name vpoll-max-items Namespace urn:ietf:params:xml:ns:caldav Purpose Provides a numeric value indicating the maximum number of items that may be contained in any instance of a VPOLL calendar object resource stored in the calendar collection. Conformance This property MAY be defined on any calendar collection. If defined, it MUST be protected and SHOULD NOT be returned by a PROPFIND DAV:allprop request (as defined in Section 12.14.1 of [RFC2518]). Description The CALDAV:vpoll-max-items is used to specify a numeric value that indicates the maximum number of iCalendar components in any one instance of a VPOLL calendar object resource stored in a calendar collection. Any attempt to store a calendar object resource with more components per instance than this value MUST result in an error, with the CALDAV: vpoll-max-items precondition York & Douglass Expires 6 September 2022 [Page 49] Internet-Draft VPOLL March 2022 Section 8.2 being violated. In the absence of this property, the client can assume that the server can handle any number of items in a VPOLL calendar component. Definition PCDATA value: a numeric value (integer greater than zero) 25 8.1.3. CALDAV:vpoll-max-active Name vpoll-max-active Namespace urn:ietf:params:xml:ns:caldav Purpose Provides a numeric value indicating the maximum number of active vpolls at any one time. Conformance This property MAY be defined on any calendar collection. If defined, it MUST be protected and SHOULD NOT be returned by a PROPFIND DAV:allprop request (as defined in Section 12.14.1 of [RFC2518]). Description The CALDAV:vpoll-max-active is used to specify a numeric value that indicates the maximum number of active VPOLLs at any one time. Any attempt to store a new active VPOLL calendar object resource which results in exceeding this limit MUST result in an error, with the CALDAV:vpoll-max-active precondition Section 8.2 being violated. In the absence of this property, the client can assume that the server can handle any number of active VPOLLs. Definition PCDATA value: a numeric value (integer greater than zero) 25 8.1.4. CALDAV:vpoll-max-voters Name vpoll-max-voters Namespace urn:ietf:params:xml:ns:caldav York & Douglass Expires 6 September 2022 [Page 50] Internet-Draft VPOLL March 2022 Purpose Provides a numeric value indicating the maximum number of voters for any instance of a VPOLL calendar object resource stored in the calendar collection. Conformance This property MAY be defined on any calendar collection. If defined, it MUST be protected and SHOULD NOT be returned by a PROPFIND DAV:allprop request (as defined in Section 12.14.1 of [RFC2518]). Description The CALDAV:vpoll-max-voters is used to specify a numeric value that indicates the maximum number of voters for any one instance of a VPOLL calendar object resource stored in a calendar collection. Any attempt to store a calendar object resource with more voters per instance than this value MUST result in an error, with the CALDAV: vpoll-max-voters precondition Section 8.2 being violated. In the absence of this property, the client can assume that the server can handle any number of voters in a VPOLL calendar component. Definition PCDATA value: a numeric value (integer greater than zero) 25 8.1.5. CalDAV:even-more-properties 8.1.6. Extensions to CalDAV scheduling This specification extends [RFC6638]. Each section of Appendix A "Scheduling Privileges Summary" is extended to include VPOLL. Any reference to the ATTENDEE property should be read to include the CALENDAR-ADDRESS property contained in the PARTICIPANT compoents. That is, for scheduling purposes the CALENDAR-ADDRESS property is handled in exactly the same manner as the ATTENDEE property. York & Douglass Expires 6 September 2022 [Page 51] Internet-Draft VPOLL March 2022 8.2. Additional Preconditions for PUT, COPY, and MOVE This specification creates additional Preconditions for PUT, COPY, and MOVE methods. These preconditions apply when a PUT operation of a VPOLL calendar object resource into a calendar collection occurs, or when a COPY or MOVE operation of a calendar object resource into a calendar collection occurs, or when a COPY or MOVE operation occurs on a calendar collection. The new preconditions are: (CALDAV:supported-vpoll-component-sets) The VPOLL resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST contain a type or combination of calendar component that is supported in the targeted calendar collection; (CALDAV:vpoll-max-items) The VPOLL resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST have a number of sub-components (excluding VTIMEZONE) less than or equal to the value of the CALDAV:vpoll-max-items property value Section 8.1.2 on the calendar collection where the resource will be stored; (CALDAV:vpoll-max-active) The PUT request, or COPY or MOVE request, MUST not result in the number of active VPOLLs being greater than the value of the CALDAV:vpoll-max-active property value Section 8.1.3 on the calendar collection where the resource will be stored; (CALDAV:vpoll-max-voters) The VPOLL resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST have a number of voters represented by PARTICIPANT components less than or equal to the value of the CALDAV:vpoll-max-voters property value Section 8.1.4 on the calendar collection where the resource will be stored; 8.3. CalDAV:calendar-query Report This allows the retrieval of VPOLLs and their included components. The query specification allows queries to be directed at the contained sub-components. For VPOLL queries this feature is disallowed. Time-range queries can only target the vpoll component itself. York & Douglass Expires 6 September 2022 [Page 52] Internet-Draft VPOLL March 2022 8.3.1. Example: Partial Retrieval of VPOLL In this example, the client requests the server to return specific components and properties of the VPOLL components that overlap the time range from December 4, 2012, at 00:00:00 A.M. UTC to December 5, 2012, at 00:00:00 A.M. UTC. In addition, the DAV:getetag property is also requested and returned as part of the response. Note that due to the CALDAV: calendar-data element restrictions, the DTSTAMP property in VPOLL components has not been returned, and the only property returned in the VCALENDAR object is VERSION. >> Request << REPORT /cyrus/work/ HTTP/1.1 Host: cal.example.com Depth: 1 Content-Type: application/xml; charset="utf-8" Content-Length: xxxx York & Douglass Expires 6 September 2022 [Page 53] Internet-Draft VPOLL March 2022 >> Response << HTTP/1.1 207 Multi-Status Date: Sat, 11 Nov 2012 09:32:12 GMT Content-Type: application/xml; charset="utf-8" Content-Length: xxxx http://cal.example.com/cyrus/work/poll2.ics "fffff-abcd2" BEGIN:VCALENDAR VERSION:2.0 BEGIN:VPOLL DTSTART;TZID=US/Eastern:20121202T120000 DURATION:PT4D SUMMARY:Poll #2 UID:00959BC664CA650E933C892C@example.com END:VPOLL END:VCALENDAR HTTP/1.1 200 OK http://cal.example.com/cyrus/work/poll3.ics "fffff-abcd3" BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//CalDAV Client//EN BEGIN:VPOLL DTSTART;TZID=US/Eastern:20121204T100000 DURATION:PT4D SUMMARY:Poll #3 UID:DC6C50A017428C5216A2F1CD@example.com END:VPOLL END:VCALENDAR HTTP/1.1 200 OK York & Douglass Expires 6 September 2022 [Page 54] Internet-Draft VPOLL March 2022 8.4. CalDAV time ranges "CALDAV:time-range XML Element" in Section 9.9 of [RFC4791] describes how to specify time ranges to limit the set of calendar components returned by the server. This specification extends [RFC4791] to describe the meaning of time ranges for VPOLL A VPOLL component is said to overlap a given time range if the condition for the corresponding component state specified in the table below is satisfied. The conditions depend on the presence of the DTSTART, DURATION, DTEND, COMPLETED and CREATED properties in the VPOLL component. Note that, as specified above, the DTEND value MUST be a DATE-TIME value equal to or after the DTSTART value if specified. York & Douglass Expires 6 September 2022 [Page 55] Internet-Draft VPOLL March 2022 +-------------------------------------------------------------------+ | VPOLL has the DTSTART property? | | +---------------------------------------------------------------+ | | VPOLL has the DURATION property? | | | +-----------------------------------------------------------+ | | | VPOLL has the DTEND property? | | | | +-------------------------------------------------------+ | | | | VPOLL has the COMPLETED property? | | | | | +---------------------------------------------------+ | | | | | VPOLL has the CREATED property? | | | | | | +-----------------------------------------------+ | | | | | | Condition to evaluate | +---+---+---+---+---+-----------------------------------------------+ | Y | Y | N | * | * | (start <= DTSTART+DURATION) AND | | | | | | | ((end > DTSTART) OR | | | | | | | (end >= DTSTART+DURATION)) | +---+---+---+---+---+-----------------------------------------------+ | Y | N | Y | * | * | ((start < DTEND) OR (start <= DTSTART)) | | | | | | | AND | | | | | | | ((end > DTSTART) OR (end >= DTEND)) | +---+---+---+---+---+-----------------------------------------------+ | Y | N | N | * | * | (start <= DTSTART) AND (end > DTSTART) | +---+---+---+---+---+-----------------------------------------------+ | N | N | Y | * | * | (start < DTEND) AND (end >= DTEND) | +---+---+---+---+---+-----------------------------------------------+ | N | N | N | Y | Y | ((start <= CREATED) OR (start <= COMPLETED))| | | | | | | AND | | | | | | | ((end >= CREATED) OR (end >= COMPLETED))| +---+---+---+---+---+-----------------------------------------------+ | N | N | N | Y | N | (start <= COMPLETED) AND (end >= COMPLETED) | +---+---+---+---+---+-----------------------------------------------+ | N | N | N | N | Y | (end > CREATED) | +---+---+---+---+---+-----------------------------------------------+ | N | N | N | N | N | TRUE | +---+---+---+---+---+-----------------------------------------------+ 9. Security Considerations Applications using these property need to be aware of the risks entailed in using the URIs provided as values. See [RFC3986] for a discussion of the security considerations relating to URIs. 10. IANA Considerations 10.1. Parameter Registrations This document defines the following new iCalendar property parameters to be added to the registry defined in Section 8.2.4 of [RFC5545]: York & Douglass Expires 6 September 2022 [Page 56] Internet-Draft VPOLL March 2022 +====================+=========+===============+ | Property Parameter | Status | Reference | +====================+=========+===============+ | REQUIRED | Current | Section 5.4.1 | +--------------------+---------+---------------+ | STAY-INFORMED | Current | Section 5.4.2 | +--------------------+---------+---------------+ Table 11 10.2. Property Registrations This document defines the following new iCalendar properties to be added to the registry defined in Section 8.2.3 of [RFC5545]: +=================+=========+===============+ | Property | Status | Reference | +=================+=========+===============+ | ACCEPT-RESPONSE | Current | Section 5.5.7 | +-----------------+---------+---------------+ | POLL-ITEM-ID | Current | Section 5.5.3 | +-----------------+---------+---------------+ | POLL-MODE | Current | Section 5.5.4 | +-----------------+---------+---------------+ | POLL-PROPERTIES | Current | Section 5.5.5 | +-----------------+---------+---------------+ | POLL-WINNER | Current | Section 5.5.6 | +-----------------+---------+---------------+ | RESPONSE | Current | Section 5.5.8 | +-----------------+---------+---------------+ Table 12 10.3. POLL-MODE Registration Template A poll mode is defined by completing the following template. Poll mode name The name of the poll mode. Purpose The purpose of the poll mode. Give a short but clear description. Reference A reference to the RFC in which the poll mode is defined 10.4. POLL-MODE Registrations This document defines the following registered poll modes. York & Douglass Expires 6 September 2022 [Page 57] Internet-Draft VPOLL March 2022 +===========+=======================================+===========+ | Poll mode | Purpose | Reference | | name | | | +===========+=======================================+===========+ | BASIC | To provide simple voting for a single | Current | | | outcome from a number of candidates. | | +-----------+---------------------------------------+-----------+ Table 13 11. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, "HTTP Extensions for Distributed Authoring - WEBDAV", RFC 2518, RFC 2518, DOI 10.17487/RFC2518, February 1999, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", RFC 3986, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, RFC 4791, DOI 10.17487/RFC4791, March 2007, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 5234, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, RFC 5545, DOI 10.17487/RFC5545, September 2009, . [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, RFC 5546, DOI 10.17487/RFC5546, December 2009, . York & Douglass Expires 6 September 2022 [Page 58] Internet-Draft VPOLL March 2022 [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based Interoperability Protocol (iMIP)", RFC 6047, RFC 6047, DOI 10.17487/RFC6047, December 2010, . [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to CalDAV", RFC 6638, RFC 6638, DOI 10.17487/RFC6638, June 2012, . [RFC9073] Douglass, M., "Event Publishing Extensions to iCalendar", RFC 9073, RFC 9073, DOI 10.17487/RFC9073, August 2021, . Appendix A. Open issues public-comment: Not documented and was a parameter on something. Really sounds like a PARTICIPANT or VOTE property Notifications: Need to do a section on what Notifications to support. A. VPOLL is about to end and you haven't voted on it yet. Instead reuse VALARMS to notify the user? Future: Restarting a confirmed/completed VPOLL What to do with changes to STATUS:CONFIRMED? Allow them or not? What do to that poll had a winning event or todo. Stress VPOLL UID MUST be unique Changing status back from CONFIRMED MUST adjust status of any events booked as a result of confirmation. MUST winning event be cancelled for POLL-MODE basic? No - voter has indicated now unable to attend - want to revote Future: Voting on a confirmed/completed VPOLL Can a voter vote after completion? May be unable to attend and wants to indicate. Requires retention of VPOLL retention period Removed status ORGANIZER/ATTENDEE validity Can a user create a poll with scheduled events where that user's isn't the organizer of the poll? So is there a requirement that the account that poll is on is able to create each one of the resources in the poll? i.e. I can't create a poll with a set of events where I am just the attendee of the events. Are there any other restrictions for components in a VPOLL? Add to security consideration Update to existing event after poll confirm When voting on existing event - winning properties ONLY are merged in to the real event. Need to write down what isn't valid in a VPOLL a. Can't change POLL-MODE York & Douglass Expires 6 September 2022 [Page 59] Internet-Draft VPOLL March 2022 Guide for ATTENDEE roles chair, NON-PARTICIPANT etc ? - some iTip notes On confirm - send itip if appropriate (PUBLISH) - all non-participating - shared - feeds Organizer can specify where result is? Confirm can specify that itip is sent - ITIP / NONE - parameter ? on POLL-WINNER Need to add example of freebusy in response BEGIN:VCALENDAR VERSION:2.0 PRODID:-//BedeworkCaldavTest//BedeworkCaldavTest METHOD: REPLY BEGIN:VPOLL ORGANIZER:mailto:douglm@mysite.edu BEGIN:PARTICIPANT PARTICIPANT-TYPE: VOTER CALENDAR-ADDRESS:mailto:eric@example.com UID:sched01-1234567890 DTSTAMP:20120101T010000Z SEQUENCE:0 SUMMARY:What to do this week BEGIN:VFREEBUSY ....... END:VFREEBUSY END:PARTICIPANT END:VPOLL END:VCALENDAR Appendix B. Change log Calext V01: 2019-10-17 MD Replace VVOTER and VOTER with PARTICIPANT. Calext V00: 2019-05-17 MD First calext version. Moved source to metanorma. No changes to specification. V03: 2014-10-28 MD * Add VVOTER and VOTE components. * Add RESPONSE property. * Remove RESPONSE parameter from VOTER. V03: 2014-05-12 MD * Add reply-url property and required parameter. * Fix ACCEPT-RESPONSE definition. York & Douglass Expires 6 September 2022 [Page 60] Internet-Draft VPOLL March 2022 V02: 2014-05-12 MD * Typos fixed, clarifications made. * Removed spurious COMMENT param. Switched some to PUBLIC- COMMENT * Changed STAY-INFORMED to remove boolean value type and state explicit TRUE/FALSE values. * iTip: Allow VPOLL DTSTART to be optional and allow VAVAILABILITY as subcomponent * iTip: fix broken table cells * Add POLL-PROPERTIES, POLL-WINNER to 5545 extensions table * Added Caldav scheduling section V01: 2013-08-07 MD * Removed method CONFIRM * Removed pollitemid from VPOLL abnf. Added text for pollwinner * Added POLL-WINNER and verbiage * Added STATUS values * Added RELTYPE=POLL * Added supported-vpoll-component-sets * Added CalDAV related parameters to VOTER * Removed bad CalDAV query example. State that queries cannot target the sub-components. Initial version: 2012-11-02 MD Authors' Addresses Eric York Email: eric.york@gmail.com Michael Douglass Email: mdouglass@bedework.com York & Douglass Expires 6 September 2022 [Page 61]