Best Practice Intranet SharePoint

SharePoint Site Swap – an adventure for a party of medium to high level players

Insights into using the SharePoint Site Swap function, and potential pitfalls

I spend an inordinate amount of my time reviewing the Microsoft roadmap and the many elements in the Office 365 Admin Center Message Centre; partly because there’s so much new stuff coming out all the time and partly because I’m a masochist like that.

Digital Workspace technologies is my sweet spot; I tend to read up on everything Microsoft is doing around that and play around with them as soon as the chance avails itself. I use this to incorporate the knowledge and features into our products & services and so I can keep our clients up to date (and keep us one step ahead of our competitors). I supplement this with my annual trip to the huge Ignite conference in the US, where I get to talk to some of the Microsoft programme managers and engineers and simultaneously attend every session I can squeeze in over the 5 days (I walked 74.5km during Ignite this year. In brogues). Invariably, I then spend the next couple of months frustrated that the new features that were showcased and promised aren’t available on our tenant for me to evaluate.

So, with considerable excitement, I noticed that the SharePoint Admin Center updates, described in the Ignite 2019 blog, became available at the end of November for us.

This is what the Message Centre announcement promised:

“Replace root site – You can replace your root site with another site from the SharePoint admin center. The original root site is moved to a different URL and can be restored, if necessary. This feature will only be available for limited customers. For more information, refer to Message Center post MC189866.”


Setting the scene “You are sitting in a bar when…”

With only mild trepidation we set about swapping out our internal intranet Classic Site (with a Modern landing page) for our shiny new Modern site linked to an ‘All Company’ Teams Area. This was something we had wanted to do for many months and looked like it was super easy. We used the new PowerShell cmdlet: Invoke-SPOSiteSwap, though Microsoft are promising a Swap site button in the SharePoint Admin Center.Site Swap

Using PowerShell, it was super easy:

  1. Connect to SharePoint Online as a global admin or SharePoint admin using the SharePoint Online Management Shell
  2. Run Invoke-SPOSiteSwap.
Invoke-SPOSiteSwap -SourceUrl -TargetUrl -ArchiveUrl
SourceUrl is the new site you want to use, TargetUrl is the old root site you are replacing and ArchiveUrl is the location where you want to archive the current root site.

Watchouts – challenge rating 1

A couple of immediate gotchas that Microsoft publicise:

  • The source and target sites cannot be connected to an Office 365 group
  • The source and target sites cannot be connected to a SharePoint Hub site. In the latter case, it’s a fairly simple matter to remove the association, do the swap, and then re-associated with your preferred Hub. Note that this means that the root site need not be a Hub and can be a ‘child’ site (if you want to think hierarchically). Equally you can make the newly swapped root site into a Hub site; this hurts my head less, but it’s still useful that it doesn’t have to be the ‘parent’ n the relationship, just because it is the first thing that people encounter.


So, the site swap happens pretty seamlessly and without initial drama. We just let people know what we were doing and asked them not to mess with things for half an hour. We even provided a nice link to the old home site, which was now to be found at:


End of level boss encounter – challenge rating 9

It didn’t take that long to realise that we had made a mistake…

red cross of dreadThe first thing I noted was that a document I had open was warning that it couldn’t complete its autosave. Then I spotted the Red Cross Of Dread on my OneDrive sync client icon. The penny dropped…

When we designed our intranet, we valued interaction and sharing of content between sites over the competing view that everything should be a separate disconnected site collection. Consequently, almost everything was a subsite of our master site. This let us do clever things by referencing assets and lists etc. that were mounted at the home level. It worked very well for us for many years. Until we did a site swap.

What happened is this: all our department sites and their content had absolute addresses based on our old root site. So our Sales site, for example, was:


Key documents, many of which we have pinned or wired up to buttons and navigation tiles, have paths such as:


All these instantly became broken as the post-site-swap address became something like:



Even some of our webparts broke

web part broke

In hindsight, Microsoft did give us fair warning:

“The previously designated root site automatically gets archived along with any subsites that may have existed.”

We weren’t thinking ‘archive’ just new location, but the effect was the same.

Picking up the pieces, healing the injured

We are now enjoying a rapid re-architecture of the site (using the rather excellent Sharegate tool to promote subsites to site collections), while fending off the withering glares of our inconvenienced colleagues.

Learning from other people’s mistakes

I leave you with this helpful advice, in the hope that you cunningly avoid the boss level encounter (and still gain the experience points):


Microsoft provides some pretty decent guidance here: We really should have read it carefully and thought about it first. In our defence, we may have made the same mistake, since the only real warning was a single bullet point, hidden in plain sight under Limitations:

All subsites contained with the source and target sites will be swapped.

Restructure first

Subsites were always going to break, regardless of how much we read. Before doing the site swap, promote all your subsites to new site collections. You could just recreate them and copy the content across if your environment is simple.

Warn your staff of the pain to come

Favourited links, pinned documents, local sync, shortcuts, inter-document links; they are all going to die, horribly (except where you made them relative links). Prepare your staff for the pain, get your support desk doubly ready.

Remember people mostly have multiple devices, so the pain is multiplied (using Edge or the new Edge Chromium helped, as at least browser favourites synchronise across all devices).


Make sure that you force the indexing process so that Search very quickly finds all the stuff in its new location – it’ll save your bacon when staff can’t remember where the things they linked to actually were.

Permissions and governance

Think about what permission inheritance might now be broken. It’s not just user permissions; any ‘up the tree’ references to master lists etc. are going to be in trouble.


SharePoint’s global navigation is rubbish. It’s also very easy to lose sites as the only place to see every site collection is from SP Admin, and that’s going to be full of random Microsoft Teams sites etc. Make sure you document all your sites and design a replacement global navigation before you start (we were lucky; our navigation was embedded as a termset, plus we have a rather excellent global navigation megamenu we built for our Hadron product that we could simply update with the revised URLs).


You are going to have to walk everyone through how to fix their locally synced content, since all their synchronised libraries are now broken. Firstly, make sure that they DO NOT save anything to the local drive as they will no longer update to the cloud. They will also see a bunch of errors in the OneDrive sync client in the tool tray (bottom right). To sort those out:

  1. Open Windows Explorer and click the company’s Sync group, the one with the building icon. This shows the sync’d libraries in the right pane. Note any that don’t have a status icon as these are the ones that are now broken: Sync
  2. Open the OneDrive sync client settings (right click and choose settings). On the Account tab, click Stop Sync on the folders identified in step 1. This should remove the sync errors.
  3. Now go back to Windows Explorer and delete the folders

URL edit

Another new feature is the ability to edit SharePoint site URLs. This is handy when you find you have conflicting site names, probably because of Microsoft Teams again.

Page upgrades

Now that you have survived the site swap and dealt with the snagging, it’s time to ensure all your classic pages are converted to lovely, shiny (and fast) Modern pages. At Ignite 2019 I asked lots of Microsoft people and migration people (Sharegate, AvePoint et al) if there was any way to do page conversions. It was a resounding no.

This morning I came across this, just announced by Microsoft (post Ignite):

Transform classic pages to modern client-side pages

Automatic conversion of classic pages to Modern, via Powershell, .NET and (Preview) user UI.

Maybe you don’t need to get a student in after all.


Please drop me a line or comment if you have feedback on this. If you just want to comment on the RPG references in order to reveal your inner geek then that’s good too.




By Simon Hudson

Simon Hudson is an entrepreneur, health sector specialist and founder of Cloud2 Ltd. and Kinata Ltd. and, most recently, Novia Works Ltd. He has an abiding, evangelical interest in information, knowledge management and has a lot to say on best practice use of Microsoft Teams, SharePoint and cloud technologies, the health sector, sustainability and more. He has had articles and editorials published in a variety of knowledge management, clinical benchmarking and health journals. He is a co-facilitator of the M365 North User Group Leeds and is Entrepreneur in Residence at the University of Hull.

Simon is passionate about rather too many things, including science, music (he writes and plays guitar & mandola), skiing, classic cars, technology and, by no means least, his family.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s