RFC 10051 Task Extensions to iCalendar October 2026
Apthorp & Douglass Standards Track [Page]
Stream:
Internet Engineering Task Force (IETF)
RFC:
10051
Updates:
5545
Category:
Standards Track
Published:
ISSN:
2070-1721
Authors:
A. Apthorp
DHL Express
M. Douglass
Bedework Commercial Services

RFC 10051

Task Extensions to iCalendar

Abstract

The "VTODO" calendar component in the Internet Calendaring and Scheduling Core Object Specification (iCalendar; RFC 5545) has seen limited adoption and use, mainly for personal reminders and to-do lists.

This document updates RFC 5545 and defines extensions to "VTODO" to provide improved status tracking, scheduling, and specification of tasks to allow its use in other contexts, such as process control and project management.

It also defines how Calendaring Extensions to WebDAV (CalDAV) (RFC 4791) servers can be extended to support certain automated task management behaviors.

Status of This Memo

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc10051.

▲

Table of Contents

1. Introduction

This document specifies extensions to the Internet Calendaring and Scheduling Core Object Specification (iCalendar) [RFC5545] and associated protocols in order to enhance the structured communication and execution of tasks. The enhancements allow for the communication, time planning, and scheduling of tasks by and between automated systems (e.g., taxi dispatch systems, smart power grids [WsCalendar], and business process management systems), as well as for human-centered tasks.

A "task" is a representation of an item of work assigned to an individual or organization. In the iCalendar Object Model [RFC5545] the representation of tasks is by "VTODO" calendar components. Tasks can be identified in a number of situations, either informally as ad hoc tasks in personal to-do lists or more formally in business processes (ranging from repetitive workflows to adaptive cases and trouble ticketing) and project management (whether for large-scale construction projects or collaborative software development).

The extensions specified in this document enhance and standardize the following:

  • The specification of tasks: How a task type is defined and the relationships between tasks; see Section 4.
  • Task planning and scheduling: Improved specification of deadlines and estimated time for completion; see Section 5.
  • Task assignment and status reporting: The addition of "VSTATUS" (Section 8) allows for more detailed reports; see Section 7.

These extensions are defined within the context of an overall architecture for task calendaring and scheduling, which elaborates that supported by [RFC5545] and related standards.

1.1. 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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The notation used in this memo to (re-)define iCalendar elements is ABNF [RFC5234], as used by [RFC5545]. Any syntax elements shown below that are not explicitly defined in this specification come from iCalendar [RFC5545].

Calendaring and scheduling roles are referred to in quoted-strings of text with the first character of each word in uppercase. For example, "Organizer" refers to the role of a "Calendar User" (CU) within the scheduling protocol.

Calendar components defined by [RFC5545] 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 a scheduling calendar component be created or modified, and "REPLY" refers to the method the recipient of a request uses to update their status with the "Organizer" of the calendar component.

Properties defined by [RFC5545] and updating specifications are referred to with capitalized quoted-strings of text, followed by the word "property". For example, the "ATTENDEE" property refers to the iCalendar property used to convey the calendar address of a "Calendar User".

Property parameters defined by [RFC5545] and updating specifications are referred to with lowercase quoted-strings of text, followed by the word "parameter". For example, the "value" parameter refers to the iCalendar property parameter used to override the default data type for a property value.

Enumerated values defined by this specification are referred to with capitalized text, either alone or followed by the word "value".

In tables, the quoted-string text is specified without quotes in order to minimize the table length.

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 a task.

BPMS:

Business Process Management Software

CU:

Calendar User. A person or software system that accesses or modifies calendar information.

CUA:

Calendar User Agent. This may be one of the following:

  1. Software with which the CU communicates with a calendar service or local calendar store to access calendar information.
  2. Software that gathers calendar data on the CU'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.

Organizer:

A calendar user who creates a calendar item, requests free/busy information, or publishes free/busy information. It is an "Organizer" who invites "Attendees" [RFC5545].

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 the "role" parameter set to 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. Examples of such resources are locations such as a bookable conference room or equipment such as projectors.

Task:

A representation of an item of work that can be assigned to one or more task actor assignees. In [RFC5545], these are "VTODO" calendar components, which are groupings of component properties and possibly "VALARM" calendar components that represent an action item or assignment.

2. Task Architecture

A reference architecture for task calendaring and scheduling is defined in order to identify the key logical elements involved in task management and the interfaces between them to enable interoperability. Central to this architecture is the Calendar and Scheduling System. The logical elements identified here establish an appropriate separation of concerns and clarify the responsibilities of different elements. However, the architecture does not prescribe the binding or packaging of elements, i.e., software systems may be developed where some elements are tightly bound and the interfaces between bound elements are not exposed. The task architecture is also described in [TARCH].

  Task        +-------+
  Trigger             |
+---------------------V---------------------+    +-----------+
|           Task Generating System          |    |           |
|        +-------------------------+        |    |           |
|        |            O            |        |    |           |
|        |           /|\           |        |    |           |
|        |           / \           |        |    |           |
|        |      Task Organizer     |        <---->           |
|        +-^--------^--------------+        |    |           |
|          |        |                       |    |           |
| +--------V-+ +----V-----+    +----------+ |    |           |
| |   Task   | | Process  |    |   Task   | |    |           |
| |Assignment| |  Logic   <---->  Domain  | |    |           |
| |  Rules   | |          |    |   Data   | |    |           |
| +----------+ +----------+    +----------+ |    |           |
|                                           |    |           |
+------^----------+-----^-------------------+    |           |
       |          |     |                        |           |
  Availability  Task   Task                      |           |
       |          |   Status                     |           |
       |          |     |                        |           |
+------v----------v-----+-------------------+    |           |
|      Calendar and Scheduling System       |    | Directory |
| +---------+  +---------+                  |    |  Service  |
| |         |  |  Task   |                  <---->           |
| |Schedule |  |  Lists  |                  |    |           |
| |         |  |         |                  |    |           |
| +---------+  +---------+      Server      |    |           |
+-------------------------------------------+    |           |
|                               Client      |    |           |
| +----------------------+    +-----------+ |    |           |
| |       Calendar       |    |   Task    | |    |           |
| |      User Agent      +----> Specific  | <---->           |
| |                      |    |Application| |    |           |
| +----------------------+    +-----------+ |    |           |
|                                           |    |           |
+-----^---------^--------+---------+--------+    |           |
      |         |        |         |             |           |
+-----V---------V--------V---------V--------+    |           |
|                Task Actors                |    |           |
|     O         O        O         O        |    |           |
|    /|\       /|\      /|\       /|\       +---->           |
|    / \       / \      / \       / \       |    |           |
|          Candidate(s)        Observer(s)  |    |           |
| Assignee(s)       Resource(s)             |    |           |
+-------------------------------------------+    +-----------+
Figure 1: Task Architecture Diagram

2.1. Task Architecture Elements

The following logical elements form the task architecture that this specification is based on:

Task Actors:

Various calendar users that may be involved in the monitoring or performing of a task. The set of actors includes Organizers, Observers, Resources, Assignees, and Candidates.

Task Organizer:

The creator of a task who also determines task assignment and scheduling and monitors task progress.

Task Domain Data:

This is any domain-specific data that may be acted on or that provides context for performing a task.

Task-Specific Application:

A task-specific application renders the data concerning the task (including task domain data) for presentation and manipulation by a task actor.

Process Logic:

Determines under what conditions one or more tasks are generated and the actions to take upon task completion or upon the occurrence (or non-occurrence) of some other status event.

Task Trigger:

An event that gives rise to the generation of a task according to Process Logic. Task triggers can come from many sources including, for example, a task being requested through the calendaring system or a status change in the progression of a business process being managed by a business process management or enterprise resource planning (ERP) system.

Task Assignment Rules:

Govern how actors are assigned to a task. A range of different assignment patterns [WfRP] may be considered, including the two general cases:

  1. Delegation to a named actor or group of actors
  2. Advertising to a pool of actors for self-selection

In either case, the assignment may be made based on a variety of criteria including, name, availability, skills, capacity, etc.

Task Generating System:

A system that creates and assigns tasks in response to some initiating event (task trigger). Process Logic defines task creation, while Task Assignment Rules determine task assignment. This system also tracks the status of tasks and will initiate further actions based upon the status. A Task Generating System can take many forms, such as a Business Process Management System, Project Management System, Bug Tracking System, and Building Control System. A Task Generating System may also be a human. In iCalendar terms the Task Generating System is the "Organizer".

Task creation, assignment, and tracking coordinated by a human "Organizer" is a special case of a Task Generating System. In this case, Task Assignment Rules and Process Logic may be either explicit or tacit.

Calendar and Scheduling System:

A software system that stores, publishes, and synchronizes calendar data such as events, tasks, and journal entries for actors. In the context of tasks, this includes schedules (i.e., allocated time and availability to perform tasks) and task lists. A calendar and scheduling system typically consists of server and client software components.

It is not within the scope of this document to specify how Process Logic or Task Assignment Rules are codified. Such logic and rules may be codified in a variety of ways, including conventional programming languages (e.g., C++ and Java) or process modeling languages (e.g., Business Process Model and Notation (BPMN) [BPMN]).

2.2. Architecture Foundations

The key standards that enable interoperability between the logical elements of the architecture are iCalendar [RFC5545] and the associated protocols. Task and task status are represented by the "VTODO" calendar component. Protocols include, in particular, the iCalendar Transport-Independent Interoperability Protocol (iTIP) [RFC5546] for task assignment and scheduling and the Calendaring Extensions to WebDAV (CalDAV) [RFC4791] for client server communication.

Additionally, this specification uses definitions from "Support for iCalendar Relationships" [RFC9253]. The "LINK", "REFID", "RELATED-TO", and "CONCEPT" properties enable context and a rich set of relationships between tasks and other calendar components to be specified.

3. Task Extensions

In order to support the task architecture described in Section 2, this document defines a number of extensions to iCalendar [RFC5545] in the following areas:

Task Specification:

Improved ability to specify domain-specific tasks.

Task Deadlines, Milestones, and Time Planning:

Clarification of deadlines and extension for task duration to support task time planning.

Task Scheduling and Assignment:

Ensure support for common patterns of scheduling and assigning tasks.

Task Status Tracking:

Improved granularity in status tracking information and alerting task actors of pending or actual task status changes.

These extensions are supported mainly by additions to the properties and parameters used within the "VTODO" calendar component.

4. Task Specification

The specification of tasks must be semantically explicit in order for them to be managed within the context of a business process or project and understood by both humans and IT systems. The "VTODO" calendar component [RFC5545] only provides for simple ad hoc tasks or to-do lists and is therefore extended by this specification as follows:

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-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.

4.1. Task Type

The "CONCEPT" property [RFC9253] is used to identify the type of task, for example:

CONCEPT:http://example.com/task/delivery

4.2. Task Context and Relationships

The "LINK" property [RFC9253] specifies a link to external information, which may provide context for the task. For example:

LINK;LINKREL=describedby;VALUE=URI:
 mid:752142.141482.307E5@mx123.example.com

The external information may consist of data to be manipulated in performing the task.

The "LINK" property can be used to relate a domain-specific service to the task. For example, it might be a URI pointing to a web page where the status of the task can be directly manipulated.

Note: The link relations below are for illustration only.

LINK;LINKREL="vacation-system";VALUE=URI:
 http://example.com/vacation-approval?id=1234

Additionally, it might be used to link data specific to the task, for example, an electronic copy of a signature taken to confirm delivery of a package.

LINK;LINKREL="electronic-signature";VALUE=URI:
 http://example.com/delivery/sig1234.jpg

The "REFID" property [RFC9253] is used to identify a key used to group tasks by that key.

REFID:Manhattan

REFID:1234567890

Extensions to the "RELATED-TO" property defined in [RFC9253] allow temporal relationships between tasks as found in project management to be specified as well as parent/child relationships and dependencies (DEPENDS-ON). Tasks ("VTODO" calendar components) may also be related to other calendar components, for example, a "VEVENT" calendar component used to block time to perform a task.

5. Task Deadlines, Milestones, and Time Planning

5.1. Deadlines

Deadlines for starting and finishing a task are defined by the "DTSTART", "DUE", and "DURATION" properties. The "DTSTART" property represents the earliest start time for beginning work on a task. The "DUE" or "DTSTART" + "DURATION" properties represent the latest finish time for a task. Thus, these properties define a "window" within which a task has to be performed. However, [RFC5545] provides no way to indicate how long the task is expected to take. This document defines a new "ESTIMATED-DURATION" property, in Section 10.1, to allow the estimated time that a task should take to be specified separately from the deadlines for starting and finishing a task. This supports time planning by enabling calendar user agents to display when tasks should occur, which allows calendar users to visualize when tasks should be performed and to allocate time to them accordingly.

5.2. Milestones

A task that has intermediary deadlines (i.e., milestones) MUST be expressed by child "VTODO" calendar components (i.e., subtasks associated with each of the milestones) in conjunction with the "RELATED-TO" property to relate the parent and child tasks.

6. Task Scheduling and Assignment

Tasks are assigned to actors using one or more "ATTENDEE" properties [RFC5545] and/or one or more "PARTICIPANT" calendar components [RFC9073], as described in Section 7.4.

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.

7. Status Reporting

7.1. Improved Granularity in Status Reporting Information

This document defines a new "VSTATUS" calendar component (see Section 12.1) that can be used to group related information about the status of the task. This might include information on why (the "REASON" property) and when (the "DTSTAMP" property) a status has changed. In addition, new status values are specified to provide for task suspension, failure, and preparation.

BEGIN:VSTATUS
STATUS:FAILED
REASON:https://example.com/reason/delivery-failed
SUBSTATE:ERROR
DTSTAMP:20130212T120000Z
COMMENT:Breakdown
END:VSTATUS

7.2. Comments Associated to Reasons and Status Changes

Multiple comments and reasons may have the same status. As situations change, further "VSTATUS" calendar components can be added to provide additional information.

CONCEPT:https://example.com/task/delivery
BEGIN:VSTATUS
STATUS:FAILED
SUBSTATE:ERROR
DTSTAMP:20220212T104900Z
COMMENT:Out of time
END:VSTATUS
BEGIN:VSTATUS
STATUS:FAILED
COMMENT:Traffic Accident on E44
REASON:https://example.com/reason/traffic
DTSTAMP:20220212T110451Z
END:VSTATUS
BEGIN:VSTATUS
STATUS:FAILED
COMMENT:Arrived after office hours
REASON:https://example.com/reason/closed
DTSTAMP:20220212T180451Z
END:VSTATUS

Note that the "VSTATUS" calendar component is not intended to be used as a history of changes to a task's properties. The purpose of the "VSTATUS" calendar component is only to document changes related to fulfilling the tasks.

7.3. Updating the Overall Status

Only the Task Organizer, or the server acting as the Organizer's proxy, may change or add "VSTATUS" calendar components and the "STATUS" property.

The overall "VSTATUS" will be changed in response to incoming "Attendee" replies. Each change of the overall "VSTATUS" MUST be accompanied by a change to the STATUS.

Note there is no defined ordering of properties and components so the DTSTAMP property SHOULD be set for each "VSTATUS" component to preserve ordering.

7.4. Relating Reason and Comments to "ATTENDEE" Property Status Changes

The "PARTICIPANT" calendar component [RFC9073] can be used to provide additional information about why an "ATTENDEE" property's participation status has changed, by following the guidelines set out in Section 7.1 of [RFC9073]. 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 failed to deliver a package because of a puncture, it might be expressed as

ATTENDEE;PARTSTAT=FAILED:mailto:xxx@example.com
...
BEGIN:PARTICIPANT
CALENDAR-ADDRESS:mailto:xxx@example.com
DTSTAMP:20130226T1104510Z
REASON:https://example.com/reason/van-break-down
COMMENT:Puncture
END:PARTICIPANT

7.5. Task Alerts and Notifications

Different requirements to alert or notify task actors of pending or actual task status changes are recognized:

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 (such as [RFC9074]) indicate that "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 "VALARM" calendar components, but sending a task via some external service may result in their removal. This issue is not addressed by this specification.

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 is the responsibility of the Task Generating System, e.g., a BPMS.

Notifications:

Task actors (Observers) not directly involved in performing a task but that have a known interest in a given task's status can be identified by the "PARTICIPANT" calendar component [RFC9073] 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 Appendix A).

7.6. Automated Status Changes

A new "TASK-MODE" property is introduced to instruct servers to apply automated operations for changing the status of a task.

8. Modifications to Calendar Components

The following changes to the syntax defined in iCalendar [RFC5545] and Event Publishing Extensions to iCalendar [RFC9073] are made here. New elements are defined in subsequent sections.

; Addition of VSTATUS as a valid component for VEVENT
eventc     = "BEGIN" ":" "VEVENT" CRLF
             eventprop *alarmc *participantc *locationc
                 *resourcec *statusc
             "END" ":" "VEVENT" CRLF

; Addition of VSTATUS as a valid component for VTODO
todoc      = "BEGIN" ":" "VTODO" CRLF
             todoprop *alarmc *participantc *locationc
                 *resourcec *statusc
             "END" ":" "VTODO" CRLF

; Addition of properties ESTIMATED-DURATION and TASK-MODE to VTODO
todoprop =/ est-duration /
            task-mode

; Addition of VSTATUS as a valid component for VJOURNAL
journalc   = "BEGIN" ":" "VJOURNAL" CRLF
              jourprop *statusc
              "END" ":" "VJOURNAL" CRLF


; Addition of VSTATUS as a valid component for VFREEBUSY
freebusyc  = "BEGIN" ":" "VFREEBUSY" CRLF
             fbprop *participantc *locationc *resourcec *statusc
             "END" ":" "VFREEBUSY" CRLF

; Addition of VSTATUS as a valid component for PARTICIPANT
participantc = "BEGIN" ":" "PARTICIPANT" CRLF
               partprop *locationc *resourcec
               *statusc
               "END" ":" "PARTICIPANT" CRLF


; Addition of properties PERCENT-COMPLETE and REASON to PARTICIPANT
partprop =/ percent / ; OPTIONAL but MUST NOT occur more than once.
            reason    ; OPTIONAL but MUST NOT occur more than once.

9. New Parameter Values

9.1. Redefined VTODO Participant Status

Participant status parameter type values are defined in Section 3.2.12 of [RFC5545]. This specification redefines that type to include the new value "FAILED" for "VTODO" calendar components.

Format Definition:

This property parameter is redefined by the following notation, which adds the value "FAILED":

partstat-todo    = ("NEEDS-ACTION"    ; To-do needs action
                 / "ACCEPTED"         ; To-do accepted
                 / "DECLINED"         ; To-do declined
                 / "TENTATIVE"        ; To-do tentatively
                                      ; accepted
                 / "DELEGATED"        ; To-do delegated
                 / "COMPLETED"        ; To-do completed
                                      ; COMPLETED property has
                                      ; DATE-TIME completed
                 / "IN-PROCESS"       ; To-do in process of
                                      ; being completed
                 / "FAILED"           ; To-do cannot be
                                      ; completed
                 / x-name             ; Experimental status
                 / iana-token)        ; Other IANA-registered
                                      ; status
; These are the participation statuses for a "VTODO".
; Default is NEEDS-ACTION.
Example:
ATTENDEE;REASON="https://example.com/reason/not-enough-time";
 PARTSTAT=FAILED:mailto:jsmith@example.com

10. New Properties

10.1. Estimated Duration

Property Name:

ESTIMATED-DURATION

Purpose:

This property specifies the estimated positive duration of time the corresponding task will take to complete.

Value Type:

DURATION

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in "VTODO" calendar components.

Format Definition:

This property is defined by the following notation:

est-duration  = "ESTIMATED-DURATION" durparam ":" dur-value CRLF
                ;consisting of a positive duration of time.

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, the "DTSTART" and "DUE" or "DTSTART" and "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 [RFC5546] messages.

Example:

The following example illustrates how this property is used to estimate a task duration of one hour:

ESTIMATED-DURATION:PT1H

10.2. Reason

Property Name:

REASON

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.

Format Definition:

This property is defined by the following notation:

reason      = "REASON" reasonparam ":" uri CRLF

reasonparam = *(";" other-param)
Description:

This property allows a change in task or participant status to be qualified with a codified reason. Typically, reasons are defined within the context of the task type and therefore SHOULD include the name-space of the authority defining the task.

Example:
REASON:https://example.com/reason/delivered-on-time

10.3. Substate

Property Name:

SUBSTATE

Purpose:

To provide additional granularity of a task status, such as IN-PROCESS.

Value Type:

TEXT

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in a "VSTATUS" calendar component.

Format Definition:

This property is defined by the following notation:

substate         = "SUBSTATE" substateparam ":" substatevalue CRLF

substateparam    = *(";" other-param)

substatevalue    = ("OK"        ; everything is fine (the default)
                  / "ERROR"     ; something is wrong (REASON
                  ;               explains why)
                  / "SUSPENDED" ; waiting on some other task to
                  ;               complete or availability of a
                  ;               resource (REASON explains why)
                  / iana-token) ; other IANA-registered type
Description:

The "SUBSTATE" property allows additional qualification and granularity of states to be recorded, in particular for the IN-PROCESS state. It allows individual substates to be recorded without the need to define and publish a subtask associated with a parent task purely to track that a particular state has been reached. This property also allows parallel states to be expressed, such as indicating that a task has been suspended at whatever state it has reached.

Example:
BEGIN:VSTATUS
STATUS:FAILED
REASON:https://example.com/reason/no-one-home
SUBSTATE:ERROR
END:VSTATUS

BEGIN:VSTATUS
STATUS:IN-PROCESS
REASON:https://example.com/reason/paint-drying
SUBSTATE:SUSPENDED
END:VSTATUS

10.4. Task Mode

Property Name:

TASK-MODE

Purpose:

This property specifies automatic operations that servers acting on behalf of the "Organizer" apply to tasks based on changes in "Attendee" status (PARTSTAT).

Value Type:

TEXT

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified zero times or once in a "VTODO" calendar component.

Format Definition:

This property is defined by the following notation:

task-mode   = "TASK-MODE" taskmodeparam ":"
                 ("AUTOMATIC-COMPLETION"
                 / "AUTOMATIC-FAILURE"
                 / "AUTOMATIC"
                 / "SERVER"
                 / "CLIENT"
                 / iana-token) CRLF

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, 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 before completion. "TASK-MODE" processing is performed on the "Organizer's" copy of the task.

To set the status, add a "VSTATUS" component as specified in Section 12.1.

The property value is an IANA-registered token that defines the mode to be used for the task. The modes are described in the following subsections.

If the "TASK-MODE" property is absent, then the "CLIENT" value is assumed.

AUTOMATIC-COMPLETION Task Mode:

The task mode value "AUTOMATIC-COMPLETION" indicates to the server that it SHOULD 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".

Failing the task MUST be handled by a client.

AUTOMATIC-FAILURE Task Mode:

The task mode value "AUTOMATIC-FAILURE" indicates to the server that it SHOULD change the "VTODO" calendar component's status to "FAILED" if either:

  1. the PARTSTAT of one "ATTENDEE" property is set to "FAILED"; or

  2. the current time is past the effective due date of the component and the task has not yet been completed. The effective due date is either the "DUE" property value or the combination of the "DTSTART" and "DURATION" property values.

    Completing the task MUST be handled by a client.

AUTOMATIC Task Mode:

This mode handles the automatic behavior of both "AUTOMATIC-COMPLETION" and "AUTOMATIC-FAILURE".

CLIENT Task Mode:

The task mode value "CLIENT" is an instruction to the server to honor the status set by the client.

SERVER Task Mode:

The task mode value "SERVER" indicates to the server that it SHOULD change 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.

Examples:
TASK-MODE:AUTOMATIC-COMPLETION
TASK-MODE:AUTOMATIC-FAILURE
TASK-MODE:SERVER

11. Property Extensions and Clarifications

11.1. Updated DURATION Property Definition for VTODO

Section 3.6.2 of [RFC5545] introduces a constraint on the use of the "DURATION" property in the "VTODO" calendar component, requiring that a "DURATION" property MUST be accompanied by a "DTSTART" property. This constraint is now dropped, reverting to the situation as specified previously. Thus, Section 3.6.2 of [RFC5545] is updated as follows:

OLD TEXT:

; Either 'due' or 'duration' MAY appear in
; a 'todoprop', but 'due' and 'duration'
; MUST NOT occur in the same 'todoprop'.
; If 'duration' appear in a 'todoprop',
; then 'dtstart' MUST also appear in
; the same 'todoprop'.

NEW TEXT:

; Either 'due' or 'duration' MAY appear in
; a 'todoprop', but 'due' and 'duration'
; MUST NOT occur in the same 'todoprop'.

Note: This allows a "VTODO" calendar component to only have a "DURATION" property.

OLD TEXT:

A "VTODO" calendar component without the "DTSTART" and "DUE" (or "DURATION") properties specifies a to-do that will be associated with each successive calendar date, until it is completed.

NEW TEXT:

A "VTODO" calendar component without the "DTSTART" and "DUE" properties specifies a to-do that will be associated with each successive calendar date, until it is completed.

11.2. Redefined STATUS Property

The "STATUS" property is defined in Section 3.8.1.11 of [RFC5545]. This specification extends that property to include new values associated with "VTODO" calendar components (see Appendix A for examples of the task state lifecycle).

Format Definition:

The "STATUS" property parameter list for tasks is redefined by the addition of the values "PENDING" and "FAILED":

statvalue-todo  = "NEEDS-ACTION" ; To-do needs action.
                / "COMPLETED"    ; To-do completed.
                / "IN-PROCESS"   ; To-do in process of.
                / "CANCELLED"    ; To-do was cancelled.
                / "PENDING"      ; A to-do has been
                                 ;   created and accepted, but
                                 ;   has not yet started.
                / "FAILED"       ; To-do has failed.
; Extended status values for "VTODO" calendar component.
Description:
PENDING:
A to-do has been created and accepted but has not yet started and is ready to start subject to other dependencies (e.g., a preceding task or DTSTART). This is the default state.
FAILED:
A to-do has failed and may need some follow-up from the "Organizer" to reschedule or cancel.
Example:

The following is an example of this property for a "VTODO" calendar component:

STATUS:FAILED

12. New Components

12.1. Status Component

Component Name:

VSTATUS

Purpose:

This component allows information to be associated with a status, for example, comments and date stamps.

Conformance:

This component can be specified multiple times in 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 [RFC9073] to allow participants in a task to specify their own status.

For backwards compatibility, when a "VSTATUS" component is added, the "STATUS" property [RFC5545] MUST be set on the parent component.

Format Definition:

This component is defined by the following notation:

statusc      = "BEGIN" ":" "VSTATUS" CRLF
               statusprop
               "END" ":" "VSTATUS" CRLF

statusprop   = *(
             ;
             ; The following is REQUIRED,
             ; but MUST NOT occur more than once.
             ;
             status /
             ;
             ; The following are OPTIONAL,
             ; but MUST NOT occur more than once.
             ;
             description / dtstamp / reason / substate / summary /
             ;
             ; The following are OPTIONAL,
             ; and MAY occur more than once.
             ;
             comment / styleddescription / iana-prop
             ;
             )
Examples:
BEGIN:VSTATUS
STATUS:COMPLETED
REASON: https://example.com/reason/delivered-on-time
DTSTAMP:20220212T120000Z
END:VSTATUS

13. CalDAV Support for Task Mode

The CalDAV [RFC4791] calendar access protocol allows clients and servers to exchange iCalendar data. With the introduction of the "TASK-MODE" property in this specification, different automated task management behaviors may be delegated to the server by the Task Organizer depending upon the value of "TASK-MODE".

In order for a CalDAV client to know what task modes are available, a CalDAV server advertises a CALDAV:supported-task-mode-set WebDAV property on calendar home or calendar collections if it supports the use of the "TASK-MODE" property as described in this specification. The server can advertise a specific set of supported task modes by including one or more CALDAV:supported-task-mode XML elements within the CALDAV:supported-task-mode-set XML element.

If no CALDAV:supported-task-mode XML elements are included in the WebDAV property, then clients MUST assume the server does not support this specification. The client MAY attempt to store iCalendar data containing "TASK-MODE" elements but needs to be prepared for a failure response from the server.

A server supporting this specification MUST return an HTTP 403 response with a DAV:error element containing a CALDAV:supported-task-mode XML element, if a client attempts to store iCalendar data with a "TASK-MODE" element value not supported by the server.

It is possible for a "TASK-MODE" value to be present in calendar data on the server being accessed by a client that does not support the "TASK-MODE" property. It is expected that existing clients, unaware of "TASK-MODE", will fail gracefully by ignoring the calendar property.

13.1. CALDAV:supported-task-mode-set Property

Name:

supported-task-mode-set

Namespace:

urn:ietf:params:xml:ns:caldav

Purpose:

Enumerates the set of supported iCalendar "TASK-MODE" element values supported by the server.

Protected:

This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of [RFC4918]).

Description:

See above.

Definition:
<!ELEMENT supported-task-mode-set(supported-task-mode*)>
<!ELEMENT supported-task-mode (#PCDATA)>
<!-- PCDATA value: string - case insensitive but
uppercase preferred -->
Example:
<C:supported-task-mode-set
   xmlns:C="urn:ietf:params:xml:ns:caldav">
  <C:supported-task-mode>AUTOMATIC</C:supported-task-mode>
  <C:supported-task-mode>SERVER</C:supported-task-mode>
  <C:supported-task-mode>CLIENT</C:supported-task-mode>
</C:supported-task-mode-set>

14. Security Considerations

This specification introduces no new security considerations beyond those identified in [RFC5545], [RFC5546], [RFC4791], and [RFC9253].

15. IANA Considerations

15.1. Component Registration

IANA has added the following new iCalendar component to the "Components" registry defined in Section 8.3.1 of [RFC5545] and located on <https://www.iana.org/assignments/icalendar>.

Table 1: Addition to the Components Registry
Component Status Reference

VSTATUS

Current

Section 12.1 of RFC 10051

15.2. Property Registrations

IANA has added the following new iCalendar properties to the "Properties" registry defined in Section 8.3.2 of [RFC5545] and located on <https://www.iana.org/assignments/icalendar>.

Table 2: Additions to the Properties Registry
Property Status Reference

ESTIMATED-DURATION

Current

Section 10.1 of RFC 10051

REASON

Current

Section 10.2 of RFC 10051

SUBSTATE

Current

Section 10.3 of RFC 10051

STATUS

Current

Section 11.2 of RFC 10051

TASK-MODE

Current

Section 10.4 of RFC 10051

15.3. STATUS Values Registry

IANA has created a new iCalendar registry called "STATUS Values" for values of the "STATUS" property defined in Section 3.8.1.11 of [RFC5545].

Additional values MAY be used, provided the process of Standards Action with Expert Review as described in Section 8.2.1 of [RFC5545] is used to register them, using the template in Section 8.2.6 of [RFC5545].

The initial contents of the "STATUS Values" registry are as follows:

Table 3: Initial Contents of the STATUS Values Registry
Name Status Reference

CANCELLED

Current

Section 3.8.1.11 of [RFC5545]

COMPLETED

Current

Section 3.8.1.11 of [RFC5545]

CONFIRMED

Current

Section 3.8.1.11 of [RFC5545]

DRAFT

Current

Section 3.8.1.11 of [RFC5545]

FAILED

Current

Section 11.2 of RFC 10051

FINAL

Current

Section 3.8.1.11 of [RFC5545]

IN-PROCESS

Current

Section 3.8.1.11 of [RFC5545]

NEEDS-ACTION

Current

Section 3.8.1.11 of [RFC5545]

PENDING

Current

Section 11.2 of RFC 10051

TENTATIVE

Current

Section 3.8.1.11 of [RFC5545]

15.4. SUBSTATE Values Registry

IANA has created a new iCalendar registry called "SUBSTATE Values" for values of the "SUBSTATE" property defined in Section 10.3.

Additional values MAY be used, provided the process of Standards Action with Expert Review described in Section 8.2.1 of [RFC5545] is used to register them, using the template in Section 8.2.6 of [RFC5545].

The initial contents of the "SUBSTATE Values" registry are as follows:

Table 4: Initial Contents of the SUBSTATE Values Registry
Substate Status Reference

OK

Current

Section 10.3 of RFC 10051

ERROR

Current

Section 10.3 of RFC 10051

SUSPENDED

Current

Section 10.3 of RFC 10051

15.5. TASK-MODE Values Registry

IANA has created a new iCalendar registry called "TASK-MODE Values" for values of the "TASK-MODE" property defined in Section 10.4.

Additional values MAY be used, provided the process of Standards Action with Expert Review described in Section 8.2.1 of [RFC5545] is used to register them, using the template in Section 8.2.6 of [RFC5545].

The initial contents of the "TASK-MODE Values" registry are as follows:

Table 5: Initial Contents of the TASK-MODE Values Registry
Task Mode Status Reference

AUTOMATIC-COMPLETION

Current

Section 10.4 of RFC 10051

AUTOMATIC-FAILURE

Current

Section 10.4 of RFC 10051

AUTOMATIC

Current

Section 10.4 of RFC 10051

CLIENT

Current

Section 10.4 of RFC 10051

SERVER

Current

Section 10.4 of RFC 10051

15.6. Participation Statuses Registry

IANA has added the following new iCalendar participation status to the "Participation Statuses" registry defined in Section 8.3.7 of [RFC5545] and located here: <https://www.iana.org/assignments/icalendar>.

Table 6: Participation Statuses Registry
Participation Status Status Reference

FAILED

Current

Section 9.1 of RFC 10051

16. References

16.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC4791]
Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, , <https://www.rfc-editor.org/info/rfc4791>.
[RFC4918]
Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, , <https://www.rfc-editor.org/info/rfc4918>.
[RFC5234]
Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, , <https://www.rfc-editor.org/info/rfc5234>.
[RFC5545]
Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, , <https://www.rfc-editor.org/info/rfc5545>.
[RFC5546]
Daboo, C., Ed., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, DOI 10.17487/RFC5546, , <https://www.rfc-editor.org/info/rfc5546>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC9073]
Douglass, M., "Event Publishing Extensions to iCalendar", RFC 9073, DOI 10.17487/RFC9073, , <https://www.rfc-editor.org/info/rfc9073>.
[RFC9074]
Daboo, C. and K. Murchison, Ed., ""VALARM" Extensions for iCalendar", RFC 9074, DOI 10.17487/RFC9074, , <https://www.rfc-editor.org/info/rfc9074>.
[RFC9253]
Douglass, M., "Support for iCalendar Relationships", RFC 9253, DOI 10.17487/RFC9253, , <https://www.rfc-editor.org/info/rfc9253>.

16.2. Informative References

[BPMN]
Object Management Group, "Business Process Model and Notation", Version 2.0.2, , <https://www.omg.org/spec/BPMN/2.0.2/About-BPMN>.
[TARCH]
CalConnect, "Task Architecture V 1.0", <https://www.calconnect.org/docs/architectures/Task%20Architecture%201.0.pdf>.
[WfRP]
Russell, N., ter Hofstede, A.H.M., Edmond, T., and W.M.P. van der Aalst, "Workflow Resource Patterns", BETA Working Paper Series, WP 127, , <http://www.workflowpatterns.com/patterns/resource/>.
[WsCalendar]
"WS-Calendar Version 1.0", OASIS Committee Specification 01, , <https://docs.oasis-open.org/ws-calendar/ws-calendar-spec/v1.0/cs01/ws-calendar-spec-v1.0-cs01.pdf>.

Appendix A. Examples of Task State Lifecycle

A.1. Simple Case Status Change

The following is an example of status changes when assigning and performing a task with one "Attendee".

Table 7: Example of Status Changes in Assigning and Performing a Task with One "Attendee"
STATUS PARTSTAT Action
1 - - Organizer draft
2 NEEDS-ACTION NEEDS-ACTION Organizer sends iTIP "REQUEST"
3 NEEDS-ACTION ACCEPTED Attendee "REPLY"
4 PENDING ACCEPTED Task accepted but waiting on some "trigger" to start (e.g., another task has to finish first)
5 IN-PROCESS IN-PROCESS Attendee "REPLY" now working on the task
6 IN-PROCESS COMPLETED Attendee "REPLY" completed
7 COMPLETED COMPLETED Overall state set by either the Organizer for TASK-MODE=CLIENT or the server for AUTOMATIC-COMPLETION

A.2. Example for Multiple "Attendees"

The following is an example of status changes when assigning and performing a task with two "Attendees" (A1 and A2).

Table 8: Example for Multiple "Attendees"
STATUS PARTSTAT (A1) PARTSTAT (A2) Action
1 - - - Organizer draft
2 NEEDS-ACTION NEEDS-ACTION NEEDS-ACTION Organizer sends iTIP "REQUEST"
4 NEEDS-ACTION ACCEPTED NEEDS-ACTION Attendee 1 "REPLY"
5 NEEDS-ACTION ACCEPTED ACCEPTED Attendee 2 "REPLY"
6 PENDING ACCEPTED ACCEPTED Task accepted but waiting on some "trigger" to start (e.g., another task has to finish first)
7 IN-PROCESS ACCEPTED IN-PROCESS Attendee 2 "REPLY" now working on the task
8 IN-PROCESS IN-PROCESS IN-PROCESS Attendee 1 "REPLY" now working on the task
9 IN-PROCESS COMPLETED IN-PROCESS Attendee 1 "REPLY" completed (overall status still IN-PROCESS)
10 IN-PROCESS COMPLETED COMPLETED Attendee 2 "REPLY" completed
11 COMPLETED COMPLETED COMPLETED Overall state set once both "Attendees" are finished. May be set by either the Organizer for TASK-MODE=CLIENT or the server for AUTOMATIC-COMPLETION

A.3. Example of Failure

The following is an example of status changes for a task that fails.

Table 9: Example of Failure
STATUS PARTSTAT Action
1 - - Organizer draft
2 NEEDS-ACTION NEEDS-ACTION Organizer sends iTIP "REQUEST"
3 NEEDS-ACTION ACCEPTED Attendee "REPLY"
4 IN-PROCESS IN-PROCESS Attendee "REPLY" now working on the task
5 IN-PROCESS FAILED Attendee "REPLY" task failed
6 FAILED FAILED Overall state set by Organizer for TASK-MODE=CLIENT or by server for AUTOMATIC-FAILURE

Acknowledgements

The authors would like to thank the members of the Calendaring and Scheduling Consortium technical committees and the following individuals for contributing their ideas, support, and comments: John Chaffee, Marten Gajda, and Ken Murchison.

The authors would also like to thank CalConnect, the Calendaring and Scheduling Consortium, for advice with this specification.

Authors' Addresses

Adrian Apthorp
DHL Express
Fritz-Erler-Str. 5
Bonn
Germany
Michael Douglass
Bedework Commercial Services
226 3rd Street
Troy, NY
United States of America