Walkthrough: How to keep old SharePoint links working after a migration

In this walkthrough I’ll show you a way how you can keep old links to SharePoint content working after a migration of a site or part of its content to a new place. This solution can help you in different scenarios when you change the content URL, but don’t want to ask your users to update their links.

In my case, I used this approach when I did a migration of inherited SharePoint 2010 to a new server. During the migration there was an upgrade to SharePoint 2013 and total revision and reorganization of the content structure. A lot of files were moved to new libraries and folders, some department sites were split up, while others were combined. The main challenge in this migration was the strong requirement that all the old links should keep working. The requirement was fulfilled and by now it has already been working in production for about a year without any issues.

Ok, let’s get started!

Steps overview


Step 1. Install IIS URL Rewrite extension.

1. Open Internet Information Services (IIS) Manager.
You can find it in your Start menu.
IIS Manager

2. Check whether you already have IIS URL Rewrite extension installed.
Select your server and take a look at IIS section.

URL Rewrite icon

Most likely, you have no URL rewrite icon there, but if you have, you can skip step 1 and go to step 2.

3. Install URL Rewrite.
Go to the official Microsoft IIS site and press Install this extension for URL Rewrite http://www.iis.net/downloads/microsoft/url-rewrite

IIS URL Rewrite download link

You will be redirected to its download page where you need to press Install Now button.

Microsoft Web Platform Installer installation link

After downloading, run the installation file

Download complete dialog

Press Install

Install ULS Rewrite dialog

Accept the licenseAccept URL Rewrite license

If you see IIS URL Rewrite Module Setup window – accept license and press install

URL Rewrite module setup

 

4. Check whether URL Rewrite is installed correctly.

When the installation completes, close IIS Manager and open it again. Now, you should be able to see URL Rewrite icon.

URL Rewrite icon


Step 2. Create redirection rules.

There are two ways for creating redirection rule. The first one is to use UI and the second one is to make changes in web.config file. Let’s start from the UI way.

1. Open necessary SharePoint web application and double-click URL Rewrite icon

Double-click URL Rewrite

2. Create a blank rule.

Press Add Rule(s) link from the action section.
Add rule

Select Blank Rule in the Inbound rules section.

Blank rule

3. Create the first simple rule.

Let’s create the first very simple rule which will redirect all the requests to our new server.

Enter a meaningful name for the rule and set (.*) for the pattern. This pattern in Regular expressions means “any number (even zero) of any characters”. So in our case it will work for every request as all the requests contain zero or more characters. Later we can get the back reference to the characters which were extracted by the pattern.

First rule name

In the Action section set action type to Redirect and set Redirect URL to “http://newsp/{R:1}”, where “newsp” is the name of the server to redirect all the requests to. “{R:1}” is the back reference to the information extracted by our pattern.

Note: When the request comes, the pattern extracts parts of the relative URL and we can reference them later using {R:1} for the first part, {R:2} for the second and so on. Our pattern extracts only one part and this part just contains the entire relative URL. So, if there is request to “http://ourserver/sites/Secretariat”, {R:1} will be equal to “sites/Secretariat” and hence our full redirect URL will be “http://newsp/sites/Secretariat”.

Redirect action

Press Apply and Back to Rules buttons on the Actions pane.

Press Apply

After that you will see the new rule in the list of rules.

New rule created

Now you can open some URL from the old site in Internet Explorer and you should be redirected to the same relative URL, but on the new server.


Step 3. Explore rules in web.config.

1. Open the directory of your web application in Explorer.

For that, right-click on the web application and click Explore.

Click explore

2. Find URL Rewrite section in web.config.

Open web.config file in notepad, press CTRL-F and search for “rewrite”. You should find the section with the created rule.

Note: always backup web.config file before making changes in it! You can just copy it to a safe place and return it back later if something goes wrong.

Rule in web.config

You can add new rules directly in web.config inside the rules section.

List of useful SharePoint rules you can find in my post:

List of useful SharePoint redirect rules for URL Rewrite.


Important notes regarding redirect rules.

1. When you start building your own rules, try to avoid using Rewrite action type and use Redirect instead. At least if you are not absolutely sure that Rewrite action is supported in your case. The reason for that is the fact that asymmetrical rewrite URLs are not supported with SharePoint. More info about that you can find here: Check Supportability of Rewrite and Redirects with SharePoint 2007/2010/2013.

2. Always thoroughly test rules before implementing on production. It is easy to make some mistake in redirect rules and get unexpected result. For instance, if you are doing redirect to another library for file Report.xls and don’t think carefully, you can accidently found that redirect works not only for Report.xls, but also for MyReport.xls.

3. Always make sure that you have backup of web.config before making any changes in it. It can save your time and nerves if you accidentally make some mistake in it.

4. Destination URL should be correctly set up in Alternate Access Mappings.

5. Sometime IIS caches rule and after you changed it, actual change doesn’t work, because of it. The cure is to disable and enable again the rule. It forces the cache to reset.

6. You can use Fiddler for debuging your rules.

7. Don’t forget about Minimal Download Strategy. It can transform links.


Conclusion

Using this walkthrough and List of useful SharePoint redirect rules for URL Rewrite you should be able to quickly create rules for the most of the tasks related to migration and changes in content organization structure. However, if you need to create some rule and can’t find it in the list, you can create it yourself. URL Rewrite Module Configuration Reference should help you in that.

Hope you found this walkthrough useful. If so, or if you have some thoughts or questions about it, don’t hesitate to share comments.

Thank you!

4 thoughts on “Walkthrough: How to keep old SharePoint links working after a migration

  1. Pingback: List of useful SharePoint redirect rules for URL RewriteSharePoint 2013 Developer's Blog

  2. This solution helps only when the old SharePoint Server still works I suppose. Is there any possibility to replace parts of the old URL to a new URL when the old Server is no longer working?

  3. Hi, URL redirect is not working for me for redirecting request for a subsite in one site collection to subsite in another site collection.

Leave a Reply

Your email address will not be published. Required fields are marked *