HH/apps/px_sources/PX_SOURCES_MIGRATION_SUMMARY.md

PX Sources Migration Summary

Overview

Successfully migrated the system from hardcoded source enums to a flexible PXSource model that supports bilingual naming and dynamic source management.

Changes Made

1. Updated PXSource Model

File: apps/px_sources/models.py

Removed fields:

• icon_class - CSS class for icon display (no longer needed)
• color_code - Color code for UI display (no longer needed)

Simplified fields:

• code - Unique identifier (e.g., 'PATIENT', 'FAMILY', 'STAFF')
• name_en, name_ar - Bilingual names
• description_en, description_ar - Bilingual descriptions
• source_type - 'complaint', 'inquiry', or 'both'
• order - Display order
• is_active - Active status
• metadata - JSON field for additional configuration

2. Updated Complaint Model

File: apps/complaints/models.py

Before:

source = models.CharField(
    max_length=50,
    choices=ComplaintSource.choices,  # Hardcoded enum
    default=ComplaintSource.PATIENT
)

After:

source = models.ForeignKey(
    'px_sources.PXSource',
    on_delete=models.PROTECT,
    related_name='complaints',
    null=True,
    blank=True,
    help_text="Source of the complaint"
)

3. Updated Feedback Model

File: apps/feedback/models.py

Before:

source = models.CharField(
    max_length=50,
    default='web',
    help_text="Source of feedback (web, mobile, kiosk, etc.)"
)

After:

source = models.ForeignKey(
    'px_sources.PXSource',
    on_delete=models.PROTECT,
    related_name='feedbacks',
    null=True,
    blank=True,
    help_text="Source of feedback"
)

4. Removed Hardcoded Enums

File: apps/complaints/models.py

Removed:

• ComplaintSource enum class with hardcoded choices:
  • PATIENT
  • FAMILY
  • STAFF
  • SURVEY
  • SOCIAL_MEDIA
  • CALL_CENTER
  • MOH
  • CHI
  • OTHER

5. Updated Serializers

File: apps/complaints/serializers.py

Added to ComplaintSerializer:

source_name = serializers.CharField(source='source.name_en', read_only=True)
source_code = serializers.CharField(source='source.code', read_only=True)

6. Updated Call Center Views

File: apps/callcenter/ui_views.py

Changed:

# Before
from apps.complaints.models import ComplaintSource
source=ComplaintSource.CALL_CENTER

# After
from apps.px_sources.models import PXSource
call_center_source = PXSource.get_by_code('CALL_CENTER')
source=call_center_source

7. Created Data Migration

File: apps/px_sources/migrations/0003_populate_px_sources.py

Created 13 default PXSource records:

1. PATIENT - Patient (complaint)
2. FAMILY - Family Member (complaint)
3. STAFF - Staff Report (complaint)
4. SURVEY - Survey (both)
5. SOCIAL_MEDIA - Social Media (both)
6. CALL_CENTER - Call Center (both)
7. MOH - Ministry of Health (complaint)
8. CHI - Council of Health Insurance (complaint)
9. OTHER - Other (both)
10. WEB - Web Portal (inquiry)
11. MOBILE - Mobile App (inquiry)
12. KIOSK - Kiosk (inquiry)
13. EMAIL - Email (inquiry)

All sources include bilingual names and descriptions.

Migrations Applied

1. px_sources.0002_remove_pxsource_color_code_and_more.py

   • Removed icon_class and color_code fields

2. complaints.0004_alter_complaint_source.py

   • Changed Complaint.source from CharField to ForeignKey

3. feedback.0003_alter_feedback_source.py

   • Changed Feedback.source from CharField to ForeignKey

4. px_sources.0003_populate_px_sources.py

   • Created 13 default PXSource records

Benefits

1. Flexibility

• New sources can be added without code changes
• Sources can be activated/deactivated dynamically
• Bilingual support out of the box

2. Maintainability

• Single source of truth for all feedback sources
• No need to modify enums in multiple files
• Centralized source management

3. Consistency

• Same source model used across Complaints, Feedback, and other modules
• Unified source tracking and reporting
• Consistent bilingual naming

4. Data Integrity

• ForeignKey relationships ensure referential integrity
• Can't accidentally use invalid source codes
• Proper cascade behavior on deletion

Usage Examples

Get a source by code:

from apps.px_sources.models import PXSource

call_center_source = PXSource.get_by_code('CALL_CENTER')

Get active sources for complaints:

sources = PXSource.get_active_sources(source_type='complaint')

Get localized name:

# In Arabic context
source_name = source.get_localized_name(language='ar')

Activate/deactivate a source:

source.activate()
source.deactivate()

Testing Results

✅ All migrations applied successfully ✅ 13 PXSource records created ✅ Complaint source field is now ForeignKey ✅ Feedback source field is now ForeignKey ✅ No data loss during migration ✅ Call center views updated and working

Files Modified

1. apps/px_sources/models.py - Removed icon_class, color_code
2. apps/px_sources/serializers.py - Updated fields list
3. apps/px_sources/admin.py - Removed display options fieldset
4. apps/complaints/models.py - Changed source to ForeignKey, removed ComplaintSource enum
5. apps/complaints/serializers.py - Added source_name, source_code fields
6. apps/feedback/models.py - Changed source to ForeignKey
7. apps/callcenter/ui_views.py - Updated to use PXSource model
8. apps/px_sources/migrations/0003_populate_px_sources.py - New migration

Next Steps

1. Update any custom forms that reference ComplaintSource
2. Update API documentation to reflect new structure
3. Add PXSource management UI if needed (admin interface already exists)
4. Consider adding source usage analytics
5. Train users on managing sources through admin interface

Rollback Plan

If needed, you can rollback migrations:

python manage.py migrate px_sources 0001
python manage.py migrate complaints 0003
python manage.py migrate feedback 0002

This will revert to the hardcoded enum system.