Entry tasks

Tasks are the building blocks to setup editorial workflows on your content. They allow editorial teams to distribute work with clear accountability.

Unresolved tasks block entry publishing

The entry publishing method will return an error if an attempt is made to publish an entry which has unresolved tasks. This is a measure to avoid the accidental publication of content which is not ready to be released.

There can be cases where an entry has to be published even though it has unresolved tasks. There are two options in this case:

• a space admin resolves or removes the tasks and then publishes the entry
• the creators of the unresolved tasks remove them and then publish the entry

Availability

Tasks are only available on all Premium plans and spaces (in former Enterprise plans Tasks are only available on Performance 1x and above space types).

Task schema

A Task has five top level properties: assignedTo, status, dueDate, body and sys. These are described in detail below.

In addition to the common sys properties tasks have the following extra sys properties

Both properties resolvedAt and resolvedBy are only defined if the task is resolved. Reopening a task will remove both fields from the sys section.

Actors

When talking about tasks in this documentation we consider the following actors:

• Task creator, the person or app that created the task.
• Task assigner, the person who assigns a task to a user/ team. It will usually be the same as the creator.
• Task assignee, the person or team that has to do the work specified in the task and resolve once finished. If a team is assigned, team members can act on its behalf (e.g. resolve a task).

Assigned Tasks collection

Get all tasks that are assigned to you

Use this endpoint to get all the tasks that are assigned to you. This API does offer pagination, calls to it will return a paginated list containing the tasks that are assigned to you and your team.

It is important to note that this endpoint expects the query parameter filter=myPendingTasks. A call without this parameter will return a 501 status code.

Permissions

Any user with read access to entries in the given space-environment can call this endpoint.

Entry Tasks collection

Get all tasks of an entry

Use this endpoint to get all the tasks of an entry. This API does offer pagination, calls to it will return a paginated list with tasks for that entry.

Permissions

Any user with read access to an entry can read all the tasks in the entry. Space admins can read all the tasks in any entry.

Create a task

Use this endpoint to create a new task. When using this endpoint, an ID will be automatically generated for the created task and returned in the response.

There’s a limit of 100 tasks per entry. An attempt to create more than 100 tasks will result in an error.

Permissions

Any user with read access to an entry can create tasks in the entry. Space admins can create tasks on any entry.

The API does not check if the task assignee has read access to the entry where the task exists. If task assignees do not have read access to the entry they won’t be able to resolve them.

Notifications

When a task is created an email is sent to the task assignee to let them know that a task has been assigned to them. If the task is assigned to a team, every user in that team receives an email.

If a due date is specified for a task, a reminder mail will be sent out two days before this date.

Errors

• A 400 - BadRequest error is returned if there’s an attempt to create more than 100 tasks in one entry.
• A 422 - ValidationFailed error is returned if:
  • The body field has a value bigger than 512 bytes
  • The status field has a value different to active or resolved

Task

Get a task

Use this endpoint to fetch a task with a specified ID.

Permissions

Any user with read access to an entry can read a task in the entry. Space admins can read any task in any entry.

Delete a task

Use this method to delete a task.

Permissions

Task creators can delete their own tasks. Admins can delete any task on any entry.

Notifications

No notification is sent when a task is deleted.

Update a task

Use this method to modify the body of the task, re-assign it to another member of the space or resolve it. Note that the body or the assignee of a task can’t be modified if the task has already been resolved. Unresolve it first to be able to update these fields.

Permissions

Update permissions are a bit more complex so we are going to use a table to present all the possible combinations of which field can be updated by whom.

Errors

• A 400 - BadRequest error is returned if a task’s body or assignee are updated after the task has been resolved.
• An 403 - AccessDenied error is returned in the following cases:
  • A user different from the task assignee or an admin marked a task as resolved.
  • A user different from the task creator or an admin changed the task assignee.
  • A user different from the task creator or an admin changed the task body.
• A 422 - ValidationFailed error is returned if:
  • The body field has a value bigger than 512 bytes
  • The status field has a value different to active or resolved

Notifications

Depending on which field is updated and by whom the recipient of the notification will vary.

• Updates to body

• Updates to assignedTo

• Updates to status