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.
The original sharepointsmart404
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:
- When someone asks for a SharePoint URL which does not exist, SharePoint redirects to the 404 error page
- The feature intercepts the 404 error and looks for the requested URL against a list of vanity URLs. Each vanity URL entry consists of a requestURL (the URL that caused the page not found error), and a redirectURL (the URL where users should be redirected).
- If there is a matching vanity URL, redirect users to the redirectURL and don’t display the "Page Not Found" message
- If there isn’t a matching vanity URL, display the "Page Not Found" message
This is the process there is a matching vanity URL:
sequenceDiagram Browser -->> ASP.NET: Requests a page ASP.NET -->> SharePoint: Requests document by URL SharePoint -->> ASP.NET: Page not found, return 404 ASP.NET -->> Smart 404: Do you have any entries for this URL? Note right of Smart 404: Found a matching vanity URL Smart 404 -->> ASP.NET: Returns a matching vanity URL ASP.NET -->> Browser: Redirect to vanity URL
This is the process when there are no matching vanity URLs:
sequenceDiagram Browser -->> ASP.NET: Requests a page ASP.NET -->> SharePoint: Requests document by URL SharePoint -->> ASP.NET: Page not found, return 404 ASP.NET -->> Smart 404: Do you have any entries for this URL? Note right of Smart 404: No matching vanity URL Smart 404 -->> ASP.NET: Return page not found ASP.NET -->> Browser: Display page not found error page
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.
Bringing Smart 404 back from the dead
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:
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!
The new Smart 404 solution
There are three elements to the Smart 404 solution:
VanityURLslist: A list which maps a
RedirectLoglist: 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
The Smart 404 Web Part uses the Content Editor Web Part to embed some HTML in the
- When the page loads, it looks to see if there is a
requestUrlparameter in the query string.
- If there is a
requestUrl, it looks for a matching entry in the
- If it finds a matching
requestURL, it redirects the user to the matching
redirectURLon SharePoint Online. It also creates an entry in the
RedirectLogslist so that we can keep track of where we’re redirecting users.
- If it does not find a matching
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
RedirectLogslist to record any potentially missing vanity URLs.
The updated sequence diagram looks as follows:
sequenceDiagram Browser -->> SharePoint: Requests a page SharePoint -->> Browser: Page not found, redirect to PageNotFoundError.aspx PageNotFoundError.aspx -->> Smart 404 Web Part: Do you have any redirect entries for this URL? Note right of Smart 404 Web Part: Found a matching redirect URL Smart 404 Web Part -->> Browser: Redirect to new URL
When looking for a match, the Smart 404 uses the following logic:
st=>start: Start e=>end: End op1=>operation: Look for exact match sub1=>subroutine: My Subroutine cond=>condition: Exact match found? op2=>operation: Look for 'Starts With' match cond2=>condition: Starts With match found? io=>inputoutput: Redirect op3=>operation: Look for Regular Expression match cond3=>condition: Regular Expression match found? ionf=>inputoutput: Display 'Page Not Found' st->op1->cond cond(yes)->io->e cond(no, bottom)->op2->cond2 cond2(yes)->io->e cond2(no, bottom)->op3->cond3 cond3(yes)->io->e cond3(no, bottom)->ionf->e
The VanityURLs List
VanityURLs list is a very simple list. It contains the following fields:
- Title: A friendly title for your redirect. Not used by the web part, but helps make your list of Vanity URLs manageable.
- RequestURL: A text field containing the original URL of a resource.
- RedirectURL: The URL where you wish to redirect users when there is a matching
- RedirectType: A choice field describing what type of redirect to use. The valid choices are either
- RegExp: The regular expression to be used for
- Order: The priority for this vanity URL when more than one vanity URL matches the current URL
The RedirectLog List
RedirectLog list contains the following fields:
- Title: A simple text description of the outcome.
- RequestURL: The URL that was requested.
- Referrer: The HTTP Referrer (in case we were directed from somewhere else)
- RedirectedTo: The URL where we sent the user.
- Outcome:: Keeps track of whether users were redirected due to an exact match, a partial match, or if they were redirected to the search page because there weren’t any matching Vanity URLs.
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:
- Large numbers of
No Matchoutcomes: 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
RequestURLwas relocated and create a new
SmartRedirectsitem to redirect them to the right place.
- Many entries to the same
RequestURLfrom 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
Referrerto see if they came from the same place.
- Many entries from the same user: This means that someone is being stubborn and has not updated their shortcuts to point to the new SharePoint Online tenant. They may simply need your help with updating their records.
- A decline in the frequency of records/no more records: This means that fewer people are trying to go to the old on-premises SharePoint server and that you should consider retiring your server without impacting your users.
To deploy the Smart 404 solution
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:
- Make changes to the
Smart404.htmlpage 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.
- Upload the modified
Smart404.htmlpage to your root site’s Site Assets folder
- Create the
RedirectLoglists (manually or using the list templates from the repo)
- Add a content viewer web part that points to your
/SiteAssets/Smart404.htmlpage to your
The 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.
- Thanks to Gary Rong for helping build the code, and Rodney Hayden for being
a test subjectvolunteer participant,
- Credit goes to Josh Carlisle for the original sharepointsmart404.
- December 16, 2019: Gary Rong added logic to handle Regular Expressions and helped identify issues with the code in Internet Explorer, because — apparently — people still use IE?!?!.