Skip to content

Latest commit

 

History

History
166 lines (112 loc) · 11.4 KB

list.mdown

File metadata and controls

166 lines (112 loc) · 11.4 KB
Raw

TaskLists

A TaskList is a named collection of tasks. All tasks are associated with exactly one TaskList.

A TaskList object has the following core properties:

  • id: Id (immutable; server-set) The id of the task list.

  • role: String|null (default: null) Denotes the task list has a special purpose. This MUST be one of the following:

    • inbox: This is the principal's default task list;
    • trash: This task list holds messages the user has discarded;

  • name: String The user-visible name of the task list. This may be any UTF-8 string of at least 1 character in length and maximum 255 octets in size.

  • description: String|null (default: null) An optional longer-form description of the task list, to provide context in shared environments where users need more than just the name.

  • color: String|null (default: null) A color to be used when displaying tasks associated with the task list.

    If not null, the value MUST be a case-insensitive color name taken from the set of names defined in Section 4.3 of CSS Color Module Level 3 COLORS, or an RGB value in hexadecimal notation, as defined in Section 4.2.1 of CSS Color Module Level 3.

    The color SHOULD have sufficient contrast to be used as text on a white background.

  • keywordColors String[String]|null (default:null) A map of keywords to the colors used when displaying the keywords associated to a task. The same considerations as for color above, apply.

  • categoryColors String[String]|null (default:null) A map of categories to the colors used when displaying the categories associated to a task. The same considerations as for color above, apply.

  • sortOrder: UnsignedInt (default: 0) Defines the sort order of task lists when presented in the client's UI, so it is consistent between devices. The number MUST be an integer in the range 0 <= sortOrder < 2^31.

    A task list with a lower order should be displayed before a list with a higher order in any list of task lists in the client's UI. Task lists with equal order SHOULD be sorted in alphabetical order by name. The sorting should take into account locale-specific character order convention.

  • isSubscribed: Boolean Has the user indicated they wish to see this task list in their client? This SHOULD default to false for task lists in shared accounts the user has access to and true for any new task list created by the user themselves.

    If false, the task list should only be displayed when the user explicitly requests it or to offer it for the user to subscribe to.

  • timeZone: String|null (default: null) The time zone to use for tasks without a time zone when the server needs to resolve them into absolute time, e.g., for alerts or availability calculation. The value MUST be a time zone id from the IANA Time Zone Database TZDB. If null, the timeZone of the account's associated Principal will be used. Clients SHOULD use this as the default for new tasks in this task list if set.

  • workflowStatuses: String[] (default: [completed, failed, in-process, needs-action, cancelled, pending]) Defines the allowed values for workflowStatus. The default values are based the values defined within [@!I-D.ietf-calext-jscalendar], Section 5.2.5 and pending. pending indicates the task has been created and accepted, but has not yet started.

    As naming and workflows differ between systems, mapping the status correctly to the present values of the Task can be challenging. In the most simple case a task system may support merely two states - done and not-done. On the other hand, statuses and their semantic meaning can differ between systems or task lists (e.g. projects). In case of uncertainty, here are some recommendations for mapping commonly observed values that can help during implementation:

    • completed: done (most simple case), closed, verified, …
    • in-process: in-progress, active, assigned, …
    • needs-action: not-done (most simple case), not-started, new, …
    • pending: waiting, deferred

  • shareWith: Id[TaskRights]|null (default: null) A map of Principal id to rights for principals this task list is shared with. The principal to which this task list belongs MUST NOT be in this set. This is null if the user requesting the object does not have the mayAdmin right, or if the task list is not shared with anyone. May be modified only if the user has the mayAdmin right. The account id for the principals may be found in the urn:ietf:params:jmap:principals:owner capability of the Account to which the task list belongs.

  • myRights: TaskRights (server-set) The set of access rights the user has in relation to this TaskList.

    • The user may fetch the task if they have the mayReadItems right on any task list the task is in.
    • The user may remove a task from a task list (by modifying the task's "taskListId" property) if the user has the appropriate permission for that task list.
    • The user may make other changes to the task if they have the right to do so in all task list to which the task belongs.

A TaskRights object has the following properties:

  • mayReadItems: Boolean The user may fetch the tasks in this task list.

  • mayWriteAll: Boolean The user may create, modify or destroy all tasks in this task list, or move tasks to or from this task list. If this is true, the mayWriteOwn, mayUpdatePrivate and mayRSVP properties MUST all also be true.

  • mayWriteOwn: Boolean The user may create, modify or destroy a task on this task list if either they are the owner of the task or the task has no owner. This means the user may also transfer ownership by updating a task so they are no longer an owner.

  • mayUpdatePrivate: Boolean The user may modify the following properties on all tasks in the task list, even if they would not otherwise have permission to modify that task. If the shareesActAs account capability is "self", these properties MUST all be stored per-user, and changes do not affect any other user of the task list. If shareesActAs is "secretary", the values are shared between all users.

    • keywords
    • color
    • useDefaultAlerts
    • alerts

    The user may also modify the above on a per-occurrence basis for recurring tasks (updating the recurrenceOverrides property of the task to do so).

  • mayRSVP: Boolean The user may modify the following properties of any Participant object that corresponds to one of the user's ParticipantIdentity objects in the account, even if they would not otherwise have permission to modify that task

    • participationStatus
    • participationComment
    • expectReply

    If the task has its "mayInviteSelf" property set to true (see Section XXX), then the user may also add a new Participant to the task with a sendTo property that is the same as the sendTo property of one of the user's ParticipantIdentity objects in the account. The roles property of the participant MUST only contain "attendee".

    If the task has its "mayInviteOthers" property set to true (see Section XXX) and there is an existing Participant in the task corresponding to one of the user's ParticipantIdentity objects in the account, then the user may also add new participants. The roles property of any new participant MUST only contain "attendee".

    The user may also do all of the above on a per-occurrence basis for recurring tasks (updating the recurrenceOverrides property of the task to do so).

  • mayAdmin: Boolean The user may modify sharing for this task list.

  • mayDelete: Boolean (server-set) The user may delete the task list itself. This property MUST be false if the account to which this task list belongs has the isReadOnly property set to true.

The user is an owner for a task if the Task object has a "participant" property, and one of the Participant objects both:

  1. Has the "chair" role.
  2. Corresponds to one of the user's ParticipantIdentity objects in the account.

A task has no owner if its participant property is null or omitted.

Alerts extension

A TaskList has the following alerts properties:

  • defaultAlertsWithTime: Id[Alert]|null A map of alert ids to Alert objects (see [@!I-D.ietf-calext-jscalendar], Section 4.5.2) to apply for tasks where "showWithoutTime" is false and "useDefaultAlerts" is true. Ids MUST be unique across all default alerts in the account, including those in other task lists; a UUID is recommended.

    If omitted on creation, the default is server dependent. For example, servers may choose to always default to null, or may copy the alerts from the default task list.

  • defaultAlertsWithoutTime: Id[Alert]|null A map of alert ids to Alert objects (see [@!I-D.ietf-calext-jscalendar], Section 4.5.2) to apply for tasks where "showWithoutTime" is true and "useDefaultAlerts" is true. Ids MUST be unique across all default alerts in the account, including those in other task lists; a UUID is recommended.

    If omitted on creation, the default is server dependent. For example, servers may choose to always default to `null`, or may copy the alerts from the default task list.

TaskList/get

This is a standard "/get" method as described in [@!RFC8620], Section 5.1. The ids argument may be null to fetch all at once.

TaskList/changes

This is a standard "/changes" method as described in [@!RFC8620], Section 5.2.

TaskList/set

This is the "Calendar/set" method as described in [@!I-D.ietf-jmap-calendars], Section XXX.

  • onDestroyRemoveTasks: Boolean (default: false)

    If false, any attempt to destroy a TaskList that still has Tasks in it will be rejected with a TaskListHasTask SetError. If true, any Tasks that were in the TaskList will be removed from it and they will be destroyed.

The "role" and "shareWith" properties may only be set by users that have the mayAdmin right. The value is shared across all users, although users without the mayAdmin right cannot see the value.

When modifying the shareWith property, the user cannot give a right to a principal if the principal did not already have that right and the user making the change also does not have that right. Any attempt to do so must be rejected with a forbidden SetError.

Users can subscribe or unsubscribe to a task list by setting the "isSubscribed" property. The server MAY forbid users from subscribing to certain task lists even though they have permission to see them, rejecting the update with a forbidden SetError.

The "timeZone", "defaultAlertsWithoutTime" and "defaultAlertsWithTime" properties are stored per-user if the task list account's "shareesActAs" capability is "self", and may be set by any user who is subscribed to the task list. Otherwise, these properties are shared, and may only be set by users that have the mayAdmin right.

The following properties may be set by anyone who is subscribed to the task list and are all stored per-user:

  • name
  • color
  • sortOrder

These properties are initially inherited from the owner's copy of the task list, but if set by a sharee that user gets their own copy of the property; it does not change for any other principals. If the value of the property in the owner's task list changes after this, it does not overwrite the sharee's value.

The following extra SetError types are defined:

For "destroy":

  • taskListHasTask: The Task List has at least one Task assigned to it, and the "onDestroyRemoveTasks" argument was false.