Migrate User Administrative Tool Project Page
Project Background
This sample is based on an internal AppleScript-based macOS administrative tool originally used in an enterprise migration workflow. After a Mac was reimaged and a user’s home folder had already been restored to the target system, the tool was used to update ownership and group permissions so the user could successfully log in and access their files.
The version included in this portfolio preserves the original workflow and administrative purpose while revising the surrounding documentation and script presentation to better reflect technical writing best practices.
My Role
I revised and edited the documentation and supporting script content for this tool. My work included:
- improving the administrator README
- refining task instructions
- clarifying warnings and prerequisites
- revising user-facing dialog text
- strengthening code comments for readability and maintainability
- making minor script refinements to improve readability and error handling
Revision Focus
The portfolio version was updated to better support an administrator audience and to present the workflow more clearly as a technical documentation sample. Revision priorities included:
- clearer audience targeting
- more explicit prerequisites
- stronger warning and confirmation language
- improved consistency in terminology and instructions
- more maintainable code comments
- more usable, task-focused documentation structure
Project Documents
Administrator Guide
Administrator-facing instructions covering the tool’s purpose, prerequisites, limitations, usage steps, and expected results.
Revised AppleScript
Portfolio edition of the script with improved comments, prompts, warnings, and readability refinements.
applescript
-- Migrate User Application
-- Portfolio edition
--
-- Purpose:
-- Restore ownership and group permissions on a migrated user home folder
-- after a Mac has been reimaged.
--
-- Intended audience:
-- Platform administrators, desktop support technicians, and macOS administrators
--
-- Assumptions:
-- 1. The user's home folder has already been copied to /Users on the target Mac.
-- 2. The entered value matches the user's short name/home folder name exactly.
-- 3. The Mac is bound to Active Directory.
-- 4. The administrator running the script has valid admin credentials.
--
-- This script does not validate the entered account name against LDAP or Active Directory.
tell application "Finder"
set validAnswer to false
-- Prompt for the user's short name/home folder name and require confirmation.
repeat while (validAnswer = false)
display dialog "Enter the Active Directory short name (home folder name) for the account being migrated.
Important:
• Enter the name exactly as it appears in /Users
• Do not enter the user's full name" default answer "" buttons {"Continue"} default button 1
set ADUserName to text returned of result
display dialog "Confirm the account name:
" & ADUserName & "
This value must exactly match the user's home folder name in /Users." buttons {"Re-enter", "Quit", "Confirm"} default button "Confirm"
if button returned of result is "Confirm" then
set validAnswer to true
else if button returned of result is "Quit" then
error number -128
end if
end repeat
-- Confirm that the migrated home folder is already in the expected location.
display dialog "Verify that the user's home folder has already been copied to the /Users directory on this Mac.
Select OK only after this has been confirmed." buttons {"OK", "Cancel"} default button "OK"
if button returned of result is "Cancel" then error number -128
-- Provide a final confirmation before permissions are updated.
display dialog "Final confirmation:
This tool will update ownership and group permissions for:
/Users/" & ADUserName & "
Proceed only if:
• the account name is correct
• the home folder is in the correct location
• the Mac is bound to Active Directory" buttons {"Cancel", "Proceed"} default button "Proceed"
if button returned of result is "Cancel" then error number -128
-- Apply ownership to the specified home folder.
try
do shell script "chown -R " & quoted form of ADUserName & " /Users/" & quoted form of ADUserName with administrator privileges
-- Apply the staff group to the same home folder.
do shell script "chgrp -R staff /Users/" & quoted form of ADUserName with administrator privileges
display dialog "Migration completed successfully for account:
" & ADUserName buttons {"OK"} default button "OK"
on error errMsg number errNum
display dialog "The migration could not be completed.
Check the following and try again:
• The account name is correct
• The home folder exists in /Users
• The Mac is bound to Active Directory
• Administrator credentials were entered successfully
Error details:
" & errMsg buttons {"OK"} default button "OK"
end try
end tell
Original AppleScript
Original version of the script included to show the basis for revision and improvement.
applescript
-- First, we need to get the old home folder name
-- Then we need to get the new home folder name
-- We need to verify that the new user's home folder name is correctly entered
-- This asks for the user name, then confirms it's correct. It gives the option to quit at
-- this point. This script does not check LDAP to ensure the username is correct.
tell application "Finder"
set validAnswer to false
repeat while (validAnswer = false)
display dialog "Please give me the Active Directory user's home folder name for the account you're migrating." default answer ""
set ADUserName to text returned of result
display dialog "Is " & ADUserName & " the correct Active Directory user name?" buttons {"Yes", "No", "Quit"} default button 1
if result = {button returned:"Yes"} then
set validAnswer to true
else
if result = {button returned:"Quit"} then error number -128
end if
end repeat
-- Now that we have the AD user name, we need to confirm it's in the right place
display dialog "Make sure the user's home folder is now in the /Users directory. Click 'OK' when that's done and not before" default button 1
display dialog "LAST CHANCE! Bad things may happen if I don't have the correct name or the home folder isn't in the proper directory. Are you sure?" buttons {"No Way", "Go For It"} default button 1
-- Now we try to change the owner and group permissions on the folder
try
do shell script "chown -R " & ADUserName & " /Users/" & ADUserName with administrator privileges
on error
display dialog "Something went wrong. Sorry.
It may be a typo, or I can't find the name in A.D."
try
do shell script "chgrp -R staff /Users/" & ADUserName with administrator privileges
on error
display dialog "Something went wrong. Sorry.
It may be a typo or I can't find the name in A.D."
end try
end try
display dialog "Successfully migrated " & ADUserName
end tell
Comparison Value
Including both the original and revised scripts demonstrates the value of this sample for editing and documentation. It shows how improvements to technical writing can strengthen an internal administrative tool by making it easier to understand, safer to use, and easier to maintain.
Areas of improvement include:
- clearer user-facing prompts
- more explicit warning language
- improved administrator guidance
- more readable code comments
- cleaner presentation for portfolio review
Notes
This repository contains a portfolio edition of the original internal tool and documentation. It is included to demonstrate documentation revision and editing rather than original software development.
The sample preserves the core workflow and administrative purpose of the original utility, but it does not represent a production-supported enterprise tool.