🔍 Code Extractor

Creates a review cycle for a specific document version, assigning reviewers with configurable approval requirements and workflow settings.

Purpose

This function initiates a formal review process for a document version in a controlled document management system. It handles user validation, creates reviewer assignments, and delegates to a controller to establish the review cycle with specified parameters like due dates, sequential vs parallel review, and approval thresholds. It's designed for regulatory or compliance-driven document review workflows where tracking and permissions are critical.

Source Code

def create_review_cycle(user, document_version_uid: str, reviewers: List[str],
                      due_date: Optional[datetime] = None, instructions: str = '',
                      sequential: bool = False, required_approval_percentage: int = 100, review_type: str = 'Regulatory Review' ) -> Dict[str, Any]:
    """Create a review cycle for a document version."""
    # Ensure user is a DocUser object, not just a UID string
    if user and not isinstance(user, DocUser):
        try:
            user_obj = DocUser(uid=user if isinstance(user, str) else user.uid)
            if not user_obj:
                logger.error("Failed to convert user parameter to DocUser object")
                return {"success": False, "message": "Invalid user"}
            user = user_obj
        except Exception as e:
            logger.error(f"Error converting user parameter to DocUser: {e}")
            return {"success": False, "message": "Invalid user parameter"}
    
    # If user is still None at this point, return an error
    #if not user:
    #    return {"success": False, "message": "User not provided"}
    
    return _controller.create_cycle(
        document_version_uid=document_version_uid,
        user_uids=reviewers,
        due_date=due_date,
        instructions=instructions,
        sequential=sequential,
        required_approval_percentage=required_approval_percentage,
        initiated_by_uid=user.uid if user else None,
        notify_users=True,review_type=review_type
    )

Parameters

Name	Type	Default	Kind
user	-	-	positional_or_keyword
document_version_uid	str	-	positional_or_keyword
reviewers	List[str]	-	positional_or_keyword
due_date	Optional[datetime]	None	positional_or_keyword
instructions	str	''	positional_or_keyword
sequential	bool	False	positional_or_keyword
required_approval_percentage	int	100	positional_or_keyword
review_type	str	'Regulatory Review'	positional_or_keyword

Parameter Details

user: The user initiating the review cycle. Can be a DocUser object, a user UID string, or an object with a 'uid' attribute. The function will attempt to convert it to a DocUser object. If None or invalid, may return an error or proceed with None (based on commented code).

document_version_uid: Unique identifier (string) for the specific document version to be reviewed. Must correspond to an existing DocumentVersion in the system.

reviewers: List of user UID strings representing the users who will be assigned as reviewers for this cycle. Each UID should correspond to a valid DocUser in the system.

due_date: Optional datetime object specifying when the review cycle should be completed. If None, no deadline is enforced. Used for tracking and notifications.

instructions: String containing instructions or guidance for reviewers. Defaults to empty string. Can include review criteria, focus areas, or special requirements.

sequential: Boolean flag indicating whether reviewers must complete their reviews in sequence (True) or can review in parallel (False). Defaults to False (parallel review).

required_approval_percentage: Integer (0-100) specifying the percentage of reviewers who must approve for the cycle to be considered successful. Defaults to 100 (unanimous approval required).

review_type: String categorizing the type of review being conducted. Defaults to 'Regulatory Review'. Used for filtering, reporting, and workflow routing.

Return Value

Type: Dict[str, Any]

Returns a dictionary with keys 'success' (boolean) and 'message' (string). On success, may include additional keys like 'review_cycle_id' or cycle details from the controller. On failure, 'success' is False and 'message' contains the error description (e.g., 'Invalid user', 'Invalid user parameter').

Dependencies

• CDocs
• typing
• datetime
• logging

Required Imports

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

Usage Example

from datetime import datetime, timedelta
from CDocs.models.user_extensions import DocUser
from your_module import create_review_cycle

# Initialize user
initiating_user = DocUser(uid='user123')

# Define reviewers
reviewer_uids = ['reviewer1_uid', 'reviewer2_uid', 'reviewer3_uid']

# Set due date (7 days from now)
due_date = datetime.now() + timedelta(days=7)

# Create review cycle
result = create_review_cycle(
    user=initiating_user,
    document_version_uid='doc_version_456',
    reviewers=reviewer_uids,
    due_date=due_date,
    instructions='Please review for regulatory compliance with FDA 21 CFR Part 11',
    sequential=False,
    required_approval_percentage=75,
    review_type='Regulatory Review'
)

if result['success']:
    print(f"Review cycle created successfully: {result.get('review_cycle_id')}")
else:
    print(f"Failed to create review cycle: {result['message']}")

Best Practices

• Always ensure the user parameter is a valid DocUser object or UID before calling this function
• Verify that all reviewer UIDs in the reviewers list correspond to active users with appropriate permissions
• Set appropriate required_approval_percentage based on your organization's policies (100% for critical documents, lower for draft reviews)
• Use sequential=True only when review order matters (e.g., technical review before management approval)
• Provide clear, actionable instructions to guide reviewers on what to evaluate
• Set realistic due_dates that account for the number of reviewers and document complexity
• Handle the return dictionary properly, checking 'success' before proceeding with subsequent operations
• The function is decorated with permission checks, so ensure the calling user has CREATE_REVIEW and INITIATE_REVIEW permissions
• The function logs actions via log_controller_action decorator, useful for audit trails
• Consider that the function calls _controller.create_cycle which may raise exceptions not caught here

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function create_review_cycle 93.5% similar

  Creates a new review cycle for a controlled document, assigning reviewers with optional sequential workflow, custom instructions, and approval requirements.

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

• function create_approval_cycle_v2 82.9% similar

  Creates an approval cycle for a specific document version, assigning approvers and configuring approval workflow parameters.

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

• function create_approval_cycle_v1 82.1% similar

  Creates a new approval cycle for a controlled document, managing approver assignments, permissions, notifications, and audit logging.

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

• function get_document_review_cycles_v1 76.6% similar

  Retrieves all review cycles associated with a specific document, with an option to filter for only active cycles.

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

• function add_review_comment_v1 75.1% similar

  Adds a comment to a document review cycle, with options to mark it as requiring resolution and specify comment type.

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

def create_review_cycle(user, document_version_uid: str, reviewers: List[str],
                      due_date: Optional[datetime] = None, instructions: str = '',
                      sequential: bool = False, required_approval_percentage: int = 100, review_type: str = 'Regulatory Review' ) -> Dict[str, Any]:
    """Create a review cycle for a document version."""
    # Ensure user is a DocUser object, not just a UID string
    if user and not isinstance(user, DocUser):
        try:
            user_obj = DocUser(uid=user if isinstance(user, str) else user.uid)
            if not user_obj:
                logger.error("Failed to convert user parameter to DocUser object")
                return {"success": False, "message": "Invalid user"}
            user = user_obj
        except Exception as e:
            logger.error(f"Error converting user parameter to DocUser: {e}")
            return {"success": False, "message": "Invalid user parameter"}
    
    # If user is still None at this point, return an error
    #if not user:
    #    return {"success": False, "message": "User not provided"}
    
    return _controller.create_cycle(
        document_version_uid=document_version_uid,
        user_uids=reviewers,
        due_date=due_date,
        instructions=instructions,
        sequential=sequential,
        required_approval_percentage=required_approval_percentage,
        initiated_by_uid=user.uid if user else None,
        notify_users=True,review_type=review_type
    )