🔍 Code Extractor

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

Purpose

This function serves as a controller endpoint to fetch a user's document review assignments. It supports pagination, status filtering, and optionally includes completed reviews. The function aggregates data from multiple models (ReviewerAssignment, ReviewCycle, DocumentVersion, ControlledDocument) to provide a comprehensive view of each assignment. It's designed for displaying a user's review workload in a document management system.

Source Code

def get_user_assigned_reviews(
    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 review 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 review assignments
        assignments = ReviewerAssignment.get_user_assignments(
            user_uid=user.uid,
            status_filter=status_filter,
            limit=limit,
            offset=offset
        )
        

        # Collect review cycle and document details
        results = []
        for assignment in assignments:
            # Get review cycle
            review_cycle = ReviewCycle(uid=assignment.review_cycle_uid)
            if not review_cycle:
                logger.warning(f"Review cycle not found for assignment {assignment.uid}")
                continue
                
            # Get document through document version
            document = None
            document_version = review_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 review cycle {review_cycle.uid}")
                continue
                
            # Add to results
            results.append({
                "assignment": assignment.to_dict(),
                "review_cycle": review_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 = ReviewerAssignment.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 review assignments for user {user.uid}: {e}")
        raise BusinessRuleError(f"Failed to retrieve review assignments: {e}")

Parameters

Parameter Details

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

status_filter: Optional filter to limit results by assignment 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 review 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 assignments to return in a single request. Used for pagination. Default is 100.

offset: Number of assignments to skip before returning results. Used for pagination to retrieve subsequent pages. Default is 0.

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 assignments matching filters), and 'assignments' (list of dicts). Each assignment dict contains: 'assignment' (ReviewerAssignment data), 'review_cycle' (ReviewCycle data), '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, Any, Optional, Union, List
from CDocs.models.user_extensions import DocUser
from CDocs.models.review import ReviewerAssignment, ReviewCycle
from CDocs.controllers import BusinessRuleError
import logging

Usage Example

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

# Get a user instance
user = DocUser.query.filter_by(email='reviewer@example.com').first()

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

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

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

# Process results
for item in result['assignments']:
    assignment = item['assignment']
    document = item['document']
    print(f"Review assignment {assignment['uid']} for document {document['doc_number']}")

Best Practices

• Always handle the BusinessRuleError exception when calling this function
• Use pagination (limit/offset) when dealing with users who may have many assignments to avoid performance issues
• Check the 'success' key in the returned dictionary before processing results
• Be aware that assignments without valid review cycles or documents are silently skipped with warnings logged
• The function is decorated with @log_controller_action, so all calls are automatically logged
• Status filter values should match the valid statuses defined in the ReviewerAssignment model
• When include_completed is True, explicitly set status_filter to None or provide all desired statuses
• The total count may differ from the count in results due to pagination and filtering of invalid references

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_user_assigned_approvals_v1 81.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_reviews 73.1% 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

• class ReviewerAssignment 70.5% similar

  Model class representing a reviewer assignment within a review cycle, managing reviewer information, status, decisions, and lifecycle tracking for document review processes.

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

• function get_user_assigned_approvals 69.9% 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_review_cycle 64.3% similar

  Retrieves comprehensive information about a review cycle, including optional reviewer assignments, comments, and associated document details.

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