HH/EXPLANATION_REQUEST_DUAL_RECIPIENT_IMPLEMENTATION.md

Explanation Request - Dual Recipient Implementation

Overview

Modified the explanation request system to send requests to BOTH the staff member AND their manager simultaneously, rather than escalating to the manager only after the staff member fails to respond.

Changes Made

1. Backend API (apps/complaints/views.py)

request_explanation method (lines 1047-1412)

Before:

• Sent explanation request only to the staff member
• Manager would only receive request if staff didn't respond within SLA

After:

• Creates TWO separate explanation records:
  1. One for the staff member
  2. One for the manager (if exists)
• Sends emails to BOTH recipients simultaneously
• Each gets a unique token for their explanation submission
• Manager's email indicates it's a "Manager Copy" and mentions the staff member
• Returns detailed results showing both recipients
• Updated audit logs and complaint updates to reflect both recipients

resend_explanation method (lines 1414-1680)

Before:

• Resent only to staff member

After:

• Regenerates tokens for BOTH staff and manager
• Resends emails to both recipients
• Handles case where manager already submitted (skips them)
• Returns detailed results for both recipients

2. Celery Tasks (apps/complaints/tasks.py)

check_overdue_explanation_requests task (lines 1648-1801)

Before:

• Escalated from staff to manager when overdue
• Created new explanation request for manager

After:

• Since manager already has request, escalation goes UP the hierarchy
• Escalates to manager's manager (second-level manager)
• Supports multi-level escalation (Level 1: Staff, Level 2: Manager, Level 3: Manager's Manager)
• Updated escalation message to reflect this is an escalation
• Tracks escalation path in metadata

3. UI Template (templates/complaints/complaint_detail.html)

Explanation Request Section (lines 912-952)

Before:

• Showed only staff member as recipient
• Text: "Send a link to the assigned staff member..."

After:

• Shows BOTH staff and manager as recipients
• Updated text: "Send explanation requests to both the assigned staff member AND their manager simultaneously."
• Displays staff email with warning if not configured
• Displays manager email with warning if not configured
• Shows warning if no manager is assigned

Explanation Display Section (lines 769-827)

Before:

• Always showed "Explanation from Staff" or "Pending Explanation"

After:

• Shows "Explanation from Manager" / "Pending Manager Explanation" for manager requests
• Shows "Explanation from Staff" / "Pending Staff Explanation" for staff requests
• Shows manager's relationship to staff member ("Team member: [name]")
• Uses different icons for staff (bi-person) vs manager (bi-person-badge)

Data Model Changes

No database migrations required. The existing ComplaintExplanation model already supports this through:

• staff field - The recipient of the explanation request
• metadata field - JSON field storing:
  • is_manager_request - Boolean indicating if this is a manager copy
  • related_staff_id - ID of the original staff member
  • related_staff_name - Name of the original staff member
  • escalation_level - Track escalation hierarchy
  • original_staff_id/name - Track who the complaint is about

API Response Changes

POST /api/complaints/{id}/request_explanation/

Old Response:

{
  "success": true,
  "message": "Explanation request sent successfully",
  "explanation_id": "...",
  "recipient": "Staff Name",
  "explanation_link": "..."
}

New Response:

{
  "success": true,
  "message": "Explanation request sent successfully",
  "results": [
    {
      "recipient_type": "staff",
      "recipient": "Staff Name",
      "email": "staff@hospital.com",
      "explanation_id": "...",
      "sent": true
    },
    {
      "recipient_type": "manager",
      "recipient": "Manager Name",
      "email": "manager@hospital.com",
      "explanation_id": "...",
      "sent": true
    }
  ],
  "staff_explanation_id": "...",
  "manager_explanation_id": "..."
}

POST /api/complaints/{id}/resend_explanation/

Similar structure to request_explanation, showing results for both recipients.

Workflow

New Explanation Request Flow:

1. PX Admin clicks "Request Explanation"
   ↓
2. System creates TWO explanation records:
   - Explanation #1: For staff member
   - Explanation #2: For manager (if exists)
   ↓
3. System sends emails to BOTH:
   - Staff gets: "We have received a complaint that requires your explanation"
   - Manager gets: "You are receiving this as the manager of [Staff Name].
     A copy of the explanation request has been sent to [Staff Name]..."
   ↓
4. Both can submit their explanations independently
   ↓
5. If both submit → Both explanations are stored and visible
6. If neither submits by SLA deadline → Escalates to manager's manager

Escalation Flow (After Changes):

Level 0: Staff receives request (simultaneous with manager)
Level 1: Manager receives request (simultaneous with staff)
Level 2: If Level 1 (Manager) doesn't respond → Escalate to Manager's Manager
Level 3: If Level 2 doesn't respond → Escalate to next level (up to max_escalation_levels)

Benefits

1. Faster Response: Manager is aware of complaint immediately, not after SLA breach
2. Accountability: Both staff and manager are equally responsible for response
3. Better Context: Manager can provide oversight even if staff responds
4. Parallel Processing: Both can submit explanations independently
5. Audit Trail: Clear record of who was notified when

Testing Recommendations

1. Test with Manager Assigned:

   • Create complaint with staff who has report_to manager
   • Request explanation
   • Verify both staff and manager receive emails
   • Verify both can submit explanations

2. Test without Manager:

   • Create complaint with staff who has no report_to
   • Request explanation
   • Verify only staff receives email
   • Verify warning shows in UI

3. Test Escalation:

   • Let explanation go overdue
   • Verify escalation goes to manager's manager (not just manager)

4. Test Resend:

   • Request explanation
   • Click "Resend"
   • Verify both get new tokens/emails

Files Modified

1. apps/complaints/views.py - request_explanation and resend_explanation methods
2. apps/complaints/tasks.py - check_overdue_explanation_requests task
3. templates/complaints/complaint_detail.html - UI updates

Backward Compatibility

• Existing explanations work as before
• API endpoints remain at same URLs
• Staff without managers still work (just no manager copy sent)
• No database migrations required