HH/docs/HIS_INTEGRATION_COMPLETE.md

# HIS Integration Complete Documentation

## Overview

This document describes the complete integration between the PX360 system and the HIS (Hospital Information System) simulator. The integration enables automatic patient journey tracking, stage completion, and post-discharge survey triggering based on real HIS data format.

## Architecture

### Components

1. **HIS Simulator** (`apps/simulator/his_simulator.py`)
   - Generates realistic patient data in actual HIS format
   - Simulates patient visits with timeline data
   - Sends data to PX360 API endpoint

2. **HIS Data Adapter** (`apps/integrations/services/his_adapter.py`)
   - Adapts real HIS data format to PX360 models
   - Maps HIS visit types to journey stages
   - Handles patient creation/updating
   - Manages journey and stage instance creation

3. **HIS Data Serializer** (`apps/integrations/serializers.py`)
   - Validates HIS data structure
   - Ensures required fields are present
   - Provides proper error messages

4. **Simulator API Views** (`apps/simulator/views.py`)
   - `his_patient_data_handler`: New endpoint for real HIS format
   - `his_events_handler`: Legacy endpoint (backward compatibility)

5. **Journey Stage Seeding** (`apps/journeys/management/commands/seed_journey_stages_his.py`)
   - Creates journey templates with HIS visit types
   - Maps HIS visit types to journey stages

## Data Flow

```
HIS Simulator → API Endpoint → Serializer Validation → HIS Adapter → 
Patient Creation → Journey Creation → Stage Completion → Survey Trigger
```

## HIS Data Format

The integration expects data in the following format (actual HIS structure):

```json
{
  "FetchPatientDataTimeStampList": [{
    "Type": "Patient Demographic details",
    "PatientID": "123456",
    "AdmissionID": "789012",
    "HospitalID": "1",
    "HospitalName": "ALH-main",
    "AdmitDate": "05-Jun-2025 11:06",
    "DischargeDate": "05-Jun-2025 15:30",
    "SSN": "1234567890",
    "PatientName": "Ahmed Mohammed",
    "MobileNo": "0501234567",
    "Gender": "Male",
    "FullAge": "35",
    "PatientNationality": "Saudi",
    "DOB": "1990-01-15",
    "ConsultantID": "PHY001",
    "PrimaryDoctor": "Dr. Mohammed",
    "InsuranceCompanyName": "Bupa",
    "BillType": "Insurance",
    "IsVIP": "No"
  }],
  "FetchPatientDataTimeStampVisitDataList": [
    {
      "Type": "Consultation",
      "BillDate": "05-Jun-2025 11:06"
    },
    {
      "Type": "Doctor Visited",
      "BillDate": "05-Jun-2025 11:20"
    },
    {
      "Type": "Clinical Condtion",
      "BillDate": "05-Jun-2025 11:30"
    },
    {
      "Type": "ChiefComplaint",
      "BillDate": "05-Jun-2025 11:35"
    },
    {
      "Type": "Prescribed Drugs",
      "BillDate": "05-Jun-2025 12:00"
    }
  ],
  "Code": 200,
  "Status": "Success"
}
```

## HIS Visit Type to Journey Stage Mapping

| HIS Visit Type | Journey Stage | Description |
|----------------|---------------|-------------|
| Consultation | MD Consultation | Initial consultation with physician |
| Doctor Visited | MD Visit | Doctor visit and examination |
| Clinical Condtion | Clinical Assessment | Clinical condition assessment |
| ChiefComplaint | Patient Assessment | Chief complaint documentation |
| Prescribed Drugs | Pharmacy | Prescribed drugs dispensing |

## Setup Instructions

### 1. Seed Journey Stages

First, run the management command to create journey stage templates:

```bash
# Seed stages for all hospitals
python manage.py seed_journey_stages_his

# Seed stages for specific hospital
python manage.py seed_journey_stages_his --hospital ALH-main

# Seed stages with specific survey template
python manage.py seed_journey_stages_his --survey-template-id 1
```

### 2. Create Survey Template

Ensure you have a post-discharge survey template:

```bash
python manage.py create_demo_survey
```

Note the survey template ID from the output.

### 3. Attach Survey Template

If you didn't attach during seeding, update the journey template:

```bash
python manage.py seed_journey_stages_his --survey-template-id <ID>
```

### 4. Test the Integration

Run the HIS simulator to send test data:

```bash
# Run the HIS simulator (generates and sends 5 patient records)
python apps/simulator/his_simulator.py

# Or specify custom parameters
python apps/simulator/his_simulator.py --num-patients 3 --hospital ALH-main
```

## API Endpoints

### New HIS Patient Data Endpoint

**Endpoint:** `POST /api/simulator/his-patient-data/`

**Purpose:** Receives real HIS format patient data

**Request Body:** See HIS Data Format section above

**Response:**

```json
{
  "success": true,
  "message": "Patient data processed successfully. Journey created with 5 stages completed.",
  "patient_id": "uuid",
  "patient_mrn": "MRN123456",
  "patient_name": "Ahmed Mohammed",
  "journey_id": "uuid",
  "encounter_id": "ENC-2025-001",
  "completed_stages": ["Consultation", "Doctor Visited", "Clinical Condtion", "ChiefComplaint", "Prescribed Drugs"],
  "survey_triggered": true,
  "journey_status": "completed"
}
```

### Legacy HIS Events Endpoint

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

**Purpose:** Receives legacy format journey events (backward compatibility)

**Note:** This endpoint is kept for backward compatibility. New integrations should use the `/api/simulator/his-patient-data/` endpoint.

## Error Handling

The integration provides detailed error messages:

### Validation Errors

```json
{
  "error": "Invalid HIS data format",
  "details": {
    "Code": ["This field is required."],
    "Status": ["This field is required."]
  }
}
```

### Processing Errors

```json
{
  "error": "Hospital with code 'ALH-main' not found. Please run seed_journey_stages_his command first."
}
```

## Logging

All HIS events are logged to:
1. **Database:** `HISRequestLog` model
2. **File:** Django logs
3. **Console:** Detailed output for debugging

### Viewing Logs

```bash
# View logs in database
python manage.py shell
>>> from apps.simulator.models import HISRequestLog
>>> logs = HISRequestLog.objects.filter(channel='his_event')
>>> for log in logs:
...     print(f"{log.timestamp}: {log.status} - {log.patient_id}")
```

Or use the web UI:
- Navigate to `/simulator/logs/`
- Filter by channel 'his_event'

## Testing

### Manual Testing

1. **Verify Journey Stages Seeded**

```bash
python manage.py shell
>>> from apps.journeys.models import PatientJourneyTemplate
>>> template = PatientJourneyTemplate.objects.first()
>>> print(template.stages.count())
```

2. **Test HIS Simulator**

```bash
python apps/simulator/his_simulator.py --num-patients 1
```

3. **Verify Patient Created**

```bash
python manage.py shell
>>> from apps.organizations.models import Patient
>>> patient = Patient.objects.last()
>>> print(f"Patient: {patient.get_full_name()}, MRN: {patient.mrn}")
```

4. **Verify Journey Created**

```bash
python manage.py shell
>>> from apps.journeys.models import PatientJourneyInstance
>>> journey = PatientJourneyInstance.objects.last()
>>> print(f"Journey: {journey.encounter_id}, Status: {journey.status}")
>>> print(f"Stages: {journey.stages.count()}")
```

5. **Verify Survey Triggered**

```bash
python manage.py shell
>>> from apps.surveys.models import SurveyInstance
>>> survey = SurveyInstance.objects.last()
>>> print(f"Survey: {survey.survey_template.title_en}")
>>> print(f"URL: {survey.get_survey_url()}")
```

### Automated Testing

Create a test script to verify the complete flow:

```python
# test_his_integration.py
import requests
import json

# HIS simulator endpoint
url = "http://localhost:8000/api/simulator/his-patient-data/"

# Sample HIS data
his_data = {
    "FetchPatientDataTimeStampList": [{
        "Type": "Patient Demographic details",
        "PatientID": "TEST001",
        "AdmissionID": "ADM001",
        "HospitalID": "1",
        "HospitalName": "ALH-main",
        "AdmitDate": "05-Jun-2025 11:06",
        "DischargeDate": "05-Jun-2025 15:30",
        "SSN": "1234567890",
        "PatientName": "Test Patient",
        "MobileNo": "0501234567"
    }],
    "FetchPatientDataTimeStampVisitDataList": [
        {"Type": "Consultation", "BillDate": "05-Jun-2025 11:06"},
        {"Type": "Doctor Visited", "BillDate": "05-Jun-2025 11:20"}
    ],
    "Code": 200,
    "Status": "Success"
}

# Send request
response = requests.post(url, json=his_data)
print(f"Status: {response.status_code}")
print(f"Response: {json.dumps(response.json(), indent=2)}")
```

Run the test:
```bash
python test_his_integration.py
```

## Troubleshooting

### Issue: "Hospital not found"

**Solution:** Run the seed command:
```bash
python manage.py seed_journey_stages_his
```

### Issue: "No stage template found for event_type"

**Solution:** Verify stages are seeded with correct trigger codes:
```bash
python manage.py shell
>>> from apps.journeys.models import PatientJourneyStageTemplate
>>> stages = PatientJourneyStageTemplate.objects.all()
>>> for stage in stages:
...     print(f"{stage.name} -> {stage.trigger_event_code}")
```

### Issue: Survey not triggered

**Solution:** Check:
1. Journey template has `send_post_discharge_survey=True`
2. Journey template has `post_discharge_survey_template` set
3. Journey is complete (all stages completed)

```bash
python manage.py shell
>>> from apps.journeys.models import PatientJourneyTemplate
>>> template = PatientJourneyTemplate.objects.first()
>>> print(f"Send survey: {template.send_post_discharge_survey}")
>>> print(f"Survey template: {template.post_discharge_survey_template}")
```

### Issue: "Patient already exists but data is different"

**Solution:** The adapter updates existing patients. Check the patient record:
```bash
python manage.py shell
>>> from apps.organizations.models import Patient
>>> patient = Patient.objects.get(mrn="TEST001")
>>> print(patient.__dict__)
```

## Production Deployment

### Checklist

- [ ] Journey stages seeded for all hospitals
- [ ] Survey templates created and attached
- [ ] HIS API endpoint configured (use `/api/simulator/his-patient-data/`)
- [ ] Error monitoring enabled
- [ ] Logging configured
- [ ] Email/SMS services configured
- [ ] Database indexes optimized

### Security Considerations

1. **API Authentication:** Consider adding API key authentication for HIS endpoint
2. **Data Validation:** Ensure all HIS data is properly sanitized
3. **Rate Limiting:** Implement rate limiting to prevent abuse
4. **HTTPS:** Always use HTTPS in production

### Performance Optimization

1. **Batch Processing:** Process multiple patients in a single request
2. **Async Processing:** Use Celery for heavy operations
3. **Database Indexing:** Ensure proper indexes on frequently queried fields
4. **Caching:** Cache survey templates and journey templates

## Maintenance

### Regular Tasks

1. **Monitor HIS Request Logs:** Check for errors and processing times
2. **Review Patient Data Quality:** Ensure patient data is accurate
3. **Update Journey Templates:** Add/remove stages as needed
4. **Review Survey Response Rates:** Track survey completion rates

### Updating HIS Mappings

To add or update HIS visit type mappings:

1. Edit `apps/journeys/management/commands/seed_journey_stages_his.py`
2. Add new entries to `his_stage_config`
3. Run the seed command:
   ```bash
   python manage.py seed_journey_stages_his
   ```

## References

- [Journey Engine Documentation](JOURNEY_ENGINE.md)
- [HIS Simulator Guide](HIS_SIMULATOR_GUIDE.md)
- [Survey Documentation](../../docs/SURVEY_DOCUMENTATION.md)
- [API Documentation](API_ENDPOINTS.md)

## Support

For issues or questions:
1. Check the troubleshooting section
2. Review the logs in `/logs/` directory
3. Check database logs via `/simulator/logs/`
4. Contact development team