🔍 Code Extractor

Completes an approval cycle by recording a decision (approve/reject) and optional comments, then returns the operation status.

Purpose

This function serves as a controller action to finalize an approval workflow cycle in a document management system. It delegates to an underlying approval controller to process the decision, update the approval cycle status, and provide feedback on whether the operation succeeded. This is typically used when an approver makes a final decision on a document or workflow item requiring approval.

Source Code

def complete_approval(user: DocUser, approval_uid: str, decision: str, comments: Optional[str] = None) -> Dict[str, Any]:
    """Complete an approval cycle."""
    success = _controller.complete_cycle(
        cycle_uid=approval_uid,
        decision=decision,
        comment=comments
    )
    return {"success": success, "message": "Approval completed successfully" if success else "Failed to complete approval"}

Parameters

Parameter Details

user: DocUser object representing the authenticated user completing the approval. This user should have appropriate permissions to complete the approval cycle and their identity is used for audit trail purposes.

approval_uid: String containing the unique identifier (UID) of the approval cycle to be completed. This references a specific ApprovalCycle instance in the system.

decision: String indicating the approval decision. Expected values are typically 'approve', 'reject', or similar workflow-specific decision values that determine the outcome of the approval cycle.

comments: Optional string parameter for providing additional context, justification, or notes about the approval decision. Can be None if no comments are needed. These comments are typically stored with the approval record for audit purposes.

Return Value

Type: Dict[str, Any]

Returns a dictionary with two keys: 'success' (boolean indicating whether the approval completion succeeded) and 'message' (string containing a human-readable status message - either 'Approval completed successfully' if success is True, or 'Failed to complete approval' if success is False). Type: Dict[str, Any]

Dependencies

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

Required Imports

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

Usage Example

from CDocs.models.user_extensions import DocUser
from typing import Dict, Any

# Assume user is authenticated and retrieved from session
user = DocUser.get_by_id('user_123')
approval_uid = 'approval_cycle_456'

# Complete approval with decision
result = complete_approval(
    user=user,
    approval_uid=approval_uid,
    decision='approve',
    comments='All requirements met, documentation is complete.'
)

if result['success']:
    print(f"Success: {result['message']}")
else:
    print(f"Error: {result['message']}")

# Complete approval without comments
result = complete_approval(
    user=user,
    approval_uid='approval_cycle_789',
    decision='reject'
)

print(result)

Best Practices

• Ensure the user parameter represents an authenticated and authorized user before calling this function
• Validate that the approval_uid exists and is in a state that allows completion before calling
• The decision parameter should match expected values defined in your workflow configuration (typically 'approve' or 'reject')
• Always check the 'success' key in the returned dictionary before proceeding with subsequent operations
• Consider providing meaningful comments for audit trail purposes, especially for rejections
• This function is decorated with @log_controller_action, so all invocations are automatically logged
• Handle the case where success is False appropriately in your application logic
• The function relies on _controller being properly initialized in the module scope
• Ensure proper error handling around this function call as it may raise PermissionError, ResourceNotFoundError, or other CDocs exceptions

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function complete_review_v1 84.4% similar

  Completes a document review cycle by recording a decision and optional comments, then returns the operation status.

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

• function complete_approval 81.1% similar

  Completes an approval cycle by recording a user's approval decision (APPROVED, REJECTED, etc.) and managing the approval workflow, including sequential approver activation and final cycle completion.

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

• function complete_approval_v1 79.3% similar

  Records a user's approval decision (APPROVED or REJECTED) for a document in an approval cycle, updating the approval status and document state accordingly.

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

• function cancel_approval_cycle_v2 77.8% similar

  Cancels an active approval cycle by its unique identifier, optionally recording a reason for the cancellation.

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

• function create_approval_cycle_v1 75.9% 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