SERVER-011 · Script
Assist Domain Migration
Inventories users and computers in an OU before a domain or tenant move, and can change user sign-in suffixes.
What it does
Report mode (default) writes two CSV files for the OU you choose:
- Users: sign-in name, UPN suffix, enabled, last sign-in, password last set, SID history, email, OU
Computers name, operating system, enabled, last sign-in, OU It also lists every UPN suffix in use, so you can see what still needs to change.
Preview and Apply change the UPN suffix for users whose suffix is -OldSuffix to -NewSuffix (for example from school.local to school.org) and save a rollback CSV with the old values. The new suffix must already be listed as an alternative UPN suffix in the forest, unless it is the domain name itself.
Requirements
Windows PowerShell 5.1 and the ActiveDirectory module (RSAT). Read rights for reports; write rights on userPrincipalName for changes.
How to run it
- Run as: a service account with the directory rights the script lists, or SYSTEM on a domain controller or the server being checked
- Run from: a domain-joined management server or admin workstation with the RSAT tools, as a scheduled task or from your management tool
- Script type: PowerShell 5.1, 64-bit
- User interaction: none; the script never prompts
- Timeout: 30 minutes for large directories or many servers
Settings
| Name | What it does | Options | Default |
|---|---|---|---|
| Mode | Report (default), Preview or Apply. | Report, Preview, Apply | Report |
| SearchBase | OU (distinguished name) to inventory. If empty, the whole domain. | ||
| OldSuffix | UPN suffix to replace, for example school.local. | ||
| NewSuffix | UPN suffix to set, for example school.org. | ||
| Server | Optional domain controller to use for every call. |
Exit codes
- 0 = Report written, or all suffix changes done
- 1 = Some suffix changes failed
- 2 = Script error (see log)
Testing steps
- Run it first with the mode set to Report on one test OU, test account or test server. Nothing is changed in that mode.
- Read the log and confirm the planned changes are what you expect.
- Run your chosen settings on the same test target and confirm the result.
- Check the exit code: 0 = OK, 1 = needs attention, 2 = error (see log), 9 = this copy is past its Valid until date.
- Roll out to a small group next, then everyone.
Rollback steps
Report and Preview modes change nothing. Apply saves a rollback CSV of the original sign-in names. To undo, run the script again with OldSuffix and NewSuffix swapped.
Version and change log
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | November 2026 | First release. |