HH/docs/COMPLAINT_DUAL_ASSIGNMENT_FEATURE.md

Complaint Dual Assignment Feature

Overview

Complaints in PX360 support two separate assignment types to clearly distinguish between:

1. Case Manager (assigned_to) - The admin who will manage and follow up on the complaint
2. Staff Member (staff) - The specific staff member that the complaint is about

Assignment Types

1. Case Manager Assignment

Purpose: Assign an admin to manage the complaint lifecycle

Field: assigned_to (ForeignKey to User)

Who can assign: All admins (PX Admins, Hospital Admins, Department Managers)

Location: Sidebar → Assignments section → Case Manager

API Endpoint: POST /complaints/api/complaints/{id}/assign/

Features:

• Dropdown to select from assignable users
• Shows currently assigned manager (if any)
• Creates timeline entry on assignment
• Logs audit event
• Includes assignment timestamp

Workflow:

1. Admin opens complaint details
2. In sidebar "Assignments" section, selects case manager from dropdown
3. Clicks submit button
4. Complaint is updated with new assigned_to user
5. Timeline entry created: "Assigned to [Manager Name]"
6. Audit event logged: "complaint assigned"

2. Staff Member Assignment

Purpose: Assign the specific staff member that the complaint is about

Field: staff (ForeignKey to Staff)

Who can assign: PX Admins only (restricted permission)

Location:

• Sidebar → Assignments section → Staff Member
• Details tab → Staff Suggestions section
• Staff Selection Modal

API Endpoint: POST /complaints/api/complaints/{id}/assign_staff/

Features:

• AI-powered staff matching with confidence scores
• Manual staff search and selection
• Filter by department
• Shows current staff with edit option
• Supports assignment reasons
• Clears AI "needs_staff_review" flag on manual assignment

Workflow:

1. AI Assignment (automatic):

   • Complaint is created
   • AI analyzes complaint text
   • Extracts potential staff names
   • Matches against staff database
   • Assigns staff with highest confidence score

2. Manual Assignment from Suggestions:

   • PX Admin views complaint details
   • In Details tab → Staff Suggestions section
   • Views AI-suggested matches with confidence scores
   • Clicks "Select" button on desired staff
   • Staff is assigned immediately

3. Manual Assignment from Search:

   • PX Admin clicks "Assign Staff" button in sidebar
   • Staff Selection Modal opens
   • Filters by department or searches by name/job title
   • Selects staff from list
   • Provides optional reason for assignment
   • Clicks "Assign Selected Staff"
   • Staff is assigned

UI Layout

Sidebar Assignments Section

<!-- Card Header -->
Assignments [People icon]

<!-- Case Manager Assignment -->
Case Manager [Person Badge icon]
Admin who will manage this complaint
[Dropdown: Select manager...] [Assign button]

<!-- Staff Assignment (PX Admin only) -->
Staff Member [Person icon]
Staff member that complaint is about
[Display current staff] OR [Assign Staff button]

Details Tab - Staff Assignment

When staff is already assigned:

Staff Member
[Staff Name] [AI Matched badge]
[Job Title]
AI Extracted Names: ["Name1", "Name2"]
Primary: "Primary Name"
Confidence: 85%

When staff needs review:

Staff Suggestions [Needs Review badge]
AI Extracted Names: ["Name1", "Name2"]
Primary: "Primary Name"
[Match 1: Name A] [85% confidence] [Select button]
[Match 2: Name B] [70% confidence] [Select button]
[Search All Staff] button

Staff Selection Modal

Filter by Department: [Dropdown]
Search Staff: [Input]

[Staff List]
  └─ Department A
     ├─ Staff 1 [Radio]
     └─ Staff 2 [Radio]
  └─ Department B
     ├─ Staff 3 [Radio]
     └─ Staff 4 [Radio]

[Cancel] [Assign Selected Staff button]

API Endpoints

Assign Case Manager

Endpoint: POST /complaints/api/complaints/{id}/assign/

Request Body:

{
  "user_id": "uuid-of-manager-user"
}

Response:

{
  "message": "Complaint assigned successfully"
}

Assign Staff Member

Endpoint: POST /complaints/api/complaints/{id}/assign_staff/

Request Body:

{
  "staff_id": "uuid-of-staff",
  "reason": "Manual selection from hospital staff list"
}

Response:

{
  "message": "Staff assigned successfully",
  "staff_id": "uuid-of-staff",
  "staff_name": "Staff Full Name"
}

Get Hospital Staff

Endpoint: GET /complaints/api/complaints/{id}/hospital_staff/

Query Parameters:

• department_id (optional): Filter by department
• search (optional): Search by name or job title

Response:

{
  "hospital_id": "uuid",
  "hospital_name": "Hospital Name",
  "staff_count": 15,
  "staff": [
    {
      "id": "uuid",
      "name_en": "John Doe",
      "name_ar": "جون دو",
      "job_title": "Nurse",
      "specialization": "ICU",
      "department": "Emergency",
      "department_id": "uuid"
    }
  ]
}

Get Staff Suggestions

Endpoint: GET /complaints/api/complaints/{id}/staff_suggestions/

Response:

{
  "extracted_name": "John from nursing",
  "staff_matches": [
    {
      "id": "uuid",
      "name_en": "John Doe",
      "name_ar": "جون دو",
      "confidence": 0.85,
      "job_title": "Nurse",
      "specialization": "ICU",
      "department": "Emergency"
    }
  ],
  "current_staff_id": "uuid",
  "needs_staff_review": true,
  "staff_match_count": 3
}

Workflow Examples

Example 1: AI Auto-Assignment

1. New complaint submitted about "rude nurse named Sarah"
2. AI analyzes complaint text
3. AI extracts: "Sarah", "nurse"
4. System searches staff database
5. Matches found:
   • Sarah Johnson (ICU Nurse) - 92% confidence
   • Sarah Ahmed (ER Nurse) - 85% confidence
6. System automatically assigns: Sarah Johnson
7. Timeline entry: "Staff assigned to Sarah Johnson (AI Matched)"
8. Staff Sarah Johnson receives explanation request email

Example 2: Manual Assignment by PX Admin

1. Complaint created with AI match confidence: 65% (low)
2. System sets: needs_staff_review = true
3. PX Admin opens complaint details
4. Sees warning: "This complaint needs staff review"
5. Views AI suggestions:
   • Staff A - 65% confidence
   • Staff B - 60% confidence
6. Clicks "Search All Staff"
7. Opens Staff Selection Modal
8. Filters by "Emergency" department
9. Searches for "Ahmed"
10. Finds: Dr. Ahmed Al-Farsi (Emergency Physician)
11. Selects and assigns
12. Timeline entry: "Staff assigned to Dr. Ahmed Al-Farsi (Emergency Physician). Manual selection from hospital staff list"
13. Metadata updated: staff_manually_assigned = true

Example 3: Case Manager Assignment

1. Complaint assigned to Dr. Ahmed Al-Farsi
2. Department Manager opens complaint
3. In sidebar, selects Case Manager dropdown
4. Chooses: "Mohammed Hassan" (Patient Relations Manager)
5. Clicks assign
6. Timeline entry: "Assigned to Mohammed Hassan"
7. Mohammed receives notification email
8. Mohammed manages complaint resolution

Permissions

Assign Case Manager

• PX Admin: Can assign any admin to any complaint
• Hospital Admin: Can assign admins from their hospital
• Department Manager: Can assign admins from their department
• Other Users: Cannot assign (no permission)

Assign Staff Member

• PX Admin: Can assign any staff member (PX-wide)
• Hospital Admin: Cannot assign (restricted)
• Department Manager: Cannot assign (restricted)
• Other Users: Cannot assign (no permission)

Notifications

Case Manager Assignment

When a complaint is assigned to a case manager:

1. Email Notification: Sent to assigned manager

   • Subject: "Complaint Notification - #ID"
   • Includes: Complaint details, summary, link to complaint

2. Timeline Entry: Created

   • Type: "assignment"
   • Message: "Assigned to [Manager Name]"

3. Audit Log: Created

   • Event: "assignment"
   • Description: "Complaint assigned to [Manager Name]"

Staff Member Assignment

When a staff member is assigned:

1. Email Notification: Sent to request explanation

   • Subject: "Explanation Request - Complaint #ID"
   • Includes: Complaint details, explanation submission link
   • Only sent if staff has email address

2. Timeline Entry: Created

   • Type: "assignment"
   • Message: "Staff assigned to [Staff Name]"
   • Metadata: Includes assignment reason

3. Audit Log: Created

   • Event: "staff_assigned"
   • Description: "Staff [Staff Name] manually assigned to complaint by [User Name]"
   • Metadata: Includes old_staff_id, new_staff_id, reason

4. AI Metadata Updated:

   • needs_staff_review = false
   • staff_manually_assigned = true
   • staff_assigned_by = user_id
   • staff_assigned_at = timestamp
   • staff_assignment_reason = reason

Best Practices

For PX Admins

1. Review AI Suggestions First: Check AI-matched staff before manual assignment
2. Use High Confidence Matches: Accept matches > 80% confidence
3. Provide Assignment Reasons: Add reasons for manual assignments for audit trail
4. Monitor Low Confidence: Review complaints with needs_staff_review flag

For Case Managers

1. Own Your Complaints: When assigned, actively manage the complaint
2. Request Explanations: Use explanation request feature early in process
3. Follow Up Regularly: Check for staff responses and escalate if needed
4. Document Actions: Add notes and timeline entries

For Hospital Admins

1. Assign Appropriate Managers: Match complaint type to manager expertise
2. Monitor SLA Compliance: Watch for overdue complaints
3. Escalate When Needed: Use escalation feature for complex cases
4. Review Assignment Patterns: Analyze staff complaint trends

Troubleshooting

Issue: Can't see Staff Assignment

Cause: User is not PX Admin

Solution:

• Only PX Admins can assign staff members
• Contact PX Admin for staff assignment
• Request PX Admin role if needed

Issue: No staff in dropdown

Cause: No staff created or no staff in hospital

Solution:

• Check if staff records exist in hospital
• Import staff data if needed
• Use staff seed command: python manage.py seed_staff

Issue: AI match is wrong

Cause: AI misinterpreted complaint text

Solution:

• Use "Search All Staff" to manually find correct staff
• Assign manually with reason explaining correction
• Consider updating AI prompts for better matching

Issue: Can't find staff in search

Cause: Staff not in database or search criteria too specific

Solution:

• Check staff spelling variations
• Use broader search terms (first name only)
• Filter by department first to narrow results
• Verify staff is active (not terminated)

Future Enhancements

Potential Improvements

1. Staff Assignment to Hospital Admins: Extend permission to hospital admins
2. Bulk Assignment: Assign multiple complaints to same staff
3. Assignment Templates: Pre-defined assignment patterns based on department/category
4. Assignment Dashboard: Overview of all assignments and workload
5. Auto-Assignment Rules: Rule-based auto-assignment based on criteria
6. Assignment History: Track assignment changes over time
7. Performance Metrics: Track assignment effectiveness and resolution times
8. Staff Notification Preferences: Allow staff to set notification preferences

Related Features

• Explanation Request: Request explanation from assigned staff
• Escalation: Automatically escalate to manager/staff chain
• SLA Monitoring: Track response times against SLA deadlines
• Timeline Updates: Complete audit trail of all activities
• Notification System: Email notifications for all key events

Support

For questions or issues with the dual assignment feature:

1. Check documentation in /docs/ folder
2. Review API endpoints in API documentation
3. Contact PX360 support team
4. Submit issue requests through support channels