What does it do ?

The SharePoint site collection at the Office 365 tenant root typically occupies the preferred location for a company Intranet. Until now the only way to apply some modern SharePoint functionality was to create a new SharePoint page and make it the Home Page for the site.

Invoke-SPOSiteSwap is a SharePoint Online PowerShell cmdlet that can be used to swap out your old classic SharePoint root site in your Microsoft 365 tenant and replace it with a shiny new Modern Communication Site (preferable), Modern Team Site or Classic team Site.

How to use it

Download and install the SharePoint Online Management Shell (version 16.0.8812.1200 or later)

Run PowerShell (as administrator) and login to SharePoint Online with ..

Connect-SPOService -Url https://mydomain-admin.sharepoint.com

.. where mydomain-admin.sharepoint.com is your tenant admin URL for SharePoint Online (you can confirm this by opening the SharePoint Admin center from the Microsoft  365 admin center)

Once connected, run the following ..

Invoke-SPOSiteSwap -SourceURl https://mydomain.sharepoint.com/sites/home 
-TargetURL https://mydomain.sharepoint.com 
-ArchiveUrl https://mydomain.sharepoint.com/sites/archivedhome

Where ..

SourceURL – This is the new site that you want to swap with your old tenant classic root. If TargetURL is the tenant root then SourceURL must be an existing Modern Communication site, Modern Team Site or Classic Team Site.

TargetURL – This is your existing Classic root site in the Office 365 tenant (or existing Search Centre, not covered here)

ArchiveURL – location to archive existing root content. Must not currently exist even in deleted sites Recycle bin. If it does use Remove-SPODeletedSite cmdlet to permanently remove the deleted site.

How long does it take ?

Typically less than 5 minutes ! No content is actually being moved around so the size of your existing tenant root is not relevant here. Having said that the content is re-crawled after the move to rebuild the search index so that could take some time. You might

What to be aware of

  • Source & target sites cannot be associated with an Office 365 Group or Hub site.
  • If a Hub site association exists then remove this first and re-create after the swap process.
  • Featured Links will be lost in the process (displayed on SharePoint Home) so take note of these and re-create as required after the swap completes.
  • Note that currently the Classic Site Collection page will still list the tenant root site even though it’s now using a Communication site template.
  • You may get a 404 error in the browser if you try to access the root site during swap. Give it a few minutes.

Possible use cases

You could develop a new Intranet based on a Modern SharePoint Communication site and web parts then swap this into place when ready to go live.

You could also decide to start afresh (as I did) and simply swap in a new Communication site to the tenant root.

Thanks

I’d like to thank Wayne Ewington, Program Manager in the OneDrive & SharePoint team, who was kind enough to clarify some functionality for me.

Update !

This functionality is coming to the SharePoint Admin UI (demonstrated at Ignite 2019) where you can simply select your old classic root site and replace it with the URL of your new Communication site.

References

docs.microsoft.com