🔍 Code Extractor

Retrieves training assignments and configuration for a specific controlled document, including assigned users and training requirements.

Purpose

This function serves as a controller endpoint to fetch comprehensive training assignment information for a document in a document management system. It verifies document existence, checks user permissions (allowing document owners or users with VIEW_ALL_TRAINING permission), retrieves training configuration settings, and returns a structured response containing document details, training settings (validity period, quiz requirements, instructions), and the list of users assigned to complete the training.

Source Code

def get_document_training_assignments(
    user: DocUser,
    document_uid: str
) -> Dict[str, Any]:
    """
    Get training assignments for a document.
    
    Args:
        user: User requesting assignments
        document_uid: UID of document
        
    Returns:
        Dictionary with training assignments
    """
    try:
        # Verify document exists
        document = ControlledDocument(uid=document_uid)
        if not document:
            raise ResourceNotFoundError(f"Document not found: {document_uid}")
        
        # Check permissions
        if (document.owner_uid != user.uid and 
            not permissions.user_has_permission(user, "VIEW_ALL_TRAINING")):
            raise PermissionError("You can only view training assignments for your own documents")
        
        # Get training configuration
        doc_training = DocumentTraining(document_uid=document_uid)
        
        # Get assigned users
        assigned_users = doc_training.get_assigned_users()
        
        return {
            "success": True,
            "document_uid": document_uid,
            "doc_number": document.doc_number,
            "title": document.title,
            "training_enabled": doc_training._data.get("training_required", False),
            "training_config": {
                "validity_days": doc_training._data.get("validity_days", 365),
                "quiz_required": doc_training._data.get("quiz_required", False),
                "instructions": doc_training._data.get("instructions", "")
            },
            "assigned_users": assigned_users
        }
        
    except (ResourceNotFoundError, PermissionError) as e:
        raise
    except Exception as e:
        logger.error(f"Error getting training assignments: {e}")
        raise BusinessRuleError(f"Failed to get training assignments: {e}")

Parameters

Parameter Details

user: DocUser object representing the authenticated user making the request. Used for permission verification to ensure the user has rights to view training assignments (must be document owner or have VIEW_ALL_TRAINING permission).

document_uid: String containing the unique identifier (UID) of the controlled document for which training assignments are being requested. Must correspond to an existing document in the system.

Return Value

Type: Dict[str, Any]

Returns a dictionary (Dict[str, Any]) containing: 'success' (bool) indicating operation success, 'document_uid' (str) echoing the requested document UID, 'doc_number' (str) the document's number, 'title' (str) document title, 'training_enabled' (bool) whether training is required, 'training_config' (dict) with 'validity_days' (int, default 365), 'quiz_required' (bool), and 'instructions' (str), and 'assigned_users' (list) containing user assignment details. May raise ResourceNotFoundError if document doesn't exist, PermissionError if user lacks access rights, or BusinessRuleError for other failures.

Dependencies

• CDocs.config
• CDocs.models.document
• CDocs.models.user_extensions
• CDocs.models.training
• CDocs.utils
• CDocs.db
• CDocs.controllers
• logging
• typing
• datetime
• traceback

Required Imports

from typing import Dict, Any
import logging
from CDocs.config import permissions
from CDocs.models.document import ControlledDocument
from CDocs.models.user_extensions import DocUser
from CDocs.models.training import DocumentTraining
from CDocs.controllers import require_permission, log_controller_action
from CDocs.controllers import PermissionError, ResourceNotFoundError, BusinessRuleError

Usage Example

from CDocs.models.user_extensions import DocUser
from CDocs.controllers.training_controller import get_document_training_assignments

# Assume user and document_uid are already obtained
current_user = DocUser(uid='user123')
document_id = 'doc-456-789'

try:
    result = get_document_training_assignments(
        user=current_user,
        document_uid=document_id
    )
    
    if result['success']:
        print(f"Document: {result['title']}")
        print(f"Training enabled: {result['training_enabled']}")
        print(f"Validity days: {result['training_config']['validity_days']}")
        print(f"Assigned users: {len(result['assigned_users'])}")
        
        for assigned_user in result['assigned_users']:
            print(f"  - User: {assigned_user}")
except ResourceNotFoundError as e:
    print(f"Document not found: {e}")
except PermissionError as e:
    print(f"Access denied: {e}")
except BusinessRuleError as e:
    print(f"Error retrieving assignments: {e}")

Best Practices

• Always handle the three specific exception types: ResourceNotFoundError, PermissionError, and BusinessRuleError when calling this function
• Ensure the user object passed is properly authenticated before calling this function
• The function enforces ownership-based access control - users can only view training assignments for their own documents unless they have VIEW_ALL_TRAINING permission
• The function is decorated with @require_permission('VIEW_TRAINING'), so the calling user must have this base permission
• Check the 'success' field in the returned dictionary before processing the results
• The function logs errors automatically, but consider additional application-level logging for audit purposes
• Be aware that this function performs multiple database operations (document lookup, training config retrieval, user assignment queries)
• The training_config dictionary may contain default values (validity_days=365) if not explicitly set in the database

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_training_info 80.3% similar

  Retrieves comprehensive training information for a specific controlled document, including training configuration, assigned users, completion status, and statistics.

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

• function get_training_assignment 78.0% similar

  Retrieves a specific training assignment for a user from a Neo4j graph database, validating user authorization and parsing a composite UID format.

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

• function assign_user_training 77.1% similar

  Assigns training requirements to multiple users for a specific controlled document, validating permissions, document training status, and user existence before creating assignments.

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

• function enable_document_training 73.3% similar

  Enables training requirements for a controlled document, setting validity period, quiz requirements, and instructions for users who need to complete training on the document.

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

• function disable_document_training 72.9% similar

  Disables the training requirement for a specific controlled document, verifying user permissions and logging the action to the audit trail.

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