🔍 Code Extractor

Retrieves or creates a shareable URL for a specific document version, checking for existing shares before creating new ones.

Purpose

This function manages document sharing by first checking if a share URL already exists for the given document version. If not, it creates a new share through the FileCloud client with a formatted name including the document title and version number. It handles error cases where the FileCloud client is unavailable or the document cannot be found, returning None in failure scenarios.

Source Code

def get_document_share_url(document_version: DocumentVersion) -> Optional[str]:
    """
    Get a share URL for a document version, creating a share if one doesn't exist.
    
    Args:
        document_version: The document version to share
        
    Returns:
        str: Share URL or None if share couldn't be created
    """
    # Check if we already have a share URL
    if hasattr(document_version, 'share_url') and document_version.share_url:
        return document_version.share_url
    
    # Create a share if needed
    fc_client = get_filecloud_client()
    if not fc_client:
        logger.error("Could not get FileCloud client")
        return None
    
    # Get document title for share name
    document = document_version.document
    if not document:
        logger.error(f"Document not found for version {document_version.uid}")
        return None
    
    share_name = f"{document.title} - v{document_version.version_number}"
    
    # Create/get share
    share_result = fc_client.manage_document_share(
        document_version=document_version,
        share_name=share_name
    )
    
    if not share_result.get('success', False):
        logger.error(f"Failed to create share: {share_result.get('message')}")
        return None
    
    return share_result.get('share_url')

Parameters

Parameter Details

document_version: A DocumentVersion model instance representing the specific version of a document to be shared. Must have a 'document' relationship and may have an existing 'share_url' attribute. Expected to have 'uid' and 'version_number' attributes.

Return Value

Type: Optional[str]

Returns a string containing the share URL if successful, or None if the share could not be created. None is returned in cases where: the FileCloud client cannot be obtained, the associated document is not found, or the share creation fails. The share URL is retrieved from the share_result dictionary returned by the FileCloud client's manage_document_share method.

Dependencies

• logging
• typing
• CDocs.models.document
• CDocs.controllers.filecloud_controller

Required Imports

from typing import Optional
from CDocs.models.document import DocumentVersion
from CDocs.controllers.filecloud_controller import get_filecloud_client
import logging

Usage Example

from CDocs.models.document import DocumentVersion
from typing import Optional

# Assume document_version is retrieved from database
document_version = DocumentVersion.query.get(version_id)

# Get or create share URL
share_url = get_document_share_url(document_version)

if share_url:
    print(f"Document can be accessed at: {share_url}")
    # Send share_url to users via email or display in UI
else:
    print("Failed to create share URL")
    # Handle error case - log, notify admin, or show error message

Best Practices

• Always check the return value for None before using the share URL
• Ensure the document_version object has a valid 'document' relationship loaded to avoid database queries
• The function caches the share URL on the document_version object if it exists, so repeated calls are efficient
• Monitor logs for 'Could not get FileCloud client' and 'Failed to create share' errors to identify configuration issues
• The share name format includes version number, making it easy to identify which version is being shared
• Consider implementing retry logic for transient FileCloud API failures
• Ensure proper error handling in calling code since this function returns None on failure rather than raising exceptions

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function manage_user_share_access 72.2% similar

  Manages user access permissions (read-only or edit) to a specific document version share in FileCloud, creating the share if it doesn't exist.

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

• function manage_user_share_access_v2 72.1% similar

  Manages user access permissions to a FileCloud document share, creating shares if needed and setting read-only or write access for specified users.

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

• function create_document_share_link 71.4% similar

  Creates a shareable link for a document in FileCloud with optional password protection, expiry, and email notifications.

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

• function manage_user_share_access_v1 70.4% similar

  Manages user access permissions to a FileCloud document share, creating the share if needed and setting read-only or write access for a specified user.

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

• function get_user_access_url 66.4% similar

  Retrieves a share URL for a document version and determines the appropriate access level (read/write) for a specific user based on their role (owner, author, reviewer, approver) and the document's current status.

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