Migrating Project Online Document Libraries Without Losing Links

Here's the pattern. A PMO finishes migrating its 120 active projects. Go-live runs cleaner than expected: schedules load correctly, dependencies survive, baselines are intact. Two weeks later a PM opens a project, clicks the Project Online document library link she has used for two years, and gets a browser error. The URL hardcoded the old PWA site collection. The PWA site is gone.

That one broken link is a nuisance. Discovering that 80 percent of your project document links are dead, after cut-over, when Project Online is in read-only mode, is a migration crisis that lands on the PMO director's desk before 9 a.m. on Monday.

Project Online document libraries are one of the most consistently under-planned parts of any migration. They don't appear in the .mpp file. They don't show up in the OData export. Because they technically live in SharePoint, most migration teams assume SharePoint will handle them. It won't, not without deliberate planning on your part before cut-over.

Context: this post is one piece of the Microsoft Project ecosystem retirement timeline, the consolidated reference covering all three Microsoft Project ecosystem retirements happening in 2026.

What you need to know upfront: Each Project Online project has a SharePoint site collection containing a document library. Those site collections are tied to the PWA permission model, and when Project Online retires on September 30, 2026, the URLs stop resolving. You have three migration paths: keep files in SharePoint and update links in the new tool, move files to modern SharePoint or OneDrive, or move files into your new PM tool's native storage. The right path depends on your SharePoint footprint and compliance requirements. The inventory work happens before cut-over, not after.

Why Project Online document library links break at cut-over

Project Online creates a SharePoint site collection for each project. Inside that site collection is a document library where PMs upload files, attach meeting notes, and store deliverables. The links you see inside Project Online point at URLs like https://yourorg.sharepoint.com/sites/pwa/projectname/Shared%20Documents/.

When the PWA site collection is decommissioned, those URLs stop resolving. Any reference to them, links in emails, bookmarks, task notes, document references from the new PM tool's project records, becomes a 404.

The secondary problem is permissions. Project Online document libraries inherit permissions from the PWA category-based access model. When that model disappears at cut-over, the site collections either lose their permission context or enter a read-only state. Links that technically still resolve may return a SharePoint login prompt for users who previously had access without re-authenticating, because the permission chain they depended on no longer exists.

A third problem sits beneath both: Power Automate flows that read documents from project site collections, trigger on document-upload events, or post notifications when files change will break silently after cut-over. There is no automatic error notification; the failure surface is when someone wonders why the weekly document-upload notification emails stopped arriving.

These three failure modes share a root cause: Project Online document storage is built on a SharePoint integration that the rest of the migration motion ignores. No export format carries it. No standard migration checklist covers it unless someone explicitly added it.

The three migration paths for project documents

There is no universal right answer. The path that fits depends on document volume, your organization's existing SharePoint maturity, and what your destination PM tool supports for native file storage.

Path 1: Keep documents in SharePoint, update the links in the new tool. Files stay exactly where they are. The migration work is re-pointing every document link in the new tool to the existing SharePoint URL, and verifying that the site collections remain accessible with a correct permission model post-cut-over. Lowest file-movement effort, most link-management work.

Path 2: Move documents to modern SharePoint Online or OneDrive, then link from the new tool. The existing PWA-linked site collections are legacy SharePoint constructs built around the PWA model. This path uses the SharePoint Migration Tool to copy content into standard modern SharePoint team sites or OneDrive folders, then re-links in the new tool. More upfront effort, cleaner long-term governance result.

Path 3: Move documents directly into the new PM tool's native storage. If your organization wants to exit the SharePoint dependency entirely, or if the destination tool ships first-class file storage attached natively to projects, this path moves files into the new system. Trade-off: higher effort for the file movement, and you lose SharePoint version history unless the new tool can import it.

The diagram below maps each path from the source PWA site collections to the post-migration storage destination.

Path 1: Keeping documents in SharePoint and updating the links

This path involves the least file movement but requires systematic link re-pointing across every migrated project. The steps are:

1. Inventory every project site collection before cut-over. Use the SharePoint admin center's active sites report, filtered by your PWA site collection URL pattern, to list every project-linked site. Export as a CSV with site URL, project name, and document count.

2. Decide which site collections to preserve and which to retire. Active projects being migrated get their site collection preserved. Projects being archived can have their documents bulk-exported before the site collection is retired.

3. Rebuild the permission model on preserved sites. PWA site collections inherit permissions from the PWA category-based model. After cut-over, that inheritance context is gone. Rebuild using standard SharePoint sharing or Azure AD security groups. The simplest approach: add the relevant users as site members directly, revoking the old PWA-linked group memberships.

4. Update document links in the new PM tool. The new tool's project records will have document link fields or attachment references. Update each one with the modern SharePoint URL for that project's site. If the new tool exposes an API, batch-update from the inventory CSV built in step 1.

The limitation of Path 1: site collections created by Project Online carry PWA-specific metadata columns and content type IDs that become noise once disconnected from the PWA model. You inherit that cruft. If your document governance requirements are strict or you're consolidating your SharePoint environment anyway, Path 2 produces a cleaner result.

Path 2: Moving documents to modern SharePoint Online

Microsoft's SharePoint Migration Tool (SPMT) handles bulk migration between SharePoint sites and can source from PWA-linked site collections. The recommended flow for this path:

1. Create a modern SharePoint team site as the document destination. Many organizations use a single "Project Documents" site with a top-level folder per project.
2. Run SPMT to copy document content from each PWA site collection to the destination. SPMT preserves file metadata and version history.
3. Spot-check a random sample of the copied documents against the source for completeness and metadata accuracy.
4. Update document links in the new PM tool to point at the modern SharePoint URLs.
5. Mark the old PWA site collections read-only, leave them accessible for 30 to 60 days post-cut-over for users with saved bookmarks, then retire them.

This path works well for organizations already investing in Microsoft 365 governance. The trade-offs: SPMT migrations need planning, permissions need rebuilding on the destination site, and the migration itself takes time proportional to document count and total file size. Budget two to three days of technical effort per 10,000 documents as a rough starting estimate.

Path 3: Moving documents into your new PM tool's storage

If your organization wants to exit the SharePoint dependency entirely, or if the new PM tool ships first-class native file storage attached to projects, moving files directly into the new tool is the cleanest option for the long run. The practical steps:

1. Export documents from each PWA site collection, either manually or via SPMT to a local or cloud staging location.
2. Import documents into the new PM tool, attaching them to the correct projects via the tool's file-upload or API endpoint.
3. Verify attachment counts against the project inventory before declaring each project migration complete.

This path has the cleanest result: documents travel with the project inside a single system, no external SharePoint dependency, no permission model to maintain separately. The cost is higher: you handle every file movement, and you lose SharePoint version history unless the destination tool can import file versions explicitly.

What actually breaks: four URL categories to check

Document link failures after cut-over come from four URL patterns. Work through this list before your cut-over date; finding these post-cut-over is significantly more expensive than finding them before.

PWA project site collection URLs. Every link in the form https://yourorg.sharepoint.com/sites/pwa/projectname/Shared%20Documents/ breaks when the PWA site is decommissioned. These links appear inside the new tool's project records, inside task notes, and in PM emails sent over the past several years. They need systematic re-pointing, not just a note to "fix them later."

Direct file links. Links pointing at a specific file, not just a library folder, break when the file moves. Path 2 and Path 3 migrations must update every direct file link after each file is moved to its new location.

PWA task attachment links. Some PMs attach documents directly to tasks inside Project Online. Those attachments live in the project site collection and are linked from the task record. Migrating the task data to the new tool does not migrate the attachments; the links become orphaned silently.

Power BI document metadata queries. Power BI datasets that pull from SharePoint document library columns (not the OData reporting feed, but the document properties such as approval status, owner, or document type) need new data source references after the site collections move or retire.

Before you migrate: building the document library inventory

Running a document inventory takes one to two days for a mid-size PMO. The output is a spreadsheet with:

• Project name and current site collection URL
• Document count and total file size per site
• Whether the project is being migrated (active) or archived
• Assigned migration path (keep in SharePoint / move to modern SPO / move to PM tool)
• Owner responsible for post-migration link verification

The free Project Online Inventory Checklist includes a document library section as part of the pre-migration discovery workflow. The broader project online migration checklist covers document libraries alongside OData feeds, Power Automate flows, and integrations under the "views, reports, and storage" category.

One consistently missed item: documents referenced in task notes rather than as formal attachments. Task notes don't export in the .mpp file and don't appear in the OData feed. They are free-text fields where PMs paste SharePoint links, Confluence page URLs, and OneNote section links. Those references break at cut-over and are invisible in any automated document audit.

Before cut-over, run a manual spot-check of task notes on your ten highest-priority active projects. Assign someone to open each task, scan the notes field for any URL, and log every URL found in the inventory. This step takes a few hours and catches a category of broken links that no automated tool surfaces.

Running a post-cut-over link check

After cut-over, run a link audit before opening the new system to the full PM population:

1. Export all document links from the new PM tool via its API or admin export function.
2. Test each URL programmatically. Any link returning a 4xx status, or any link that redirects to a SharePoint login prompt when it should resolve directly, is a failure.
3. Categorize failures: wrong URL (needs re-pointing to the correct new location), missing file (file was not moved and needs to be located and re-uploaded), permissions issue (file is at the right URL but access was not granted correctly).
4. Fix systematically, working from highest-priority projects outward, before end-users encounter the broken links on their own.

A working document link is invisible to end-users. A broken one, discovered when a PM needs a contract file twenty minutes before a steering committee meeting, is a high-visibility failure that damages confidence in the migration and generates escalations during the busiest week of the transition. Clearing link failures before go-live costs an afternoon. Fixing them reactively after go-live in response to individual PM complaints costs weeks of distraction during a period when the team should be stabilizing the new system.

Use the Migration Preview tool against your sample projects before committing to a path. It surfaces which data elements from your current project files survive the tool boundary, so you understand the full scope of the re-linking work before your cut-over date arrives.

Run the free Migration Preview Upload a sample .mpp file and see which data elements survive the tool boundary before you commit to a migration path. No signup required. → Open Migration Preview

Microsoft Project Online™ is a trademark of Microsoft Corporation. Onplana is not affiliated with Microsoft.