HH/HIS_SIMULATOR_PATIENT_JOURNEYS_SUMMARY.md

HIS Simulator - Patient Journeys Summary

Overview

This document summarizes the patient journeys implemented in the HIS simulator and the survey delivery system.

Patient Journeys (4 Types)

The HIS simulator supports 4 distinct patient journey types, each with its own survey template:

1. Inpatient Journey (PatientType: 1)

• Survey Template: Inpatient Post-Discharge Survey
• Requirements: Must have a discharge date
• Flow:
  1. Patient admission
  2. Hospital stay
  3. Discharge event → Triggers survey
  4. Survey sent via SMS

2. OPD Journey (PatientType: 2)

• Survey Template: OPD Patient Experience Survey
• Requirements: No discharge required (sent after visit)
• Flow:
  1. Patient registration
  2. Consultation/visit
  3. Visit completion → Triggers survey
  4. Survey sent via SMS

3. EMS Journey (PatientType: 3)

• Survey Template: EMS Emergency Services Survey
• Requirements: No discharge required (sent after emergency visit)
• Flow:
  1. Emergency arrival
  2. Emergency treatment
  3. Visit completion → Triggers survey
  4. Survey sent via SMS

4. Day Case Journey (PatientType: 4)

• Survey Template: Day Case Patient Survey
• Requirements: Has discharge date (same-day procedure)
• Flow:
  1. Patient admission
  2. Procedure/treatment
  3. Same-day discharge → Triggers survey
  4. Survey sent via SMS

Technical Implementation

HIS Integration Endpoint

• URL: POST /api/integrations/events/
• View: HISPatientDataView (in apps/integrations/views.py)
• Service: HISAdapter.process_his_data() (in apps/integrations/services/his_adapter.py)

Patient Type Mapping

The system maps HIS PatientType codes to survey types:

HIS Code	Survey Type	Template Name
"1"	INPATIENT	Inpatient Post-Discharge Survey
"2", "O"	OPD	OPD Patient Experience Survey
"3", "E"	EMS	EMS Emergency Services Survey
"4"	DAYCASE	Day Case Patient Survey

Survey Template Selection Logic

The system searches for appropriate survey templates using a hierarchical approach:

1. Primary search: Look for template by patient type keywords, filtered by hospital
2. Secondary search: Look for template by patient type keywords, without hospital filter
3. Fallback 1: Use any active template for the hospital
4. Fallback 2: Use any active template in the system

Search terms (in order of specificity):

• INPATIENT: "INPATIENT", "Inpatient"
• OPD: "OPD", "Outpatient"
• EMS: "EMS", "Emergency"
• DAYCASE: "Day Case"

Data Flow

HIS System
    ↓
POST /api/integrations/events/
    ↓
HISPatientDataView
    ↓
HISAdapter.process_his_data()
    ↓
1. Parse patient data
2. Get or create Hospital
3. Get or create Patient
4. Get appropriate SurveyTemplate (based on PatientType)
5. Create SurveyInstance
6. Send survey via SMS (SurveyDeliveryService.deliver_survey)
    ↓
Survey sent to patient's phone number

Patient Data Structure

{
  "FetchPatientDataTimeStampList": [{
    "PatientID": "MRN001",
    "AdmissionID": "ADM001",
    "HospitalID": "1",
    "HospitalName": "Al Hammadi Hospital - Riyadh",
    "PatientType": "1",  // 1=Inpatient, 2=OPD, 3=EMS, 4=Day Case
    "AdmitDate": "28-Jan-2025 09:00",
    "DischargeDate": "01-Feb-2025 14:00",  // Required for Inpatient/Day Case
    "PatientName": "Full Name",
    "Gender": "Male",
    "MobileNo": "0501234567",
    "Email": "email@example.com",
    "DOB": "15-Mar-1985 00:00",
    // ... additional fields
  }],
  "FetchPatientDataTimeStampVisitDataList": [
    // Visit/activity data
  ],
  "Code": 200,
  "Status": "Success"
}

Survey Templates

All survey templates are created via Django management command:

python manage.py create_his_survey_templates

This creates 4 templates for the specified hospital:

1. Inpatient Post-Discharge Survey (7 questions)
2. OPD Patient Experience Survey (6 questions)
3. EMS Emergency Services Survey (6 questions)
4. Day Case Patient Survey (6 questions)

Testing

A comprehensive test script is available:

python test_all_patient_types.py

This script tests all 4 patient types and verifies:

• Survey creation
• Correct template selection
• Survey URL generation
• Database persistence

Key Features

1. Patient Deduplication: Existing patients are updated with new information
2. Survey Deduplication: Only one survey per admission ID
3. Hospital Management: Automatic hospital creation/lookup
4. Flexible Template Matching: Multiple fallback mechanisms ensure a survey is always sent
5. SMS Delivery: Surveys are automatically sent via SMS
6. Status Tracking: Survey status is tracked (SENT, COMPLETED, etc.)

Important Notes

1. Inpatient patients MUST have a discharge date before a survey is sent
2. OPD and EMS patients do NOT require discharge dates (surveys sent after visit)
3. Day Case patients have discharge dates (same-day procedures)
4. Survey templates must be active (is_active=True)
5. Patient phone number is required for SMS delivery

Files Modified/Created

Core Integration Files

• apps/integrations/views.py - HISPatientDataView
• apps/integrations/services/his_adapter.py - HISAdapter service
• apps/integrations/urls.py - API endpoint configuration

Survey Templates

• apps/surveys/management/commands/create_his_survey_templates.py - Template creation command

Testing

• test_all_patient_types.py - Comprehensive test suite for all patient types

Summary

The HIS simulator successfully implements 4 patient journey types, each with:

• Distinct patient classification (Inpatient, OPD, EMS, Day Case)
• Appropriate survey template selection
• Automatic survey creation and delivery
• Patient and hospital management
• Flexible fallback mechanisms

All journeys are tested and working correctly, with surveys being sent via SMS to patients based on their patient type and discharge status.