HH/docs/HIS_SIMULATOR_GUIDE.md

HIS Simulator - Complete Implementation Guide

Overview

The HIS (Hospital Information System) simulator is a continuous event generator that simulates patient journeys through the healthcare system and sends survey invitations when journeys are complete.

Architecture

┌─────────────────┐
│   HIS Simulator │
│   (Python)      │
└────────┬────────┘
         │ Sends events
         ↓
┌─────────────────┐
│   PX360 API     │
│   /api/simulator│
│   /his-events/  │
└────────┬────────┘
         │
         ├─► Creates Patient
         ├─► Creates Journey Instance
         ├─► Completes Stages
         └─► Sends Survey
                 │
                 ↓
         ┌───────────────┐
         │ Notifications │
         │ Service       │
         └───────────────┘
                 │
        ┌────────┴────────┐
        ↓                 ↓
   Email Simulator   SMS Simulator
   (Terminal + SMTP)  (Terminal)

Components

1. Journey Templates & Surveys

File: apps/simulator/management/commands/seed_journey_surveys.py

Creates:

• EMS Journey (2-4 random stages)

  • Stages: Ambulance Dispatch, On Scene Care, Patient Transport, Hospital Handoff
  • Survey: EMS Experience Survey (4 questions)

• Inpatient Journey (3-6 random stages)

  • Stages: Admission, Treatment, Nursing Care, Lab Tests, Radiology, Discharge
  • Survey: Inpatient Experience Survey (7 questions)

• OPD Journey (3-5 random stages)

  • Stages: Registration, Consultation, Lab Tests, Radiology, Pharmacy
  • Survey: OPD Experience Survey (7 questions)

2. HIS Simulator Script

File: apps/simulator/his_simulator.py

Features:

• Continuous event generation (infinite or limited)
• Generates realistic patient data (Arabic names, Saudi phone numbers)
• Creates both full and partial journeys (40% full, 60% partial)
• Sends events to PX360 API
• Displays statistics every 10 patients
• Configurable delay between events

3. API Endpoint

File: apps/simulator/views.py - his_events_handler()

Endpoint: POST /api/simulator/his-events/

Processes:

1. Patient creation/retrieval
2. Journey instance creation
3. Stage instance completion
4. Post-discharge survey sending (when journey complete)

4. Survey Sending

File: apps/simulator/views.py - send_post_discharge_survey()

When journey is complete:

• Creates SurveyInstance
• Sends email via NotificationService.send_survey_invitation()
• Sends SMS via NotificationService.send_sms()
• Both email and SMS contain secure survey link

Setup Instructions

Step 1: Seed Journey Templates and Surveys

# Run management command
python manage.py seed_journey_surveys

This creates:

• Hospital: Al Hammadi Hospital (ALH-main)
• Departments: Emergency, Cardiology, Orthopedics, Pediatrics, Lab, Radiology, Pharmacy, Nursing
• 3 Journey Templates (EMS, Inpatient, OPD) with random stages
• 3 Survey Templates with bilingual questions

Step 2: Start Django Server

# In one terminal
python manage.py runserver

Step 3: Run HIS Simulator

# In another terminal
python apps/simulator/his_simulator.py

Options:

# Default settings (infinite patients, 5 second delay)
python apps/simulator/his_simulator.py

# Custom URL
python apps/simulator/his_simulator.py --url http://localhost:8000/api/simulator/his-events/

# Custom delay (10 seconds between patients)
python apps/simulator/his_simulator.py --delay 10

# Limited patients (stop after 20 patients)
python apps/simulator/his_simulator.py --max-patients 20

# Combined options
python apps/simulator/his_simulator.py --url http://localhost:8000/api/simulator/his-events/ --delay 3 --max-patients 50

Expected Output

HIS Simulator Output

======================================================================
🏥 HIS SIMULATOR - Patient Journey Event Generator
======================================================================
API URL: http://localhost:8000/api/simulator/his-events/
Delay: 5 seconds between events
Max Patients: Infinite
======================================================================

Starting simulation... Press Ctrl+C to stop

📤 Sending 4 events for Ahmed Al-Saud...

✅ 🏥 Patient Journey Created
   Patient: Ahmed Al-Saud
   Encounter ID: ENC-2024-00123
   Type: OPD - Partial Journey
   Stages: 3/5 completed
   API Status: Success

Email Simulator Output (in Django terminal)

╔═══════════════════════════════════════════════════════════════════════════════╗
║               📧 EMAIL SIMULATOR                                         ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ Request #: 1                                                               ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ To:      ahmed.alsaud@gmail.com                                             ║
║ Subject: Your Experience Survey - Al Hammadi Hospital                        ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ Message:                                                                     ║
║         Dear Ahmed Al-Saud,                                                  ║
║         Thank you for your visit to Al Hammadi Hospital.                    ║
║         We value your feedback and would appreciate if you could take        ║
║         a few minutes to complete our survey.                               ║
║         Survey Link: http://localhost:8000/surveys/abc123xyz/               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

SMS Simulator Output (in Django terminal)

╔═══════════════════════════════════════════════════════════════════════════════╗
║               📱 SMS SIMULATOR                                              ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ Request #: 1                                                               ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ To:      +966501234567                                                       ║
║ Time:    2024-01-20 16:30:00                                                ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ Message:                                                                     ║
║         Your experience survey is ready:                                      ║
║         http://localhost:8000/surveys/abc123xyz/                             ║
╚═══════════════════════════════════════════════════════════════════════════════╝

Statistics Output (every 10 patients)

======================================================================
📊 SIMULATION STATISTICS
======================================================================
Total Journeys: 10
Successful: 10 (100.0%)
Failed: 0
Full Journeys: 4
Partial Journeys: 6
EMS Journeys: 3
Inpatient Journeys: 4
OPD Journeys: 3
Total Events Sent: 38
======================================================================

Testing Scenarios

Scenario 1: Full Journey with Survey

1. HIS simulator generates patient with full OPD journey (5 stages)
2. All 5 events sent to API
3. Journey marked as complete
4. Survey instance created
5. Email and SMS sent with survey link

Check:

# Check survey was created
python manage.py shell
>>> from apps.surveys.models import SurveyInstance
>>> SurveyInstance.objects.count()  # Should be > 0
>>> survey = SurveyInstance.objects.first()
>>> survey.status  # Should be 'pending'
>>> survey.get_survey_url()  # Should return URL

Scenario 2: Partial Journey (No Survey)

1. HIS simulator generates patient with partial EMS journey (2 of 4 stages)
2. Only 2 events sent to API
3. Journey NOT complete
4. NO survey created
5. NO email/SMS sent

Check:

# Check journey status
python manage.py shell
>>> from apps.journeys.models import PatientJourneyInstance
>>> journey = PatientJourneyInstance.objects.last()
>>> journey.is_complete()  # Should be False

Scenario 3: Multiple Stages

1. Patient starts journey
2. First stage completed → journey created
3. Second stage completed → journey updated
4. Third stage completed → journey still not complete
5. Fourth stage completed → journey complete → survey sent

Check:

# Check stage instances
python manage.py shell
>>> from apps.journeys.models import PatientJourneyStageInstance, StageStatus
>>> journey = PatientJourneyInstance.objects.last()
>>> stages = journey.stage_instances.all()
>>> for stage in stages:
...     print(f"{stage.stage_template.name}: {stage.status}")

API Response Format

Successful Response:

{
  "success": true,
  "message": "Processed 4 events successfully",
  "results": [
    {
      "encounter_id": "ENC-2024-00123",
      "patient_id": "uuid",
      "journey_id": "uuid",
      "stage_id": "uuid",
      "stage_status": "completed",
      "survey_sent": true,
      "survey_id": "uuid",
      "survey_url": "/surveys/abc123xyz/",
      "delivery_channel": "email_and_sms"
    }
  ],
  "surveys_sent": 1,
  "survey_details": [
    {
      "encounter_id": "ENC-2024-00123",
      "survey_id": "uuid",
      "survey_url": "/surveys/abc123xyz/"
    }
  ]
}

Partial Journey Response (no survey):

{
  "success": true,
  "message": "Processed 2 events successfully",
  "results": [
    {
      "encounter_id": "ENC-2024-00124",
      "patient_id": "uuid",
      "journey_id": "uuid",
      "stage_id": "uuid",
      "stage_status": "completed",
      "survey_sent": false
    }
  ],
  "surveys_sent": 0,
  "survey_details": []
}

Troubleshooting

Issue: "No active journey template found"

Cause: Journey templates not seeded

Solution:

python manage.py seed_journey_surveys

Issue: Survey not sent after journey completion

Check:

1. Journey template has send_post_discharge_survey = True
2. First stage has survey template associated
3. Check logs: grep "survey" logs/django.log

Issue: Email/SMS not displayed

Check:

1. Django server is running
2. NotificationService is configured correctly
3. Check terminal output for formatted messages

Issue: API returns 500 error

Check:

1. Django logs: logs/django.log
2. Check if all required fields are present in event data
3. Verify database migrations are up to date

Advanced Usage

Custom Journey Templates

Edit seed_journey_surveys.py to add:

• New journey types
• Custom stage names
• Additional survey questions
• Different scoring thresholds

Realistic Testing

For production-like testing:

# Simulate 100 patients over 10 minutes
python apps/simulator/his_simulator.py \
  --max-patients 100 \
  --delay 6 \
  --url http://localhost:8000/api/simulator/his-events/

Stress Testing

# High frequency (1 second between patients)
python apps/simulator/his_simulator.py --delay 1 --max-patients 50

Database Tables Created

1. Patient - Patient records
2. PatientJourneyTemplate - Journey definitions
3. PatientJourneyStageTemplate - Stage definitions
4. PatientJourneyInstance - Patient journeys
5. PatientJourneyStageInstance - Stage instances
6. SurveyTemplate - Survey definitions
7. SurveyQuestion - Survey questions
8. SurveyInstance - Survey instances
9. SurveyResponse - Survey responses (when patient completes survey)

Next Steps

After successful testing:

1. Implement survey completion UI (Phase 4)
2. Add survey response scoring
3. Integrate with PX Action Center for negative feedback
4. Add analytics dashboard for survey results
5. Implement real-time notifications (Celery + Redis)

Files Created/Modified

Created:

• apps/simulator/management/commands/seed_journey_surveys.py
• apps/simulator/his_simulator.py
• apps/simulator/serializers.py

Modified:

• apps/simulator/views.py - Added HIS events handler
• apps/simulator/urls.py - Added HIS events endpoint

Documentation:

• docs/HIS_SIMULATOR_GUIDE.md (this file)