🔍 Code Extractor

Determines the next status for a controlled document based on an approval decision (APPROVED or REJECTED), transitioning documents through their lifecycle workflow.

Purpose

This function implements document status transition logic after an approval decision is made. It handles the workflow state machine for controlled documents, moving approved documents to APPROVED status and rejected documents back to DRAFT for corrections. It includes error handling to ensure documents default to DRAFT status if any issues occur during status determination.

Source Code

def get_status_after_approval(document_uid: str, approval_decision: str) -> str:
    """
    Determine the next document status after an approval decision.
    
    Args:
        document_uid: UID of the document
        approval_decision: Decision from the approval process (APPROVED, REJECTED, etc.)
        
    Returns:
        Next status code for the document
    """
    try:
        document = ControlledDocument(uid=document_uid)
        if not document:
            logger.error(f"Document not found: {document_uid}")
            return "DRAFT"
            
        current_status = document.status
        
        # If approved, move to APPROVED status
        if approval_decision == "APPROVED":
            if current_status == "IN_APPROVAL":
                return "APPROVED"
            elif current_status == "DRAFT":
                return "APPROVED"
                
        # If rejected, move back to DRAFT for corrections
        elif approval_decision == "REJECTED":
            return "DRAFT"
            
        # Default to keeping current status
        return current_status
        
    except Exception as e:
        logger.error(f"Error determining status after approval: {e}")
        return "DRAFT"

Parameters

Parameter Details

document_uid: Unique identifier (UID) string for the controlled document. This should be a valid UID that exists in the document management system. Used to retrieve the document object and its current status.

approval_decision: String representing the approval decision outcome. Expected values are 'APPROVED' (document passes approval), 'REJECTED' (document needs corrections), or other values which will maintain current status. Case-sensitive string matching is used.

Return Value

Type: str

Returns a string representing the next status code for the document. Possible return values include: 'APPROVED' (if decision is APPROVED and current status is IN_APPROVAL or DRAFT), 'DRAFT' (if decision is REJECTED or if document is not found or if an error occurs), or the current_status (if decision doesn't match known values). Always returns a valid status string, never None.

Dependencies

• logging
• CDocs.models.document
• CDocs.config.settings
• CDocs.db
• CDocs.models.document_status

Required Imports

import logging
from CDocs.models.document import ControlledDocument

Usage Example

import logging
from CDocs.models.document import ControlledDocument

# Setup logger
logger = logging.getLogger(__name__)

# Example 1: Approve a document in approval workflow
document_uid = "doc-12345-abcde"
approval_decision = "APPROVED"
next_status = get_status_after_approval(document_uid, approval_decision)
print(f"Document status after approval: {next_status}")  # Output: APPROVED

# Example 2: Reject a document
document_uid = "doc-67890-fghij"
approval_decision = "REJECTED"
next_status = get_status_after_approval(document_uid, approval_decision)
print(f"Document status after rejection: {next_status}")  # Output: DRAFT

# Example 3: Handle unknown decision
document_uid = "doc-11111-kkkkk"
approval_decision = "PENDING"
next_status = get_status_after_approval(document_uid, approval_decision)
print(f"Document maintains status: {next_status}")  # Output: current_status

Best Practices

• Always ensure the document_uid exists before calling this function to avoid unnecessary error logging
• The function uses defensive programming with try-except to always return a valid status, defaulting to DRAFT on errors
• Approval decisions are case-sensitive; use exact strings 'APPROVED' or 'REJECTED'
• The function logs errors but does not raise exceptions, making it safe for use in workflows without additional error handling
• Consider validating the approval_decision parameter before calling if you need stricter input validation
• The function assumes a logger instance is available in the module scope; ensure logging is properly configured
• This function only determines the next status but does not persist it; the caller is responsible for updating the document status in the database
• The function handles both IN_APPROVAL and DRAFT current statuses when approving, providing flexibility in workflow design

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function update_status_after_approval 86.8% similar

  Updates a controlled document's status after an approval workflow completes, determining the next status based on the approval decision and logging the change to the audit trail.

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

• function complete_approval_v1 75.5% similar

  Records a user's approval decision (APPROVED or REJECTED) for a document in an approval cycle, updating the approval status and document state accordingly.

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

• function get_next_status 67.1% similar

  Determines the next logical status in a document lifecycle workflow based on the current status, using either configured transitions or a predefined fallback flow.

  From: /tf/active/vicechatdev/CDocs/models/document_status.py

• function complete_approval 66.3% similar

  Completes an approval cycle by recording a user's approval decision (APPROVED, REJECTED, etc.) and managing the approval workflow, including sequential approver activation and final cycle completion.

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

• function close_approval_cycle_v1 65.1% similar

  Administratively closes an approval cycle by setting a final decision (APPROVED or REJECTED), updating the associated document status, and notifying relevant stakeholders.

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