SharePoint Site URL Redirection


When migrating the content from On-Premises to the Cloud, you will follow a certain process, for instance:
  • Informing the users about the migration
  • Planning for the content to be migrated
  • Performing the migration
  • Validating the content
  • Performing incremental work
  • Locking down site
  • URL re-direction
Again, all the above steps may not be exactly the same, but in most migration scenarios, the business requirement is to redirect the users to the new sites. This could be because users might have bookmarked the old on-premise URL and would like to have a redirection in place for some time until all the users are aware of the new site.
In this article, we will go through the URL redirection for the SP2013 on-premises site to Office 365 SharePoint online. To have this redirection we will not use SharePoint designer, instead will use the concept of Custom Action. This is applicable for SharePoint 2013 and SharePoint 2016 sites.
The idea here is when a user navigates to Old URL the javascript gets rendered which notifies the user via a notification banner regarding the new site and redirects the user to the new site.
SharePoint Site URL Redirection

Custom Action

Before we go to steps, we need to understand what Custom-Action is. A Custom-Action is a new concept introduced in SharePoint 2010 which is used to customize the ribbon and list item menus. In SharePoint 2013, with the introduction of the add-in model, there is no need to deploy a full trust code to customize ribbons and list menu items. Here you use REST API or SharePoint CSOM (client-side object model) to achieve these kinds of customizations which are referred to as ‘Remote Provisioning Pattern’. The advantage here is there is no hard update to application pages, all the rendering happens during the runtime.

Upload the redirection script

In this stage, upload the URL redirect script to Style Library in the Site Contents page and then publish the file to the final version.
Below are the steps,
Step 1
Have the following code saved as ‘SiteURLRedirection.js’,
  1. var title = "";  
  2. var desSite = "";  
  3. var str1 = "Site has been migrated to the new URL - " + desSite  
  4. var str2 = "You will be redirected to the new URL shortly ..."  
  6. function getUrlVars() {  
  7.     var vars = [],  
  8.         hash;  
  9.     var hashes = window.location.href.slice(window.location.href.indexOf('?') + 1).split('&');  
  10.     for (var i = 0; i < hashes.length; i++) {  
  11.         hash = hashes[i].split('=');  
  12.         vars.push(hash[0]);  
  13.         vars[hash[0]] = hash[1];  
  14.     }  
  15.     return vars;  
  16. }  
  18. function ShowStatusBarMessage(title, message) {  
  19.     var statusId = SP.UI.Status.addStatus(title, message, true);  
  20.     SP.UI.Status.setStatusPriColor(statusId, 'yellow'); /* Set a status-color */  
  21.     return statusId;  
  22. }  
  24. function ShowNotificationMessage(tooltip, message, sticky) {  
  25.     SP.UI.Notify.addNotification(message, sticky, tooltip, null);  
  26. }  
  27. if (getUrlVars()["stopredirect"] == "1") {} else {  
  28.     setTimeout(function() {  
  29.         var nid = ShowStatusBarMessage(title, str1, true);  
  30.         setTimeout(function() {  
  31.             SP.UI.Status.removeStatus(nid);  
  32.             nid = ShowStatusBarMessage(title, str2, true);  
  33.             setTimeout(function() {  
  34.                 SP.UI.Status.removeStatus(nid);  
  35.                 setTimeout("location.href='" + desSite + "'", 1000);  
  36.             }, 1000);  
  37.         }, 2000);  
  38.     }, 2000);  
  39. }   
Step 2
In the variable ‘dessite’, make sure to update the URL to the correct destination according to your needs.
Step 3
Upload the script to your ‘Style Library’ which is available in site contents. As a best practice, create a folder inside the style library (I am creating it as ‘CustomScripts’). This way when registering this script as a custom action, it will be easy to modify or manage custom action.
Step 4
Observe that when uploading any custom scripts to the style library, it will be in checked-out mode. Make sure to check this script and publish the final version. This is very important.
SharePoint Site URL Redirection
SharePoint Site URL Redirection
SharePoint Site URL Redirection

Register the Custom Action

Now you have all the bells and whistles ready, you just need to have the final action which is redirection to happen. To achieve this run the following lines of PowerShell command. This command creates the custom action which will redirect the users to a new destination. No matter what pages within the old site collection the user goes it needs to redirect to the new site. Whether the user is on the Documents page, homepage, or site contents page, articles page, etc, it should redirect to a new destination.
Please note that the redirection happens to the home page of the URL that you have mentioned in the script. For example, if the user is in the documents library in the old site, it will not navigate to the document library in the new site, it only navigates to the new site home page.  
  1. $loadInfo1 = [System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")  
  2. $loadInfo2 = [System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")  
  3. #Must be SharePoint Site Collection Administrator URL  
  4. $siteUrl = Read - Host - Prompt "Input Site URL"  
  5. $ctx = New - Object Microsoft.SharePoint.Client.ClientContext($siteUrl)  
  6. $site = $ctx.Site  
  7. $username = Read - Host - Prompt "Input Admin ID"  
  8. write - host "Please enter your password"  
  9. $password = read - host - AsSecureString  
  10. $ctx.Credentials = New - Object System.Net.NetworkCredential($username, $password)  
  11. $ctx.Load($site)  
  12. $ctx.ExecuteQuery()  
  13. $userCustomActions = $site.get_userCustomActions();  
  14. $newUserCustomAction = $userCustomActions.add();  
  15. $newUserCustomAction.set_location('ScriptLink');  
  16. $newUserCustomAction.set_scriptSrc('~SiteCollection/Style Library/CustomScripts/SiteURLReDirection.js');  
  17. $newUserCustomAction.set_sequence(10);  
  18. $newUserCustomAction.set_title('Contoso URL Redirection');  
  19. $newUserCustomAction.set_description('Contoso URL Redirection');  
  20. $newUserCustomAction.update();  
  21. $ctx.ExecuteQuery()   
Since the JavaScript needs to run on every page in the site collection I am using location type as ‘ScriptLink’. Make sure to update the scriptSrc to the correct location. The sequence can be between 1 and 1000. I have given as 10. Set a proper title and description. In this case, I have given as ‘Contoso URL Redirection’ for both title and description.


At first script prompts for the URL of the site collection, enter the site collection URL.
Next, it asks for an admin ID. The account needs to be a site collection admin. After that, it prompts for the password.
SharePoint Site URL Redirection
On successful authentication, you should see the following messages in the notification banner.  
SharePoint Site URL Redirection
SharePoint Site URL Redirection

Unregister the custom action

For some reason, if you need to cancel the redirection you can run the following PS command to unregister the custom action. After this observe that URL redirection no longer works.
  1. $loadInfo1 = [System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")  
  2. $loadInfo2 = [System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")  
  3. #Must be SharePoint Administrator URL  
  4. $siteUrl = Read - Host - Prompt "Input Site URL"  
  5. $ctx = New - Object Microsoft.SharePoint.Client.ClientContext($siteUrl)  
  6. $site = $ctx.Site  
  7. $username = Read - Host - Prompt "Input Admin ID"  
  8. write - host "Please enter your password"  
  9. $password = read - host - AsSecureString  
  10. $ctx.Credentials = New - Object System.Net.NetworkCredential($username, $password)  
  11. $ctx.Load($site)  
  12. $ctx.ExecuteQuery()  
  13. $userCustomActions = $site.get_userCustomActions();  
  14. $ctx.Load($userCustomActions)  
  15. $ctx.ExecuteQuery()  
  16. foreach($action in $userCustomActions) {  
  17.     if ($action.title - eq 'Contoso URL Redirection') {  
  18.         $action.DeleteObject()  
  19.         Write - Host $action.Title 'Contoso Branding Customization Custom action deleted.'  
  20.         $ctx.ExecuteQuery()  
  21.     }  
  22. }  
  23. $ctx.ExecuteQuery()   
Powershell Output
SharePoint Site URL Redirection


Thus, in this article, we have seen how to make the URL redirection from on-prem site to cloud SPO site, using custom action. We haven’t used SharePoint designer to achieve this.