🔍 Code Extractor

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

Purpose

This function serves as a controller action to fetch metadata associated with a controlled document stored in FileCloud. It validates the document exists, constructs the appropriate FileCloud path, and retrieves metadata through the FileCloud API client. It's used in document management workflows where metadata needs to be accessed without downloading the full document content.

Source Code

def get_document_metadata_from_filecloud(
    document_uid: str,
    version: Optional[str] = None
) -> Dict[str, Any]:
    """
    Get metadata for a document from FileCloud.
    
    Args:
        document_uid: UID of the document
        version: Optional specific version to get metadata for
        
    Returns:
        Dictionary of metadata values
        
    Raises:
        ResourceNotFoundError: If document or version not found
        FileCloudError: If metadata retrieval fails
    """
    # Get document instance
    doc = ControlledDocument(uid=document_uid)
    if not doc:
        raise ResourceNotFoundError(f"Document not found: {document_uid}")
    
    # Get file path
    file_path = get_filecloud_document_path(doc, version)
    
    try:
        client = get_filecloud_client()
        
        # Get metadata
        result = client.get_file_metadata(file_path)
        
        if not result.get('success', False):
            logger.error(f"Failed to get metadata from FileCloud: {result.get('message', 'Unknown error')}")
            raise FileCloudError(f"Failed to get metadata: {result.get('message', 'Unknown error')}")
        
        return result.get('metadata', {})
        
    except Exception as e:
        logger.error(f"Error getting document metadata from FileCloud: {e}")
        raise FileCloudError(f"Error getting document metadata: {e}")

Parameters

Parameter Details

document_uid: Unique identifier (UID) string for the controlled document. This is used to instantiate a ControlledDocument object and locate the document in the system. Must be a valid UID that exists in the database.

version: Optional string specifying a particular version of the document to retrieve metadata for. If None, metadata for the current/latest version is retrieved. The version format depends on the document versioning scheme used in the system.

Return Value

Type: Dict[str, Any]

Returns a dictionary (Dict[str, Any]) containing metadata key-value pairs retrieved from FileCloud. The exact structure depends on FileCloud's metadata schema but typically includes properties like file size, creation date, modification date, content type, and custom metadata fields. Returns an empty dictionary if no metadata exists.

Dependencies

• CDocs
• typing

Required Imports

from typing import Dict, Any, Optional
from CDocs.models.document import ControlledDocument
from CDocs.controllers import log_controller_action, ResourceNotFoundError
from CDocs.utils.FC_api import FileCloudAPI

Usage Example

from CDocs.controllers.document_controller import get_document_metadata_from_filecloud
from CDocs.controllers import ResourceNotFoundError, FileCloudError

try:
    # Get metadata for latest version
    metadata = get_document_metadata_from_filecloud(
        document_uid='doc-12345-abcde'
    )
    print(f"File size: {metadata.get('size')}")
    print(f"Modified: {metadata.get('modified_date')}")
    
    # Get metadata for specific version
    version_metadata = get_document_metadata_from_filecloud(
        document_uid='doc-12345-abcde',
        version='v2.1'
    )
    print(f"Version metadata: {version_metadata}")
    
except ResourceNotFoundError as e:
    print(f"Document not found: {e}")
except FileCloudError as e:
    print(f"FileCloud error: {e}")

Best Practices

• Always wrap calls in try-except blocks to handle ResourceNotFoundError and FileCloudError exceptions
• Validate document_uid format before calling if possible to avoid unnecessary database queries
• The function is decorated with log_controller_action, so all calls are automatically logged for audit purposes
• Check the 'success' key in the returned metadata to verify the operation completed successfully
• Be aware that this function requires active FileCloud connection and proper authentication
• The function does not cache metadata, so repeated calls will make new API requests to FileCloud
• Ensure proper permissions are configured as this is a controller action that may have permission requirements

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function upload_document_to_filecloud 78.3% similar

  Uploads a document version to FileCloud storage system with metadata, handling file creation, folder structure, and audit logging.

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

• function update_document_metadata_in_filecloud 77.9% similar

  Updates metadata for a document stored in FileCloud, merging new metadata with existing values and logging the update in an audit trail.

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

• function get_document_v2 77.9% 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_v1 77.4% similar

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

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

• function get_document 77.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