You’ve run the test batch and the files are there. Then someone opens a drilling program: the author says System Account, the created date is last Tuesday, and the revision history is gone. The data copy usually works. Migrations that hurt tend to fail later, on metadata, versions and sign-off.
This is what we’ve learned moving SharePoint and document estates for Oil & Gas, Financial Services and Manufacturing clients. Older runbooks miss three recent changes:
- SharePoint Online now applies version history limits to new libraries across the organisation, and those limits can permanently trim history you’ve just migrated.
- Migration Manager added delta sync for file shares in July 2025, so Microsoft’s own tools now run incremental file-share passes.
- The SharePoint Migration Assessment Tool (SMAT) is out of support from 1 October 2026. Use the SPMT scan instead.
What happens to metadata and version history in a migration?
Metadata and version history carry over only when the tool supports your source, and only as far as you configure it to. Created and modified dates and author names are the fields most often lost, especially when the source is a file share.
Start with the source, because it decides what history even exists. A Windows file share has no version history to migrate. On a shared drive full of well files or engineering records, the revision trail lives in file names (“Rev C”, “_final_v3”) and folder structure.
Getting that into SharePoint is a metadata-mapping job: parse the revision, well identifier or drawing number into columns during migration. SharePoint Server, DocuShare and Google Drive do hold real version chains, and that’s where the version decision matters.
Version options in each migration tool
In the SharePoint Migration Tool (SPMT), the “Migrate file version history” setting gives three choices:
- Off: only the latest version moves.
- On, keeping all versions.
- On, with a set number of versions to migrate.
SPMT also migrates the managed metadata terms in use on a site, with site fields and content types as a separate option. Its “migrate files created after” and “modified after” filters let you leave old content behind in line with your retention schedule.
Other tools handle versions differently:
| Tool | Version options | Watch for |
|---|---|---|
| SPMT | Off, all versions, or a set number | Site fields and content types are a separate option |
| Migration Manager | Google sources only: none (the default), a set number, or all versions up to 50,000 | Microsoft recommends 10 or fewer for performance; Dropbox, Box and Egnyte come across as the latest version |
| ShareGate | All versions or the latest X | Versioning must be on in the destination library; a majors-only library won’t receive draft versions |
Choose the version setting by record type
Pick the setting for each type of record rather than one setting for the whole project:
| Content | Typical setting | Why |
|---|---|---|
| Well files, regulatory submissions, signed engineering records | All versions, or current version plus a read-only archive of the history | The history is part of the record |
| Active engineering drawings | Current revision in the working library, prior revisions archived | Engineers need the latest; auditors need the chain |
| General team documents | Latest version, or a small number | History has little value, and every version adds data to move |
Version counts affect throughput too. Each version is another copy of the file, so five versions is roughly five times the data per document.
We treat version history as a records-management decision. On our most recent DocuShare migration we moved current content and kept the version chain as a read-only archive. Engineering metadata such as drawing number, revision, discipline and asset ID needs a mapping table tested on a representative slice first. Read the DocuShare case study.
Created and modified dates, and authors
Most migrations lose fidelity on dates and authors without anyone noticing. Plan to test them in the pilot, per tool and per source.
From file shares, SPMT fills both Created By and Modified By from the NTFS file owner. It doesn’t read the author stored inside an Office document. On many file servers the owner is BUILTIN\Administrators or a service account, so without a user mapping file every document shows the system account as author. A mapping file can remap the owner to a real user or group.
ShareGate has a “Preserve authors and timestamps” option that copies Created, Created By, Modified and Modified By. For file-share copies, its documentation says the Created date is set to the copy date. Migration Manager’s cloud connectors can reset created and modified dates to the migration date, so test dates per connector in the pilot.
Set destination version limits before you migrate
SharePoint Online now applies version history limits at organisation, site or library level, either Automatic or a manual count with optional expiry. Versions over a library’s limit are deleted permanently, bypassing the recycle bin. If you migrate 200 versions into a library capped at 100, you lose 100.
Set the library version limits before the migration runs, and have the Purview landing zone live before any regulated wave.
Content under a retention policy or eDiscovery hold ignores the limits, and records block version deletion. That’s why retention has to be in place first for regulated content.
How do you test-run a migration before cutover?
Run a pilot wave on a small, representative slice, then re-run the same jobs incrementally until the final pass is a short delta. Every mainstream tool supports this, though each one decides what counts as “changed” in its own way.
We pilot on the smallest, simplest department to prove the mechanics end to end, then fix what breaks before the next wave. The sequence after that:
- Later waves bring in the hard cases: deep folder paths, unique permissions, a large mailbox, a critical app.
- Once the pilot is signed off, production moves in waves with validation checkpoints.
- Each wave is re-run until the delta is small.
- The last pass runs behind a source freeze or read-only window, so nothing is edited in both places.
For TD Wealth, 1+ TB of SharePoint 2013 content moved to SharePoint Online with ShareGate in phased waves with validation checkpoints. Where custom migration code is needed, we build runs to be re-runnable without creating duplicates.
How each tool handles repeat passes
SPMT lets you save a completed task and re-run it to copy only new or updated files. Source files older than the target are skipped. File-share files are matched by path, SharePoint Server items by list item GUID.
The SPMT incremental setting is global and must be set before the first job is submitted. An auto re-run option can repeat a task up to five times. Don’t rename or move migrated files in the destination before the final pass, or SPMT will overwrite them.
Migration Manager’s file-share delta sync copies only new or updated files by default, skipping any file whose destination path is unchanged and whose destination copy is newer. It doesn’t pick up permission-only changes at the source unless you choose “Migrate all files and overwrite any existing ones”, so re-run with overwrite after a permissions clean-up. The destination can’t be changed after the first run.
ShareGate’s “Copy if newer (incremental)” replaces an item only when the destination copy is older than the source. It suits repeated passes during a long coexistence window.
Quest On Demand Migration runs an initial bulk pass for SharePoint, then incremental passes that pick up new structures, new content and changes. For OneDrive it carries created and modified authorship, document properties and file versions.
How do you validate a migration and get sign-off?
A wave is signed off by workload, against a checklist agreed before the wave starts. Automated reports prove the data moved; business-owner sampling proves people can work with it.
The sign-off checklist by workload
Identity:
- Pilot and wave users sign in with MFA and land in the right Conditional Access policies.
- Report-only results reviewed, emergency access accounts tested.
Mail:
- Mailbox item counts and sizes match source reports.
- MX, SPF and Autodiscover resolve correctly after cutover.
- Inbound and outbound mail tested, including relay devices such as scanners and alerting systems.
- Shared mailboxes and delegates open for the right people.
Files, SharePoint and OneDrive:
- File and item counts reconciled against the source for every batch.
- Tool reports show zero unexplained failures. In Migration Manager, a file with version migration on is marked successful only when all its versions arrive, and MVERSIONDISABLE flags a destination library with versioning off.
- Permissions spot-checked on folders with unique access, such as HR, payroll and land files, comparing effective access in the source and the destination.
- A sample of files checked for authors, created and modified dates, version counts and mapped metadata columns.
- Destination version limits confirmed on regulated libraries.
Teams:
- Team and channel structure matches the plan, channel files open, owners assigned.
Devices and apps:
- Pilot devices compliant, Microsoft 365 Apps signing in, critical line-of-business apps tested end to end.
Compliance:
- Sensitivity labels, retention policies, DLP and audit logging behave as designed on migrated content.
Business-owner acceptance:
- A named owner in each area finds real records and signs off. The field superintendent pulls last month’s field tickets, engineering opens a drawing at the right revision, finance finds the approved invoices.
- The source stays read-only, not deleted, until sign-off and the rollback window has passed.
On the E.S. Fox DocuShare migration, every batch was reconciled against the source before sign-off, and phased cutovers kept production available.
When a check fails, start here
| Common issue | Likely cause | First checks |
|---|---|---|
| Permissions look wrong after file migration | Users not synced or mapped, Deny and special permissions dropped, inherited permissions not carried over from SharePoint Server sources | Confirm user mapping, then compare effective source permissions against mapped SharePoint roles |
| Author shows as System Account or Administrators | File-share owner is a built-in or service account | Review NTFS owners and add owner mappings to the user mapping file |
| Created dates show the migration date | Tool or connector treats files as new uploads | Check the tool’s author and timestamp settings; re-test the source with another tool in the pilot |
| Fewer versions than expected | Destination version limits, majors-only library, versioning off | Library version settings, retention coverage, tool version report |
| SharePoint or OneDrive migration is slow | Too many versions in scope, network path, throttling | Version setting, agent count, off-hours scheduling |
In what order should identity, mail, files, devices and apps move?
Identity goes first, then mail and files, then devices. Each step depends on the one before it, and doing them out of order breaks access without any error to warn you.
Identity first
File permissions only survive when each user has a matching account in the cloud. Microsoft’s guidance is that the easiest way is to synchronise Active Directory to Entra ID. SPMT’s automatic user mapping, on by default, matches on-premises users to Entra ID users.
Without synced users or a mapping file, migrated files take the destination’s default permissions. Nobody notices until a crew lead can see the payroll folder, or can’t see their own site’s safety forms. Mailbox moves, Conditional Access and device enrolment all key off the same cloud identity.
Mail and files, then devices
Mail and files come next, while people are still on their existing devices. Hybrid Exchange keeps mail flowing between old and new during phased moves, and incremental file passes keep the shares current until each wave’s cutover. Users change one thing at a time.
Devices come last. Intune enrolment and compliance-based Conditional Access need identities and the security baseline in place. A device enrolled before its user’s data has moved gives them a new machine pointing at the old world. For field crews on rotation, a device change needs a scheduled window at the yard or camp, and doing it last means one visit.
Apps run alongside all three:
- Inventory enterprise apps and legacy authentication early.
- Move sign-in to Entra ID as identity lands.
- Fix anything that sends mail over Basic auth before mail cutover.
- Test critical line-of-business apps in the pilot.
For the wider plan, including assessment, licensing, mail methods and network, see our Microsoft 365 migration guide.
Plan the metadata, version and sign-off decisions early
We’ve migrated SharePoint and document estates for clients including E.S. Fox (about 4 TB of DocuShare content) and TD Wealth (a two-year SharePoint consolidation). If you’re scoping a migration and want the metadata, version and sign-off decisions made before the first wave, talk to us.