Dec 16, 2019
I’ve covered this before, but I’ll repeat myself: moving to SharePoint Online isn’t just about moving your documents.
You also need to move your users.
Not physically, of course. But you need to help your users transition to the new platform, and it should be as painless as possible for them.
You should spend some time preparing your users for the upcoming changes, educating them and answering their questions. Because, for most users, change is a scary thing.
But even if you spend countless hours educating your users and holding their hands through the migration process, they may still have bookmarks to content that you moved from your on-premises SharePoint server to SharePoint Online. They may have shortcuts and favorites?
Some of the documents that you migrated may have links to your old on-premises SharePoint installation. Are you going to update every single document that contain hyperlinks to the old SharePoint site?
And how can you whether your users are still trying to go to old on-prem SharePoint links that are no longer there?
In today’s post, we’ll bring an old feature back from the dead to help make your migration to SharePoint Online a lot easier for you and your users.
It only works in situations where you keep your old SharePoint on-premises (2013, 2016, and 2019) server up and running while you migrate the content from it to your SharePoint Online instance.
Best of all, you won’t need to install any Dlls, Sandbox solutions, or Add-ons on your servers.
Back in 2009 a brilliant person by the name of Josh Carlisle created a cool solution called sharepointsmart404. It enhanced the out-of-the-box SharePoint “Page Not Found” error (also known as a 404 error) to provide support for vanity URLs.
A vanity URL, in case you’re wondering, is a unique URL branded for marketing purposes. Instead of using long and ugly URLs, you can use shorter, easier to remember URLs.
With smart 404, when people looked for a page or document that was no longer there, SharePoint would redirect them to the new location of that page/document as long as it found a matching vanity URL.
NOTE: If you are the author of the original sharepointsmart404, or know the original author, I would like to link to their profile and give them credit. Please contact me, and I’ll make sure to update this post.
Here is how the feature worked:
This is the process there is a matching vanity URL:
This is the process when there are no matching vanity URLs:
Unfortunately, the original smart 404 is no longer maintained and does not work on SharePoint 2013 or newer.
But the idea was brilliant. So much so that nearly 10 years later, I haven’t forgotten about it.
I set out to re-create the smart 404 to help anyone who wants to migrate from SharePoint 2013, 2016, or 2019 to SharePoint Online.
The original version used an ASP.NET HttpModule to intercept the request and required deploying DLLs to the server; I wanted to re-create it without using any custom DLLs, Add-ins, or anything of the sort.
To make the solution easier to deploy on any version of SharePoint 2013 or later, I’ll provide the steps to create the required lists and deploy the feature using out-of-the-box features of SharePoint. The instructions should work for 2013, 2016, or 2019, but I was only able to test it in 2013 and 2019. Let me know if you find any issues.
You can also download the web part and list templates from my repo if you’d like.
Since SharePoint 2013, all 404 errors result in SharePoint displaying the PageNotFoundError.aspx, located in the Pages library of the root SharePoint site.
When SharePoint redirects a request to the PageNotFoundError.aspx page, it adds a query string parameter called requestUrl, which contains the request URL (and caused a 404 error).
So if you requested a page called WheresMyStuff on your sharepoint.contoso.com server which resulted in a 404 error, SharePoint would redirect you to:
https://sharepoint.consoso.com/Pages/PageNotFoundError.aspx?requestUrl=https://sharepoint.contoso.com/WheresMyStuff
But here is the secret: the PageNotFoundError.aspx is a standard SharePoint web part page!
And our Smart 404 is just a regular good ol’ web part on that page!
There are three elements to the Smart 404 solution:
VanityURLs list: A list which maps a redirectUrl for each requestUrl.RedirectLog list: A list which records when the Smart 404 Web Part displays, the requested URL , who requested it, and what the outcome was.Let’s explore each component in details.
The Smart 404 Web Part uses the Content Editor Web Part to embed some HTML in the PageNotFoundError.aspx page.
The HTML has some JavaScript which performs the following steps:
requestUrl parameter in the query string.requestUrl, it looks for a matching entry in the SmartRedirects list.requestURL, it redirects the user to the matching redirectURL on SharePoint Online. It also creates an entry in the RedirectLogs list so that we can keep track of where we’re redirecting users.requestURL, it displays the “Page Not Found” error message (or, optionally, it redirects to the SharePoint Online search page). It also creates a record in the RedirectLogs list to record any potentially missing vanity URLs.The updated sequence diagram looks as follows:
When looking for a match, the Smart 404 uses the following logic:
The VanityURLs list is a very simple list. It contains the following fields:
RequestURLExact Match, Begins With or Regular ExpressionRegular Expression matchesThe RedirectLog list contains the following fields:
The list also contains the standard Created, CreatedBy, Modified, ModifiedBy fields, which are used to record who and when the redirection occurred.
Once you deploy the Smart 404 Web Part, you can monitor the logs and look for the following patterns:
No Match outcomes: Means that users are still trying to go to your old on-premises SharePoint server without a matching RedirectURL. You should consider finding where the content matching the RequestURL was relocated and create a new SmartRedirects item to redirect them to the right place.RequestURL from multiple users: This means that somewhere out there, there is an old shortcut pointing to the on-premises SharePoint server that hasn’t been updated. It could be an existing system, a link in a document, etc. Look at the Referrer to see if they came from the same place.As promised earlier, the Smart 404 solution does not require deploying any DLLs or add-ins to your servers. You simply need to create the required lists, add the Content Editor Web Part to your PageNotFoundError.aspx page, and start adding some entries in your SmartRedirects list.
The detailed instructions, along with the code for the Smart 404 Web Part, can be found on my Smart 404 repository, but he’s the summary:
Smart404.html page as necessary to meet your own needs. For example, you can change the look and feel of the “Page Not Found” content template, or the “Your File Has Moved” template.Smart404.html page to your root site’s Site Assets folderVanityURLs and RedirectLog lists (manually or using the list templates from the repo)/SiteAssets/Smart404.html page to your PageNotFoundError.aspxThe process of migrating your SharePoint content from on-premises to SharePoint Online can take a while. During that time, your users may have shortcuts that point them to the old SharePoint instance.
The Smart 404 is a simple solution you can deploy on your on-premises SharePoint server that will replace the standard “Page Not Found” behavior of your SharePoint on-premises server to redirect users to the SharePoint Online equivalent of the content they were looking for.