HH/POST_DISCHARGE_SURVEY_IMPLEMENTATION.md

Post-Discharge Survey Implementation

Overview

This implementation replaces the per-stage survey system with a comprehensive post-discharge survey that merges questions from all completed stages into a single survey sent after patient discharge.

Changes Made

1. Model Changes

PatientJourneyTemplate Model

• Added:
  • send_post_discharge_survey: Boolean field to enable/disable post-discharge surveys
  • post_discharge_survey_delay_hours: Integer field for delay after discharge (in hours)

PatientJourneyStageTemplate Model

• Removed:
  • auto_send_survey: No longer auto-send surveys at each stage
  • survey_delay_hours: No longer needed for individual stage surveys
• Retained:
  • survey_template: Still linked for collecting questions to merge

2. Task Changes

process_inbound_event (apps/integrations/tasks.py)

• New Logic:
  • Detects patient_discharged event code
  • Checks if journey template has send_post_discharge_survey=True
  • Schedules create_post_discharge_survey task with configured delay
• Removed:
  • No longer triggers surveys at individual stage completion

create_post_discharge_survey (apps/surveys/tasks.py)

• New Task:
  • Fetches all completed stages for the journey
  • Collects survey templates from each completed stage
  • Creates a comprehensive survey template on-the-fly
  • Merges questions from all stages with section headers
  • Sends the comprehensive survey to the patient

3. Admin Changes

PatientJourneyStageTemplateInline

• Removed:
  • auto_send_survey from inline fields
• Retained:
  • survey_template for question configuration

PatientJourneyStageTemplateAdmin

• Removed:
  • auto_send_survey from list_display, list_filter, fieldsets
  • survey_delay_hours from fieldsets

PatientJourneyTemplateAdmin

• Added:
  • New "Post-Discharge Survey" fieldset with:
    • send_post_discharge_survey
    • post_discharge_survey_delay_hours

How It Works

Workflow

1. Patient Journey Starts:

   • Patient goes through various stages (admission, treatment, etc.)
   • Each stage has a survey_template configured with questions
   • No surveys are sent at this point

2. Patient Discharges:

   • System receives patient_discharged event via process_inbound_event
   • If send_post_discharge_survey=True on journey template:
     • Schedules create_post_discharge_survey task after configured delay

3. Comprehensive Survey Created:

   • Task collects all completed stages
   • Creates new survey template with merged questions
   • Questions organized with section headers for each stage
   • Survey sent to patient via SMS/WhatsApp/Email

4. Patient Responds:

   • Patient completes the comprehensive survey
   • System calculates score and processes feedback
   • Negative scores trigger PX Actions (existing functionality)

Survey Structure

The post-discharge survey includes:

Post-Discharge Survey - [Patient Name] - [Encounter ID]

--- Stage 1 Name ---
  [Question 1 from Stage 1]
  [Question 2 from Stage 1]
  ...

--- Stage 2 Name ---
  [Question 1 from Stage 2]
  [Question 2 from Stage 2]
  ...

--- Stage 3 Name ---
  [Question 1 from Stage 3]
  [Question 2 from Stage 3]
  ...

Configuration

Enabling Post-Discharge Surveys

1. Go to Admin → Patient Journey Templates
2. Select or create a journey template
3. In "Post-Discharge Survey" section:
   • Check "Send post-discharge survey"
   • Set "Post-discharge survey delay (hours)" (default: 24)

Setting Stage Questions

1. Go to Patient Journey Templates → Edit Template
2. For each stage in "Journey stage templates" section:
   • Select a Survey template (contains questions)
   • These questions will be merged into the post-discharge survey

Benefits

1. Reduced Survey Fatigue: One comprehensive survey instead of multiple surveys
2. Better Patient Experience: Patients not overwhelmed with frequent surveys
3. Complete Picture: Captures feedback for entire hospital stay
4. Flexible Configuration: Easy to enable/disable per journey template
5. Contextual Organization: Questions grouped by stage for clarity

Migration Details

Migration File: apps/journeys/migrations/0003_remove_patientjourneystagetemplate_auto_send_survey_and_more.py

Changes:

• Remove auto_send_survey from PatientJourneyStageTemplate
• Remove survey_delay_hours from PatientJourneyStageTemplate
• Add send_post_discharge_survey to PatientJourneyTemplate
• Add post_discharge_survey_delay_hours to PatientJourneyTemplate
• Make survey_template nullable on PatientJourneyStageTemplate

Task Parameters

create_post_discharge_survey

Parameters:

• journey_instance_id: UUID of the PatientJourneyInstance

Returns:

{
    'status': 'sent' | 'skipped' | 'error',
    'survey_instance_id': str,
    'survey_template_id': str,
    'notification_log_id': str,
    'stages_included': int,
    'total_questions': int,
    'reason': str  # if skipped/error
}

Skip Conditions:

• No completed stages in journey
• No survey templates found for completed stages

Audit Events

The implementation creates audit logs for:

• post_discharge_survey_sent: When comprehensive survey is created and sent

Metadata includes:

• survey_template: Name of comprehensive survey
• journey_instance: Journey instance ID
• encounter_id: Patient encounter ID
• stages_included: Number of stages merged
• total_questions: Total questions in survey
• channel: Delivery channel (sms/whatsapp/email)

Future Enhancements

Potential improvements:

1. Add per-stage question filtering (optional stages)
2. Allow custom question ordering
3. Add conditional questions based on stage outcomes
4. Implement survey reminders for post-discharge surveys
5. Add analytics comparing pre/post implementation metrics

Testing Checklist

• Verify journey template has post-discharge survey enabled
• Create journey with multiple stages, each with survey templates
• Complete all stages
• Send patient_discharged event
• Verify task is scheduled with correct delay
• Verify comprehensive survey is created
• Verify all stage questions are merged with section headers
• Verify survey is sent to patient
• Test patient survey completion
• Verify score calculation works correctly
• Verify negative survey triggers PX Action

Rollback Plan

If needed, rollback steps:

1. Disable send_post_discharge_survey on all journey templates
2. Revert migration: python manage.py migrate journeys 0002
3. Manually restore auto_send_survey and survey_delay_hours fields if needed
4. Update process_inbound_event to restore stage survey logic

Related Documentation

• Journey Engine
• Survey System
• Notifications
• PX Action Center