🔍 Code Extractor

Retrieves comprehensive details of a controlled document by its UID, with optional inclusion of version history, review cycles, and approval cycles.

Purpose

This function serves as the primary retrieval mechanism for controlled documents in a document management system. It fetches a document by its unique identifier and optionally enriches the response with related data including version history, review cycles, and approval workflows. The function is decorated with logging capabilities and is designed to support document control workflows in regulated environments where traceability and audit trails are critical.

Source Code

def get_document(
    document_uid: str,
    include_versions: bool = True,
    include_reviews: bool = True,
    include_approvals: bool = True
) -> Dict[str, Any]:
    """
    Get document details by UID.
    
    Args:
        document_uid: UID of document to retrieve
        include_versions: Whether to include version history
        include_reviews: Whether to include review cycles
        include_approvals: Whether to include approval cycles
        
    Returns:
        Dictionary with document details
        
    Raises:
        ResourceNotFoundError: If document not found
    """
    try:
        # Get document instance
        document = ControlledDocument(uid=document_uid)
        if not document:
            raise ResourceNotFoundError(f"Document not found: {document_uid}")
        
        # Convert to dictionary
        result = document.to_dict()
        
        # Get current version if any
        current_version = document.current_version
        if current_version:
            result["current_version"] = current_version.to_dict()
        
        # Add version history if requested
        if include_versions:
            versions = document.get_all_versions()
            result["versions"] = [v.to_dict() for v in versions]
        
        # Add review cycles if requested
        if include_reviews:
            from CDocs.models.review import ReviewCycle
            reviews = ReviewCycle.get_reviews_for_document(document_uid)
            result["reviews"] = [r.to_dict() for r in reviews]
        
        # Add approval cycles if requested
        if include_approvals:
            from CDocs.models.approval import Approval
            approvals = Approval.get_approvals_for_document(document_uid)
            result["approvals"] = [a.to_dict() for a in approvals]
        
        return result
        
    except ResourceNotFoundError:
        # Re-raise not found error
        raise
    except Exception as e:
        logger.error(f"Error retrieving document {document_uid}: {e}")
        raise BusinessRuleError(f"Failed to retrieve document: {e}")

Parameters

Parameter Details

document_uid: Unique identifier (UID) string for the document to retrieve. This is a required parameter that must correspond to an existing document in the system. Expected to be a string, likely a UUID format.

include_versions: Boolean flag (default: True) that determines whether to include the complete version history of the document in the response. When True, all historical versions are fetched and included in the 'versions' key of the returned dictionary.

include_reviews: Boolean flag (default: True) that controls whether to fetch and include all review cycles associated with the document. When True, review cycle information is retrieved and added to the 'reviews' key in the response.

include_approvals: Boolean flag (default: True) that determines whether to include approval cycle information in the response. When True, all approval workflows for the document are fetched and included in the 'approvals' key.

Return Value

Type: Dict[str, Any]

Returns a dictionary (Dict[str, Any]) containing comprehensive document details. The base dictionary includes all document properties from document.to_dict(). If a current version exists, it's added under 'current_version' key. Optionally includes 'versions' (list of version dictionaries), 'reviews' (list of review cycle dictionaries), and 'approvals' (list of approval dictionaries) based on the boolean parameters. Each nested object is converted to a dictionary representation via their respective to_dict() methods.

Dependencies

• logging
• uuid
• os
• tempfile
• typing
• datetime
• io
• panel
• shutil
• traceback
• CDocs
• config

Required Imports

from typing import Dict, Any
from CDocs.models.document import ControlledDocument
from CDocs.controllers import ResourceNotFoundError, BusinessRuleError
import logging

Conditional/Optional Imports

These imports are only needed under specific conditions:

from CDocs.models.review import ReviewCycle

from CDocs.models.approval import Approval

Usage Example

from typing import Dict, Any
from CDocs.models.document import ControlledDocument
from CDocs.controllers import ResourceNotFoundError, BusinessRuleError
import logging

# Basic usage - get document with all related data
try:
    document_data = get_document(
        document_uid='550e8400-e29b-41d4-a716-446655440000'
    )
    print(f"Document title: {document_data.get('title')}")
    print(f"Current version: {document_data.get('current_version')}")
    print(f"Number of versions: {len(document_data.get('versions', []))}")
except ResourceNotFoundError as e:
    print(f"Document not found: {e}")
except BusinessRuleError as e:
    print(f"Error retrieving document: {e}")

# Get document without version history
document_minimal = get_document(
    document_uid='550e8400-e29b-41d4-a716-446655440000',
    include_versions=False,
    include_reviews=False,
    include_approvals=False
)

# Get document with only reviews
document_with_reviews = get_document(
    document_uid='550e8400-e29b-41d4-a716-446655440000',
    include_versions=False,
    include_reviews=True,
    include_approvals=False
)

Best Practices

• Always wrap calls in try-except blocks to handle ResourceNotFoundError and BusinessRuleError exceptions
• Use the boolean parameters to optimize performance by only fetching required related data
• Ensure the document_uid is validated before calling this function to avoid unnecessary database queries
• The function performs lazy imports for ReviewCycle and Approval models only when needed, which is efficient but requires those modules to be available when the respective flags are True
• This function is decorated with log_controller_action, so all invocations are automatically logged for audit purposes
• The function re-raises ResourceNotFoundError specifically to allow calling code to distinguish between 'not found' and other errors
• Consider the performance impact when setting all include_* parameters to True for documents with extensive history
• The returned dictionary structure may vary based on the boolean parameters, so check for key existence before accessing nested data

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_versions 82.8% similar

  Retrieves detailed information about a specific document version by its UID, including associated document context and version status.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function get_document_versions_v1 80.6% similar

  Retrieves all versions of a document from the database given its unique identifier (UID).

  From: /tf/active/vicechatdev/document_controller_backup.py

• function download_document_version 73.0% similar

  Downloads a specific version of a controlled document from FileCloud storage, with optional audit trail and watermark inclusion, and logs the download event.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function get_document_download_url 72.5% similar

  Retrieves a download URL for a controlled document, automatically selecting between editable (Word) and PDF formats based on document status or explicit request.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function delete_document 67.5% similar

  Deletes a controlled document from the system with permission checks, status validation, and audit logging.

  From: /tf/active/vicechatdev/document_controller_backup.py