🔍 Code Extractor

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

Purpose

This function is used in document management systems to enforce training compliance. It allows authorized users (document owners or users with MANAGE_ALL_TRAINING permission) to mark a document as requiring training, specify how long the training remains valid, whether a quiz is mandatory, and provide training instructions. The function validates permissions, creates training records, and logs the action for audit purposes.

Source Code

def enable_document_training(
    user: DocUser,
    document_uid: str,
    validity_days: int = 365,
    quiz_required: bool = False,
    instructions: str = ""
) -> Dict[str, Any]:
    """
    Enable training requirement for a document.
    
    Args:
        user: User enabling training
        document_uid: UID of document
        validity_days: Number of days training is valid
        quiz_required: Whether quiz is required
        instructions: Training instructions
        
    Returns:
        Dictionary with operation status
    """
    try:
        logger.info(f"enable_document_training called with user: {user.username if user else 'None'}, document_uid: {document_uid}")
        
        # Verify document exists using document controller
        from CDocs.controllers import document_controller
        logger.info("Loading document...")
        document = document_controller.get_document(document_uid)
        if not document:
            logger.error(f"Document not found: {document_uid}")
            raise ResourceNotFoundError(f"Document not found: {document_uid}")
        
        logger.info(f"Document loaded: {document.get('docNumber', 'Unknown')}")
        
        # 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"):
            logger.warning(f"Permission denied: User {user.uid} cannot manage training for document owned by {document.get('ownerUID')}")
            raise PermissionError("Only document owner can enable training requirements")
        
        # Validate parameters
        if validity_days < 1 or validity_days > 3650:  # Max 10 years
            logger.error(f"Invalid validity_days: {validity_days}")
            raise ValidationError("Validity days must be between 1 and 3650")
        
        logger.info(f"Enabling training for document {document_uid} with validity_days: {validity_days}, quiz_required: {quiz_required}")
        
        # Enable training
        doc_training = DocumentTraining(document_uid=document_uid)
        logger.info("DocumentTraining instance created, calling enable_training...")
        success = doc_training.enable_training(
            validity_days=validity_days,
            quiz_required=quiz_required,
            instructions=instructions
        )
        
        logger.info(f"DocumentTraining.enable_training result: {success}")
        
        if not success:
            logger.error("DocumentTraining.enable_training returned False")
            raise BusinessRuleError("Failed to enable training for document")
        
        # Log event
        audit_trail.log_event(
            event_type="TRAINING_ENABLED",
            user=user.uid,  # Pass UID instead of full user object
            resource_uid=document_uid,
            resource_type="ControlledDocument",
            details={
                "validity_days": validity_days,
                "quiz_required": quiz_required,
                "doc_number": document.get('doc_number', 'Unknown')
            }
        )
        
        return {
            "success": True,
            "message": f"Training enabled for document {document.get('doc_number', 'Unknown')}",
            "document_uid": document_uid,
            "validity_days": validity_days
        }
        
    except (ResourceNotFoundError, ValidationError, PermissionError, BusinessRuleError) as e:
        raise
    except Exception as e:
        logger.error(f"Error enabling training for document {document_uid}: {e}")
        raise BusinessRuleError(f"Failed to enable training: {e}")

Parameters

Parameter Details

user: DocUser object representing the user enabling the training requirement. Must be the document owner or have MANAGE_ALL_TRAINING permission. Used for authorization checks and audit logging.

document_uid: String containing the unique identifier (UID) of the document for which training is being enabled. Must correspond to an existing ControlledDocument in the system.

validity_days: Integer specifying how many days the training remains valid before users need to retrain. Default is 365 days. Must be between 1 and 3650 (approximately 10 years). Determines the expiration period for completed training records.

quiz_required: Boolean flag indicating whether users must complete a quiz as part of the training. Default is False. When True, users cannot complete training without passing the associated quiz.

instructions: String containing custom instructions or guidance for users completing the training. Default is empty string. Can include information about what to focus on, prerequisites, or special requirements.

Return Value

Type: Dict[str, Any]

Returns a dictionary with keys: 'success' (bool, True if training was enabled), 'message' (str, human-readable confirmation message including document number), 'document_uid' (str, the UID of the document), and 'validity_days' (int, the validity period set). On error, raises one of: ResourceNotFoundError (document not found), PermissionError (user lacks authorization), ValidationError (invalid parameters), or BusinessRuleError (operation failed).

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 enable_document_training

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

# Enable training with default settings (365 days, no quiz)
result = enable_document_training(
    user=user,
    document_uid=document_uid
)
print(result['message'])  # Training enabled for document DOC-001

# Enable training with custom settings
result = enable_document_training(
    user=user,
    document_uid=document_uid,
    validity_days=180,
    quiz_required=True,
    instructions='Please review sections 3-5 carefully and complete the quiz with 80% or higher.'
)

if result['success']:
    print(f"Training enabled for {result['validity_days']} days")

Best Practices

• Always ensure the user object passed has been properly authenticated before calling this function
• The function is decorated with @transaction, so database operations will be rolled back on error
• Validity days should be set based on organizational compliance requirements (e.g., annual training = 365 days)
• The function enforces that only document owners or users with MANAGE_ALL_TRAINING permission can enable training
• All operations are logged to the audit trail for compliance tracking
• Handle the specific exception types (ResourceNotFoundError, PermissionError, ValidationError, BusinessRuleError) separately for better error reporting
• The function performs lazy import of document_controller to avoid circular dependencies
• Maximum validity period is capped at 10 years (3650 days) for data integrity
• Consider the quiz_required flag carefully - it affects user workflow and may require quiz content to be created separately

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function disable_document_training 85.0% 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

• function complete_user_training 81.9% 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 76.6% 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 complete_user_training_by_uid 73.8% similar

  Completes a user's training assignment for a controlled document by updating the training relationship status, recording completion date and score, and logging the event to the audit trail.

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

• function reset_document_training 73.3% 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