🔍 Code Extractor

Updates properties of a controlled document including title, description, status, owner, and metadata, with special handling for status transitions that require format conversions or publishing workflows.

Purpose

This function serves as the primary interface for modifying document properties in a controlled document management system. It enforces business rules around status transitions, particularly when moving from editable to published states, ensures proper audit logging, validates ownership changes, and delegates to specialized publishing workflows when necessary. It's designed to maintain document integrity and compliance with document lifecycle management requirements.

Source Code

def update_document(
    user: DocUser,
    document_uid: str,
    title: Optional[str] = None,
    description: Optional[str] = None,
    status: Optional[str] = None,
    owner_uid: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """
    Update a document's properties, handling format transitions when status changes.
    
    Args:
        user: User making the update
        document_uid: UID of document to update
        title: New document title (optional)
        description: New document description (optional)
        status: New document status (optional)
        owner_uid: New document owner UID (optional)
        metadata: New document metadata (optional)
        
    Returns:
        Dictionary with update status
    """
    try:
        # Get document instance
        document = ControlledDocument(uid=document_uid)
        if not document:
            raise ResourceNotFoundError(f"Document not found: {document_uid}")
        
        # Store original values for audit
        original_values = {
            'title': document.title,
            'description': document.description,
            'status': document.status,
            'owner_uid': document.owner_uid
        }
        
        # Track what changed
        changes = {}
        
        # Update title if provided
        if title is not None and title != document.title:
            document.title = title
            changes['title'] = {'old': original_values['title'], 'new': title}
        
        # Update description if provided
        if description is not None and description != document.description:
            document.description = description
            changes['description'] = {'old': original_values['description'], 'new': description}
        
        # Handle status update with special consideration for format transitions
        if status is not None and status != document.status:
            current_status = document.status
            target_status = status.lower()
            
            # Check if the transition is valid
            if not document.can_transition_to(target_status):
                raise BusinessRuleError(f"Invalid status transition from {current_status} to {target_status}")
            
            # Check if we're transitioning from editable to non-editable status
            if is_editable_status(current_status) and is_published_status(target_status):
                # Status requires PDF publishing
                if target_status == STATUS_PUBLISHED:
                    # Call publish_document instead
                    result = publish_document(
                        user=user,
                        document_uid=document_uid,
                        publish_comment=metadata.get('comment', 'Status updated to Published') if metadata else None
                    )
                    return result
                else:
                    # For other non-editable statuses, check if PDF exists
                    current_version = document.current_version
                    if current_version and not current_version.pdf_file_path:
                        raise BusinessRuleError(f"Document must be published before changing to {target_status}")
            
            # For transitions that don't require special handling, update status normally
            document.status = target_status
            changes['status'] = {'old': current_status, 'new': target_status}
            
            # Log status change
            audit_trail.log_document_lifecycle_event(
                event_type="DOCUMENT_STATUS_CHANGED",
                user=user,
                document_uid=document_uid,
                details={
                    'old_status': current_status,
                    'new_status': target_status,
                    'comment': metadata.get('comment') if metadata else None
                }
            )
        
        # Update owner if provided
        if owner_uid is not None and owner_uid != document.owner_uid:
            # Check if new owner exists
            owner_exists = db.run_query(
                "MATCH (u:User {UID: $uid}) RETURN COUNT(u) > 0 as exists",
                {"uid": owner_uid}
            )
            
            if not owner_exists or not owner_exists[0].get('exists', False):
                raise ValidationError(f"User not found: {owner_uid}")
                
            # Update owner
            document.owner = owner_uid
            changes['owner_uid'] = {'old': original_values['owner_uid'], 'new': owner_uid}
        
        # Update metadata if provided
        if metadata:
            # Merge with existing metadata if any
            existing_metadata = getattr(document, 'metadata', {}) or {}
            updated_metadata = {**existing_metadata, **metadata}
            
            # Update in database
            db.update_node(document_uid, {'metadata': updated_metadata})
            changes['metadata'] = {'updated': True}
        
        # Notify about document update if significant changes were made
        if changes:
            notifications.notify_document_update(document, "DOCUMENT_UPDATED")
        
        # Return success response with changes
        return {
            "success": True,
            "message": "Document updated successfully",
            "document_uid": document_uid,
            "changes": changes
        }
        
    except (ResourceNotFoundError, ValidationError, PermissionError, BusinessRuleError) as e:
        # Re-raise known errors
        raise
    except Exception as e:
        logger.error(f"Error updating document: {e}")
        raise BusinessRuleError(f"Failed to update document: {e}")

Parameters

Parameter Details

user: DocUser object representing the authenticated user performing the update. Used for permission checks, audit logging, and notification purposes.

document_uid: Unique identifier (string) of the document to be updated. Must correspond to an existing ControlledDocument in the system.

title: Optional new title for the document (string). If provided and different from current title, the document title will be updated. Pass None to leave unchanged.

description: Optional new description for the document (string). If provided and different from current description, the document description will be updated. Pass None to leave unchanged.

status: Optional new status for the document (string). Must be a valid status value and transition. Special handling applies when transitioning from editable to published states. Common values include 'draft', 'in_review', 'published', 'archived'. Pass None to leave unchanged.

owner_uid: Optional UID (string) of the new document owner. Must correspond to an existing User in the system. Ownership transfer is validated before applying. Pass None to leave unchanged.

metadata: Optional dictionary containing additional metadata to merge with existing document metadata. Can include custom fields like 'comment' which is used in status change logging. Pass None to leave unchanged.

Return Value

Type: Dict[str, Any]

Returns a dictionary with keys: 'success' (boolean indicating operation success), 'message' (string describing the outcome), 'document_uid' (string echoing the updated document's UID), and 'changes' (dictionary detailing what changed, with each changed field containing 'old' and 'new' values or update indicators). If status transition triggers publishing, returns the result from publish_document function instead.

Dependencies

• logging
• uuid
• os
• tempfile
• typing
• datetime
• io
• panel
• shutil
• traceback
• CDocs
• config

Required Imports

from typing import Dict, List, Any, Optional, Union, BinaryIO, Tuple
from datetime import datetime, timedelta
from CDocs import db
from CDocs.config import settings, permissions
from CDocs.models.document import ControlledDocument, DocumentVersion
from CDocs.models.user_extensions import DocUser
from CDocs.utils import document_processor, notifications, audit_trail
from CDocs.db.schema_manager import NodeLabels, RelTypes
from CDocs.controllers import require_permission, log_controller_action, transaction, PermissionError, ResourceNotFoundError, ValidationError, BusinessRuleError, IntegrationError
from CDocs.models.document_status import is_editable_status, is_published_status, STATUS_PUBLISHED
import logging

Conditional/Optional Imports

These imports are only needed under specific conditions:

from CDocs.controllers.document_controller import publish_document

Usage Example

from CDocs.models.user_extensions import DocUser
from CDocs.controllers.document_controller import update_document

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

# Update document title and description
result = update_document(
    user=user,
    document_uid=document_uid,
    title='Updated Document Title',
    description='This document has been revised with new information',
    metadata={'comment': 'Updated per review feedback'}
)

if result['success']:
    print(f"Document updated: {result['changes']}")

# Change document status (may trigger publishing workflow)
status_result = update_document(
    user=user,
    document_uid=document_uid,
    status='published',
    metadata={'comment': 'Approved for publication'}
)

# Transfer document ownership
ownership_result = update_document(
    user=user,
    document_uid=document_uid,
    owner_uid='new_owner_uid_789'
)

Best Practices

• Always provide the authenticated user object for proper permission checking and audit logging
• Only pass parameters that need to be updated; use None for fields that should remain unchanged
• Be aware that changing status to 'published' from an editable state will trigger the publish_document workflow instead of direct status update
• Include a 'comment' in the metadata dictionary when changing status to provide context in audit logs
• Validate that the new owner_uid exists before calling this function to avoid validation errors
• Handle all exception types appropriately: ResourceNotFoundError, ValidationError, PermissionError, BusinessRuleError
• The function is decorated with transaction support, so database changes are atomic
• Check the 'changes' dictionary in the return value to see exactly what was modified
• Ensure the user has EDIT_DOCUMENT permission for the specified document_uid before calling
• When transitioning to non-editable statuses other than 'published', ensure a PDF version exists
• Use the function within a try-except block to handle potential business rule violations during status transitions

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function create_document_v2 71.8% similar

  Creates a new controlled document in a document management system with specified properties, type, department, and status.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function publish_document 67.6% similar

  Publishes an approved controlled document by converting it to PDF with signatures and audit trail, uploading to FileCloud, and updating the document status to PUBLISHED.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function set_current_version 66.1% similar

  Sets a specific version of a controlled document as the current/active version, updating the document's currentVersionUID property and logging the change.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function delete_document 65.6% similar

  Deletes a controlled document from the system with permission checks, status validation, and audit logging.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function get_document 64.3% similar

  Retrieves comprehensive details of a controlled document by its UID, with optional inclusion of version history, review cycles, and approval cycles.

  From: /tf/active/vicechatdev/document_controller_backup.py