Tasks

The Tasks API is responsible for managing tasks (i.e., work to be done by staff members). The API provides methods for creating, updating, (re)assigning, labeling, commenting on, completing, and closing tasks.

Basic Usage

The Tasks interface is designed to be straightforward and offers a collection of functions that can be utilized to manage the lifecycle of tasks in the system.

from datetime import date
from canvas_core import tasks
from canvas_core.tasks.models import Task

>>> from canvas_core import staffing, tasks

# Create a task.
>>> review_refills_task = tasks.create_task(
...     title="Review all refill requests",
...     creator=staffing.get_service_user_staff(),
...     labels=["urgent"],
... )

# Retrieve a task by its ID.
>>> review_refills_task = tasks.get_task(task_id=review_refills_task.id)

# Assign the task to the appropriate team (or staff member).
>>> Team = staffing.get_team_model()
>>> refills_team = next(staffing.list_teams(responsibility=Team.Responsibility.PROCESS_REFILL_REQUESTS))
>>> tasks.assign_task(review_refills_task, assignee=refills_team)
# Or:
>>> tasks.assign(assignee=refills_team)

# Update a task (e.g., set its due date).
>>> tasks.update_task(review_refills_task, due=date.today())

# Add a label to a task.
>>> tasks.add_task_labels(review_refills_task, label_names=("important",))
# Or:
>>> review_refills_task.add_label(label="important")

# Remove a label from a task.
>>> tasks.remove_task_label(review_refills_task, label_name="urgent")
# Or:
>>> review_refills_task.remove_label(label="urgent")

# Comment on a task.
>>> tasks.add_task_comment(review_refills_task, comment="We'll need to get this done quickly!")
# Or:
>>> review_refills_task.add_comment(comment="We'll need to get this done quickly!")

# Close a task (i.e., as incomplete)
>>> tasks.close_task(review_refills_task)
# Or:
>>> review_refills_task.close()

# Reopen a (closed) task.
>>> tasks.reopen_task(review_refills_task)
# Or:
>>> review_refills_task.reopen()

# Mark a task as complete.
>>> tasks.complete_task(review_refills_task)
# Or:
>>> review_refills_task.complete()

# List tasks and filter by their status, assignee, or creator.
>>> refill_reviews = tasks.list_tasks(status=Task.Status.OPEN, assignee=refills_team)

Models

The Tasks interface provides the following models:

canvas_core.tasks.models.Task, the Task itself.
canvas_core.tasks.models.Comment, a comment on a Task.
canvas_core.tasks.models.Label, a label on a Task.

API Reference

exception canvas_core.tasks.InvalidTaskStatusError(action: str, expected_status: str, actual_status: str)

Raised when attempting to perform an action on a task that is not in the expected status.

action: The action being performed on the task.

expected_status: The expected status of the task for the action.

actual_status: The actual status of the task when the action was attempted.

exception canvas_core.tasks.TaskError: An exception raised for task-related errors.

exception canvas_core.tasks.TaskNotFound: Raised when a task cannot be found with the given criteria.

exception canvas_core.tasks.TaskValidationError(message, code=None, params=None): Raised when an inappropriate argument value is used to create/update a task.

canvas_core.tasks.add_task_comment(task: Task, comment: str, creator: Staff | None = None) → Task

Add a comment to the given task, created by the specified staff member.

Parameters:

task – The task to add the comment to.
comment – The text of the comment to add.
creator – The staff member who created the comment. If no creator is specified, the service user will be used.

Returns:

The updated task object.

canvas_core.tasks.add_task_labels(task: Task, label_names: Iterable[str]) → Task

Add the given labels to the given task.

Parameters:

task – The task to add the labels to.
label_names – An iterable of strings representing the labels to add.

Returns:

The updated task object.

canvas_core.tasks.assign_task(task: Task, assignee: Staff | Team) → Task

Assign a task to the given assignee if the task is open.

Parameters:

task – The task to be reassigned.
assignee – The intended assignee for the task.

Returns:

The reassigned task.

Return type:

Task

Raises:

InvalidTaskStatusError – If the task is not in a valid state to be reassigned.

canvas_core.tasks.close_task(task: Task) → Task

Close the given task if it is in the “open” state.

Parameters:: task – The task to close.
Returns:: The updated task object.
Raises:: InvalidTaskStatusError – If the task is not in the “open” state.

canvas_core.tasks.complete_task(task: Task) → Task

Mark the given task as completed if it is in the “open” state.

Parameters:: task – The task to complete.
Returns:: The updated task object.
Raises:: InvalidTaskStatusError – If the task is not in the “open” state.

Create a new Task.

Parameters:

title – The title of the new task.
creator – The staff member who created the new task.
assignee – The staff member or team to whom the new task is assigned.
patient – The patient that is linked to the new task, or None if there is no linked patient.
labels – The labels to be associated with the new task, or None if there are no labels.
due – The due date of the new task, or None if there is no due date. Defaults to None.

Returns:

The new Task object.

Return type:

Task

canvas_core.tasks.get_comment_model() → type[Comment]: Return the Comment model.

canvas_core.tasks.get_label_model() → type[Label]: Return the Label model.

canvas_core.tasks.get_task(task_id: int) → Task

Retrieve a task by its ID.

Parameters:: task_id – The ID of the task to retrieve.
Returns:: The retrieved task.
Raises:: TaskNotFound – If the task with the given ID does not exist.

Retrieve a list of tasks from the database based on the specified filters.

Parameters:

status – The status of the tasks to retrieve.
assignee – The staff member or team to whom the new task is assigned.
creator – The staff member who created the new task.

Returns:

A queryset matching the specified filters.

canvas_core.tasks.remove_task_label(task: Task, label_name: str) → Task

Remove the label with the specified name from the given task.

Parameters:

task – The task to remove the label from.
label_name – The name of the label to remove.

Returns:

The updated task object.

canvas_core.tasks.reopen_task(task: Task) → Task

Reopen a task if its status is not already open.

Parameters:: task – The task to reopen.
Returns:: The reopened task.

canvas_core.tasks.update_task(task: Task, title: str | None = None, due: datetime | None = None, patient: Patient | None = None) → Task

Update the properties of an existing task.

Parameters:

task – The task to update.
title – The new title for the task.
due – The new due date for the task.
patient – The new linked patient for the task.

Returns:

The updated task object.

Raises:

InvalidTaskStatusError – If the task to update is not OPEN.

class canvas_core.tasks.models.Comment(*args, **kwargs)

Proxy model for a comment made on a Task.

exception DoesNotExist

exception MultipleObjectsReturned

class canvas_core.tasks.models.Label(*args, **kwargs)

Proxy model representing a label for a Task.

exception DoesNotExist

exception MultipleObjectsReturned

class canvas_core.tasks.models.Task(*args, **kwargs)

Proxy model for a`Task`.

exception DoesNotExist

exception MultipleObjectsReturned

class Status(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

add_comment(comment: str, creator: _Staff) → None: Add a comment to the task. creator indicating the staff member who created the comment.

add_label(label: str) → None: Add a single label to the task.

add_labels(labels: Iterable[str]) → None: Add multiple labels to the task.

assign(assignee: _Staff | _Team) → None: Assign the task to the given assignee, who can be either a Staff member or a Team.

close() → None: Close the task.

complete() → None: Complete the task.

remove_label(label_name: str) → None: Remove the given label name from the task.

reopen() → None: Reopen the task.