🔍 Code Extractor

Retrieves an approval cycle by its unique identifier (UID) and optionally includes associated comments and document information.

Purpose

This function fetches approval cycle data from the database, with options to enrich the response with related comments (including commenter names) and full document details. It's used in document management workflows to retrieve approval status, history, and context for controlled documents.

Source Code

def get_approval_cycle(
    approval_uid: str, 
    include_comments: bool = False, 
    include_document: bool = False
) -> Dict[str, Any]:
    """
    Get an approval cycle by UID.
    
    Args:
        approval_uid: UID of the approval cycle
        include_comments: Whether to include comments
        include_document: Whether to include document info
        
    Returns:
        Approval cycle data
    """
    try:
        # Get approval cycle
        approval_cycle = ApprovalCycle(uid=approval_uid)
        if not approval_cycle:
            return None
            
        # Get approval cycle data
        result = approval_cycle.to_dict()
        
        # Add comments if requested
        if include_comments:
            comments = []
            for comment in approval_cycle.comments:
                comment_data = comment.to_dict()
                if comment.commenter_uid:
                    commenter = DocUser(uid=comment.commenter_uid)
                    if commenter:
                        comment_data["user_name"] = commenter.name
                comments.append(comment_data)
            
            result["comments"] = comments
        from CDocs.controllers.document_controller import get_document
        # Add document info if requested
        if include_document:
            document_uid = approval_cycle.document_uid
            if document_uid:
                document = get_document(document_uid=document_uid)
                if document:
                    result["document"] = document
                    
        return result
        
    except Exception as e:
        logger.error(f"Error getting approval cycle: {e}")
        return None

Parameters

Parameter Details

approval_uid: String identifier (UID) of the approval cycle to retrieve. This is a required parameter that uniquely identifies the approval cycle in the system.

include_comments: Boolean flag (default: False) that determines whether to include all comments associated with the approval cycle. When True, fetches comments with commenter user names enriched from DocUser records.

include_document: Boolean flag (default: False) that determines whether to include the full document information associated with this approval cycle. When True, calls get_document() to fetch complete document details.

Return Value

Type: Dict[str, Any]

Returns a dictionary containing the approval cycle data with keys from ApprovalCycle.to_dict(). If include_comments is True, adds a 'comments' key with a list of comment dictionaries (each containing comment data plus 'user_name' field). If include_document is True, adds a 'document' key with full document information. Returns None if the approval cycle is not found or if an error occurs during retrieval.

Dependencies

• CDocs
• logging

Required Imports

from typing import Dict, Any
import logging
from CDocs.models.approval import ApprovalCycle
from CDocs.models.user_extensions import DocUser
from CDocs.controllers.document_controller import get_document

Conditional/Optional Imports

These imports are only needed under specific conditions:

from CDocs.controllers.document_controller import get_document

Usage Example

# Basic usage - get approval cycle only
approval_data = get_approval_cycle(approval_uid='abc-123-def')
if approval_data:
    print(f"Approval status: {approval_data.get('status')}")

# Get approval cycle with comments
approval_with_comments = get_approval_cycle(
    approval_uid='abc-123-def',
    include_comments=True
)
if approval_with_comments:
    for comment in approval_with_comments.get('comments', []):
        print(f"{comment['user_name']}: {comment['text']}")

# Get complete approval cycle with document info
full_approval = get_approval_cycle(
    approval_uid='abc-123-def',
    include_comments=True,
    include_document=True
)
if full_approval:
    doc = full_approval.get('document')
    print(f"Document: {doc.get('title')}")
    print(f"Comments: {len(full_approval.get('comments', []))}")

Best Practices

• Always check if the returned value is None before accessing dictionary keys to handle cases where the approval cycle doesn't exist
• Use include_comments and include_document flags judiciously as they add additional database queries and can impact performance
• The function logs errors but returns None on failure, so implement appropriate error handling in calling code
• Be aware that the get_document import occurs inside the function, which may affect performance if called frequently
• The function is decorated with log_controller_action, so all calls are automatically logged for audit purposes
• Consider caching results if the same approval cycle is accessed multiple times in a short period

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_approval_cycle 92.6% 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 90.3% similar

  Retrieves a specific approval cycle by its unique identifier (UID) with optional inclusion of associated document details and approval comments.

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

• function get_approval_v1 89.3% 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

• function get_document_approvals 80.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 79.1% 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