🔍 Code Extractor

Retrieves all approval cycles associated with a specific document, with an option to filter for only active cycles. This is a backwards-compatible wrapper function.

Purpose

This function serves as a backwards-compatible interface to retrieve approval cycle information for a document in a controlled document management system. It delegates to an underlying controller method (_controller.get_cycles_for_document) to fetch approval workflow data, including approval status, approvers, comments, and cycle metadata. Use this when you need to display approval history, check approval status, or audit document approval workflows.

Source Code

def get_document_approvals(document_uid: str, include_active_only: bool = False) -> Dict[str, Any]:
    """Get all approval cycles for a document.
    
    This is a wrapper function for backwards compatibility.
    
    Args:
        document_uid: UID of the document
        include_active_only: Whether to include only active approval cycles
        
    Returns:
        Dictionary with approval cycles and document information
    """
    return _controller.get_cycles_for_document(document_uid, include_active_only)

Parameters

Parameter Details

document_uid: Unique identifier (UID) string for the document whose approval cycles should be retrieved. This should be a valid document UID that exists in the system. Expected format is typically a UUID string.

include_active_only: Boolean flag that determines whether to return all approval cycles (False) or only currently active approval cycles (True). Defaults to False, meaning all historical and current approval cycles are returned. Set to True when you only need to see ongoing approvals.

Return Value

Type: Dict[str, Any]

Returns a Dictionary containing approval cycle information and document metadata. The exact structure depends on the underlying controller implementation, but typically includes: 'cycles' (list of approval cycle objects with status, approvers, timestamps), 'document' (document metadata), and potentially 'active_cycles' (filtered list when include_active_only=True). Each cycle object contains approval workflow details like WorkflowStatus, ApproverAssignment records, and ApprovalComment entries.

Dependencies

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

Required Imports

from typing import Dict, Any
from CDocs.controllers import log_controller_action

Usage Example

from typing import Dict, Any
from your_module import get_document_approvals

# Get all approval cycles for a document
document_uid = "550e8400-e29b-41d4-a716-446655440000"
all_approvals = get_document_approvals(document_uid)
print(f"Total cycles: {len(all_approvals.get('cycles', []))}")

# Get only active approval cycles
active_approvals = get_document_approvals(document_uid, include_active_only=True)
for cycle in active_approvals.get('cycles', []):
    print(f"Cycle ID: {cycle.get('id')}, Status: {cycle.get('status')}")

# Check if document has any pending approvals
if active_approvals.get('cycles'):
    print("Document has active approval cycles")
else:
    print("No active approvals")

Best Practices

• This is a wrapper function for backwards compatibility - consider using the underlying controller method directly in new code
• Always validate that the document_uid exists before calling this function to avoid ResourceNotFoundError
• Use include_active_only=True when you only need current approval status to reduce data transfer and processing
• The function is decorated with @log_controller_action, so all calls are automatically logged for audit purposes
• Handle potential exceptions like ResourceNotFoundError, PermissionError, or ValidationError when calling this function
• The returned dictionary structure may vary based on the controller implementation - always check for key existence before accessing nested data
• Consider caching results if calling this function repeatedly for the same document within a short time period

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_approvals 90.2% similar

  Retrieves all approval cycles associated with a specific document, with optional filtering for active cycles only.

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

• function get_document_approval_cycles 87.8% similar

  Retrieves all approval cycles associated with a specific document, with optional filtering for active cycles only.

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

• function get_document_approval_cycles_v1 86.8% 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 get_approval_cycle 83.3% similar

  Retrieves detailed information about an approval cycle by its UID, with optional inclusion of comments and associated document details.

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

• function get_approval_v1 83.2% similar

  A convenience wrapper function that retrieves approval cycle details by delegating to get_approval_cycle with the same parameters.

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