🔍 Code Extractor

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

Purpose

This function retrieves a document version (either specified or current) from a document management system, processes it with optional features (audit trail, watermark), and returns the file content along with comprehensive metadata. It enforces permission checks, validates document and version existence, handles file retrieval from FileCloud storage, and maintains an audit trail of download activities. Used in document management workflows where controlled access to versioned documents is required.

Source Code

def download_document_version(
    user: DocUser,
    document_uid: str,
    version_uid: Optional[str] = None,
    include_audit_trail: bool = False,
    include_watermark: bool = False
) -> Dict[str, Any]:
    """
    Download a document version.
    
    Args:
        user: User downloading the document
        document_uid: UID of document
        version_uid: Optional specific version to download (if None, downloads current version)
        include_audit_trail: Whether to include audit trail in the document
        include_watermark: Whether to include watermark
        
    Returns:
        Dictionary with download details and file content
    """
    try:
        # Get document instance
        document = ControlledDocument(uid=document_uid)
        if not document:
            raise ResourceNotFoundError(f"Document not found: {document_uid}")
            
        # Get version to download
        version = None
        if version_uid:
            version = DocumentVersion(uid=version_uid)
            if not version or version.document_uid != document_uid:
                raise ResourceNotFoundError(f"Version not found for document: {version_uid}")
        else:
            # Get current version
            version = document.current_version
            if not version:
                raise ResourceNotFoundError(f"No current version found for document {document_uid}")
                
        # Download file from FileCloud
        file_content = download_document_from_filecloud(
            user=user,
            document_uid=document_uid,
            version=version.version_number
        )
        
        # If not bytes, something went wrong
        if not isinstance(file_content, bytes):
            raise BusinessRuleError("Failed to download file content")
            
        # Handle special processing if needed
        processed_content = file_content
        
        # Include audit trail if requested
        if include_audit_trail:
            # Implementation for audit trail...
            pass
                
        # Add watermark if requested
        if include_watermark:
            # Implementation for watermark...
            pass
                
        # Log download event - CHANGED: Use DOCUMENT_DOWNLOADED instead of VERSION_DOWNLOADED
        audit_trail.log_document_lifecycle_event(
            event_type="DOCUMENT_DOWNLOADED", 
            user=user,
            document_uid=document_uid,
            details={
                "version_uid": version.uid,
                "version_number": version.version_number,
                "include_audit_trail": include_audit_trail,
                "include_watermark": include_watermark
            }
        )
        
        # Build result
        return {
            "success": True,
            "document_uid": document_uid,
            "document_number": document.doc_number,
            "title": document.title,
            "version_uid": version.uid,
            "version_number": version.version_number,
            "file_name": version.file_name,
            "file_extension": '.'+version.file_type,
            "file_size": len(processed_content),
            "content": processed_content,
            "audit_trail_included": include_audit_trail,
            "watermark_included": include_watermark
        }
        
    except (ResourceNotFoundError, PermissionError, BusinessRuleError) as e:
        # Re-raise known errors
        raise
    except Exception as e:
        logger.error(f"Error downloading document version: {e}")
        raise BusinessRuleError(f"Failed to download document version: {e}")

Parameters

Parameter Details

user: DocUser object representing the authenticated user performing the download. Used for permission validation and audit logging.

document_uid: String containing the unique identifier (UID) of the document to download. Must correspond to an existing ControlledDocument in the system.

version_uid: Optional string containing the UID of a specific document version to download. If None or not provided, the function downloads the current/latest version of the document.

include_audit_trail: Boolean flag indicating whether to append the document's audit trail to the downloaded file. Defaults to False. When True, audit history is embedded in the document.

include_watermark: Boolean flag indicating whether to apply a watermark to the downloaded document. Defaults to False. When True, a watermark is added to the file content.

Return Value

Type: Dict[str, Any]

Returns a dictionary (Dict[str, Any]) containing download operation results. Keys include: 'success' (bool), 'document_uid' (str), 'document_number' (str), 'title' (str), 'version_uid' (str), 'version_number' (int/str), 'file_name' (str), 'file_extension' (str with leading dot), 'file_size' (int in bytes), 'content' (bytes of file data), 'audit_trail_included' (bool), 'watermark_included' (bool). The 'content' key contains the actual binary file data ready for download or further processing.

Dependencies

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

Required Imports

from typing import Dict, Any, Optional
from CDocs.models.document import ControlledDocument, DocumentVersion
from CDocs.models.user_extensions import DocUser
from CDocs.utils import audit_trail
from CDocs.controllers import require_permission, log_controller_action, ResourceNotFoundError, PermissionError, BusinessRuleError
from CDocs.controllers.filecloud_controller import download_document_from_filecloud
import logging

Usage Example

from CDocs.models.user_extensions import DocUser
from CDocs.controllers.document_controller import download_document_version

# Initialize user object
user = DocUser(uid='user123')

# Download current version of a document
result = download_document_version(
    user=user,
    document_uid='doc-abc-123'
)

if result['success']:
    file_content = result['content']
    file_name = result['file_name']
    # Save to disk or send to client
    with open(file_name, 'wb') as f:
        f.write(file_content)

# Download specific version with audit trail and watermark
result = download_document_version(
    user=user,
    document_uid='doc-abc-123',
    version_uid='ver-xyz-456',
    include_audit_trail=True,
    include_watermark=True
)

print(f"Downloaded {result['file_name']} (Version {result['version_number']})")
print(f"File size: {result['file_size']} bytes")

Best Practices

• Always handle the returned 'content' bytes data appropriately - it can be large and should be streamed or written to disk rather than kept in memory for extended periods
• The function requires proper permission decorators (@require_permission('DOWNLOAD_DOCUMENT', 'document_uid')) to be applied at the function definition level
• Catch specific exceptions (ResourceNotFoundError, PermissionError, BusinessRuleError) separately to provide appropriate error handling and user feedback
• The function logs download events with 'DOCUMENT_DOWNLOADED' event type - ensure audit trail system is properly configured
• When version_uid is None, the function downloads the current version - verify that documents have a current version set before calling
• The include_audit_trail and include_watermark features have placeholder implementations (pass statements) - verify these are implemented before using in production
• File content validation checks that returned data is bytes type - ensure FileCloud integration returns proper binary data
• The function is decorated with @log_controller_action which provides automatic logging - ensure this decorator is properly configured
• Consider implementing rate limiting or download quotas for production use to prevent abuse
• The returned dictionary includes file_size calculated from processed_content - this may differ from original if audit trail or watermark is added

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_download_url 82.6% 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 convert_document_to_pdf 75.9% similar

  Converts a document version from an editable format (e.g., Word) to PDF without changing the document's status, uploading the result to FileCloud and updating the version record.

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

• function get_document_versions 74.7% 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 create_document_v1 73.4% similar

  Creates a new version of an existing document in a document management system, storing the file in FileCloud and tracking version metadata in Neo4j graph database.

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

• function get_document 73.0% similar

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

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