124 lines
3.3 KiB
Markdown
124 lines
3.3 KiB
Markdown
# 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` |
|