HH/docs/STAFF_CONTACT_POPULATION.md

Staff Contact Information Population Guide

Overview

This guide explains how to populate existing staff records with random email addresses and phone numbers using the populate_staff_contact management command.

Command Overview

The populate_staff_contact command fills in missing contact information for staff records that don't have email addresses or phone numbers.

Usage

Basic Syntax

python manage.py populate_staff_contact [options]

Command Options

Option	Description	Default
--hospital-code	Target specific hospital code	All hospitals
--email-only	Only populate email addresses	Both email and phone
--phone-only	Only populate phone numbers	Both email and phone
--overwrite	Overwrite existing email/phone	Fill missing only
--dry-run	Preview changes without updating database	False

Examples

1. Preview Changes (Dry Run)

See what will be updated without making changes:

python manage.py populate_staff_contact --dry-run

Output:

============================================================
Staff Contact Information Populator
============================================================

Target: All hospitals
Found 15 staff to update
  Email only: False
  Phone only: False
  Overwrite existing: False
  Dry run: True

  Would update: ABDULAZIZ SALEH ALHAMMADI
    - email: None → abdulaziz.alhammadi@alhammadi.sa
    - phone: None → +966 54 123 456
  Would update: VARGHESE NINAN
    - email: None → varghese.ninan@alhammadi.sa
    - phone: None → +966 57 789 012
  ...

============================================================
Summary:
  Total staff processed: 15
  Emails populated: 15
  Phone numbers populated: 15
  Skipped: 0
============================================================

DRY RUN: No changes were made

2. Populate All Missing Contact Info

Fill in missing emails and phone numbers for all staff:

python manage.py populate_staff_contact

3. Populate for Specific Hospital

Only update staff at a specific hospital:

python manage.py populate_staff_contact --hospital-code ALHAMMADI

4. Only Populate Emails

Add email addresses without touching phone numbers:

python manage.py populate_staff_contact --email-only

5. Only Populate Phone Numbers

Add phone numbers without touching emails:

python manage.py populate_staff_contact --phone-only

6. Overwrite Existing Contact Info

Replace existing email and phone numbers with new random values:

python manage.py populate_staff_contact --overwrite

Generated Data Formats

Email Addresses

Format: {firstname}.{lastname}@{hospital}.sa

Examples:

• mohammed.alotaibi@alhammadi.sa
• fatimah.aldosari@alhammadi.sa
• varghese.ninan12@alhammadi.sa (with random suffix for duplicates)

Domain: Uses the hospital code (lowercased) as the domain

Uniqueness: Adds random number suffix (1-999) if email already exists

Phone Numbers

Format: +966 5X XXX XXXX (Saudi mobile format)

Examples:

• +966 50 123 456
• +966 57 789 012
• +966 55 345 678

Structure:

• Country code: +966 (Saudi Arabia)
• Mobile prefix: 5X (X = random digit 0-9)
• Number groups: XXX XXX (random 3-digit groups)

How It Works

1. Query Staff

The command queries staff records based on options:

• Without --overwrite: Only finds staff with missing email/phone
• With --overwrite: Finds all staff in target scope
• With --hospital-code: Filters by specific hospital

2. Generate Contact Info

For each staff member:

1. Email Generation:

   • Uses staff.name if available (original CSV name)
   • Falls back to first_name + last_name
   • Generates email in format: {firstname}.{lastname}@{hospital}.sa
   • Checks for duplicates and adds random suffix if needed
   • Skips staff without name fields

2. Phone Generation:

   • Generates random Saudi mobile number
   • Format: +966 5X XXX XXXX
   • No uniqueness check (phone numbers can be duplicated)

3. Update Records

• Uses database transaction for data integrity
• Shows progress for each updated staff
• Displays summary statistics at the end

Best Practices

1. Always Use Dry Run First

Preview changes before applying:

python manage.py populate_staff_contact --dry-run

2. Back Up Before Overwriting

If using --overwrite, backup first:

python manage.py dumpdata organizations.Staff > staff_backup.json

3. Update in Stages

For large datasets, consider updating in stages:

# Stage 1: Emails only
python manage.py populate_staff_contact --email-only

# Stage 2: Phone numbers only
python manage.py populate_staff_contact --phone-only

4. Target Specific Hospitals

For multi-tenant systems, update one hospital at a time:

python manage.py populate_staff_contact --hospital-code HOSPITAL1 --dry-run
python manage.py populate_staff_contact --hospital-code HOSPITAL1

Troubleshooting

Issue: "All staff already have contact information"

Problem: No staff have missing email/phone fields.

Solution:

• Use --overwrite to replace existing values
• Or use --email-only or --phone-only for specific fields

Issue: "Skipping staff: Missing first/last name"

Problem: Staff record doesn't have first_name and last_name fields populated.

Solution:

• Ensure staff have names before running
• Or populate names manually first
• Check if staff.name field has data (used as fallback)

Issue: Duplicate Emails

Problem: Email generation not adding suffix for duplicates.

Solution:

• The command automatically handles duplicates
• Adds random number (1-999) if email exists
• If you see duplicates, staff may have been added after generation

Issue: Wrong Hospital Domain

Problem: Emails using wrong hospital code in domain.

Solution:

• Verify hospital code in staff.hospital field
• Use --hospital-code to target specific hospital
• Or manually update hospital assignments first

Output Interpretation

Success Indicators

✓ Updated: ABDULAZIZ SALEH ALHAMMADI
    Email: abdulaziz.alhammadi@alhammadi.sa
    Phone: +966 54 123 456

Warning Indicators

⚠ Skipping staff 123: Missing first/last name

This means the staff record doesn't have name fields required for email generation.

Summary Statistics

Summary:
  Total staff processed: 15
  Emails populated: 15
  Phone numbers populated: 15
  Skipped: 0

• Total staff processed: Number of staff matching query
• Emails populated: Count of emails generated
• Phone numbers populated: Count of phone numbers generated
• Skipped: Staff that couldn't be updated (missing names, etc.)

Integration with Other Commands

After CSV Import

Import staff from CSV, then populate contact info:

# Import staff from CSV
python manage.py import_staff_csv staff_data.csv --hospital-code ALHAMMADI

# Populate contact info for imported staff
python manage.py populate_staff_contact --hospital-code ALHAMMADI

Before User Account Creation

Ensure staff have emails before creating user accounts:

# Populate emails first
python manage.py populate_staff_contact --email-only

# Then create user accounts
python manage.py create_staff_users --hospital-code ALHAMMADI

Related Documentation

• Staff Hierarchy Integration
• Staff Seeding
• User Account Creation
• CSV Import Guide

Support

For issues or questions:

1. Use --dry-run to preview changes
2. Check staff records have required name fields
3. Verify hospital codes are correct
4. Review Django logs for detailed errors