🔍 Code Extractor

Retrieves comprehensive information about a review cycle, including optional reviewer assignments, comments, and associated document details.

Purpose

This function fetches detailed information about a specific review cycle in a document management system. It supports flexible data retrieval by allowing the caller to optionally include review comments and document metadata. The function handles complex relationships between ReviewCycle, DocumentVersion, and ControlledDocument entities, with fallback mechanisms to ensure document information is retrieved even when direct relationships fail. It's primarily used in document review workflows to display review status, assignments, and feedback.

Source Code

def get_review_cycle(review_uid: str, include_comments: bool = False, include_document: bool = False) -> Dict[str, Any]:
    """
    Get detailed information about a review cycle.
    
    Args:
        review_uid: UID of the review cycle
        include_comments: Whether to include review comments
        include_document: Whether to include document details
        
    Returns:
        Dictionary with review cycle information
    """
    try:
        # Get ReviewCycle instance
        from CDocs.models.review import ReviewCycle
        review_cycle = ReviewCycle(uid=review_uid)
        
        if not review_cycle:
            raise ResourceNotFoundError(f"Review cycle not found: {review_uid}")
            
        # Get basic review data
        result = review_cycle.to_dict()
        result['on_version'] = review_cycle.document_version_number
        
        # Add document information if requested
        if include_document:
            # First get the document version this review is for
            document_version_uid = review_cycle.document_version_uid
            
            if document_version_uid:
                from CDocs.models.document import DocumentVersion, ControlledDocument
                doc_version = DocumentVersion(uid=document_version_uid)
                
                # Now get the document from the version
                if doc_version and doc_version.document:
                    document = doc_version.document
                    result['document'] = {
                        'uid': document.uid,
                        'doc_number': document.doc_number,
                        'title': document.title,
                        'department': document.department,
                        'status': document.status,
                        'doc_type': document.doc_type,
                        'revision': doc_version.version_number
                    }
                    # Store document_uid for use elsewhere
                    result['document_uid'] = document.uid
            
            # Fallback if we couldn't get the document through normal relationships
            if 'document' not in result:
                # Try to find the document directly from the database
                from CDocs import db
                doc_query = """
                MATCH (d:ControlledDocument)-[:HAS_VERSION]->(v:DocumentVersion)<-[:FOR_REVIEW]-(r:ReviewCycle)
                WHERE r.UID = $review_uid
                RETURN d.UID as doc_uid, d.docNumber as doc_number, d.title as title
                LIMIT 1
                """
                doc_result = db.run_query(doc_query, {"review_uid": review_uid})
                
                if doc_result and doc_result[0].get('doc_uid'):
                    result['document'] = {
                        'uid': doc_result[0].get('doc_uid'),
                        'doc_number': doc_result[0].get('doc_number'),
                        'title': doc_result[0].get('title')
                    }
                    # Store document_uid for use elsewhere
                    result['document_uid'] = doc_result[0].get('doc_uid')
        
        # Add reviewer assignments if they exist
        reviewer_assignments = review_cycle.get_reviewer_assignments()
        if reviewer_assignments:
            result['reviewer_assignments'] = [
                assignment.to_dict() for assignment in reviewer_assignments
            ]
        
        # Add comments if requested
        if include_comments:
            comments = review_cycle.comments
            if comments:
                result['comments'] = [
                    comment.to_dict() for comment in comments
                ]
                
        return result
        
    except Exception as e:
        logger.error(f"Error retrieving review cycle: {e}")
        logger.error(traceback.format_exc())
        raise BusinessRuleError(f"Failed to retrieve review cycle: {e}")

Parameters

Parameter Details

review_uid: Unique identifier (UID) string for the review cycle to retrieve. This is the primary key used to locate the specific review cycle in the database.

include_comments: Boolean flag (default: False) that determines whether to fetch and include all review comments associated with this review cycle. Set to True when displaying detailed review feedback.

include_document: Boolean flag (default: False) that determines whether to fetch and include detailed information about the document being reviewed. Set to True when context about the document (title, number, department, status, type, revision) is needed.

Return Value

Type: Dict[str, Any]

Returns a dictionary containing review cycle information. The base dictionary includes all fields from the ReviewCycle model's to_dict() method plus 'on_version' (document version number). If reviewer_assignments exist, includes 'reviewer_assignments' as a list of dictionaries. If include_comments is True, includes 'comments' as a list of comment dictionaries. If include_document is True, includes 'document' (dict with uid, doc_number, title, department, status, doc_type, revision) and 'document_uid' (string). Raises ResourceNotFoundError if review cycle not found, or BusinessRuleError for other failures.

Dependencies

• CDocs.models.review
• CDocs.models.document
• CDocs
• CDocs.controllers
• logging
• traceback

Required Imports

from typing import Dict, Any
import logging
import traceback
from CDocs.controllers import log_controller_action, ResourceNotFoundError, BusinessRuleError

Conditional/Optional Imports

These imports are only needed under specific conditions:

from CDocs.models.review import ReviewCycle

from CDocs.models.document import DocumentVersion, ControlledDocument

from CDocs import db

Usage Example

# Basic usage - get review cycle without extras
review_info = get_review_cycle('review-uid-12345')
print(f"Review on version: {review_info['on_version']}")

# Get review with comments
review_with_comments = get_review_cycle(
    review_uid='review-uid-12345',
    include_comments=True
)
for comment in review_with_comments.get('comments', []):
    print(f"Comment: {comment['text']}")

# Get complete review information including document details
full_review = get_review_cycle(
    review_uid='review-uid-12345',
    include_comments=True,
    include_document=True
)
print(f"Document: {full_review['document']['doc_number']} - {full_review['document']['title']}")
print(f"Reviewers: {len(full_review.get('reviewer_assignments', []))}")
print(f"Comments: {len(full_review.get('comments', []))}")

Best Practices

• Always wrap calls in try-except blocks to handle ResourceNotFoundError and BusinessRuleError exceptions
• Use include_comments=True only when comments are actually needed to avoid unnecessary database queries
• Use include_document=True only when document context is required to optimize performance
• The function has a fallback mechanism for document retrieval using direct database queries, which ensures robustness but may indicate relationship issues in the data model
• Check for existence of optional keys ('comments', 'reviewer_assignments', 'document') in the returned dictionary before accessing them
• The function is decorated with log_controller_action, so all calls are automatically logged for audit purposes
• Ensure the review_uid is valid before calling to avoid unnecessary exception handling overhead

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_review_cycles 86.0% similar

  Retrieves all review cycles associated with a specific document, with optional filtering for active cycles only.

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

• function get_review 85.5% similar

  Retrieves a specific review cycle by its unique identifier (UID) with optional inclusion of associated document details and review comments.

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

• function get_approval_cycle 79.3% similar

  Retrieves detailed information about an approval cycle by its UID, with optional inclusion of comments and associated document details.

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

• function get_approval_cycle_v1 72.9% similar

  Retrieves an approval cycle by its unique identifier (UID) and optionally includes associated comments and document information.

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

• function notify_review 71.6% similar

  Sends review notifications to specified reviewers for a document review cycle, supporting multiple notification types (requested, reminder, overdue, completed).

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