🔍 Code Extractor

Creates a new controlled document in a document management system with versioning, audit trails, and optional initial content.

Purpose

This function serves as the primary entry point for creating controlled documents in the CDocs system. It handles document creation with full lifecycle management including: generating unique identifiers, establishing relationships in a graph database (Neo4j), creating initial document versions, logging audit events, and sending notifications. The function enforces permissions, validates inputs, and ensures transactional integrity through decorators.

Source Code

def create_document(
    user: DocUser,
    title: str,
    doc_type: str,
    department: str,
    status: str = 'DRAFT',
    doc_text: str = '',
    doc_number: Optional[str] = None,
    revision: str = '1.0',
    effective_date: Optional[str] = None,
    review_date: Optional[str] = None,
    is_public: bool = False,
    metadata: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """Create a new controlled document."""
    try:
        logger = logging.getLogger('CDocs.controllers.document_controller')
        logger.info(f"Creating document: {title}, Type: {doc_type}")
        
        # Import schema constants
        from CDocs.db.schema_manager import NodeLabels, RelTypes
        
        # Normalize document type to uppercase if it's a string
        if isinstance(doc_type, str):
            doc_type = doc_type.upper()
            
        # Prepare additional properties
        properties = {
            'UID': str(uuid.uuid4()),  # Generate UID here
            'status': status,
            'revision': revision,
            'isPublic': is_public,
            'createdDate': datetime.now(),
            'modifiedDate': datetime.now(),
            'title': title,
            'docType': doc_type,
            'department': department,
        }
        
        # Set creator and owner information
        if hasattr(user, 'UID'):
            properties['creatorUID'] = user.uid
            properties['ownerUID'] = user.uid
            
        if hasattr(user, 'name'):
            properties['creatorName'] = user.name
            properties['ownerName'] = user.name
        
        # Add doc_number if provided, otherwise it will be generated later
        if doc_number:
            properties['docNumber'] = doc_number
        else:
            # Generate a document number
            try:
                from ..config import settings
                if hasattr(settings, 'generate_document_number'):
                    properties['docNumber'] = settings.generate_document_number(doc_type, department)
                else:
                    # Simple fallback document number generation
                    prefix = doc_type[:3] if doc_type else "DOC"
                    dept_code = department[:3] if department else "GEN"
                    import random
                    properties['docNumber'] = f"{prefix}-{dept_code}-{random.randint(1000, 9999)}"
            except Exception as e:
                logger.warning(f"Error generating document number: {e}")
                # Simple fallback
                import random
                properties['docNumber'] = f"DOC-{random.randint(10000, 99999)}"
            
        # Add dates if provided
        if effective_date:
            properties['effectiveDate'] = effective_date
            
        if review_date:
            properties['reviewDate'] = review_date
            
        # Add metadata if provided
        if metadata:
            properties['metadata'] = metadata

        # Create the document node
        logger.debug(f"Creating document node with properties: {properties}")
        doc_data = db.create_node(NodeLabels.CONTROLLED_DOCUMENT, properties)
        
        if not doc_data:
            raise BusinessRuleError("Failed to create document in database")
            
        # Find CDocs root node and create relationship
        cdocs_result = db.run_query("MATCH (c:CDocs) RETURN c.UID as uid LIMIT 1")
        if cdocs_result and 'uid' in cdocs_result[0]:
            cdocs_uid = cdocs_result[0]['uid']
            
            # Create relationship between CDocs root and document
            db.create_relationship(
                cdocs_uid,
                doc_data['UID'],
                RelTypes.HAS_DOCUMENT  # Now we know this is defined in RelTypes
            )
            logger.debug(f"Created relationship from CDocs root to document: {doc_data['UID']}")
        else:
            logger.warning("CDocs root node not found. Document created without relationship.")
        
        # Now create a document object properly with the node data (not just the UID)
        document = ControlledDocument(doc_data)
        
        # If document content is provided, create an initial version
        if doc_text:
            try:
                # Create version properties
                version_props = {
                    'UID': str(uuid.uuid4()),  # Generate UID here
                    'versionNumber': revision,
                    'content': doc_text,
                    'status': status,
                    'createdDate': datetime.now(),
                    'comment': 'Initial version'
                }
                
                # Add creator info if available
                if hasattr(user, 'UID'):
                    version_props['creatorUID'] = user.uid
                    
                if hasattr(user, 'name'):
                    version_props['creatorName'] = user.name
                
                # Create the version node
                version_data = db.create_node(NodeLabels.DOCUMENT_VERSION, version_props)
                
                if version_data:
                    # Create relationship from document to version
                    db.create_relationship(
                        doc_data['UID'],
                        version_data['UID'],
                        RelTypes.HAS_VERSION
                    )
                    
                    # Create relationship for current version
                    db.create_relationship(
                        doc_data['UID'],
                        version_data['UID'],
                        RelTypes.CURRENT_VERSION
                    )
                    
                    # Update document with current version UID
                    db.update_node(
                        doc_data['UID'],
                        {'currentVersionUID': version_data['UID']}
                    )
                    
                    logger.debug(f"Created initial version for document: {doc_data['UID']}")
            except Exception as e:
                logger.error(f"Error creating initial version: {e}")
                # Continue anyway, document created without initial version
        
        # Log document creation event
        audit_trail.log_document_lifecycle_event(
            event_type="DOCUMENT_CREATED",
            user=user,
            document_uid=document.uid,
            details={"title": title, "doc_type": doc_type, "department": department}
        )
        
        # Send notification if configured
        notifications.notify_document_update(document, "DOCUMENT_CREATED")
        
        # Return result with document information
        return {
            "success": True,
            "document": document.to_dict(),
            "message": f"Document {document.doc_number} created successfully"
        }
        
    except Exception as e:
        logger.error(f"Error creating document: {e}")
        import traceback
        logger.error(f"Traceback: {traceback.format_exc()}")
        raise BusinessRuleError(f"Failed to create document: {e}")

Parameters

Parameter Details

user: DocUser object representing the authenticated user creating the document. Must have UID and name attributes. Used for setting creator/owner information and permission checks.

title: String containing the document title. Required field that identifies the document.

doc_type: String specifying the document type (e.g., 'SOP', 'POLICY', 'PROCEDURE'). Will be normalized to uppercase. Used for document categorization and number generation.

department: String identifying the department or organizational unit owning the document. Used for document organization and number generation.

status: String representing the document lifecycle status. Defaults to 'DRAFT'. Common values include DRAFT, IN_REVIEW, APPROVED, PUBLISHED, EFFECTIVE, ARCHIVED, OBSOLETE.

doc_text: String containing the initial document content/body. If provided, creates an initial document version. Empty string by default.

doc_number: Optional string for manually specifying the document number. If None, a document number is auto-generated using doc_type and department codes.

revision: String representing the document revision number. Defaults to '1.0'. Used for version tracking.

effective_date: Optional string (ISO format recommended) specifying when the document becomes effective. Stored as document property.

review_date: Optional string (ISO format recommended) specifying when the document should be reviewed next. Used for compliance tracking.

is_public: Boolean flag indicating if the document is publicly accessible. Defaults to False for controlled access.

metadata: Optional dictionary containing additional custom metadata key-value pairs to be stored with the document.

Return Value

Type: Dict[str, Any]

Returns a dictionary with three keys: 'success' (boolean indicating operation success), 'document' (dictionary representation of the created ControlledDocument object including UID, doc_number, title, status, and all properties), and 'message' (string with success message including the generated document number). On error, raises BusinessRuleError exception.

Dependencies

• logging
• uuid
• os
• tempfile
• typing
• datetime
• io
• panel
• shutil
• traceback
• random

Required Imports

import logging
import uuid
from datetime import datetime
from typing import Dict, Any, Optional
from CDocs import db
from CDocs.config import settings
from CDocs.models.document import ControlledDocument
from CDocs.models.user_extensions import DocUser
from CDocs.utils import notifications
from CDocs.utils import audit_trail
from CDocs.db.schema_manager import NodeLabels, RelTypes
from CDocs.controllers import require_permission, log_controller_action, transaction
from CDocs.controllers import BusinessRuleError

Conditional/Optional Imports

These imports are only needed under specific conditions:

from CDocs.db.schema_manager import NodeLabels, RelTypes

from ..config import settings

import random

Usage Example

from CDocs.models.user_extensions import DocUser
from CDocs.controllers.document_controller import create_document
from datetime import datetime, timedelta

# Create user object
user = DocUser({'UID': 'user-123', 'name': 'John Doe'})

# Create a simple document
result = create_document(
    user=user,
    title='Quality Management Procedure',
    doc_type='SOP',
    department='Quality',
    status='DRAFT'
)

print(f"Document created: {result['document']['docNumber']}")
print(f"Document UID: {result['document']['UID']}")

# Create document with full options
result = create_document(
    user=user,
    title='Safety Protocol',
    doc_type='POLICY',
    department='Safety',
    status='DRAFT',
    doc_text='This is the initial content of the safety protocol...',
    doc_number='POL-SAF-2024-001',
    revision='1.0',
    effective_date=(datetime.now() + timedelta(days=30)).isoformat(),
    review_date=(datetime.now() + timedelta(days=365)).isoformat(),
    is_public=False,
    metadata={'priority': 'high', 'category': 'safety', 'tags': ['critical', 'compliance']}
)

if result['success']:
    doc = result['document']
    print(f"Created: {doc['title']} ({doc['docNumber']})")
    print(f"Status: {doc['status']}, Revision: {doc['revision']}")

Best Practices

• Always ensure the user object has valid UID and name attributes before calling this function
• The function is decorated with @require_permission('CREATE_DOCUMENT'), so ensure proper permission setup
• The @transaction decorator ensures database operations are atomic - do not wrap in additional transactions
• Document numbers are auto-generated if not provided; provide custom doc_number only when following specific numbering schemes
• Use ISO format strings for effective_date and review_date for consistency
• The function creates an initial document version only if doc_text is provided; for empty documents, versions must be added separately
• Handle BusinessRuleError exceptions which may be raised on database failures or validation errors
• The function logs extensively - ensure logging is properly configured for debugging
• CDocs root node must exist in the database before calling this function
• Document type (doc_type) is normalized to uppercase automatically
• The function creates multiple database relationships (HAS_DOCUMENT, HAS_VERSION, CURRENT_VERSION) - ensure schema is properly initialized
• Audit events and notifications are sent asynchronously - configure these systems before use
• Metadata dictionary can contain any JSON-serializable values for flexible document properties

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function create_document_legacy 94.0% similar

  Creates a new controlled document in a document management system with versioning, audit trails, and notifications. Generates document nodes in a graph database with relationships to users and versions.

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

• function create_controlled_document 82.4% similar

  Creates a new controlled document node in a graph database with metadata, establishes relationships with the CDocs root node, and returns a ControlledDocument instance.

  From: /tf/active/vicechatdev/CDocs/FC_sync.py

• function create_document_v3 80.7% 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 create_document_v4 78.1% similar

  Creates a new controlled document in the CDocs system with specified metadata, content, and properties, returning a status dictionary with the created document details.

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

• function create_document_v2 70.7% similar

  Creates a new version of a controlled document by generating version metadata, storing the file in FileCloud, updating the document's revision number, and creating an audit trail entry.

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