Watching Your Sitecore Upgrade Steps

Tuesday, March 29, 2016 @ 10:27

By: Scott Gillis, Lead Consultant – In recent months, teams here at Paragon have seen an uptick in Sitecore upgrade projects. I don’t know if it’s the warming weather that has people ready for a change or the realization that the latest and greatest from Sitecore provides their organization with lots of options to increase the value that visitors have through better personalization and engagement with them.

As any Sitecore developer can attest, no two Sitecore upgrades go the same way, and even different environments for the same site may behave differently. Through our recent round of upgrades and preparing my teams for many more this year, we have generated a check-list of things we have found that need to be watched out for or done to help make the process a little smoother and a lot less painful.

The initial creation of this list was done after numerous upgrades from both 6.x and 7.x to 8.1.

To-Do Items

Here is a list of items that you should do at the start, during, and end of the upgrade process

  • Read all of the upgrade documents multiple times before trying anything, the older documents especially have a habit of leaving important details out until the end
  • Take the time to make sure all custom configurations are moved into patch files. If you are unsure what has been customized, grab a clean install of your current Sitecore version and, using your preferred file compare tool, see what is different
  • Make copies of the Master, Web, and Core Databases often
  • Make copies of your web root directory even more often! Nothing sucks more than trying to rollback without a good backup
  • After the last upgrade step, it is helpful to compare the BIN and App_Config to that of a clean install. This way you can quickly recognize old files that need deleted or see files that differ, meaning they may not have updated correctly
  • During the move from 7.2 to 7.5IR, you will see a note to disable the Speak configuration file. Instead of disabling it, delete the Speak configuration file. After the upgrade has completed, you will then want to copy over all of the Speak configuration files from a clean 7.5IR install
  • When reaching Sitecore 8.0 update 6 OR Sitecore 8.1 Initial Release, the web.config will have become too large, causing IIS to throw System 500 errors. The only indication that something bad has happened will appear in the Server Event Logs
    • To fix it at this level, you will need to move at minimum the <settings> node into a separate file
    • Thankfully, Sitecore has corrected this issue starting in Sitecore 8.1 update 1, where the entire <Sitecore> node has been moved into a separate file
  • Moving from 7.2 will require the following minimum steps:
    • 7.2 Initial -> 7.5 Initial -> 8.0 Initial -> 8.1 Initial -> 8.1 update 2
  • Moving from 6.5 Initial will require the following minimum steps:
    • 6.6 IR -> 7 IR -> 7.1 IR -> 7.2 IR -> 7.5 Initial -> 8.0 Initial -> 8.1 Initial -> 8.1 update 2
  • You can save time by delaying your source code re-build and testing until your upgrade reaches its final point. The Sitecore upgrade process is fully focused on database and file system changes
  • You will need to have a MongoDB instance connected to get through some of the install steps for WFFM and EXM, or you may experience odd error messages
  • Sitecore 8.1 now requires a license with the “Sitecore.xDB.base” key to enable all features of the Experience Platform. If your license file does not contain this key, Sitecore will default to Experience Management (CMS-only) mode. Be sure to contact your Sitecore partner or account manager to get a properly issued license

Watch-Out For This

This is a list of things to be aware of that might trigger heart burn and a bad migraine:

  • The upgrade installation wizard is known to not properly add and delete files from the file system. If, after running the upgrade wizard, things seem strange, I always copy the entire BIN and App_Config from a clean install and perform a replace
  • If using Solr, be aware of the separate Solr support directories with updated assemblies
  • If Solr is the targeted search solution, you will need specific core naming patch files to make it all the way through the process, see my post on Sitecore Upgrades Mixed with Solr for more details
  • If upgrading WFFM, you will need to perform some re-work on any custom JS and CSS, as there have been structural changes to the HTML that is output
  • If upgrading WFFM, you may need to re-assign all save actions. I’m not clear if this issue has been solved in the latest version
  • If upgrading WFFM, you may need Sitecore support code to allow custom CSS classes to properly render, see the support issue with public reference number 98776
  • If the site was built with the latest MVC version, then it will not match with the Sitecore required version to run the upgrade wizard. In these cases, you will need to copy all the MVC related assemblies from a clean web root, and then update the dependent assembly node of the web.config to require all MVC to point to this ‘older version’. This may mean the site won’t run correctly, but it will allow you to get through the upgrade process
  • Starting with 7.5 it is recommended to place all custom configure patch files inside App_Config / Include /zzMyCustom Directory, to make sure that they always load last, as more and more configuration files are added. For more details on how configuration files are loaded check out my post How Sitecore Configuration Files Load
  • If you are upgrading from 6.x, then you need to plan for a major development and testing effort for site search, as the entire Search API has been changed starting in 7.x
  • Sitecore 8.x seems to be much more resource intense then previous versions, everything I’ve read and have firsthand experience with has shown that a server sized for 6.x or 7.x may not support the additional features of Sitecore 8.x at an acceptable level

Questions to Ask Before You Start

  • Are there any custom reports that report against the Analytics database?
  • If you will be upgrading to Sitecore Experience Platform (8.x +) for the first time, what are the plans to support MongoDB in each environment?
  • Will the site need to continue to communicate with any other services (Sitecore or third-party)?
  • Has the site gone through any Sitecore upgrades already? If so, what was the initial version? (This allows you to look for old files and configuration settings that may not have been cleaned up after the last upgrade)
  • Has any planning been done to support the new server roles available as defined in Sitecore's documents?

As always, feel free to tweet me questions or comments @thecodeattic or on Sitecore Slack Community as @gillissm.



Scott Gillis, Lead Consultant at Paragon and 2017 Sitecore MVP, has been working with Sitecore for several years. He has a deep passion for helping clients leverage their content and data into powerful new capabilities in Sitecore and has produced successful outcomes as the technical lead on numerous, complex implementations. Recently, Scott has been focusing on helping these clients take advantage of the wealth of data collected by Sitecore Experience Analytics.