# Set-StudentEmail

PowerShell script to bulk-assign email addresses to Active Directory student users based on their AD username (SamAccountName).

## How It Works

The script scans all user accounts in a specified Organisational Unit (OU) and sets each user's email address to:

```
[username]@[domain]
```

For example, a student with the AD username **jsmith** would be assigned `jsmith@niddrieautisticschool.vic.edu.au`.

- Emails are forced to **lowercase** and any leading/trailing spaces in the username are stripped.

## Requirements

- Windows PowerShell 5.1+ or PowerShell 7+
- **Active Directory** PowerShell module (`RSAT: Active Directory Domain Services`)
- Sufficient AD permissions to modify user attributes in the target OU
- Run from a domain-joined machine or via `Enter-PSSession` to a DC

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `-OU` | String | `OU=Student,OU=Users,OU=5362-NiddrieAutistic,DC=curric,DC=niddrieautistic,DC=wan` | Distinguished name of the OU to search |
| `-Domain` | String | `niddrieautisticschool.vic.edu.au` | Email domain to append |
| `-Force` | Switch | `$false` | Overwrite existing email addresses |
| `-WhatIf` | Switch | `$false` | Preview changes without applying them |

## Usage Examples

### Preview changes (recommended first step)

Dry-run that shows what *would* happen without touching AD:

```powershell
.\Set-StudentEmail.ps1 -WhatIf
```

### Run with defaults

Uses the default OU and domain baked into the script:

```powershell
.\Set-StudentEmail.ps1
```

### Custom OU

Target a different OU while keeping the default domain:

```powershell
.\Set-StudentEmail.ps1 -OU "OU=Year7,OU=Students,DC=school,DC=local"
```

### Custom domain

Keep the default OU but use a different email domain:

```powershell
.\Set-StudentEmail.ps1 -Domain "anotherschool.vic.edu.au"
```

### Custom OU and domain together

```powershell
.\Set-StudentEmail.ps1 -OU "OU=Year7,DC=school,DC=local" -Domain "otherschool.edu.au"
```

### Overwrite existing emails

By default the script skips users who already have an email set. Use `-Force` to overwrite:

```powershell
.\Set-StudentEmail.ps1 -Force
```

### Combine Force with WhatIf for a safe preview

See what a forced run would change before committing:

```powershell
.\Set-StudentEmail.ps1 -Force -WhatIf
```

### Verbose output

PowerShell's built-in `-Verbose` flag works too:

```powershell
.\Set-StudentEmail.ps1 -Verbose
```

## Output

The script prints colour-coded status lines as it processes each user:

| Prefix | Colour | Meaning |
|--------|--------|---------|
| `SET:` | Green | Email was successfully applied |
| `OK:` | Grey | User already has the correct email (skipped) |
| `SKIP:` | Yellow | User skipped (has a different email without `-Force`) |
| `FAIL:` | Red | An error occurred updating the user |

A summary is printed at the end:

```
--- Summary ---
Updated: 12
Skipped: 3
Errors:  0
```

## Troubleshooting

| Issue | Fix |
|-------|-----|
| `Get-ADUser : Unable to find a default server` | Run from a domain-joined machine, or specify `-Server` manually in the script |
| `Access is denied` | Run as an account with write permissions to user objects in the target OU |
| `Module 'ActiveDirectory' not found` | Install RSAT: `Add-WindowsCapability -Online -Name Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0` |