SharePoint Online Site Swap Feature Rolling Out

Swap Old Sites for New With the Invoke-SPOSiteSwap PowerShell Cmdlet

Office 365 Notification MC187289
Office 365 Notification MC187289

Office 365 Notification MC187289 posted on August 5 told us that Microsoft has started the roll-out of the SharePoint “site swap” feature described in Office 365 roadmap item 51259. The original plan for the roll-out called for a measured deployment (some would say “slow”) across different categories of tenants and is due to complete in October 2019. On September 6, Microsoft issued notification MC189866 with news that they had started to deploy to to Office 365 tenants with less than 10,000 tenants. Larger tenants will still have to wait for a further update. Fortunately, my tenant was updated in the first part of the deployment and I could swap sites to my heart’s content.

The new feature uses the Invoke-SPOSiteSwap PowerShell cmdlet (part of the SharePoint Online PowerShell module from version 16.0.8812.1200 on). The latest version is 16.0.9119.1200, but I used the cmdlet with version 16.0.9021.1201. The cmdlet swaps an entire site collection.

Old SharePoint Site

I’ve been using SharePoint Online since 2011 and my root site was a very old page (Figure 1) that I put together years ago when sites could still be accessed by external users. I haven’t paid any attention to the page for a long time.

Figure 1: Old SharePoint root site

To replace the root page, I created a new SharePoint communications site and made some minor changes to it. I then ran the Invoke-SPOSiteSwap cmdlet to swap the new communications site to become the root site using this command:

# Swap a SharePoint site
Invoke-SPOSiteSwap -SourceURL https://office365itpros.sharepoint.com/sites/NewMarketingComms -TargetURL https://office365itpros.sharepoint.com -ArchiveURL https://office365itpros.sharepoint.com/sites/OldMarketingComms

Invoke-SPOSiteSwap starts off a background job to move things around. In this case, it took the old root site (https://office365itpros.sharepoint.com) and moved it to an archived site (https://office365itpros.sharepoint.com/sites/OldMarketingComms) and replaced the root site with the new communications site that I had updated (https://office365itpros.sharepoint.com/sites/NewMarketingComms). After a few minutes (you’ll see a 404 error while the moving around happens), the new root site was available (Figure 2). It was all very easy.

The new root page after Invoke-SPOSiteSwap does its magic
Figure 2: The new root page after Invoke-SPOSiteSwap does its magic

Audit Records

Office 365 captures audit records when you run Invoke-SPOSiteSwap to start the background job (SiteSwapScheduled) and when the job completes (SiteSwapped). These records are visible through the Audit log search in the Security and Compliance Center. They can also be found with the Search-UnifiedAuditLog cmdlet using a command like:

# Find records for SharePoint site swaps
Search-UnifiedAuditLog -Operations SiteSwapped, SiteSwapScheduled -StartDate 7-Aug-2019 -EndDate 8-Aug-2019

Some Restrictions

Some restrictions exist. The source or target sites can’t be associated with an Office 365 Group (team) or a hub site. The target site can only be the root site or the search center. There’s several other notes to read up on in the documentation. Basically, this is a focused cmdlet that does what it says: Invokes a job to swap the location of a site with another site while archiving the original site.


Read more about managing SharePoint Online in the Office 365 for IT Pros eBook, including many other PowerShell examples.

9 Replies to “SharePoint Online Site Swap Feature Rolling Out”

    1. I assume when the cmdlet shows up. That’s when I knew.

  1. Hi, how do you know that you can not perform swap sites with O365 groups? Aren’t all of new SPO sites associated with a group?

    1. You know that you can’t swap group-connected sites because Microsoft says so…

  2. Questions:

    1. What is the difference using this “Invoke-SPOSiteSwap” cmdlet and “Make Homepage” button to make a modern page as the main homepage?

    2. If I use “Invoke-SPOSiteSwap” cmdlet to promote a new modern page, will this use the Master Page of the current homepage?

    Thank you for your replies.

  3. This has to involve a simple dns change by Msft, rerouting the tenant sub-domain to the modern site and a new subdomain to the old site. But as usual, Msft’s terminology is vague – is it SITE COLLECTION swap or SITE swap? What happens to the many subsites under the root site I need to retain at their existing urls?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.