Staffing
The Staffing API is responsible for managing staffing-related resources. It provides a simple interface for managing staff and teams.
Basic Usage
>>> from canvas_core import staffing
# Create a Staff user.
>>> staff, generated_password = staffing.create_staff(
... username="staffuser",
... email="staff-user@example.com",
... first_name="Staff",
... last_name="User",
... )
# Retrieve a staff user by its key.
>>> staff = staffing.get_staff_by_key(key=staff.key)
# Retrieve the service user (useful for automations that require a staff reference).
>>> service_staff = staffing.get_service_user_staff()
# List all active staff.
>>> active_staff = staffing.list_staff()
# Create a team.
>>> my_team = staffing.create_team(name="My Team")
# List staff belonging to a particular team.
>>> my_team_staff = staffing.list_staff(team=my_team)
# Or:
>>> my_team_staff = team.list_members()
# Add a staff member to a team.
>>> staffing.add_staff_to_team(staff=staff, team=my_team)
# Or:
>>> my_team.add_member(staff)
# Remove a staff member from a team.
>>> staffing.remove_staff_from_team(staff=staff, team=my_team)
# Or:
>>> my_team.remove_member(staff)
# Create a team with one or more specific responsibilities.
>>> Team = staffing.get_team_model()
>>> prescriptions_team = staffing.create_team(
... name="Prescription Management Team",
... responsibilities=(
... Team.Responsibility.PROCESS_REFILL_REQUESTS,
... Team.Responsibility.PROCESS_CHANGE_REQUESTS,
... # Specify your own custom responsibility strings, if needed.
... "REVIEW_PRESCRIPTIONS",
... )
... )
# Retrieve a team by name.
>>> team = staffing.get_team_by_name(name="My Team")
# List all teams.
>>> all_teams = staffing.list_teams()
# List teams with a specific responsibility.
>>> specimen_teams = staffing.list_teams(
... responsibility=Team.Responsibility.COLLECT_SPECIMENS_FROM_PATIENT
... )
API Reference
- canvas_core.staffing.add_staff_to_team(*, staff: Staff, team: Team) None
Add a staff member to a team.
- Parameters:
staff – The staff member to add to the team.
team – The team to which the staff member should be added.
- canvas_core.staffing.create_staff(*, username: str, email: str, first_name: str, last_name: str, password: str | None = None, active: bool = True) tuple[Staff, str]
Create a Staff object.
- Parameters:
username – The username that the staff member will use to log in.
email – The staff member’s email address.
first_name – The staff member’s first name.
last_name – The staff member’s last name.
password – The password that the staff member will use to log in. If no password is set, one will be generated.
active – When False, marks the user as inactive and prevents them from logging in.
- Returns:
A tuple containing the created Staff object and its password.
- canvas_core.staffing.create_team(*, name: str, responsibilities: Iterable[Team.Responsibility | str] = ()) Team
Create a Team object.
- Parameters:
name – The name of the team.
responsibilities – An iterable of responsibilities that the team should have.
- Returns:
The new Team object.
- canvas_core.staffing.filter_staff_by_users(users: list[User]) QuerySet
Filter staff by a list of users.
- canvas_core.staffing.get_service_user_staff() Staff
Return the service (i.e., “bot”) user’s Staff object.
- canvas_core.staffing.get_staff_by_key(*, key: str) Staff
Retrieve a Staff object by its key.
Requires at least one of key, email, or username to be provided.
- Parameters:
key – The staff key.
email – The staff member’s email address.
username – The staff member’s username.
- canvas_core.staffing.get_staff_by_user_id(user_id: int) Staff | None
Returns staff associated to a given user.
- canvas_core.staffing.list_staff(*, team: Team | None = None, include_inactive: bool = False) Iterable[Staff]
Retrieve a list of Staff with the given criteria.
- Parameters:
team – The team to which the returned staff members should belong.
include_inactive – Include inactive staff members in the result.
- Returns:
An iterable of Staff objects.
- canvas_core.staffing.list_teams(*, responsibility: Team.Responsibility | str | None = None) Iterable[Team]
Retrieve a list of Teams with the given criteria.
- Parameters:
responsibility – the responsibility that all returned teams should have.
- Returns:
An iterable of Team objects.
- canvas_core.staffing.remove_staff_from_team(*, staff: Staff, team: Team) None
Remove a staff member from a team.
- Parameters:
staff – The staff member to remove from the team.
team – The team to which the staff member should be removed.
- class canvas_core.staffing.models.Staff(*args, **kwargs)
A staff member.
- exception DoesNotExist
- exception MultipleObjectsReturned
- class canvas_core.staffing.models.Team(*args, **kwargs)
A named team of staff members.
- exception DoesNotExist
- exception MultipleObjectsReturned
- class Responsibility(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)
- add_member(staff: Staff) None
Add the given staff member to the team.
- Parameters:
staff – The staff member to add to the team.