HH/docs/STAFF_SEED_COMMAND_UPDATE.md

Staff Seed Command Update Documentation

Overview

The seed_staff management command has been updated to integrate with the new Staff user account management system. It now uses the StaffService for consistent user account creation and adds new features for email delivery.

What Changed

1. Integration with StaffService

The command now uses the StaffService class for all user account operations:

• StaffService.generate_username() - For username generation
• StaffService.generate_password() - For secure password generation
• StaffService.create_user_for_staff() - For user account creation
• StaffService.get_staff_type_role() - For proper role assignment
• StaffService.send_credentials_email() - For credential email delivery

2. Staff Email Field

The command now sets the email field on the Staff model:

• Format: {firstname}.{lastname}@{hospital_code}.sa
• Example: mohammed.alsalem@almadina.sa
• Handles duplicates by using username as fallback

3. New --send-emails Flag

Added a new command-line flag to send credential emails:

python manage.py seed_staff --create-users --send-emails

When enabled:

• Generates secure random passwords
• Sends credential emails to staff members
• Reports success/failure for each email

4. Enhanced Error Handling

The command now includes comprehensive error handling:

• Catches and reports user creation errors
• Catches and reports email sending errors
• Continues processing even if individual operations fail
• Provides clear error messages for debugging

5. Role Assignment

User accounts are now created with proper roles:

• All staff types receive the staff role
• Role is set using StaffService.get_staff_type_role()
• Consistent with the rest of the system

Usage

Basic Usage (Staff Profiles Only)

Create staff profiles without user accounts:

python manage.py seed_staff

Create Staff with User Accounts

Create staff profiles and user accounts:

python manage.py seed_staff --create-users

Create Staff with User Accounts and Email Delivery

Create staff, user accounts, and send credential emails:

python manage.py seed_staff --create-users --send-emails

Target Specific Hospital

Create staff for a specific hospital:

python manage.py seed_staff --hospital-code ALMADINA --create-users

Custom Counts

Specify the number of each staff type:

python manage.py seed_staff \
  --physicians 5 \
  --nurses 10 \
  --admin-staff 3 \
  --create-users

Dry Run

Preview what would be created without making changes:

python manage.py seed_staff --dry-run --create-users

Clear Existing Staff First

Delete all existing staff before creating new ones:

python manage.py seed_staff --clear --create-users

Command-Line Options

Option	Type	Default	Description
--hospital-code	string	all	Target hospital code
--count	integer	10	Number of staff per type
--physicians	integer	10	Number of physicians
--nurses	integer	15	Number of nurses
--admin-staff	integer	5	Number of admin staff
--create-users	flag	False	Create user accounts for staff
--send-emails	flag	False	Send credential emails
--clear	flag	False	Clear existing staff first
--dry-run	flag	False	Preview without making changes

Output Examples

Without User Accounts

============================================================
Staff Data Seeding Command
============================================================

Found 3 hospital(s) to seed staff

Configuration:
  Physicians per hospital: 10
  Nurses per hospital: 15
  Admin staff per hospital: 5
  Total staff per hospital: 30
  Create user accounts: False
  Send credential emails: False
  Clear existing: False
  Dry run: False

Seeding Physician...
Seeding Nurse...
Seeding Administrative...

============================================================
Summary:
  Physicians created: 30
  Nurses created: 45
  Admin staff created: 15
  Total staff created: 90
============================================================

Staff seeding completed successfully!

With User Accounts and Emails

============================================================
Staff Data Seeding Command
============================================================

Found 3 hospital(s) to seed staff

Configuration:
  Physicians per hospital: 10
  Nurses per hospital: 15
  Admin staff per hospital: 5
  Total staff per hospital: 30
  Create user accounts: True
  Send credential emails: True
  Clear existing: False
  Dry run: False

Seeding Physician...
    ✓ Created user: mohammed.alotaibi (role: staff)
    ✓ Sent credential email to: mohammed.alotaibi@almadina.sa
    ✓ Created user: ahmed.aldosari (role: staff)
    ✓ Sent credential email to: ahmed.aldosari@almadina.sa
    ...
  ✓ Created 30 Physician

Seeding Nurse...
    ✓ Created user: fatimah.alharbi (role: staff)
    ✓ Sent credential email to: fatimah.alharbi@almadina.sa
    ...
  ✓ Created 45 Nurse

Seeding Administrative...
    ✓ Created user: abdulrahman.almutairi (role: staff)
    ✓ Sent credential email to: abdulrahman.almutairi@almadina.sa
    ...
  ✓ Created 15 Administrative

============================================================
Summary:
  Physicians created: 30
  Nurses created: 45
  Admin staff created: 15
  Total staff created: 90
============================================================

Staff seeding completed successfully!

With Errors

Seeding Physician...
    ✓ Created user: mohammed.alotaibi (role: staff)
    ✓ Sent credential email to: mohammed.alotaibi@almadina.sa
    ⚠ Failed to send email: SMTP server not configured
    ✗ Failed to create user for Ahmed Aldosari: Email already exists
  ✓ Created 29 Physician

Email Requirements

For --send-emails to work, the following Django email settings must be configured in config/settings/base.py:

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'your-smtp-server.com'
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'your-email@domain.com'
EMAIL_HOST_PASSWORD = 'your-password'
DEFAULT_FROM_EMAIL = 'noreply@px360.local'

Optional setting for login URL in emails:

SITE_URL = 'https://px360.yourdomain.com'

If SITE_URL is not configured, it defaults to http://localhost:8000.

Data Generation

Staff Names

• Bilingual (English and Arabic)
• Paired to ensure correspondence between languages
• Gender-appropriate for staff types:
  • Nurses: 70% female, 30% male
  • Physicians: 60% male, 40% female
  • Admin staff: 60% male, 40% female

Employee IDs

Format: {TYPE}-{HOSPITAL_CODE}-{RANDOM_NUMBER}

Examples:

• Physicians: DR-ALMADINA-12345
• Nurses: RN-ALMADINA-23456
• Admin: ADM-ALMADINA-34567

Usernames

Format: {firstname}.{lastname} (lowercase)

Examples:

• mohammed.alotaibi
• fatimah.alharbi
• ahmed.aldosari

Duplicate handling: Appends number if username exists:

• mohammed.alotaibi2
• mohammed.alotaibi3

Email Addresses

Format: {username}@{hospital_code}.sa

Examples:

• mohammed.alotaibi@almadina.sa
• fatimah.alharbi@riyadh.sa

Passwords

• Length: 12 characters
• Characters: Letters, numbers, and special characters
• Generated using secrets module for cryptographic security
• Included in credential email

Testing

Test Dry Run

python manage.py seed_staff --dry-run --physicians 1 --nurses 1

Test User Account Creation (No Email)

python manage.py seed_staff --physicians 1 --nurses 1 --create-users

Test Full Workflow

python manage.py seed_staff \
  --hospital-code ALMADINA \
  --physicians 2 \
  --nurses 3 \
  --admin-staff 1 \
  --create-users \
  --send-emails

Test Error Handling

The command handles various error scenarios:

• Duplicate usernames
• Email conflicts
• SMTP server not configured
• Missing hospitals or departments

Best Practices

1. Use Dry Run First Always test with --dry-run before running the actual command to preview what will be created.

2. Start Small Begin with small numbers (e.g., --physicians 1 --nurses 1) to verify everything works.

3. Test Email Configuration Test email delivery with a single staff member before sending to many:

   python manage.py seed_staff --physicians 1 --create-users --send-emails
   

4. Backup Data Use --clear with caution as it deletes all existing staff:

   python manage.py seed_staff --clear --create-users
   

5. Monitor Logs Check the output for:

   • ✅ Successful user creations
   • ⚠ Email sending warnings
   • ✗ Error messages

Troubleshooting

Issue: "SMTP server not configured"

Solution: Configure email settings in config/settings/base.py

Issue: "Email already exists"

Solution: The command automatically handles this by using username as email fallback

Issue: "Username already exists"

Solution: The command automatically appends a number to make the username unique

Issue: "No hospitals found"

Solution: Create hospitals first using the hospital seed command or manually

Issue: "No departments found"

Solution: This is a warning. Staff will be created without departments. Create departments if needed.

Migration Notes

If you're upgrading from an older version:

1. Email Field Migration The Staff model already has the email field, so no migration is needed.

2. User Account Creation Existing staff without user accounts can have accounts created via:

   • UI: Staff Detail page → "Create User Account" button
   • API: POST /api/organizations/staff/{id}/create_user_account/
   • Admin: Select staff → "Create user accounts" action

3. Backward Compatibility The command is fully backward compatible. Running without flags creates staff profiles only.

Related Documentation

• Staff User Account Implementation
• Organization Model
• API Endpoints

Future Enhancements

Potential improvements for future versions:

1. CSV Import

   • Import staff from CSV files
   • Support bulk upload with user account creation

2. Department Assignment

   • Better department matching logic
   • Auto-assign based on specialization

3. Email Templates

   • Customizable email templates per hospital
   • Multi-language email support

4. Progress Tracking

   • Real-time progress updates for large batches
   • Percentage complete indicator

5. Audit Logging

   • Log all seed command executions
   • Track who ran the command and when

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review the Staff User Account Implementation documentation
3. Check Django logs for detailed error messages
4. Ensure all dependencies are installed and configured correctly