🔍 Code Extractor

Logs a document lifecycle event to an audit trail by delegating to a generic log_event function with document-specific parameters.

Purpose

This function serves as a specialized wrapper for logging audit events related to controlled document lifecycle operations. It simplifies the logging process by pre-configuring the resource_type as 'ControlledDocument' and accepting document-specific parameters. This is used to track document creation, modification, approval, archival, and other lifecycle events for compliance and audit purposes.

Source Code

def log_document_lifecycle_event(event_type: str,
                               user: Union[DocUser, str],
                               document_uid: str,
                               details: Optional[Dict[str, Any]] = None) -> Optional[str]:
    """
    Log a document lifecycle event.
    
    Args:
        event_type: Type of event from EVENT_TYPES
        user: User who performed the action or their UID
        document_uid: UID of document
        details: Additional details about the event
        
    Returns:
        UID of the created audit event or None if creation failed
    """
    return log_event(
        event_type=event_type,
        user=user,
        resource_uid=document_uid,
        resource_type='ControlledDocument',
        details=details
    )

Parameters

Parameter Details

event_type: A string representing the type of lifecycle event being logged. Must be a valid value from EVENT_TYPES (e.g., 'created', 'updated', 'approved', 'archived'). This categorizes the audit event.

user: The user who performed the action. Can be either a DocUser object (user model instance) or a string containing the user's UID. This identifies who triggered the document lifecycle event.

document_uid: A string containing the unique identifier (UID) of the controlled document that the event relates to. This links the audit event to a specific document.

details: An optional dictionary containing additional contextual information about the event. Can include any key-value pairs relevant to the specific event type (e.g., field changes, approval comments, version numbers). Defaults to None if not provided.

Return Value

Type: Optional[str]

Returns an Optional[str] which is either the UID (unique identifier) of the newly created audit event record as a string if the logging was successful, or None if the audit event creation failed for any reason (e.g., database error, validation failure).

Dependencies

• logging
• uuid
• typing
• datetime
• json
• CDocs

Required Imports

from typing import Dict, Any, Optional, Union
from CDocs.models.user_extensions import DocUser

Usage Example

from CDocs.models.user_extensions import DocUser
from typing import Dict, Any

# Example 1: Log document creation with user object
user = DocUser(uid='user123', username='john.doe')
document_uid = 'doc-456'
event_uid = log_document_lifecycle_event(
    event_type='created',
    user=user,
    document_uid=document_uid,
    details={'version': '1.0', 'template': 'SOP'}
)
if event_uid:
    print(f'Audit event created: {event_uid}')

# Example 2: Log document approval with user UID string
event_uid = log_document_lifecycle_event(
    event_type='approved',
    user='user789',
    document_uid='doc-456',
    details={
        'approver_role': 'Quality Manager',
        'approval_date': '2024-01-15',
        'comments': 'Approved with minor revisions'
    }
)

# Example 3: Log simple event without details
event_uid = log_document_lifecycle_event(
    event_type='viewed',
    user='user123',
    document_uid='doc-456'
)

Best Practices

• Always provide valid event_type values from the EVENT_TYPES constant to ensure consistency in audit logs
• Include meaningful details in the details parameter to provide context for future audits and compliance reviews
• Check the return value to verify that the audit event was successfully created before proceeding with critical operations
• Use DocUser objects when available rather than string UIDs for better type safety and validation
• Ensure the document_uid exists in the database before logging events to maintain referential integrity
• Consider wrapping calls in try-except blocks if audit logging failures should not interrupt the main workflow
• Use consistent detail dictionary keys across similar event types for easier querying and reporting

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function log_version_event 81.7% similar

  A convenience wrapper function that logs audit events specifically for document version operations by delegating to a generic log_event function with the resource_type fixed as 'DocumentVersion'.

  From: /tf/active/vicechatdev/CDocs/utils/audit_trail.py

• function log_event 76.0% similar

  Creates and persists an audit trail event in a Neo4j graph database, linking it to users, resources, and an audit trail node with comprehensive event metadata.

  From: /tf/active/vicechatdev/CDocs/utils/audit_trail.py

• function log_review_event 75.3% similar

  A convenience wrapper function that logs audit events specifically for review cycle operations by delegating to a generic log_event function with the resource_type pre-set to 'ReviewCycle'.

  From: /tf/active/vicechatdev/CDocs/utils/audit_trail.py

• function log_training_event 74.4% similar

  A wrapper function that logs training-related events by delegating to a generic log_event function with pre-configured resource type.

  From: /tf/active/vicechatdev/CDocs/utils/audit_trail.py

• function log_approval_event 73.7% similar

  A convenience wrapper function that logs approval-related events by delegating to a generic log_event function with the resource_type fixed as 'Approval'.

  From: /tf/active/vicechatdev/CDocs/utils/audit_trail.py