🔍 Code Extractor

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

Purpose

This function initiates a formal approval process for a document version in a controlled document management system. It allows configuration of approval workflow including sequential or parallel approval, required approval percentage, due dates, and custom instructions. The function enforces permission checks and logs the action for audit purposes.

Source Code

def create_approval_cycle(user: DocUser, document_version_uid: str, approvers: List[str],
                       due_date: Optional[datetime] = None, instructions: str = '',
                       sequential: bool = True, required_approval_percentage: int = 100) -> Dict[str, Any]:
    """Create an approval cycle for a document version."""
    return _controller.create_cycle(
        document_version_uid=document_version_uid,
        user_uids=approvers,
        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
    )

Parameters

Parameter Details

user: DocUser object representing the user initiating the approval cycle. Used to track who started the approval process and for permission validation. Can be None but will result in initiated_by_uid being None.

document_version_uid: String unique identifier for the specific document version that requires approval. Must reference an existing DocumentVersion in the system.

approvers: List of string UIDs representing users who need to approve the document. Each UID must correspond to a valid DocUser in the system. The order matters if sequential=True.

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

instructions: String containing custom instructions or context for approvers. Defaults to empty string. Can include guidance on what to review or specific approval criteria.

sequential: Boolean flag determining approval order. If True, approvers must approve in the order listed. If False, all approvers can review simultaneously. Defaults to True.

required_approval_percentage: Integer (0-100) specifying the percentage of approvers who must approve for the cycle to succeed. Defaults to 100 (unanimous approval required). Allows for majority or threshold-based approval workflows.

Return Value

Type: Dict[str, Any]

Returns a Dictionary containing details about the created approval cycle. Expected keys include cycle metadata such as cycle UID, status, created timestamp, assigned approvers, and configuration parameters. The exact structure depends on the _controller.create_cycle implementation but typically includes 'uid', 'status', 'document_version_uid', 'approvers', 'due_date', 'sequential', and 'required_approval_percentage'.

Dependencies

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

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_approval_cycle

# Assume user and document_version_uid are already obtained
initiating_user = DocUser.get_by_uid('user-123')
approver_uids = ['approver-1', 'approver-2', 'approver-3']
due_in_7_days = datetime.now() + timedelta(days=7)

# Create sequential approval cycle requiring 100% approval
result = create_approval_cycle(
    user=initiating_user,
    document_version_uid='doc-version-456',
    approvers=approver_uids,
    due_date=due_in_7_days,
    instructions='Please review the updated safety procedures and approve if compliant.',
    sequential=True,
    required_approval_percentage=100
)

print(f"Approval cycle created with UID: {result['uid']}")

# Create parallel approval requiring only 67% approval
result_parallel = create_approval_cycle(
    user=initiating_user,
    document_version_uid='doc-version-789',
    approvers=approver_uids,
    due_date=due_in_7_days,
    instructions='Majority approval needed for this change.',
    sequential=False,
    required_approval_percentage=67
)

Best Practices

• Always ensure the user parameter has appropriate permissions (CREATE_APPROVAL and INITIATE_APPROVAL) before calling this function
• Validate that document_version_uid exists and is in a state that allows approval cycles before calling
• Verify all approver UIDs in the approvers list correspond to valid, active users
• When using sequential=True, order the approvers list carefully as it determines approval sequence
• Set required_approval_percentage appropriately: 100 for unanimous approval, lower values for majority/threshold approval
• Provide clear, actionable instructions to help approvers understand what they're reviewing
• Set realistic due_date values considering the number of approvers and sequential vs parallel workflow
• Handle potential exceptions: PermissionError, ResourceNotFoundError, ValidationError, BusinessRuleError
• The function automatically sends notifications to approvers, so ensure notification system is properly configured
• This function is decorated with logging and permission checks, so errors will be logged automatically

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function create_approval_cycle_v1 94.7% 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 create_approval_cycle 84.0% similar

  Creates a new approval cycle for a document, assigning approvers with configurable workflow options (sequential/parallel), instructions, and due dates.

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

• function create_review_cycle_v1 82.9% similar

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

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

• function get_document_approval_cycles_v1 81.5% similar

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

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

• function create_review_cycle 80.8% 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