tasks

Apply one bulk action from BULK_TASK_ACTIONS to the selected tasks (BC-23219).

Code
The action set is not restated here: it lives in ``BULK_TASK_ACTIONS``
(``lib/domain/constants.py``) alongside the map of which payload field each
one takes, and a copy in this docstring would go stale the next time one is
added or removed.

Guarded by the same ``britecore/tasks`` rw permission as ``modify_task``,
because that is what this ultimately performs: the service drives each task
through the single-task path so every one keeps its own history entry and
events. The queue's ``edit_tasks`` capability decides whether the bulk
controls are offered in the UI, which is an affordance rather than access
control -- this decorator is the actual gate.

A batch that fails for some tasks still applies to the rest; the response
reports each task's outcome and the reason for every failure.

create_task

Create a new task definition.

Code
Args:
    task_definition_data: The task definition data to create

Returns:
    The created task definition

Create task definitions assignees for roles and user groups.

Code
Args:
    assignment_data: The assignment data containing task_definition_id,
                    role_ids list, and user_group_ids list

Returns:
    List of created assignments

Write a note on a task.

Code
Parameters
----------
task_id : str
    UUID of the task the note belongs to.
contents : str
    The note body. Required, and capped at 10000 characters.
share_to_policy : bool, optional
    Defaults to false. When true the note is also published to the task's
    policy, appearing on that policy's Notes tab as well as on the task.
    Needs no permission beyond this endpoint's own, but the task must be
    attached to a policy. Cannot be changed after the note is written.

Returns
-------
dict
    The created note in the same shape ``retrieve_task_notes`` returns.

Delete a task definition (soft delete).

Code
Args:
    id: The ID of the task definition to delete

Returns:
    Success response

Export the task queue's current query as CSV.

Code
Accepts the same ``query`` / ``filters`` / ``sorting`` / ``view`` as
retrieve_tasks, and returns the whole filtered set rather than one page,
split into files of ``TASK_EXPORT_ROWS_PER_FILE`` rows.

Call it twice. Omit ``file_index`` for the plan: the row total, the file
count, and each file's name and row range. Then request one file at a time
by index, echoing back the plan's ``filename_timestamp`` so every file is
named for the same instant. A ``file_index`` past the last file is rejected.

Optional ``filters.ids`` limits the export to specific task uuids;
``group_by_policy`` keeps each policy's tasks together in the file;
``task_scopes`` names whether to include ``policy`` work, ``claim`` work or
both, so an export taken from the Underwriting queue matches what that queue
lists.

Requires read on ``britecore/tasks``.

Schemas: lib/api/api_specs/request-export_tasks.json and
response-export_tasks.json.

Updates an existing task.

Code
Partial: only the keys sent are changed. The stored selection strategy is
re-run -- which can move the task to a different assignee -- only when the
payload touches assignment, since ``modify_task`` merges that strategy onto
the partial payload and cannot tell a merged value from a sent one.

Update an existing task definition.

Code
Args:
    task_definition_payload: The task definition data to update

Returns:
    The updated task definition

Modify task definitions assignees by adding or deleting roles and user groups.

Code
Args:
    assignment_data: The assignment data containing task_definition_id,
                    add_role_ids, add_user_group_ids, delete_role_ids, delete_user_group_ids

Returns:
    List of current assignments after modifications

Replace the outcome catalog for a task definition.

Code
Accepts the full desired outcome list for a task definition.  Rows the
payload keeps by id are updated in place; new entries are inserted;
entries the payload omits are soft-deleted.

Resolve which contact would be auto-assigned using a given strategy.

Code
Used by the task form to preview the assignee for a non-manual strategy
before the task is saved. An optional assigned subgroup restricts the
candidate pool to that single role / user group.

Args:
    task_definition_id: The task definition to resolve against
    strategy: The strategy to use (round_robin, availability, capacity)
    assigned_role_id: Optional role subgroup to restrict the pool to
    assigned_user_group_id: Optional user group subgroup to restrict the pool to

Returns:
    Contact object or None

Retrieve contacts allowed to be assigned to tasks of every given task definition.

Code
Returns the intersection, not the union: a bulk reassign validates each task
against its own definition, so only a contact allowed by all of the
definitions in the selection can be applied to the whole of it. Passing a
single id gives the same result as retrieve_task_definition_allowed_assignees
without an assigned subgroup.

Schemas: lib/api/api_specs/request-retrieve_common_allowed_assignees.json and
lib/api/api_specs/response-retrieve_common_allowed_assignees.json.

Args:
    task_definition_ids: The IDs of the task definitions to intersect
    limit: Optional maximum number of assignees to return
    search: Optional search term to filter contacts by name or id
    assigned_role_id: Optional role the selection is pinned to, narrowing
        the result on top of the definitions
    assigned_user_group_id: Optional user group the selection is pinned to

Returns:
    List of contact objects allowed by every given task definition

Code
Retrieve available filter options for tasks.
Returns options for status, priority, and task types.

Return the current user's queue capabilities and the lifecycle buckets.

Code
The queue shows different affordances to different users (BC-23218). Each
capability resolves from a permission path server-side, so the client asks
for a capability by name instead of re-deriving permission rules of its own.
The lifecycle buckets ride along so the client keeps no copy of the
status-to-bucket mapping. Gating affordances is not access control:
endpoints keep their own permission decorators and scoping.

Return a single task, with the policy context the detail sidebar needs.

Code
Parameters
----------
id : str
    UUID of the task.

Returns
-------
dict
    The task. ``policy_context`` carries agent, underwriter, agency group,
    additional interest count and written premium. It is ``null`` without
    ``britecore/policies/information`` read, and on every other endpoint
    returning this shape.

    ``trigger`` is the automation that created the task, ``null`` when a
    person did. ``type`` is ``workflow``, ``stp_rule`` or
    ``underwriting_rule``; ``trigger_id`` / ``trigger_name`` identify the
    configured workflow or rule and ``run_id`` the one firing.
    ``rule_description`` is that workflow's or rule's own text, not the
    task's ``description``, which is editable.

    ``trigger.linked_item`` is what the trigger was looking at, which can be
    narrower than the task's policy -- a ``driver``-category rule fired on
    one driver, and ``id`` is that contact. ``policy_id`` is the policy it
    is reached through. ``label`` is best effort, and ``null`` once the record
    is deleted or without ``britecore/policies/information`` read;
    ``linked_item`` is ``null`` only on a triage task.

retrieve_task_definition

Retrieve contacts that are allowed to be assigned to tasks for a given task definition.

Code
This endpoint maps the configured roles and user groups to actual contacts/users.
An optional assigned subgroup narrows the result to that single role /
user group.

Schemas: lib/api/api_specs/request-retrieve_task_definition_allowed_assignees.json
and lib/api/api_specs/response-retrieve_task_definition_allowed_assignees.json.

Args:
    task_definition_id: The ID of the task definition
    limit: Optional maximum number of assignees to return
    search: Optional search term to filter contacts by name or id
    assigned_role_id: Optional role subgroup to restrict results to
    assigned_user_group_id: Optional user group subgroup to restrict results to

Returns:
    List of contact objects representing allowed assignees

Return the outcome catalog for a task definition.

Code
Args:
    task_definition_id: The ID of the task definition whose outcomes to return.

Returns:
    List of active outcomes (id, key, name, description, sort order).

Return the roles / user groups wired to a task definition, as the subgroup options a task instance can be pinned to.

Code
Args:
    task_definition_id: The ID of the task definition

Returns:
    List of {id, type, name} entries ("role" or "user_group")

retrieve_task_definitions

Retrieve task definitions assignees.

Code
Args:
    params: Optional dict containing task_definition_id to filter by

Returns:
    List of assignments (all if no task_definition_id provided, filtered otherwise)

Return the documents on the record a task is attached to, newest first.

Code
Nothing links a file to a task, so these are the linked claim's files for a
claim task and the linked policy's for a policy task. Capped at the newest
``domain.constants.TASK_DOCUMENT_LIST_LIMIT`` rows; folders, the emailed
duplicate of a printed deliverable, and private files the caller's roles may
not see are all left out.

Parameters
----------
id : str
    UUID of the task.

Returns
-------
dict
    ``permitted`` is False when the caller may not read attachments on the
    linked record, and ``documents`` is then empty -- an empty list alone
    cannot say which of the two happened. ``truncated`` is True when the
    record holds more files than the cap, so ``documents`` is a page and its
    length is not the record's total.

    Each entry in ``documents`` has ``id``, ``name``, ``mime_type``,
    ``size`` (bytes), ``uploaded_at``, ``uploader``, ``is_system`` and
    ``previewable``. ``is_system`` marks a file the system attached itself
    -- a generated deliverable or a vendor push -- rather than one a person
    uploaded, and those carry no ``uploader``. ``previewable`` is true only
    for the types ``core.uploads.getAttachment`` serves inline (PDF,
    non-SVG image); everything else downloads.

retrieve_task_history

Return the notes written on a task, newest first.

Code
Parameters
----------
id : str
    UUID of the task.

Returns
-------
list of dict
    Each entry has ``id``, ``task_id``, ``contents``, ``author``,
    ``created_at`` and ``shared_to_policy``. ``author`` is the name
    recorded when the note was written, not a contact reference.
    ``shared_to_policy`` marks a note that was promoted to the task's
    policy when it was written, so it also appears on the policy's Notes
    tab; the rest are readable only here.

Return rule-execution provenance rows for a task created by an effect.

Code
Returns ``None`` when the task was not created by a rule effect.

retrieve_tasks

Return per-underwriter open / overdue / blocked task counts.

Code
Backs the admin Team Workload view. This one is genuine access control, not
just an affordance: the response exposes other users' workload, so the
service refuses a caller without the ``view_team_workload`` capability rather
than relying on the client not to ask.

Return per-day counts of the caller's open tasks for one month.

Code
Backs the Dashboard calendar, which is navigable: paging months must not
re-fetch the whole dashboard payload. ``month`` is ``YYYY-MM`` and defaults
to the current one; the response pads either side by
UW_DASHBOARD_CALENDAR_PAD_DAYS so adjacent-month days in the grid carry
their density too.

Return the Underwriting Dashboard's My Dashboard payload.

Code
The caller's own KPI counts, the premium their overdue work puts at risk,
their Priority Work rows, and their queue capabilities - one round trip.
Ungated beyond task read: every figure is derived from the caller's own
tasks.

Return the Dashboard's Recent Activity, Upcoming Renewals and Pipeline.

Code
Separate from retrieve_underwriting_dashboard so the KPI strip and Priority
Work are not held up by three secondary aggregates.

Return the Team Performance payload: workload, On Hold, cycle time.

Code
Enforces ``view_team_workload``: every figure here describes other people's
work, so this is access control and not an affordance.