🔍 Code Extractor

Constructs and returns the FileCloud storage path for a controlled document, either for a specific version or the current version.

Purpose

This function generates the hierarchical FileCloud path for controlled documents based on department, document type, and document number. It supports retrieving paths for specific document versions or the current version. The function handles both ControlledDocument instances and document UIDs as input, making it flexible for different calling contexts. It's used to locate documents in the FileCloud storage system for retrieval, linking, or reference purposes.

Source Code

def get_filecloud_document_path(document: Union[ControlledDocument, str], version: Optional[str] = None) -> str:
    """
    Get the FileCloud path for a document or specific version.
    
    Args:
        document: ControlledDocument instance or document UID
        version: Optional version number (if None, gets current version path)
        
    Returns:
        Full path to document in FileCloud
        
    Raises:
        ResourceNotFoundError: If document or version not found
    """
    # Get document instance if UID provided
    if isinstance(document, str):
        doc = ControlledDocument(uid=document)
        if not doc:
            raise ResourceNotFoundError(f"Document not found: {document}")
    else:
        doc = document
    
    # Base folder structure
    department_folder = f"/{settings.FILECLOUD_ROOT_FOLDER}/{doc.department}"
    doc_type_folder = f"{department_folder}/{doc.doc_type}"
    document_folder = f"{doc_type_folder}/{doc.doc_number}"
    
    # Get specific version if requested
    if version:
        version_obj = doc.get_version_by_number(version)
        if not version_obj:
            raise ResourceNotFoundError(f"Version {version} not found for document {doc.uid}")
        
        return f"{document_folder}/{doc.doc_number}_v{version_obj.version_number}.{version_obj.file_type}"
    
    # Get current version
    current_version = doc.current_version
    if not current_version:
        raise ResourceNotFoundError(f"No current version found for document {doc.uid}")
    
    return f"{document_folder}/{doc.doc_number}_v{current_version.version_number}.{current_version.file_type}"

Parameters

Parameter Details

document: Either a ControlledDocument model instance or a string containing the document's unique identifier (UID). If a string UID is provided, the function will attempt to load the corresponding ControlledDocument. This parameter identifies which document's path should be constructed.

version: Optional string specifying the version number of the document to retrieve. If None (default), the function returns the path to the current/active version of the document. If provided, it must match an existing version number for the document.

Return Value

Type: str

Returns a string containing the full FileCloud path to the document file. The path follows the structure: /{FILECLOUD_ROOT_FOLDER}/{department}/{doc_type}/{doc_number}/{doc_number}_v{version_number}.{file_type}. For example: '/controlled_docs/Engineering/SOP/DOC-001/DOC-001_v3.pdf'

Dependencies

• CDocs.config.settings
• CDocs.models.document.ControlledDocument
• CDocs.controllers.ResourceNotFoundError

Required Imports

from CDocs.config import settings
from CDocs.models.document import ControlledDocument
from CDocs.controllers import ResourceNotFoundError
from typing import Union, Optional

Usage Example

# Example 1: Get current version path using document instance
from CDocs.models.document import ControlledDocument
from CDocs.controllers import get_filecloud_document_path

doc = ControlledDocument(uid='DOC-12345')
path = get_filecloud_document_path(doc)
print(path)  # Output: /controlled_docs/Engineering/SOP/DOC-001/DOC-001_v3.pdf

# Example 2: Get specific version path using document UID
path = get_filecloud_document_path('DOC-12345', version='2')
print(path)  # Output: /controlled_docs/Engineering/SOP/DOC-001/DOC-001_v2.pdf

# Example 3: Handle errors
try:
    path = get_filecloud_document_path('INVALID-UID')
except ResourceNotFoundError as e:
    print(f'Error: {e}')

Best Practices

• Always wrap calls in try-except blocks to handle ResourceNotFoundError when document or version might not exist
• Use document instances when available rather than UIDs to avoid unnecessary database lookups
• Ensure the ControlledDocument has a current_version set before calling without the version parameter
• The function is decorated with log_controller_action, so all calls are automatically logged for audit purposes
• The returned path is a logical FileCloud path, not a filesystem path - use appropriate FileCloud API methods to access the actual file
• Version numbers should be passed as strings, not integers
• The function does not verify that the file actually exists in FileCloud, only constructs the expected path

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_filecloud_document_path_v1 91.8% similar

  Constructs and returns the FileCloud storage path for a controlled document, supporting both custom and standard folder structures with version-specific file paths.

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

• function get_document_metadata_from_filecloud 76.7% similar

  Retrieves metadata for a specific document (and optionally a specific version) from FileCloud storage system.

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

• function get_document_download_url 73.1% 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 download_document_version 72.7% 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_edit_url_v1 71.8% similar

  Generates a FileCloud URL to view or edit a controlled document, selecting the appropriate file format (PDF or Word) based on document status and version availability.

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