Using Invoke-SPOSiteSwap to Swap in a New Root Site in Office 365

Things we used to think of as miracles happen almost every week in Office 365. The latest thing that impressed me is the ability to swap an existing site into the root site of your tenant using the Invoke-SPOSiteSwap PowerShell cmdlet.

The Sympraxis tenant has been around since practically the old BPOS days, so the root site originally was effectively a SharePoint 2010 -style site. (Remember when we could decide whether we wanted the 13 or 14 experience? Meet the old modern – same as the new modern…)

The cmdlet is pretty simple. You just provide the SourceUrl, the TargetUrl, and the ArchiveUrl – where you’d like the old site to be moved.

  -SourceUrl <string>
  -TargetUrl <string>
  -ArchiveUrl <string>

In my case, it looked like this:


Making the swap is actually pretty painless, but there are some constraints. Neither the source or target site can be:

  • Connected to an Office 365 Group
  • Be a Hub Site, or
  • Be associated with a Hub Site

I found the documentation to be a little unclear on this, so I’ve already made some suggestions about how to make it clearer in a pull request.

When I first tried to run the cmdlet, I got the error:

Invoke-SPOSiteSwap : The site cannot be used with this cmdlet because it's a hub site At line:1 char:1 + Invoke-SPOSiteSwap -SourceUrl ... + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~         + CategoryInfo          : NotSpecified: (:) [Invoke-SPOSiteSwap], ServerException     + FullyQualifiedErrorId : Microsoft.SharePoint.Client.ServerException,Microsoft.Online.SharePoint.PowerShell.SwapSite

My Intranet site was a Hub Site, so I needed to:

  • Dissociate the sites associated with Intranet
  • Demote Intranet from being a Hub Site
  • Do the swap
  • Promote Intranet to a Hub Site again
  • Re-associate the sites which were associated with it before

All in all, another great tool to add to out toolkit. It is useful in a case like mine, but also consider the case where you want to launch an entirely new Intranet look and feel. You could build out the root site as much as possible, then swap it in when you are ready! You do need to think things through, especially with respect to search indexing, links in things like Words docs (just don’t do this!), etc. As with many things, the technical part is now easy, but it doesn’t mean you get off the hook on thinking things through.


from Marc D Anderson’s Blog