🔍 Code Extractor

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

Purpose

This function fetches approval cycles assigned to a user that are in 'IN_APPROVAL' status and filters them to only include approvals where the user can currently take action. It's used in workflow systems to display actionable approval tasks to users, preventing them from seeing approvals they're assigned to but cannot yet act upon due to sequential approval requirements or other business rules.

Source Code

def get_user_pending_approvals(user: DocUser, limit: int = 10) -> Dict[str, Any]:
    """
    Get approvals pending for a user.
    
    Args:
        user: The user to get pending approvals for
        limit: Maximum number of approvals to return
        
    Returns:
        Dictionary with list of pending approvals
    """
    try:
        # Get pending approvals
        result = get_user_assigned_approvals(
            user=user,
            status_filter="IN_APPROVAL",
            include_completed=False,
            limit=limit
        )
        
        # Only include approvals where user can approve now
        if result.get('success') and 'approvals' in result:
            filtered_approvals = []
            for approval in result['approvals']:
                approval_cycle = ApprovalCycle(uid=approval.get('UID'))
                if approval_cycle and approval_cycle.can_approve(user.uid):
                    filtered_approvals.append(approval)
                    
            result['approvals'] = filtered_approvals[:limit]
            result['total'] = len(filtered_approvals)
            
        return result
        
    except Exception as e:
        logger.error(f"Error getting user pending approvals: {e}")
        import traceback
        logger.error(traceback.format_exc())
        return {
            "success": False,
            "message": "An unexpected error occurred",
            "approvals": []
        }

Parameters

Parameter Details

user: A DocUser object representing the user whose pending approvals should be retrieved. This object must have a 'uid' attribute for identification and permission checking.

limit: An integer specifying the maximum number of approval records to return. Defaults to 10. This limit is applied after filtering, so the function may process more records internally but will only return up to this many results.

Return Value

Type: Dict[str, Any]

Returns a dictionary with keys: 'success' (boolean indicating operation success), 'message' (string with error details if success is False), 'approvals' (list of approval dictionaries that the user can currently act upon, limited by the limit parameter), and 'total' (integer count of filtered approvals). On error, returns a dictionary with success=False, an error message, and an empty approvals list.

Dependencies

• CDocs
• typing
• logging
• traceback

Required Imports

from typing import Dict, Any
from CDocs.models.user_extensions import DocUser
from CDocs.models.approval import ApprovalCycle
from CDocs.controllers import log_controller_action
import logging
import traceback

Conditional/Optional Imports

These imports are only needed under specific conditions:

import traceback

Usage Example

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

# Assuming you have a DocUser instance
user = DocUser(uid='user123')

# Get pending approvals for the user
result = get_user_pending_approvals(user=user, limit=5)

if result['success']:
    print(f"Found {result['total']} pending approvals")
    for approval in result['approvals']:
        print(f"Approval UID: {approval.get('UID')}")
else:
    print(f"Error: {result['message']}")

Best Practices

• Always check the 'success' key in the returned dictionary before processing the 'approvals' list
• The function applies a secondary filter using ApprovalCycle.can_approve(), so the actual number of approvals returned may be less than the limit parameter
• Error handling is comprehensive with logging, but callers should still handle the error case gracefully
• The function depends on get_user_assigned_approvals which must be defined in the same module or imported
• The limit parameter is applied after filtering, so database queries may retrieve more records than the final result
• Ensure the DocUser object passed has a valid 'uid' attribute as it's used for permission checking
• The decorator log_controller_action will log this function's execution, so ensure logging is properly configured

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_user_pending_approvals 84.7% 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_assigned_approvals 80.1% 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_pending_reviews 69.5% similar

  Retrieves all pending (and optionally completed) document reviews assigned to a specific user, with support for date filtering and pagination.

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

• function get_user_assigned_approvals_v1 69.5% 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 add_approver_to_active_approval_v1 61.0% similar

  Adds a new approver to an active approval cycle with permission checks, validation, audit logging, and email notifications.

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