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

```bash
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:

```bash
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:

```bash
python manage.py populate_staff_contact
```

### 3. Populate for Specific Hospital

Only update staff at a specific hospital:

```bash
python manage.py populate_staff_contact --hospital-code ALHAMMADI
```

### 4. Only Populate Emails

Add email addresses without touching phone numbers:

```bash
python manage.py populate_staff_contact --email-only
```

### 5. Only Populate Phone Numbers

Add phone numbers without touching emails:

```bash
python manage.py populate_staff_contact --phone-only
```

### 6. Overwrite Existing Contact Info

Replace existing email and phone numbers with new random values:

```bash
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:

```bash
python manage.py populate_staff_contact --dry-run
```

### 2. Back Up Before Overwriting

If using `--overwrite`, backup first:

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

### 3. Update in Stages

For large datasets, consider updating in stages:

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

```bash
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:

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

```bash
# 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_HIERARCHY_INTEGRATION.md)
- [Staff Seeding](STAFF_SEED_COMMAND_UPDATE.md)
- [User Account Creation](STAFF_USER_ACCOUNT_FEATURE_COMPLETE.md)
- [CSV Import Guide](STAFF_CSV_IMPORT_GUIDE.md)

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