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):

{
  "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:

# 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:

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:

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

4. Test the Integration

Run the HIS simulator to send test data:

# 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:

{
  "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

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

Processing Errors

{
  "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

# 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

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

2. Test HIS Simulator

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

3. Verify Patient Created

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

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

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:

# 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:

python test_his_integration.py

Troubleshooting

Issue: "Hospital not found"

Solution: Run the seed command:

python manage.py seed_journey_stages_his

Issue: "No stage template found for event_type"

Solution: Verify stages are seeded with correct trigger codes:

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)

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:

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:

   python manage.py seed_journey_stages_his
   

References

• Journey Engine Documentation
• HIS Simulator Guide
• Survey Documentation
• API Documentation

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