HH/EXPLANATION_REQUEST_WORKFLOW_IMPLEMENTATION.md

Explanation Request Workflow Implementation

Overview

Modified the explanation request system with the following workflow:

1. Initial Request: Link sent to staff, informational notification to manager
2. Escalation: If staff doesn't respond within SLA, manager gets a link to respond
3. Manager Response: Manager can submit their perspective when escalated

Workflow Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                    EXPLANATION REQUEST FLOW                          │
└─────────────────────────────────────────────────────────────────────┘

    INITIAL REQUEST
         │
         ├──► Staff receives: Link to submit explanation
         │     (can respond immediately)
         │
         └──► Manager receives: Informational email only
               (no link - just notification)
                        │
                        │
         ┌──────────────┴──────────────┐
         │                             │
    [Staff responds]              [No response]
         │                             │
         ▼                             ▼
   Explanation saved         After SLA deadline
   System notifies              (e.g., 48 hours)
   assigned user                      │
                                       ▼
                              ESCALATION TRIGGERED
                                       │
                                       ▼
                              Manager receives:
                              Link to submit explanation
                              as escalation response
                                       │
                                       ▼
                              [Manager responds]
                                       │
                                       ▼
                              Manager explanation saved
                              Linked to staff explanation

Changes Made

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

request_explanation method

Behavior:

• Creates ONE explanation record (for staff only)
• Sends link to staff member
• Sends informational email to manager (no link, no token)

Staff Email:

• Subject: "Explanation Request - Complaint #..."
• Contains: Link to submit explanation
• SLA deadline applies

Manager Email:

• Subject: "Staff Explanation Request Notification - Complaint #..."
• Contains: Complaint details for awareness
• States: "If no response is received within the SLA deadline, you will receive a follow-up request with a link to provide your perspective as the manager."
• NO link/token included

API Response:

{
  "success": true,
  "results": [
    {
      "recipient_type": "staff",
      "recipient": "Dr. Ahmed Smith",
      "sent": true,
      "explanation_id": "..."
    },
    {
      "recipient_type": "manager",
      "recipient": "Dr. Sarah Johnson",
      "sent": true,
      "informational_only": true,
      "note": "Manager will receive link if staff does not respond within SLA"
    }
  ],
  "staff_explanation_id": "...",
  "manager_notified": true
}

resend_explanation method

Behavior:

• Only resends to staff member (regenerates token)
• Manager informational email is NOT resent (they already received it)

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

check_overdue_explanation_requests task

Behavior:

• Runs every 15 minutes
• Finds staff explanations that are overdue (past SLA deadline)
• Creates NEW explanation record for manager with:
  • Unique token/link
  • Fresh SLA deadline
  • Escalation metadata
• Sends email to manager with link

Manager Escalation Email:

• Subject: "Explanation Request: Complaint #..."
• Contains: Link to submit explanation
• Message: "ESCALATED: [Staff Name] did not provide an explanation within the SLA deadline..."

Escalation Linkage:

staff_explanation.escalated_to_manager = manager_explanation
staff_explanation.escalated_at = now

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

Before Request:

• Shows staff as primary recipient (with link)
• Shows manager as "Notification Only"
• Note: "Will receive link only if staff doesn't respond within SLA"

After Request:

• Shows staff explanation status
• Shows manager escalation status (when applicable)
• Distinguishes between:
  • "Explanation from Staff" / "Pending Staff Explanation"
  • "Explanation from Manager (Escalated)" / "Pending Manager Explanation"

Data Model

Staff Explanation Record

{
    "id": "uuid",
    "staff": staff_id,
    "token": "secure_token_for_staff",
    "is_used": false/true,
    "sla_due_at": "2026-02-12T10:00:00Z",
    "escalated_to_manager": null or manager_explanation_id,
    "escalated_at": null or timestamp,
    "metadata": {
        "escalation_level": 0  // Staff is level 0
    }
}

Manager Explanation Record (Created on Escalation)

{
    "id": "uuid",
    "staff": manager_id,  // The manager
    "token": "secure_token_for_manager",
    "is_used": false/true,
    "sla_due_at": "2026-02-14T10:00:00Z",  // Fresh SLA
    "escalated_to_manager": null,  // Manager can also escalate up
    "metadata": {
        "escalated_from_explanation_id": "staff_explanation_id",
        "escalation_level": 1,
        "original_staff_id": "staff_id",
        "original_staff_name": "Staff Name",
        "is_escalation": True
    }
}

API Endpoints

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

Send initial explanation request to staff + informational notification to manager.

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

Resend explanation request to staff only (new token).

GET /complaints/{complaint_id}/explain/{token}/

Public form for submitting explanation (works for both staff and manager tokens).

Escalation Hierarchy

Level 0: Staff (initial request with link)
         ↓ (if no response within SLA)
Level 1: Manager (receives link via escalation)
         ↓ (if no response within SLA)
Level 2: Manager's Manager (receives link via escalation)
         ↓
Level 3+: Continue up hierarchy...

Benefits of This Approach

1. Staff Priority: Staff gets first chance to respond with direct link
2. Manager Awareness: Manager is informed immediately but not burdened with link
3. Clear Escalation Path: Manager only gets involved if staff doesn't respond
4. Audit Trail: Clear record of escalation from staff to manager
5. Fresh SLA: Manager gets their own SLA deadline when escalated
6. Parallel Visibility: Both explanations visible in complaint detail

Testing Scenarios

Scenario 1: Staff Responds Immediately

1. Request explanation → Staff gets link, Manager gets notification
2. Staff clicks link and submits explanation
3. System shows "Explanation from Staff" as submitted
4. Manager escalation never triggered

Scenario 2: Staff Doesn't Respond

1. Request explanation → Staff gets link, Manager gets notification
2. Staff doesn't respond within SLA (e.g., 48 hours)
3. Escalation task runs → Manager gets link
4. Manager submits explanation
5. System shows:
   • Staff: "Pending Explanation (Overdue)"
   • Manager: "Explanation from Manager (Escalated)"

Scenario 3: No Manager Assigned

1. Request explanation → Only staff gets email
2. System shows warning "No manager assigned"
3. If staff doesn't respond, no escalation possible

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 staff explanations work as before
• Manager escalation creates new explanation record
• No database migrations required
• API endpoints remain at same URLs