🔍 Code Extractor

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

Purpose

This function serves as a controller endpoint to fetch approval cycle information for a given document in a controlled document management system. It's used to track the approval workflow history and current status of document reviews, enabling users to see who has approved, rejected, or is pending review on a document. The function delegates to an underlying controller base class method and includes logging via a decorator.

Source Code

def get_document_approval_cycles(document_uid: str, include_active_only: bool = False) -> Dict[str, Any]:
    """Get all approval cycles for a document."""
    return _controller.get_cycles_for_document(document_uid, include_active_only)

Parameters

Parameter Details

document_uid: A unique string identifier for the document whose approval cycles should be retrieved. This is typically a UUID or other unique identifier that references a ControlledDocument in the system.

include_active_only: A boolean flag that determines whether to return all approval cycles (False, default) or only currently active/in-progress cycles (True). Active cycles are those that have not been completed, cancelled, or expired.

Return Value

Type: Dict[str, Any]

Returns a dictionary containing approval cycle data. The structure typically includes keys for cycle information such as cycle IDs, status (pending, approved, rejected), approver assignments, timestamps, comments, and workflow metadata. The exact structure depends on the _controller.get_cycles_for_document implementation but follows the Dict[str, Any] type hint allowing flexible nested data structures.

Dependencies

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

Required Imports

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

Usage Example

# Assuming the function is imported from a CDocs controller module
from CDocs.controllers.approval_controller import get_document_approval_cycles

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

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

Best Practices

• Always validate that the document_uid exists before calling this function to avoid ResourceNotFoundError exceptions
• Use include_active_only=True when you only need current workflow 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 such as ResourceNotFoundError, PermissionError, or ValidationError that may be raised by the underlying controller
• Consider caching results if calling this function frequently for the same document, as approval cycles don't change rapidly
• Ensure the user has appropriate permissions to view approval cycles for the specified document

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_approvals_v1 86.8% similar

  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.

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

• function get_document_review_cycles_v1 84.8% 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 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 create_approval_cycle_v2 81.5% 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 get_document_approval_cycles 80.3% 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