diff --git a/ical-tasks/sources/sections-ietf/02-conventions.adoc b/ical-tasks/sources/sections-ietf/02-conventions.adoc index 2a93812..d53fe7b 100644 --- a/ical-tasks/sources/sections-ietf/02-conventions.adoc +++ b/ical-tasks/sources/sections-ietf/02-conventions.adoc @@ -12,11 +12,10 @@ text with the first character of each word in upper case. For example, "Organizer" refers to a role of a "Calendar User" (CU) within the scheduling protocol. -Calendar components defined by <> are referred to with -capitalized, quoted-strings of text. All calendar components start -with the letter "V". For example, "VEVENT" refers to the event -calendar component, "VTODO" refers to the to-do calendar component, -and "VJOURNAL" refers to the daily journal calendar component. +Calendar components defined by <> and updating specifications are referred to with +capitalized, quoted-strings of text, followed by the words "calendar component". For example, "VEVENT" calendar component refers to the event +calendar component, "VTODO" calendar component refers to the to-do calendar component, +and "VJOURNAL" calendar component refers to the daily journal calendar component. Scheduling methods are referred to with capitalized, quoted-strings of text. For example, "REQUEST" refers to the method for requesting @@ -24,7 +23,7 @@ a scheduling calendar component be created or modified; "REPLY" refers to the method a recipient of a request uses to update their status with the "Organizer" of the calendar component. -Properties defined by [RFC5545] are referred to with capitalized, +Properties defined by <> and updating specifications are referred to with capitalized, quoted-strings of text, followed by the word "property". For example, "ATTENDEE" property refers to the iCalendar property used to convey the calendar address of a "Calendar User". diff --git a/ical-tasks/sources/sections-ietf/98-references.adoc b/ical-tasks/sources/sections-ietf/98-references.adoc index 4ad42df..978ed0a 100644 --- a/ical-tasks/sources/sections-ietf/98-references.adoc +++ b/ical-tasks/sources/sections-ietf/98-references.adoc @@ -11,6 +11,7 @@ * [[[RFC9073,RFC 9073]]] * [[[RFC9074,RFC 9074]]] * [[[RFC9253,RFC 9253]]] +* [[[draft-ietf-calext-subscription-upgrade,draft-ietf-calext-subscription-upgrade]]] [bibliography] == Informative References diff --git a/ical-tasks/sources/sections/03-terms.adoc b/ical-tasks/sources/sections/03-terms.adoc index 514f75e..5a278d8 100644 --- a/ical-tasks/sources/sections/03-terms.adoc +++ b/ical-tasks/sources/sections/03-terms.adoc @@ -3,7 +3,7 @@ Terms defined and used in this specification include: -Assignee:: A calendar user assigned to perform a given task. An assignee is equivalent to an attendee of an event. +Assignee:: A calendar user assigned to perform a given task. An assignee is equivalent to an "A"ttendee" of a task. BPMS:: Business Process Management Software @@ -16,13 +16,17 @@ Calendar User Agent (CUA):: This may be 2. Software that gathers calendar data on the Calendar User's behalf. Candidate:: -A calendar user who might be able to perform a given task, prior to actually being assigned the task, e.g., a dispatcher has a list of taxi drivers (candidates) from which one will be selected to pick-up a passenger. +A calendar user who might be able to perform a given task, prior to actually +being assigned the task, e.g., a dispatcher has a list of taxi drivers (candidates) from which one will be selected to pick-up a passenger. Organizer:: -A calendar user who creates a calendar item, requests free/busy information, or published free/busy information. It is an Organizer who invites Attendees <>. +A calendar user who creates a calendar item, requests free/busy information, +or published free/busy information. It is an "Organizer" who invites "Attendees" <>. Observer:: -A calendar user interested in a calendar component, e.g., a manager may have interest in all tasks that have not been completed. Often represented as an attendee with ROLE=NON-PARTICIPANT. +A calendar user interested in a calendar component, e.g., a manager may +have interest in all tasks that have not been completed. Often represented as +an "Attendee" with ROLE=NON-PARTICIPANT. Resource:: A resource in the scheduling context is any shared entity that can be scheduled by a calendar user, but does not control its own attendance status. Resources can be of "Location", "Equipment", or "Role" type. diff --git a/ical-tasks/sources/sections/06-architecture-foundations.adoc b/ical-tasks/sources/sections/06-architecture-foundations.adoc index 83462f3..223e581 100644 --- a/ical-tasks/sources/sections/06-architecture-foundations.adoc +++ b/ical-tasks/sources/sections/06-architecture-foundations.adoc @@ -3,7 +3,9 @@ == Architecture Foundations -The key standards that enable interoperability between the logical elements of the architecture are the Internet Calendaring and Scheduling Core Object Specification (iCalendar) <> and associated protocols. Task and task status are represented by the iCalendar "VTODO" component. Protocols include, in particular, the iCalendar Transport-Independent Interoperability Protocol (iTIP) <> for task assignment and scheduling, and Calendaring Extensions to WebDAV (CalDAV) <> for client server communication. +The key standards that enable interoperability between the logical elements of the +architecture are the Internet Calendaring and Scheduling Core Object Specification (iCalendar) <> +and associated protocols. Task and task status are represented by the iCalendar "VTODO" calendar component. Protocols include, in particular, the iCalendar Transport-Independent Interoperability Protocol (iTIP) <> for task assignment and scheduling, and Calendaring Extensions to WebDAV (CalDAV) <> for client server communication. Additionally, this specification uses definitions from Support for iCalendar Relationships <>. The LINK, REFID, RELATED-TO and CONCEPT properties enable context and a rich set of relationships between tasks and other iCalendar components to be specified. diff --git a/ical-tasks/sources/sections/07-task-extensions.adoc b/ical-tasks/sources/sections/07-task-extensions.adoc index bab5c81..e270143 100644 --- a/ical-tasks/sources/sections/07-task-extensions.adoc +++ b/ical-tasks/sources/sections/07-task-extensions.adoc @@ -13,4 +13,4 @@ Task Scheduling and Assignment:: ensure support for common pattens of scheduling Task Status Tracking:: improved granularity in status tracking information and alerting task actors to pending or actual task status changes -These extensions are supported mainly by additions to the properties and parameters used within the "VTODO" component. +These extensions are supported mainly by additions to the properties and parameters used within the "VTODO" calendar component. diff --git a/ical-tasks/sources/sections/08-task-specification.adoc b/ical-tasks/sources/sections/08-task-specification.adoc index af7181e..bd02477 100644 --- a/ical-tasks/sources/sections/08-task-specification.adoc +++ b/ical-tasks/sources/sections/08-task-specification.adoc @@ -6,11 +6,12 @@ The specification of tasks must be semantically explicit in order for them to be Task type:: explicitly what type of task is to be performed is identified. -Task context and relationships:: how a specific task relates to other tasks and other objects that need to be understood for the effective execution of a task. +Task context and relationships:: how a specific task relates to other tasks +and other objects that need to be understood for the effective execution of a task. Task specific data:: the form and content of domain data provided as input to a task and/or that may be output from a task. -Organizer and attendee:: recognizes that a task organizer or attendee can be an automated system. +Organizer and attendee:: recognizes that a task "Organizer" or "Attendee" can be an automated system. === Task type diff --git a/ical-tasks/sources/sections/10-scheduling.adoc b/ical-tasks/sources/sections/10-scheduling.adoc index 12a1c47..2bc5e62 100644 --- a/ical-tasks/sources/sections/10-scheduling.adoc +++ b/ical-tasks/sources/sections/10-scheduling.adoc @@ -2,9 +2,13 @@ == Task Scheduling and Assignment -Tasks are assigned to actors using one or more <> ATTENDEE -properties and/or one or more <> PARTICIPANT components. +Tasks are assigned to actors using one or more <> "ATTENDEE" +properties and/or one or more <> "PARTICIPANT" calendar components. -Communication of task assignment or delegation to one or more actors who are allocated to a task by the organizer is directly supported by iTIP, i.e., all included ATTENDEES in an iTIP REQUEST are expected to perform the task. +Communication of task assignment or delegation to one or more actors who are +allocated to a task by the organizer is directly supported by iTIP, i.e., all +included "ATTENDEE" properties in an iTIP REQUEST are expected to perform the task. -The offering or advertising of a task to one or more (potential) actors where only one or a subset of the candidates may accept the task will be addressed by a later specification. +The offering or advertising of a task to one or more (potential) actors where +only one or a subset of the candidates may accept the task will be addressed +by a later specification. diff --git a/ical-tasks/sources/sections/102-iana.adoc b/ical-tasks/sources/sections/102-iana.adoc index 9a55813..cf35c65 100644 --- a/ical-tasks/sources/sections/102-iana.adoc +++ b/ical-tasks/sources/sections/102-iana.adoc @@ -8,30 +8,10 @@ This specification updates <> by adding and updating a number of elements according to the procedures and templates specified in <>. -==== Initialization of the Status registry - -This specification updates <> by adding a Status value registry to the iCalendar Elements registry -located here: and initializing it as per <>. - -.Initial Status Value Registry -[cols="a,a,a",options=header] -|=== -| Name | Status | Reference - -| CANCELLED | Current | <> -| COMPLETED | Current | <> -| CONFIRMED | Current | <> -| DRAFT | Current | <> -| FINAL | Current | <> -| IN-PROCESS | Current | <> -| NEEDS-ACTION | Current | <> -| TENTATIVE | Current | <> - -|=== - ==== Update of the Status registry -This specification further updates the Status registry with additional values defined in this document. +This specification updates the Status registry defined in <> +with additional values defined in this document. .Updated Status Value Registry [cols="a,a,a",options=header] diff --git a/ical-tasks/sources/sections/11-status-reporting.adoc b/ical-tasks/sources/sections/11-status-reporting.adoc index 9ded133..ed65fdd 100644 --- a/ical-tasks/sources/sections/11-status-reporting.adoc +++ b/ical-tasks/sources/sections/11-status-reporting.adoc @@ -4,24 +4,24 @@ === Improved granularity in status reporting information -This document defines a new "VSTATUS" component (see section <>) +This document defines a new "VSTATUS" calendar component (see section <>) that can be used to group related information about the status of the task. This might include information on why (REASON) and when (DTSTAMP) a status has changed. In addition, new status values are specified to provide for task suspension, failure and preparation. -Note that while VSTATUS is intended to allow multiple date-stamped +Note that while the "VSTATUS" component is intended to allow multiple date-stamped status changes to be stored it is not intended to be used as a history of changes to a tasks properties. -=== Relating reason and comments to ATTENDEE status changes. +=== Relating reason and comments to "ATTENDEE" property status changes. -The <> PARTICIPANT component can be used to provide additional -information about why an ATTENDEE participation status has changed. -The COMMENT property can also +The <> "PARTICIPANT" calendar component can be used to provide additional +information about why an "ATTENDEE" property participation status has changed. +The "COMMENT" property can also be used to include additional human-readable information about why the -associated STATUS or ATTENDEE property changed. For example, if a driver +associated "STATUS" or "ATTENDEE" property changed. For example, if a driver failed to deliver a package because of a puncture it might be expressed as @@ -79,18 +79,18 @@ END:VSTATUS Different needs to alert or notify task actors of pending or actual task status changes are recognized: -Alarms:: Alarms (VALARM components) operate in the calendar user agent +Alarms:: Alarms ("VALARM" calendar components) operate in the calendar user agent space to notify the task actor of a pending task state for a task they are assigned to or are interested in. -Current standards (see <>) indicate VALARMs SHOULD be removed +Current standards (see <>) indicate "VALARM" calendar components SHOULD be removed from incoming data and many systems in fact do so. In a task assignment scenario it may be appropriate for the organizer to be able to set alarms for the participants. A system implementing these standards may choose to -preserve VALARMs but sending a task via some external service may result in +preserve "VALARM" calendar components but sending a task via some external service may result in them being removed. This issue is not addressed by this specification. -Escalations:: An escalation or notification to the ATTENDEE, ORGANIZER, +Escalations:: An escalation or notification to the "Attendee", "Organizer", or other task actor may be required if a deadline associated with a task is exceeded or for some other reason. Process Logic identifying when and who to propagate escalations to is the responsibility of the @@ -98,8 +98,8 @@ Task Generating System, e.g., a BPMS. Notifications:: Task actors (observers) not directly involved in performing a task but with a known interest in a given task's status -can be identified by the PARTICIPANT component <> against certain -components e.g. ALARM, to identify which task events the +can be identified by the "PARTICIPANT" calendar component <> against certain +components e.g. the "VALARM" calendar component, to identify which task events the stakeholder/party is interested in. Notifications on shared calendars will allow task actors to register an interest in changes to tasks within a calendar (see <>). diff --git a/ical-tasks/sources/sections/51-new-parameter-values.adoc b/ical-tasks/sources/sections/51-new-parameter-values.adoc index a1836a3..eb73fa6 100644 --- a/ical-tasks/sources/sections/51-new-parameter-values.adoc +++ b/ical-tasks/sources/sections/51-new-parameter-values.adoc @@ -8,7 +8,7 @@ Participant status parameter type values are defined in <>. This specification redefines that type -to include the new value FAILED for VTODO iCalendar components. +to include the new value FAILED for "VTODO" iCalendar components. Format Definition:: This property parameter is extended by the following notation: diff --git a/ical-tasks/sources/sections/52-new-properties.adoc b/ical-tasks/sources/sections/52-new-properties.adoc index 8c62ea8..f091247 100644 --- a/ical-tasks/sources/sections/52-new-properties.adoc +++ b/ical-tasks/sources/sections/52-new-properties.adoc @@ -25,7 +25,12 @@ est-duration = "ESTIMATED-DURATION" durparam ":" dur-value CRLF durparam = *(";" other-param) ---- -Description:: In a "VTODO" calendar component the property MAY be used to specify the estimated duration for the to-do, with or without an explicit time window in which the event should be started and completed. When present, DTSTART and DUE/DURATION represent the window in which the task can be performed. ESTIMATED-DURATION SHOULD be passed from ORGANIZER to ATTENDEE in iTIP <> messages. +Description:: In a "VTODO" calendar component the property MAY be +used to specify the estimated duration for the to-do, with or without +an explicit time window in which the event should be started and completed. +When present, "DTSTART" and "DUE"/"DURATION" properties represent the +window in which the task can be performed. The "ESTIMATED-DURATION" property +SHOULD be passed from the organizer to the "Attendee" in iTIP <> messages. Example:: The following is an example of this property that estimates the duration of a task to be one hour: @@ -39,13 +44,13 @@ ESTIMATED-DURATION:PT1H Property name:: REASON -Purpose:: To indicate the reason for a status change or change of attendee participation status. +Purpose:: To indicate the reason for a status change or change of "Attendee" participation status. Value Type:: URI Property Parameters:: IANA and non-standard property parameters can be specified on this property. -Conformance:: This property can be specified in "VSTATUS" and PARTICIPANT calendar components. +Conformance:: This property can be specified in "VSTATUS" and "PARTICIPANT" calendar components. Format Definition:: This property is defined by the following notation: @@ -162,7 +167,7 @@ taskmodeparam = *(";" other-param) Description:: In a "VTODO" calendar component this property MAY be used to indicate to servers how they can automatically change the -state of the task based on iTIP replies from Attendees. For example, +state of the task based on iTIP replies from "Attendees". For example, the server can automatically set the overall task status to COMPLETED when every attendee has marked their own status (PARTSTAT) as COMPLETED, or the server could mark the task as FAILED if its DUE date passes @@ -185,17 +190,17 @@ TASK-MODE:AUTOMATIC-FAILURE AUTOMATIC-COMPLETION Task Mode:: The task mode value "AUTOMATIC-COMPLETION" indicates to the server -that it can change the "VTODO" component's status to "COMPLETED" as -soon as all ATTENDEEs in the task have replied with a "PARTSTAT" +that it can change the "VTODO" calendar component's status to "COMPLETED" as +soon as all attendees in the task have replied with a "PARTSTAT" parameter set to "COMPLETED". [[task-mode-automatic-failure]] AUTOMATIC-FAILURE Task Mode:: The task mode value "AUTOMATIC-FAILURE" indicates to the server that -it SHOULD change the "VTODO" component's status to "FAILED" if either: +it SHOULD change the "VTODO" calendar component's status to "FAILED" if either: -. the PARTSTAT of one ATTENDEE is set to FAILED; or +. the PARTSTAT of one "ATTENDEE" property is set to FAILED; or . the current time is past the effective due date of the component and the task has not yet been completed. @@ -213,10 +218,10 @@ the status set by the client. SERVER Task Mode:: The task mode value "SERVER" indicates to the server that it can change -the "VTODO" component's status to an appropriate value, based on -implementation defined "business rules", as ATTENDEE responses are +the "VTODO" calendar component's status to an appropriate value, based on +implementation defined "business rules", as attendee responses are processed or as deadlines related to the task pass. + -The server can add this property to a "VTODO" component to indicate to +The server can add this property to a "VTODO" calendar component to indicate to the client that it will be managing the status. diff --git a/ical-tasks/sources/sections/53-property-extensions.adoc b/ical-tasks/sources/sections/53-property-extensions.adoc index 7b59409..3f15783 100644 --- a/ical-tasks/sources/sections/53-property-extensions.adoc +++ b/ical-tasks/sources/sections/53-property-extensions.adoc @@ -65,7 +65,7 @@ statvalue-todo = / "PENDING" ;Indicates a to-do has been ;created and accepted, but has ; not yet started. / "FAILED" ;Indicates to-do has failed. -;Extended status values for "VTODO". +;Extended status values for "VTODO" calendar component. ---- Description: diff --git a/ical-tasks/sources/sections/54-new-components.adoc b/ical-tasks/sources/sections/54-new-components.adoc index 1d2b901..f641d31 100644 --- a/ical-tasks/sources/sections/54-new-components.adoc +++ b/ical-tasks/sources/sections/54-new-components.adoc @@ -16,7 +16,7 @@ any calendar component. Description:: This component provides a way for multiple date-stamped statuses to be associated with a component such as a participant, task or event. -This component may be added to the <> PARTICIPANT component +This component may be added to the <> "PARTICIPANT" component to allow participants in a task to specify their own status. For backwards compatibility, when a VSTATUS component is added the diff --git a/ical-tasks/sources/sections/a1-eg-task-state-lifecycle.adoc b/ical-tasks/sources/sections/a1-eg-task-state-lifecycle.adoc index 5a1d20f..b89d523 100644 --- a/ical-tasks/sources/sections/a1-eg-task-state-lifecycle.adoc +++ b/ical-tasks/sources/sections/a1-eg-task-state-lifecycle.adoc @@ -44,7 +44,8 @@ Example of status changes in assigning and performing a task with two attendees |=== -NOTE: The logic for determining the status change to the VTODO is determined by the task organizer based on the ATTENDEE status and other business logic. +NOTE: The logic for determining the status change to the VTODO calendar component +is determined by the task organizer based on the "ATTENDEE" property status and other business logic. === Example of Failure