🔍 Code Extractor

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

Purpose

This function serves as a controller endpoint to fetch a user's approval assignments in a document management system. It supports pagination, status filtering, and can optionally include completed approvals. The function aggregates data from multiple models (ApproverAssignment, ApprovalCycle, DocumentVersion, ControlledDocument) to provide a comprehensive view of documents awaiting user approval or previously approved by the user. It's decorated with log_controller_action for audit trail purposes.

Source Code

def get_user_assigned_approvals(
    user: DocUser,
    status_filter: Optional[Union[str, List[str]]] = None,
    include_completed: bool = False,
    limit: int = 100,
    offset: int = 0
) -> Dict[str, Any]:
    """
    Get all approval assignments for a user.
    """
    try:
        # Normalize status filter
        if isinstance(status_filter, str):
            status_filter = [status_filter]
            
        # Default to active statuses if not including completed
        if not status_filter and not include_completed:
            status_filter = ["ACTIVE", "PENDING"]
            
        # Get user's approval assignments
        assignments = ApproverAssignment.get_user_assignments(
            user_uid=user.uid,
            status_filter=status_filter,
            limit=limit,
            offset=offset
        )
        

        # Collect approval cycle and document details
        results = []
        for assignment in assignments:
            # Get approval cycle
            approval_cycle = ApprovalCycle(uid=assignment.approval_cycle_uid)
            if not approval_cycle:
                logger.warning(f"Approval cycle not found for assignment {assignment.uid}")
                continue
                
            # Get document through document version
            document = None
            document_version = approval_cycle.document_version
            logger.info(f"Document version: {document_version}")
            if document_version:
                document = document_version.document
            
            if not document:
                logger.warning(f"Document not found for approval cycle {approval_cycle.uid}")
                continue
                
            # Add to results
            results.append({
                "assignment": assignment.to_dict(),
                "approval_cycle": approval_cycle.to_dict(),
                "document": {
                    "uid": document.uid,
                    "doc_number": document.doc_number,
                    "title": document.title,
                    "doc_type": document.doc_type,
                    "department": document.department,
                    "status": document.status
                },
                "version": {
                    "uid": document_version.uid,
                    "version_number": document_version.version_number
                } if document_version else None
            })
            
        # Get total count
        total_count = ApproverAssignment.count_user_assignments(
            user_uid=user.uid,
            status_filter=status_filter
        )
        
        return {
            "success": True,
            "count": len(results),
            "total": total_count,
            "assignments": results
        }
        
    except Exception as e:
        logger.error(f"Error retrieving approval assignments for user {user.uid}: {e}")
        raise BusinessRuleError(f"Failed to retrieve approval assignments: {e}")

Parameters

Parameter Details

user: DocUser object representing the user whose approval assignments are being retrieved. Must be a valid DocUser instance with a uid attribute.

status_filter: Optional filter to limit results by approval status. Can be a single status string (e.g., 'ACTIVE') or a list of status strings (e.g., ['ACTIVE', 'PENDING']). If None and include_completed is False, defaults to ['ACTIVE', 'PENDING'].

include_completed: Boolean flag indicating whether to include completed approval assignments in the results. When False and status_filter is None, only active and pending assignments are returned. Default is False.

limit: Maximum number of assignment records to return. Used for pagination. Default is 100. Must be a positive integer.

offset: Number of records to skip before starting to return results. Used for pagination. Default is 0. Must be a non-negative integer.

Return Value

Type: Dict[str, Any]

Returns a dictionary with keys: 'success' (bool, always True on successful execution), 'count' (int, number of assignments in current page), 'total' (int, total count of matching assignments across all pages), and 'assignments' (list of dicts). Each assignment dict contains: 'assignment' (assignment details as dict), 'approval_cycle' (approval cycle details as dict), 'document' (dict with uid, doc_number, title, doc_type, department, status), and 'version' (dict with uid and version_number, or None if no version). Raises BusinessRuleError on failure.

Dependencies

• logging
• uuid
• os
• typing
• datetime
• traceback
• CDocs

Required Imports

from typing import Dict, List, Any, Optional, Union
from CDocs.models.user_extensions import DocUser
from CDocs.models.approval import ApproverAssignment, ApprovalCycle
from CDocs.models.document import ControlledDocument, DocumentVersion
from CDocs.controllers import log_controller_action, BusinessRuleError
import logging

Usage Example

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

# Get a user instance
user = DocUser.query.filter_by(uid='user-123').first()

# Get active and pending approvals (default)
result = get_user_assigned_approvals(user)
print(f"Found {result['count']} assignments out of {result['total']} total")

# Get only active approvals with pagination
result = get_user_assigned_approvals(
    user=user,
    status_filter='ACTIVE',
    limit=20,
    offset=0
)

# Get all approvals including completed ones
result = get_user_assigned_approvals(
    user=user,
    include_completed=True,
    limit=50
)

# Process results
for assignment_data in result['assignments']:
    doc = assignment_data['document']
    print(f"Document: {doc['doc_number']} - {doc['title']}")
    print(f"Status: {assignment_data['assignment']['status']}")

Best Practices

• Always pass a valid DocUser instance with a uid attribute to avoid errors
• Use pagination (limit and offset) when dealing with users who may have many approval assignments to avoid performance issues
• Handle the BusinessRuleError exception that may be raised on failure
• Check the 'success' key in the returned dictionary before processing results
• Be aware that assignments with missing approval cycles or documents are silently skipped with warning logs
• The function normalizes status_filter from string to list internally, so both formats are acceptable
• When include_completed is False and no status_filter is provided, the function defaults to ['ACTIVE', 'PENDING'] statuses
• The 'total' count in the response may differ from 'count' when using pagination
• Ensure the logger is properly configured as the function logs warnings and errors

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_user_assigned_approvals 83.7% 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 81.1% similar

  Retrieves all review assignments for a specific user with optional filtering by status, including associated review cycle, document, and version details.

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

• function get_user_pending_approvals 77.3% 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

• class ApproverAssignment 72.4% similar

  Model class representing an approver assignment within an approval cycle, managing the relationship between an approver and their approval task including status, decisions, and lifecycle tracking.

  From: /tf/active/vicechatdev/CDocs/models/approval_bis.py

• class ApproverAssignment_v1 70.5% similar

  Model class representing an approver assignment within an approval cycle, managing the relationship between an approver and their approval task including status, decisions, and timeline tracking.

  From: /tf/active/vicechatdev/CDocs/models/approval.py