🔍 Code Extractor

Retrieves permission information for a specific document by its unique identifier, returning structured data about who can access the document and their permission levels.

Purpose

This function serves as an API endpoint to fetch comprehensive permission details for a controlled document. It validates the document ID, retrieves the document object, and delegates to a permission management function to gather all access control information. The function includes error handling and logging for debugging and monitoring purposes. It's designed to be used in document management systems where access control and permission auditing are required.

Source Code

def get_document_permissions(doc_id: str) -> Dict[str, Any]:
    """
    API endpoint to get document permissions information.
    
    Args:
        doc_id: Document UID
        
    Returns:
        Dict: Document permissions information
    """
    try:
        logger.debug(f"Getting permissions info for document {doc_id}")
        
        if not doc_id:
            return {
                'success': False,
                'message': 'Missing document ID'
            }
        
        # Get document
        document = ControlledDocument(uid=doc_id)
        if not document:
            return {
                'success': False,
                'message': 'Document not found'
            }
        
        # Get current permissions info
        permission_info = manage_document_permissions(document)
        
        # Return the full permissions information
        return permission_info
        
    except Exception as e:
        logger.error(f"Error getting document permissions: {e}")
        import traceback
        logger.error(traceback.format_exc())
        
        return {
            'success': False,
            'message': f'Error: {str(e)}'
        }

Parameters

Parameter Details

doc_id: A string representing the unique identifier (UID) of the document whose permissions are being queried. Must be a non-empty string. If empty or None, the function returns an error response.

Return Value

Type: Dict[str, Any]

Returns a dictionary (Dict[str, Any]) containing permission information. On success, returns the output from manage_document_permissions() which includes permission details. On failure, returns a dictionary with 'success': False and 'message' key containing error details. The structure always includes at least 'success' (bool) and 'message' (str) keys, with additional permission data on successful retrieval.

Dependencies

• logging
• typing
• panel
• traceback
• CDocs.models.document
• CDocs.models.user_extensions
• CDocs.controllers.share_controller

Required Imports

import logging
from typing import Dict, Any
from CDocs.models.document import ControlledDocument
from CDocs.controllers.share_controller import manage_document_permissions

Conditional/Optional Imports

These imports are only needed under specific conditions:

import traceback

Usage Example

import logging
from typing import Dict, Any
from CDocs.models.document import ControlledDocument
from CDocs.controllers.share_controller import manage_document_permissions

# Setup logger
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.DEBUG)

# Get permissions for a document
doc_id = "doc-12345-abcde"
result = get_document_permissions(doc_id)

if result['success']:
    print(f"Permissions retrieved successfully")
    # Access permission details from result
    # Structure depends on manage_document_permissions return value
else:
    print(f"Error: {result['message']}")

# Handle missing document ID
result = get_document_permissions("")
print(result)  # {'success': False, 'message': 'Missing document ID'}

Best Practices

• Always validate the doc_id parameter before calling this function to avoid unnecessary API calls
• Handle both success and failure cases in the returned dictionary by checking the 'success' key
• Ensure proper logging configuration is in place before using this function for debugging purposes
• The function catches all exceptions broadly - consider implementing more specific exception handling for production use
• Ensure the calling context has appropriate permissions to query document permissions
• The function depends on manage_document_permissions() - understand its return structure for proper result handling
• Consider implementing rate limiting or caching if this endpoint is called frequently for the same documents

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_access 85.1% similar

  Retrieves document access information for a specific user, including permissions (write access, owner, reviewer, approver status) and share URL.

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

• function get_document 68.9% 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

• function get_document_v1 68.5% 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 manage_document_permissions 67.7% similar

  Comprehensive function to manage document sharing and user permissions. This function: 1. Creates a share only if needed for active users 2. Adds/updates users with appropriate permissions based on their roles 3. Removes users who shouldn't have access anymore 4. Cleans up shares that are no longer needed 5. Manages ACL entries for write permissions on the document's folder Args: document: The document to manage permissions for Returns: Dict: Result of permission updates with detailed information

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

• function set_document_permissions_in_filecloud 66.9% similar

  Sets user and group permissions for a document in FileCloud by updating access controls on the document's folder path and logging the permission changes to an audit trail.

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