🔍 Code Extractor

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

Purpose

This function fetches review cycle data from a document management system, allowing callers to retrieve comprehensive information about a review process including reviewer assignments, status, dates, and optionally the document being reviewed and any comments made during the review. It's designed for document review workflow management where users need to track and display review progress, decisions, and feedback.

Source Code

def get_review(review_uid, include_document=False, include_comments=False):
    """
    Get a specific review cycle by UID
    
    Parameters
    ----------
    review_uid : str
        The UID of the review cycle to retrieve
    include_document : bool, optional
        Whether to include the associated document details
    include_comments : bool, optional
        Whether to include review comments
    
    Returns
    -------
    dict
        Review cycle data with additional details based on include parameters
    
    Raises
    ------
    ResourceNotFoundError
        If the review cycle is not found
    PermissionError
        If the user doesn't have permission to view the review
    """
    # This is a placeholder implementation
    # In a real implementation, this would query the database
    
    # For now, return dummy data for testing
    review_data = {
        'uid': review_uid,
        'status': 'IN_PROGRESS',
        'review_type': 'FORMAL',
        'initiated_date': '2025-01-15T14:30:00',
        'due_date': '2025-02-15T14:30:00',
        'initiated_by_name': 'John Smith',
        'instructions': 'Please review the document carefully for technical accuracy and compliance with standards.',
        'reviewer_assignments': [
            {
                'reviewer_uid': '123456',
                'reviewer_name': 'Alice Johnson',
                'role': 'SME',
                'status': 'COMPLETED',
                'decision': 'APPROVED',
                'assigned_date': '2025-01-15T14:30:00',
                'decision_date': '2025-01-20T10:15:00'
            },
            {
                'reviewer_uid': '789012',
                'reviewer_name': 'Bob Williams',
                'role': 'COMPLIANCE',
                'status': 'PENDING',
                'assigned_date': '2025-01-15T14:30:00'
            }
        ]
    }
    
    # Add document data if requested
    if include_document:
        review_data['document'] = {
            'uid': 'doc-12345',
            'doc_number': 'DOC-2025-001',
            'title': 'Sample Document for Review',
            'revision': 'A',
            'doc_type': 'SOP',
            'department': 'Engineering',
            'status': 'IN_REVIEW'
        }
    
    # Add comments if requested
    if include_comments:
        review_data['comments'] = [
            {
                'uid': 'comment-123',
                'user_name': 'Alice Johnson',
                'timestamp': '2025-01-20T10:00:00',
                'text': 'Section 3.2 needs more detail on safety procedures.',
                'section': 'Section 3.2'
            },
            {
                'uid': 'comment-456',
                'user_name': 'John Smith',
                'timestamp': '2025-01-18T09:30:00',
                'text': 'Overall the document is well structured, but there are a few areas that need clarification.',
                'section': 'General'
            }
        ]
    
    return review_data

Parameters

Parameter Details

review_uid: String identifier uniquely identifying the review cycle to retrieve. This is the primary key used to look up the review in the database. Expected format is a string UID (e.g., 'review-12345').

include_document: Boolean flag (default: False) that controls whether the associated document details should be included in the response. When True, adds a 'document' key to the returned dictionary containing document metadata like UID, document number, title, revision, type, department, and status.

include_comments: Boolean flag (default: False) that controls whether review comments should be included in the response. When True, adds a 'comments' key to the returned dictionary containing an array of comment objects with user names, timestamps, text content, and section references.

Return Value

Returns a dictionary containing review cycle data. The base structure always includes: 'uid' (review identifier), 'status' (current review status like 'IN_PROGRESS'), 'review_type' (e.g., 'FORMAL'), 'initiated_date' (ISO 8601 timestamp), 'due_date' (ISO 8601 timestamp), 'initiated_by_name' (string), 'instructions' (string), and 'reviewer_assignments' (list of dictionaries with reviewer details including UID, name, role, status, decision, and dates). If include_document=True, adds 'document' dictionary with document metadata. If include_comments=True, adds 'comments' list with comment objects. Returns None or raises exceptions if review not found or permission denied.

Dependencies

• CDocs
• logging
• uuid
• os
• typing
• datetime
• traceback

Required Imports

from CDocs import db
from CDocs.config import settings
from CDocs.config import permissions
from CDocs.models.document import ControlledDocument
from CDocs.models.document import DocumentVersion
from CDocs.models.review import ReviewCycle
from CDocs.models.review import ReviewComment
from CDocs.models.review import ReviewerAssignment
from CDocs.models.user_extensions import DocUser
from CDocs.utils import audit_trail
from CDocs.utils import notifications
from CDocs.controllers import require_permission
from CDocs.controllers import log_controller_action
from CDocs.controllers import transaction
from CDocs.controllers import PermissionError
from CDocs.controllers import ResourceNotFoundError
from CDocs.controllers import ValidationError
from CDocs.controllers import BusinessRuleError
from CDocs.controllers import IntegrationError
from CDocs.controllers.document_controller import get_document
from CDocs.controllers.document_controller import update_document
from CDocs.controllers.share_controller import manage_document_permissions
from CDocs.controllers.share_controller import update_reviewer_permissions
from CDocs.db import db_operations as db
import logging
import uuid
import os
from typing import Dict, List, Any, Optional, Union, Set
from datetime import datetime, timedelta
import traceback

Usage Example

# Basic usage - get review cycle only
review = get_review('review-abc123')
print(f"Review status: {review['status']}")
print(f"Reviewers: {len(review['reviewer_assignments'])}")

# Get review with document details
review_with_doc = get_review('review-abc123', include_document=True)
print(f"Document: {review_with_doc['document']['title']}")
print(f"Document number: {review_with_doc['document']['doc_number']}")

# Get review with all details
full_review = get_review('review-abc123', include_document=True, include_comments=True)
print(f"Comments count: {len(full_review['comments'])}")
for comment in full_review['comments']:
    print(f"{comment['user_name']}: {comment['text']}")

# Handle exceptions
try:
    review = get_review('invalid-uid')
except ResourceNotFoundError:
    print('Review not found')
except PermissionError:
    print('Access denied')

Best Practices

• Always handle ResourceNotFoundError and PermissionError exceptions when calling this function
• Use include_document and include_comments flags judiciously to avoid unnecessary data retrieval and improve performance
• Validate the review_uid parameter before calling to ensure it's a valid string identifier
• Consider caching review data if it will be accessed multiple times in a short period
• Check user permissions before calling this function to provide better user experience
• The current implementation returns dummy data - in production, this would query a real database
• When integrating with a real database, ensure proper indexing on review_uid for performance
• Consider implementing pagination for comments if reviews can have many comments
• Log access to review cycles for audit trail purposes
• Validate that the user has appropriate permissions to view the review before returning sensitive data

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_review_cycle 85.5% similar

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

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

• function get_approval 82.7% similar

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

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

• function get_document_review_cycles 81.6% 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_document 75.5% 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

• function get_approval_cycle_v1 74.8% 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