This guide walks you through bulk migrating workgroup-joined Windows devices into an AD or Entra Joined state using PowerSyncPro.
 

Migration Scripts: https://github.com/PowerSyncPro/MigrationAgent/tree/main/BulkWorkgroup

It is designed for environments where:

• Devices are not joined to an Active Directory domain or Microsoft 365 Entra
• You have remote management of machines (RMM, etc)
• You need to preserve the user’s local profile

Use Case

You have standalone Windows machines (workgroup only) and need to migrate them to AD or Entra Joined without requiring reimaging, Autopilot, or user-profile disruptions.

Limitations

• Only one local profile per device can be migrated.
  • If multiple local profiles exist, you must designate which one to migrate.
• Additional users may sign in post-migration, but their prior local profiles will not be automatically migrated.
• Workstations must be licensed with Windows 10 / 11 Professional or higher.
  • Windows Home versions do not support AD or Entra join.
  • Verify this using your RMM / Management tools before attempting a migration.

Prerequisites

Setup Steps

Create the Migration CSV

Create a file named mig_db.csv containing these headers:

computer_name,local_username,target_upn,target_identity

Field definitions:

You may use the blank CSV provided in the repository.

Populate this CSV with the machines and local username combinations you wish to migrate.  When the script runs it will check if its running on a machine listed in this CSV.  If it is, it will check if the specified local user exists.  If everything appears correct, it uses this information to build the translation table.

Populate User Identity (SID or GUID)

For Entra

On a machine with Microsoft Graph Powershell installed, Run:

.\1-Lookup_User_GUID_or_SID.ps1 -CsvPath .\mig_db.csv -TargetType Entra

You will authenticate against the target Entra tenant. The script resolves each UPN to its Entra Object ID and writes the value into target_identity in the CSV.

This can also be manually populated from the Entra Portal if you do not want to use the script.

For AD

On a machine with a connection to the Target Active Directory, Run:

.\1-Lookup_User_GUID_or_SID.ps1 -CsvPath .\mig_db.csv -TargetType AD

The script will lookup the UPNs listed in the CSV in Active Directory and write the current SID to the CSV under target_identity. This will be used by the migration script to build a translation table for the local user to the domain user.

This can be manually populated from Active Directory Users and Computers, it is shown under objectSID in the Attribute Editor.

Populate the Dummy AD Environment

PowerSyncPro requires each device to exist in a source directory. Since these machines are workgroup-joined, you must create dummy computer objects inside an AD domain.

You may use:

• A existing AD domain, or
• A dedicated dummy domain (recommended)
  • The PowerSyncPro server can be promoted to a domain controller and used as a dummy domain if necessary.

No communication between the migrating workstations and the dummy domain is required.  It solely acts as a place to store computer objects so that PowerSyncPro can import them into its database.

Requirements

• Promote the PSP server to a domain controller (if using a dedicated dummy domain).
• Add the dummy domain as a Source Directory in PowerSyncPro.
• Ensure that the schedule is setup within PowerSyncPro (Sync Service -→ Schedule)
• Create a Match Only sync profile between the dummy domain and target directory (Entra or AD).
• Only computer objects matter for this process.
• No matching rules are required, this is solely to ensure that PowerSyncPro syncs computer objects from the source / dummy domain into its database.

Create the dummy AD objects

On the source domain controller, run:

.\2-Create_Dummy_AD_Objects.ps1 -CsvPath .\mig_db.csv

or

.\2-Create_Dummy_AD_Objects.ps1 -CsvPath .\mig_db.csv -TargetOU "OU=PSP Computers,DC=pspdummy,DC=local" 

• CsvPath is the path to the CSV File
• TargetOU is the distinguished name of the OU where the computer objects will be created.
  • TargetOU is optional, by default objects will be created in the default “Computers” container.

Notes:

• The script creates AD computer objects matching the computer_name values.
• After creation, run a PSP sync to import these objects.
  • Sync Service Tab -→ Schedule -→ Run Now

After the objects are created and the sync has run, you can confirm they exist using the “Single Object Report”.

Licensing Reminder

Your PSP license must include:

• Source: dummy domain (dummy.local)
• Target:
  • Your Entra tenant (company.onmicrosoft.com) or
  • Your Target AD Domain (domain.company.com)

Build Runbooks and Batches

Create the Runbook

Create a new runbook for this migration and obtain the GUID of the runbook.

For Migrations Targeting Entra

• Migration Agent Tab → Runbooks → Create
  • Source Directory: Dummy Domain
  • Target Directory: Entra
• Startup Tab:
  • Ensure you setup a Fallback Username / Password (Breakglass Account)
  • Enable Prevent Login
• User Experience Tab:
  • Customize as needed, can be left as default.
• Device State Tab:
  • Remove From: All Directories
  • Domain Join: Entra ID
  • Enroll to Intune if Necessary
• Permission Updates Tab:
  • Leave as Default
• App Reconfiguration Tab:
  • Can likely be left as default.  If the workgroup joined machines are currently using the same Entra / M365 tenant as the target, no reconfiguration is needed.
• Completion Tab:
  • Can be left as default

 

 

Get Runbook GUID

You will need the GUID of the runbook that you just created.  This will be included in the script deployed to workstations.  This can be obtained directly from the SQL database or via Developer Mode in your browser.

• In a Chromium based browser (e.g. Chrome, Edge, Brave, Opera, etc) open the Runbooks page in PowerSyncPro.
• Press F12 to open Developer Mode (or Ctrl + Shift + I)
• Click the “Network” tab in Developer Mode
• Click the “Edit” button on your selected runbook.
• You will see a request for “EditModal” with your runbook ID as a parameter.
  • Ex: https://psp1.company.com/migrationAgent/Runbooks/EditModal?runbookId=df0a0278-9d4a-4c96-32dc-08de15914463
• You can right-click on the request and say Copy URL.
• The runbook ID is the GUID included after the “=” sign in the URL.
  • Ex: df0a0278-9d4a-4c96-32dc-08de15914463
• Save this runbook ID to your notes, you will need it to edit the script below.

Create a Batch

• Migration Agent Tab -→ Batches -→ Create
• Source Directory: Dummy Domain
• Target Directory: Target Directory (Entra or AD)
• Runbooks: Assign the runbook created above.
  • Available From: Time that you want users to be alerted of a migration being available after the script runs.  If you want it to prompt immediately, make it now, or in the past.
  • Enforced After: When you want the migration to be completed by.  Users will be forced to migrate at this time.
  • Timezone: Local, unless UTC is required.
• Computer Tab:
  • If your computer objects are already added to the dummy domain, you should be able to add them here.
  • If you want to migrate all computers, you can select “All computers except the following”, this will apply this batch to all computers in the dummy active directory.

Customize the Deployment Script

You must edit WorkgroupMigrator.ps1 downloaded from the GitHub before deploying it to your endpoints via RMM or other remote management tooling.

Update:

• $basePath
  • Directory where RMM will place the CSV and MSI (e.g. C:\Temp).
• $csvName
  • Name of the CSV created earlier (e.g. mig_db.csv).
• $domainName
  • Dummy domain FQDN (e.g. dummy.local).
• $RunbookGUIDs
  • GUID(s) of the PSP runbook to execute for migration.  You obtained this above.
• $PspMsiName
  • Filename of the PSP Migration Agent MSI you downloaded.
• $PSPServerUrl
  • Your PSP server’s Agent endpoint URL (e.g., https://psp1.company.com/Agent).
• $PspPsk
  • Migration Agent PSK for your server.

After updating, you will need to package the following files for deployment via your RMM or other remote tooling:

• The customized PowerShell script
• The CSV file
• The PSP Migration Agent MSI

RMM Deployment Instructions

Your RMM should:

• Copy the CSV, MSI, and PowerShell Script into the directory defined by $basePath.
• Execute WorkgroupMigrator.ps1 as Administrator or SYSTEM.

The script will:

• Load the CSV
• Confirm that it is running on a hostname contained within the CSV
• Install and register the PSP Migration Agent
• Build the required translation table
• Prepare the device for PSP-managed migration.

If the device is already part of an active batch, it will prompt for migration immediately.
Otherwise, it will wait for standard PSP batch scheduling.

The script logs to C:\Temp\Migration_Kickoff_Log.log