🔍 Code Extractor

Retrieves a user's training dashboard data by querying Neo4j for required and completed training records associated with controlled documents.

Purpose

This function provides a comprehensive view of a user's training status by fetching both pending/in-progress training requirements and completed training records from a Neo4j graph database. It returns structured data suitable for displaying a training dashboard UI, including document details, dates, status, and summary statistics. The function handles Neo4j DateTime conversions and provides error handling with fallback responses.

Source Code

def get_user_training_dashboard(user: DocUser) -> Dict[str, Any]:
    """
    Get user's training dashboard data including required and completed training.
    
    Args:
        user: User requesting training dashboard
        
    Returns:
        Dictionary with training data
    """
    try:
        from CDocs.models.training import UserTraining
        
        # Get user's required training (not yet completed)
        required_query = """
        MATCH (u:User {UID: $user_uid})-[r:REQUIRES_TRAINING]->(d:ControlledDocument)
        WHERE r.status IN ['REQUIRED', 'IN_PROGRESS']
        RETURN {
            uid: u.UID + '-' + d.UID,
            document: {
                uid: d.UID,
                title: d.title,
                doc_number: d.docNumber
            },
            expires_date: r.expires_date,
            assigned_date: r.assigned_date,
            status: r.status,
            assigned_by: r.assigned_by,
            validity_days: r.validity_days,
            user_uid: u.UID,
            document_uid: d.UID
        } as training
        ORDER BY r.expires_date ASC
        """
        
        required_training = []
        required_result = db.run_query(required_query, {"user_uid": user.uid})
        if required_result:
            required_training = [record["training"] for record in required_result]
        
        # Get user's completed training records
        completed_query = """
        MATCH (u:User {UID: $user_uid})-[r:REQUIRES_TRAINING]->(d:ControlledDocument)
        WHERE r.status = 'COMPLETED'
        RETURN {
            uid: u.UID + '-' + d.UID,
            document: {
                uid: d.UID,
                title: d.title,
                doc_number: d.docNumber
            },
            completed_date: r.completed_date,
            assigned_date: r.assigned_date,
            status: r.status,
            score: r.score,
            assigned_by: r.assigned_by,
            user_uid: u.UID,
            document_uid: d.UID
        } as training
        ORDER BY r.completed_date DESC
        """
        
        completed_training = []
        completed_result = db.run_query(completed_query, {"user_uid": user.uid})
        if completed_result:
            completed_training = [record["training"] for record in completed_result]
        
        # Convert Neo4j DateTime objects to ISO strings
        def convert_datetime(item):
            if isinstance(item, dict):
                for key, value in item.items():
                    if hasattr(value, 'iso_format'):  # Neo4j DateTime
                        item[key] = value.iso_format()
                    elif isinstance(value, dict):
                        convert_datetime(value)
            return item
        
        required_training = [convert_datetime(item) for item in required_training]
        completed_training = [convert_datetime(item) for item in completed_training]
        
        return {
            "success": True,
            "required_training": required_training,
            "completed_training": completed_training,
            "summary": {
                "required_count": len(required_training),
                "completed_count": len(completed_training),
                "total_count": len(required_training) + len(completed_training)
            }
        }
        
    except Exception as e:
        logger.error(f"Error getting user training dashboard: {e}")
        return {
            "success": False,
            "message": f"Failed to get training dashboard: {e}",
            "required_training": [],
            "completed_training": [],
            "summary": {
                "required_count": 0,
                "completed_count": 0,
                "total_count": 0
            }
        }

Parameters

Parameter Details

user: A DocUser object representing the user requesting their training dashboard. Must have a 'uid' attribute that corresponds to a User node in the Neo4j database. This UID is used to query the user's training relationships.

Return Value

Type: Dict[str, Any]

Returns a dictionary with keys: 'success' (bool indicating operation success), 'required_training' (list of training records with status REQUIRED or IN_PROGRESS, sorted by expiration date), 'completed_training' (list of completed training records sorted by completion date descending), 'summary' (dict with counts: required_count, completed_count, total_count), and 'message' (error message if success is False). Each training record includes document details (uid, title, doc_number), dates, status, and assignment information.

Dependencies

• CDocs.models.training
• CDocs.models.user_extensions
• CDocs.db.db_operations
• CDocs.controllers
• logging

Required Imports

from typing import Dict, Any
from CDocs.models.user_extensions import DocUser
from CDocs.db import db_operations as db
from CDocs.controllers import log_controller_action
import logging

Conditional/Optional Imports

These imports are only needed under specific conditions:

from CDocs.models.training import UserTraining

Usage Example

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

# Assume user object is already authenticated and retrieved
user = DocUser(uid='user-123', name='John Doe')

# Get training dashboard
dashboard_data = get_user_training_dashboard(user)

if dashboard_data['success']:
    print(f"Required training: {dashboard_data['summary']['required_count']}")
    print(f"Completed training: {dashboard_data['summary']['completed_count']}")
    
    # Display required training
    for training in dashboard_data['required_training']:
        print(f"Document: {training['document']['title']}")
        print(f"Status: {training['status']}")
        print(f"Expires: {training['expires_date']}")
    
    # Display completed training
    for training in dashboard_data['completed_training']:
        print(f"Document: {training['document']['title']}")
        print(f"Completed: {training['completed_date']}")
        print(f"Score: {training.get('score', 'N/A')}")
else:
    print(f"Error: {dashboard_data['message']}")

Best Practices

• Ensure the user object passed has a valid 'uid' attribute that exists in the Neo4j database
• The function handles exceptions gracefully and returns a structured response even on failure, so always check the 'success' field before processing results
• Neo4j DateTime objects are automatically converted to ISO format strings for JSON serialization
• The function is decorated with @log_controller_action, so ensure logging is properly configured
• Required training is sorted by expiration date (ascending) to prioritize urgent items
• Completed training is sorted by completion date (descending) to show recent completions first
• The function queries relationships with specific status values: 'REQUIRED', 'IN_PROGRESS', and 'COMPLETED' - ensure these match your database schema
• Consider implementing pagination if users have large numbers of training records to avoid performance issues

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_training_overview 80.4% similar

  Retrieves a comprehensive training overview for the admin panel, including training plans, active assignments, and recent completions from a Neo4j graph database.

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

• function get_document_training_info 72.2% 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 70.6% 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 get_training_assignment 70.4% 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

• class UserTraining 69.7% similar

  A model class representing a user's training status for a specific controlled document, managing training assignments, completion tracking, and expiration dates.

  From: /tf/active/vicechatdev/CDocs/models/training.py