🔍 Code Extractor

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

Purpose

This function allows authorized users (document owners or users with MANAGE_ALL_TRAINING permission) to remove the training requirement from a controlled document. It validates document existence, checks user permissions, disables the training requirement through the DocumentTraining model, and logs the action for audit purposes. This is typically used when a document no longer requires users to complete training before accessing it.

Source Code

def disable_document_training(
    user: DocUser,
    document_uid: str
) -> Dict[str, Any]:
    """
    Disable training requirement for a document.
    
    Args:
        user: User disabling training
        document_uid: UID of document
        
    Returns:
        Dictionary with operation status
    """
    try:
        # Verify document exists using document controller
        from CDocs.controllers import document_controller
        document = document_controller.get_document(document_uid)
        if not document:
            raise ResourceNotFoundError(f"Document not found: {document_uid}")
        
        # Check if user can manage training for this document
        if document.get('ownerUID') != user.uid and not permissions.user_has_permission(user, "MANAGE_ALL_TRAINING"):
            raise PermissionError("Only document owner can disable training requirements")
        
        # Disable training
        doc_training = DocumentTraining(document_uid=document_uid)
        success = doc_training.disable_training()
        
        if not success:
            raise BusinessRuleError("Failed to disable training for document")
        
        # Log event
        audit_trail.log_event(
            event_type="TRAINING_DISABLED",
            user=user.uid,  # Pass UID instead of full user object
            resource_uid=document_uid,
            resource_type="ControlledDocument",
            details={
                "doc_number": document.get('doc_number', 'Unknown')
            }
        )
        
        return {
            "success": True,
            "message": f"Training disabled for document {document.get('doc_number', 'Unknown')}",
            "document_uid": document_uid
        }
        
    except (ResourceNotFoundError, ValidationError, PermissionError, BusinessRuleError) as e:
        raise
    except Exception as e:
        logger.error(f"Error disabling training for document {document_uid}: {e}")
        raise BusinessRuleError(f"Failed to disable training: {str(e)}")

Parameters

Parameter Details

user: DocUser object representing the user attempting to disable training. Must be either the document owner or have MANAGE_ALL_TRAINING permission. The user's UID is used for permission checks and audit logging.

document_uid: String containing the unique identifier (UID) of the document for which training should be disabled. Must correspond to an existing document in the system.

Return Value

Type: Dict[str, Any]

Returns a dictionary with three keys: 'success' (boolean, always True on successful execution), 'message' (string describing the operation result including document number), and 'document_uid' (string echoing the input document UID). On error, raises one of several exception types instead of returning.

Dependencies

• CDocs.config
• CDocs.models.document
• CDocs.models.user_extensions
• CDocs.models.training
• CDocs.utils
• CDocs.db
• CDocs.controllers

Required Imports

from typing import Dict, Any
from CDocs.models.user_extensions import DocUser
from CDocs.models.training import DocumentTraining
from CDocs.utils import audit_trail
from CDocs.config import permissions
from CDocs.controllers import require_permission, log_controller_action, transaction
from CDocs.controllers import PermissionError, ResourceNotFoundError, ValidationError, BusinessRuleError
import logging

Conditional/Optional Imports

These imports are only needed under specific conditions:

from CDocs.controllers import document_controller

Usage Example

from CDocs.models.user_extensions import DocUser
from your_module import disable_document_training

# Assume user and document_uid are already obtained
user = DocUser.get_by_uid('user123')
document_uid = 'doc-456-789'

try:
    result = disable_document_training(user=user, document_uid=document_uid)
    print(f"Success: {result['message']}")
    print(f"Document UID: {result['document_uid']}")
except ResourceNotFoundError:
    print("Document not found")
except PermissionError:
    print("User lacks permission to disable training")
except BusinessRuleError as e:
    print(f"Business rule violation: {e}")

Best Practices

• Always wrap calls in try-except blocks to handle ResourceNotFoundError, PermissionError, ValidationError, and BusinessRuleError exceptions
• Ensure the user object is properly authenticated and loaded before calling this function
• The function is decorated with require_permission('MANAGE_TRAINING'), so the calling context must support decorator execution
• The transaction decorator means this operation will be rolled back on failure, so database state remains consistent
• The function performs permission checks at two levels: decorator-level (MANAGE_TRAINING) and function-level (document owner or MANAGE_ALL_TRAINING)
• Audit trail events are automatically logged, so no additional logging is needed by the caller
• The function uses lazy import of document_controller to avoid circular dependencies
• Only document owners can disable training unless the user has MANAGE_ALL_TRAINING permission

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function enable_document_training 85.0% 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 reset_document_training 80.5% similar

  Resets all training records for a specific controlled document, typically used when a document is republished or updated, requiring users to retrain.

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

• function complete_user_training 75.1% similar

  Marks a user's training as complete for a specific controlled document, validating quiz requirements and setting expiration dates.

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

• function get_document_training_info 73.1% 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_document_training_assignments 72.9% similar

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

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