HH/docs/SLA_TESTING_GUIDE.md

SLA Testing Guide

This guide provides comprehensive information for testing the Service Level Agreement (SLA) system, including the new second reminder feature.

Overview

The SLA system ensures complaints are resolved within specified timeframes by:

• First Reminder: Sent at a configurable time before the complaint is due
• Second Reminder (NEW): Sent closer to the due date if no action has been taken
• Escalation: Automatically escalates complaints if they remain overdue
• Thank You Email: Sent when a complaint is closed

System Components

1. Complaint Model (apps/complaints/models.py)

Key SLA-related fields:

• due_at: When the complaint is due
• reminder_sent_at: Timestamp when first reminder was sent
• second_reminder_sent_at: Timestamp when second reminder was sent (NEW)
• is_overdue: Boolean flag for overdue status
• escalated_at: Timestamp when escalation occurred
• metadata: JSON field storing escalation history

2. SLA Configuration (ComplaintSLAConfig)

Configurable per hospital, severity, and priority:

• sla_hours: Total SLA duration (e.g., 48 hours)
• reminder_hours_before: First reminder timing (e.g., 24 hours before due)
• second_reminder_enabled: Enable/disable second reminder (NEW)
• second_reminder_hours_before: Second reminder timing (e.g., 6 hours before due)
• thank_you_email_enabled: Enable thank you email on close

3. Escalation Rules (EscalationRule)

Multi-level escalation logic:

• Level 1: Department Manager (triggers when overdue)
• Level 2: Hospital Admin (triggers after first reminder + X hours)
• Level 3+: Configurable higher-level roles

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

• send_sla_reminders(): Runs hourly to check and send reminders
• check_overdue_complaints(): Runs hourly to flag overdue complaints
• escalate_after_reminder(): Runs after reminders to escalate if needed

Email Templates

First Reminder

• English: templates/complaints/emails/sla_reminder_en.txt
• Arabic: templates/complaints/emails/sla_reminder_ar.txt

Second Reminder (NEW)

• English: templates/complaints/emails/sla_second_reminder_en.txt
• Arabic: templates/complaints/emails/sla_second_reminder_ar.txt

Automated Testing

Run the Test Suite

# Run the comprehensive SLA test script
python test_sla_functionality.py

The test script:

1. Creates test hospital, department, user, and staff
2. Sets up SLA configuration with second reminder enabled
3. Creates escalation rules
4. Generates a test complaint with specific timing
5. Tests first reminder logic
6. Tests second reminder logic
7. Tests escalation logic
8. Displays complaint timeline

Test Output Analysis

The test output shows:

• ✓ Test data setup status
• ✓ SLA configuration details
• ✓ Escalation rules configured
• ✓ Complaint creation details
• Reminder timing calculations
• Current escalation status
• Timeline updates

Manual Testing

1. Configure SLA Settings

Via Admin Panel:

1. Login as admin
2. Navigate to: /admin/complaints/complaintslaconfig/add/
3. Configure for your hospital:

   Hospital: Your Hospital
   Severity: medium
   Priority: medium
   SLA Hours: 48
   Reminder Hours Before: 24
   Second Reminder Enabled: ✓
   Second Reminder Hours Before: 6
   Thank You Email Enabled: ✓
   Is Active: ✓
   

4. Save

Via API:

curl -X POST http://localhost:8000/api/complaints/sla-configs/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "hospital": "HOSPITAL_UUID",
    "severity": "medium",
    "priority": "medium",
    "sla_hours": 48,
    "reminder_hours_before": 24,
    "second_reminder_enabled": true,
    "second_reminder_hours_before": 6,
    "thank_you_email_enabled": true
  }'

2. Create Test Complaint

Create a complaint with specific timing to test reminders:

from datetime import timedelta
from django.utils import timezone
from apps.complaints.models import Complaint, ComplaintStatus

# Due in 26 hours (triggers first reminder at 24h, second at 6h)
complaint = Complaint.objects.create(
    title="SLA Test Complaint",
    description="Testing SLA reminders",
    hospital=hospital,
    department=department,
    status=ComplaintStatus.OPEN,
    priority='medium',
    severity='medium',
    due_at=timezone.now() + timedelta(hours=26),
    is_overdue=False
)

3. Trigger Reminders Manually

# Trigger reminder task
celery -A config worker -l info
celery -A config beat -l info

# Or trigger manually from Django shell
python manage.py shell

>>> from apps.complaints.tasks import send_sla_reminders
>>> result = send_sla_reminders.delay()
>>> print(result.get())

4. Monitor Email Sending

Check logs for email sending activity:

tail -f logs/celery.log | grep -i "sla reminder"
tail -f logs/django.log | grep -i "email"

5. Verify Timeline Updates

Check complaint timeline in admin panel or via API:

from apps.complaints.models import Complaint, ComplaintUpdate

complaint = Complaint.objects.get(id="COMPLAINT_UUID")
updates = complaint.updates.all().order_by('-created_at')

for update in updates:
    print(f"{update.update_type}: {update.message}")
    print(f"Metadata: {update.metadata}")

Testing Scenarios

Scenario 1: First Reminder Only

1. Create complaint due in 26 hours
2. Wait for or trigger first reminder (at 24 hours)
3. Verify email sent
4. Verify reminder_sent_at timestamp set
5. Check ComplaintUpdate created

Scenario 2: Second Reminder

1. Create complaint due in 26 hours
2. Wait for first reminder (at 24 hours)
3. Wait for second reminder (at 6 hours)
4. Verify second reminder email sent
5. Verify second_reminder_sent_at timestamp set
6. Check ComplaintUpdate created

Scenario 3: Escalation After Reminder

1. Create complaint with escalation rules configured
2. Let first reminder be sent
3. Wait for escalation trigger (e.g., 12 hours after reminder)
4. Verify complaint escalated
5. Verify escalated_at timestamp set
6. Verify escalation level increased in metadata
7. Verify notification sent to escalation target

Scenario 4: Complaint Closure

1. Create and resolve a complaint
2. Close the complaint
3. Verify thank you email sent (if enabled in SLA config)
4. Check ComplaintUpdate for closure

Scenario 5: No Second Reminder (Disabled)

1. Configure SLA with second_reminder_enabled=False
2. Create complaint due in 26 hours
3. Wait past second reminder timing
4. Verify no second reminder sent
5. Verify second_reminder_sent_at remains null

Production Configuration

Celery Beat Schedule

Ensure Celery Beat is configured to run SLA tasks:

# config/celery.py
from celery.schedules import crontab

app.conf.beat_schedule = {
    'check-sla-reminders': {
        'task': 'apps.complaints.tasks.send_sla_reminders',
        'schedule': crontab(minute=0),  # Every hour
    },
    'check-overdue-complaints': {
        'task': 'apps.complaints.tasks.check_overdue_complaints',
        'schedule': crontab(minute=0),  # Every hour
    },
}

Email Configuration

Ensure email backend is configured in settings:

# config/settings/dev.py
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'  # For testing

# config/settings/production.py
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.your-provider.com'
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'your-email@example.com'
EMAIL_HOST_PASSWORD = 'your-password'
DEFAULT_FROM_EMAIL = 'noreply@your-domain.com'

Monitoring

Set up monitoring for:

1. Celery task execution logs
2. Email delivery success/failure
3. Overdue complaints count
4. Escalation activity
5. Reminder sending frequency

Troubleshooting

Reminders Not Sending

Check:

1. Is Celery Beat running?
2. Is reminder_hours_before > hours_until_due?
3. Is reminder_sent_at already set?
4. Is complaint still open?
5. Check logs: logs/celery.log

Escalation Not Triggering

Check:

1. Is escalation rule configured for hospital?
2. Is is_active=True on escalation rule?
3. Is trigger condition met (overdue or reminder-based)?
4. Is reminder_escalation_enabled=True for reminder-based?
5. Check escalation level hasn't exceeded max_escalation_level

Emails Not Delivered

Check:

1. Email backend configuration
2. Email template files exist and are valid
3. Recipient email addresses are valid
4. SMTP server is accessible (for production)
5. Check logs for email sending errors

Database Migration Issues

If you encounter migration issues with the new second_reminder_sent_at field:

# Check migration status
python manage.py showmigrations complaints

# If needed, create new migration
python manage.py makemigrations complaints

# Apply migration
python manage.py migrate complaints

# Verify field exists
python manage.py dbshell
\dt complaints_complaint
\d complaints_complaint

API Endpoints

List SLA Configurations

GET /api/complaints/sla-configs/

Create SLA Configuration

POST /api/complaints/sla-configs/

Update SLA Configuration

PUT /api/complaints/sla-configs/{id}/

List Escalation Rules

GET /api/complaints/escalation-rules/

Create Escalation Rule

POST /api/complaints/escalation-rules/

Best Practices

1. Start with conservative settings: Set longer SLA times during testing
2. Test in stages: Test first reminders, then second, then escalation
3. Monitor closely: Watch logs during initial deployment
4. Configure per hospital: Different hospitals may need different SLAs
5. Use severity/priority: Configure different SLAs for different complaint types
6. Document escalation paths: Ensure staff understand escalation flow
7. Test email delivery: Verify emails reach recipients before going live
8. Plan capacity: Ensure system can handle email volume at peak times

Support

For issues or questions:

1. Check logs: logs/celery.log, logs/django.log
2. Review documentation in /docs/
3. Check configuration in .env
4. Run test script: python test_sla_functionality.py
5. Verify Celery is running: ps aux | grep celery

Changelog

Version 2.0 (Current)

• ✅ Added second reminder feature
• ✅ Added second_reminder_sent_at field to Complaint model
• ✅ Created bilingual second reminder email templates
• ✅ Enhanced send_sla_reminders() task for second reminder
• ✅ Updated test script to cover second reminder

Version 1.0 (Previous)

• Initial SLA system with first reminder
• Escalation rules
• Thank you email feature
• Timeline tracking