🔍 Code Extractor

Retrieves all approval assignments for a specific user, with optional filtering by status and inclusion of completed approvals.

Purpose

This function serves as a controller action to fetch approval assignments for a given user in a document management system. It provides a filtered view of approvals based on status (defaulting to PENDING and IN_PROGRESS if not specified) and can optionally include completed approvals. The function is decorated with logging capabilities and returns a standardized response dictionary containing the assignments and total count.

Source Code

def get_user_assigned_approvals(user: DocUser, status_filter: Optional[List[str]] = None, 
                                include_completed: bool = False) -> Dict[str, Any]:
    """Get all approvals assigned to a user."""
    if not include_completed and not status_filter:
        status_filter = ["PENDING", "IN_PROGRESS"]
        
    assignments, total = _controller.get_assignments_for_user(
        user_uid=user.uid if user else None,
        status_filter=status_filter,
        limit=100,
        offset=0
    )
    return {"success": True, "assignments": assignments, "total": total}

Parameters

Parameter Details

user: A DocUser object representing the user whose approval assignments should be retrieved. The function extracts the user's UID to query assignments. Can be None, though this would likely return no assignments.

status_filter: Optional list of status strings to filter approval assignments. If not provided and include_completed is False, defaults to ['PENDING', 'IN_PROGRESS']. Expected values likely include 'PENDING', 'IN_PROGRESS', 'COMPLETED', 'REJECTED', etc., based on AssignmentStatus enum values.

include_completed: Boolean flag indicating whether to include completed approvals in the results. When False (default) and no status_filter is provided, automatically filters to only PENDING and IN_PROGRESS statuses. When True, all statuses are included unless explicitly filtered.

Return Value

Type: Dict[str, Any]

Returns a dictionary with three keys: 'success' (bool, always True in successful execution), 'assignments' (list of approval assignment objects/dictionaries assigned to the user), and 'total' (int, total count of matching assignments). The structure follows a standard API response pattern for the CDocs system.

Dependencies

• CDocs

Required Imports

from typing import Dict, List, Any, Optional
from CDocs.models.user_extensions import DocUser
from CDocs.controllers import log_controller_action

Usage Example

from CDocs.models.user_extensions import DocUser
from your_module import get_user_assigned_approvals

# Get current user (assume from session/auth)
current_user = DocUser.get_by_id(user_id)

# Get only pending and in-progress approvals (default)
result = get_user_assigned_approvals(current_user)
print(f"Found {result['total']} pending approvals")
for assignment in result['assignments']:
    print(f"Assignment ID: {assignment['id']}")

# Get all approvals including completed
all_approvals = get_user_assigned_approvals(
    user=current_user,
    include_completed=True
)

# Get only rejected approvals
rejected = get_user_assigned_approvals(
    user=current_user,
    status_filter=['REJECTED']
)

Best Practices

• Always pass a valid DocUser object; passing None may result in empty results or errors
• Use include_completed=True when you need historical approval data, but be aware this may return large result sets
• The function has a hardcoded limit of 100 assignments; for pagination, you may need to modify or extend this function
• The status_filter parameter should use values from the AssignmentStatus enum to ensure consistency
• This function is decorated with log_controller_action, so all calls are automatically logged for audit purposes
• Handle the response dictionary consistently by checking the 'success' key before processing 'assignments'
• Consider implementing pagination if users may have more than 100 assignments
• The function does not raise exceptions for invalid users; it returns an empty assignments list instead

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_user_assigned_approvals_v1 94.1% similar

  Retrieves all approval assignments for a specific user with optional filtering by status, including associated approval cycles, documents, and version information.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller.py

• function get_user_pending_approvals_v2 90.3% similar

  Retrieves pending approval assignments for a specific user, with an option to include completed and rejected approvals.

  From: /tf/active/vicechatdev/CDocs single class/controllers/approval_controller.py

• function get_user_assigned_approvals 83.2% similar

  Retrieves and paginates approval cycles assigned to a specific user, with optional filtering by status and completion state.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller_bis.py

• function get_user_assigned_reviews_v1 79.7% similar

  Retrieves all review assignments for a specific user, with optional filtering by status and inclusion of completed reviews.

  From: /tf/active/vicechatdev/CDocs single class/controllers/review_controller.py

• function get_user_pending_approvals 79.4% similar

  Retrieves all pending approval assignments for a specific user, with optional filtering by completion status and date range, returning structured approval data for UI display.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller.py