HH/SURVEY_FEEDBACK_INTEGRATION.md

Survey-Feedback Integration

Overview

This document describes the integration between the Survey and Feedback systems, enabling a closed-loop workflow for handling negative survey responses.

Workflow

1. Negative Survey Detection

When a patient completes a survey with a score below the threshold (default: 3.0/5.0):

• Survey is automatically marked as is_negative=True
• Staff receives notification/alert about the negative feedback
• Survey detail page displays a warning banner with follow-up actions

2. Patient Contact

Staff member contacts the patient to discuss the negative feedback:

• Action: Click "Log Patient Contact" button on survey detail page
• Required: Contact notes documenting the conversation
• Optional: Mark issue as "Resolved" or "Explained"
• Tracked: Who contacted, when, and what was discussed

3. Send Satisfaction Feedback

After contacting the patient, staff can send a satisfaction check:

• Action: Click "Send Satisfaction Feedback" button
• Creates: New Feedback record of type SATISFACTION_CHECK
• Links: Feedback is linked to the original survey via related_survey field
• Sends: Notification to patient with feedback form link (TODO: implement notification)

4. Patient Completes Feedback

Patient receives and completes the satisfaction feedback form:

• Rates their satisfaction with how concerns were addressed
• Provides additional comments if needed
• Feedback is tracked in the system

5. Close Loop

Staff reviews the satisfaction feedback:

• If satisfied → Close both survey and feedback
• If still unsatisfied → Escalate or repeat process

Database Schema

Feedback Model Changes

# New field in Feedback model
related_survey = ForeignKey(
    'surveys.SurveyInstance',
    on_delete=models.SET_NULL,
    null=True,
    blank=True,
    related_name='follow_up_feedbacks'
)

# New feedback type
FeedbackType.SATISFACTION_CHECK = 'satisfaction_check', 'Satisfaction Check'

SurveyInstance Model Changes

# Patient contact tracking
patient_contacted = BooleanField(default=False)
patient_contacted_at = DateTimeField(null=True, blank=True)
patient_contacted_by = ForeignKey('accounts.User', ...)
contact_notes = TextField(blank=True)
issue_resolved = BooleanField(default=False)

# Satisfaction feedback tracking
satisfaction_feedback_sent = BooleanField(default=False)
satisfaction_feedback_sent_at = DateTimeField(null=True, blank=True)

API Endpoints

Survey Actions

• POST /surveys/instances/<uuid>/log-contact/ - Log patient contact
• POST /surveys/instances/<uuid>/send-satisfaction/ - Send satisfaction feedback

Views

• survey_log_patient_contact(request, pk) - Handle patient contact logging
• survey_send_satisfaction_feedback(request, pk) - Trigger satisfaction feedback

Background Tasks

send_satisfaction_feedback

@shared_task(bind=True, max_retries=3)
def send_satisfaction_feedback(self, survey_instance_id, user_id=None):
    """
    Creates and sends satisfaction feedback form to patient.
    
    - Validates patient was contacted
    - Creates Feedback record linked to survey
    - Sends notification to patient
    - Updates survey tracking fields
    """

UI Components

Survey Detail Page

For negative surveys, displays:

1. Warning Alert: "Action Required: Contact patient to discuss negative feedback"
2. Contact Form:
   • Contact notes textarea
   • Issue resolved checkbox
   • Submit button
3. Contact Summary (after logging):
   • Who contacted and when
   • Contact notes
   • Resolution status
4. Send Satisfaction Button (after contact):
   • Disabled until patient contacted
   • Triggers satisfaction feedback creation

Feedback Detail Page

For satisfaction check feedbacks, displays:

1. Related Survey Card:
   • Original survey name and score
   • Survey completion date
   • Patient contact information
   • Link to view original survey

Permissions

• Log Patient Contact: Hospital Admin or PX Admin
• Send Satisfaction Feedback: Hospital Admin or PX Admin
• View Related Survey: Same as survey permissions

Audit Trail

All actions are logged:

• survey_patient_contacted - When patient is contacted
• satisfaction_feedback_sent - When satisfaction feedback is sent
• Standard feedback audit events for the satisfaction check

Migration

Run migrations to apply database changes:

python3 manage.py migrate feedback
python3 manage.py migrate surveys

Future Enhancements

1. Notifications: Implement SMS/WhatsApp/Email notifications for satisfaction feedback
2. Automated Reminders: Send reminders if satisfaction feedback not completed
3. Analytics: Track satisfaction improvement rates
4. Templates: Customizable satisfaction feedback templates
5. Multi-language: Support for Arabic satisfaction feedback forms

Testing Checklist

• Create survey with negative score
• Verify warning appears on survey detail
• Log patient contact with notes
• Verify contact information is saved
• Send satisfaction feedback
• Verify feedback record is created and linked
• View feedback detail and verify survey link
• View survey detail and verify feedback link
• Test permissions for different user roles
• Verify audit logs are created

Related Files

Models

• apps/feedback/models.py - Feedback model with related_survey field
• apps/surveys/models.py - SurveyInstance model with contact tracking

Views

• apps/surveys/ui_views.py - Survey contact and satisfaction views
• apps/feedback/views.py - Feedback views (no changes needed)

Tasks

• apps/surveys/tasks.py - send_satisfaction_feedback task

Templates

• templates/surveys/instance_detail.html - Survey detail with follow-up actions
• templates/feedback/feedback_detail.html - Feedback detail with survey link

URLs

• apps/surveys/urls.py - New URL patterns for contact and satisfaction

Migrations

• apps/feedback/migrations/0002_add_survey_linkage.py
• apps/surveys/migrations/0003_add_survey_linkage.py

Configuration

Settings

# Survey token expiry (default: 30 days)
SURVEY_TOKEN_EXPIRY_DAYS = 30

# Negative survey threshold (default: 3.0 out of 5.0)
# Configured per survey template in database

Support

For questions or issues, contact the development team or refer to the main project documentation.