🔍 Code Extractor

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

Purpose

This function queries the approval system to fetch all approval assignments associated with a given user. It's primarily used to display a user's approval queue, showing documents or items awaiting their review. The function supports filtering by status (pending, in-progress, completed, rejected) and returns a structured response containing the assignments and total count. It's decorated with logging functionality to track controller actions for audit purposes.

Source Code

def get_user_pending_approvals(user: DocUser, include_completed: bool = False) -> Dict[str, Any]:
    """Get pending approvals for a user."""
    status_filter = ["PENDING", "IN_PROGRESS"]
    if include_completed:
        status_filter.extend(["COMPLETED", "REJECTED"])
        
    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, "approvals": assignments, "total": total}

Parameters

Parameter Details

user: A DocUser object representing the user whose pending approvals should be retrieved. The function extracts the user's UID (unique identifier) to query assignments. If None is passed, the function will still execute but may return no results or all assignments depending on the underlying controller implementation.

include_completed: Boolean flag (default: False) that determines whether to include completed and rejected approvals in the results. When False, only returns PENDING and IN_PROGRESS assignments. When True, also includes COMPLETED and REJECTED assignments, providing a full approval history for the user.

Return Value

Type: Dict[str, Any]

Returns a dictionary with three keys: 'success' (bool, always True in this implementation), 'approvals' (list of ApproverAssignment objects matching the filter criteria), and 'total' (int, the total count of matching assignments). The dictionary structure follows a standard API response pattern for consistent client-side handling.

Dependencies

• CDocs

Required Imports

from typing import Dict, Any
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_pending_approvals

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

# Get only pending approvals
result = get_user_pending_approvals(user=current_user)
print(f"Pending approvals: {result['total']}")
for approval in result['approvals']:
    print(f"Document: {approval.document_id}, Status: {approval.status}")

# Get all approvals including completed ones
all_approvals = get_user_pending_approvals(user=current_user, include_completed=True)
print(f"Total approval history: {all_approvals['total']}")

Best Practices

• Always pass a valid DocUser object to ensure proper user-specific filtering
• Use include_completed=True sparingly as it may return large datasets for users with extensive approval history
• The function has a hardcoded limit of 100 assignments; consider pagination for users with many approvals
• The function is decorated with log_controller_action, so all calls are automatically logged for audit purposes
• Handle the returned dictionary structure consistently across your application for uniform error handling
• Consider implementing pagination by modifying the hardcoded limit and offset parameters if needed
• The function always returns success=True; implement proper error handling in the calling code for database or controller failures

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_user_assigned_approvals_v2 90.3% similar

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

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

• function get_user_assigned_approvals_v1 85.7% 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 84.5% 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

• function get_user_pending_reviews_v1 83.5% similar

  Retrieves pending review assignments for a specific user, with an option to include completed reviews.

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

• function get_user_pending_approvals_v1 78.1% similar

  Retrieves a filtered list of approval cycles pending action from a specific user, ensuring the user has current approval authority for each returned item.

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