Install the Active Directory agent

Active Directory lives inside your network, where MigrateX cannot and should not reach. The agent is one PowerShell script that runs on a Windows server in that network, reads the domain with Microsoft's own Active Directory module, and calls out to MigrateX over HTTPS. Nothing connects in, so two domains with no trust, VPN or route between them can still be synced — each has its own agent and MigrateX carries the plan between them.

Before you start

• A domain-joined Windows Server (a member server is fine; it does not have to be a domain controller) with Windows PowerShell 5.1.
• The Active Directory PowerShell module: Server Manager → Add features → Remote Server Administration Tools → AD DS Tools → Active Directory module for Windows PowerShell.
• Outbound HTTPS (443) from that server to your MigrateX address. No inbound rule is needed.
• A Windows account to run it. For a source domain an ordinary domain user is enough. For a target domain, delegate create and manage user, group, contact, computer and OU objects on the OUs you sync — not Domain Admin.
• You are an owner in MigrateX (owners create agents).

Step by step

1. Create the agent in MigrateXOn Directory sync, under Active Directory agents, type a name (for example “Head office DC”) and press Create agent. The token appears once, at the top of the page. Copy it now.
2. Download the scriptPress Agent script and save MigrateX-AdAgent.ps1 to a folder on the server, such as C:\MigrateX. It is plain text — read it first if you like.
3. Run it once with the tokenSigned in as the account that will run it, open PowerShell in that folder and run the first command below. The token is saved encrypted for that Windows account on that machine, and the first upload happens straight away.
4. Check MigrateXRefresh Directory sync. The directory shows the domain name, Agent online and the number of objects read.
5. Schedule itIn Task Scheduler create a task that runs every 15 minutes, whether the user is logged on or not, as the same account, with the second command below. Add -Mode ReadWrite only on a domain that is the target of a sync.

# once: store the token and do the first upload
.\MigrateX-AdAgent.ps1 -Server https://your-migratex-address -Token mxa_… -SaveToken

# scheduled task (source domain: read only)
powershell.exe -ExecutionPolicy Bypass -File C:\MigrateX\MigrateX-AdAgent.ps1 -Server https://your-migratex-address

# scheduled task (target domain: also applies the changes you approve)
powershell.exe -ExecutionPolicy Bypass -File C:\MigrateX\MigrateX-AdAgent.ps1 -Server https://your-migratex-address -Mode ReadWrite

# optional: read only one part of the tree
… -SearchBase "OU=Staff,DC=corp,DC=local"

You see: each run prints one line — how many users, groups, contacts, OUs and computers it uploaded — and, in ReadWrite mode, how many changes it applied and how many failed.

What each run does

1. Says hello with its token; MigrateX records the domain name and the time.
2. Reads users, groups with their members, contacts, the OU tree and computer accounts, and uploads them in pages. Built-in system accounts are skipped.
3. In -Mode ReadWrite only: collects the changes you applied in MigrateX for this domain, carries them out, and reports each one back as done or failed with the reason.

What it can and cannot change

How the access works

• The token is a long random value. MigrateX stores only its SHA-256 fingerprint, so it cannot be shown again or recovered from the database.
• On the server it is kept in agent.token, encrypted with Windows data protection: only that Windows account on that machine can read it.
• The script refuses any MigrateX address that does not start with https://.
• MigrateX keeps only the fields the sync uses — names, addresses, titles, phone numbers, group membership, OU paths. Anything else is discarded on arrival.
• Revoke at any time: an owner presses the ✕ next to the agent. The token stops working immediately; nothing in Active Directory changes. Then delete the scheduled task and the folder.

Things worth knowing

• Changes reach an Active Directory target at the agent's next run, so allow up to one schedule interval after pressing Apply.
• While a batch is waiting for the agent, a second one is not queued on top — a scheduled sync simply waits.
• Every action is safe to repeat: if a run is interrupted, the next one finishes the batch without creating anything twice.
• New users land in the OU with the same path as in the source when OU structure is part of the sync; otherwise in the domain's default Users container.
• For a move between two Active Directories that also needs SID history or passwords carried over, MigrateX prepares the objects and OUs; that last step belongs to Microsoft's own migration tooling.
• Lost the token? Remove the agent and create a new one — it takes a minute.