Sitecore Upgrade Background

As with most COTS packages, you will one day find the need to upgrade your platform to leverage the latest and greatest features of your investment.With Sitecore, this is a "choose your own adventure" that comes with 2 primary options.For the rest of this blog I will refer to these options as In-Place Upgrade (IPU) and Parallel Upgrade (PU).

IPU Overview

The in place upgrade modifies the existing instance of the platform.For Sitecore, this is a meticulous task that is very error prone due to the manual nature of the documented changes - See Upgrade guide at this link (Sitecore 8 Upgrade Guide Page).


No migration of content or operational data

Recommended approach by Sitecore

Indirectly creates strong awareness of version differences


Complicated process to clone existing environments to practice the upgrade

Have to perform 4 distinct upgrades to get to latest version of Sitecore 8 (Update-3)

Single shot approach per environment

Very hard to roll back

Requires time-intensive outage during release

PU Overview

The parallel upgrade involves installing a new instance of the platform alongside the existence instance.For Sitecore, this is a straight forward initial task to install the latest version of 8, but involves migrating content and potentially operational data.


Process is very straight forward, an installation and package migration

Flexible approach that allows for simultaneous testing of 7.5 and 8 environments

Approach also allows for migration production instance ahead of time for Staging/UAT validation

Requires short outage window


Manual steps required to move operational data (Mongo, Analytics DB)

No Sitecore documentation provided for this approach

Our Environment

Local: single DB, single Sitecore instance - combined CM (Content Management) and CD (Content Delivery) environment

Prod/Test: Physically separated CM and CD environemnts with dedicated DBs for each.

Our Approach

Once we decided to upgrade, our goal was simple: find the best way to migrate the site with the least amount of impact. We decided to divide & conquer the challenge, assigning 2 different teams the task of performing the 2 options. After 2 days and lots of frustrations, the first team successfully migrated their local environment using the IPU approach. After 2 hours and very little frustration, the second team successfully migrated their local environment using the PU approach. Our definition of success was being able to bring up the admin console and the website in a single instance environment (CM only, no CD). Then we had team 1 validate team 2's approach to make sure they didn't make any assumptions. At this point, based on effort, complexity, and the before mentioned flexibility of this option, the PU option was selected as our approach. From this point on, almost all of our challenges were in properly configuring the CD environment in Sitecore 8. These complications would have been encountered regarless of PU or IPU options, but are still important to note. While not specific to the upgrade, I will include the challenges we faced migrating to Sitecore 8 in case it is helpful to anyone. The code/configuration changes for Sitecore 8 are documented below, but next are the upgrade steps once the code is modified.

Step 1 – Install Sitecore 8

If you have installed 7.5, this is the exact same process. We do our installs manually, instead of using the installer, and I was able to follow the 7.5 instructions to install Sitecore 8.

Step 2 – Install code and base content (see changes we identified below)

It is important that this is installed before migrating the content. All the dependent templates, custom workflows, etc. need to be in place for content to migrate successfully. Our project leverages TDS Hedgehog to facilitate content installation from source control.

Step 3 – Package and Migrate 7.5 Content

Perform the following high level steps

1. Next export and import the content from 7.5 to 8. **This worked even better than we hoped and was the key to this approach working

2. Go to the 7.5 admin console and create a package of all necessary content, Desktop -> Development Tools -> Package Designer. Generate the zip and download.

3. Go to the 8.0 admin console and import the package, Desktop -> Installation Wizard. Upload the package and Install.

Step 4 – Publish

Publish the content to all defined targets.


At this point you should verify the following:

1. Go to Content Editor and verify content tree looks correct

2. Open a page in Page Editor and validate functionality

3. Open the CM web and CD sites and check functionality and content

4. Check the logs on CM and CD for errors

Code/Configuration Changes

Most of the challenges we encountered were around figuring out the right configurations for the CD environment. I have included these and any other interesting findings we encountered along the way.

Sitecore 8 CD Configuration

Config Files

The first thing we found when moving to Sitecore 8 is that many of our configuration overrides were lost. After some quick searching, we found out it was because Sitecore moved many configuration files into folders. The order of loading configuration files is

1. Files alphabetically

2. Folders alphabetically with files found processed alphabetically

This resulted in many of our patches being ignored since the configuration it was trying to patch hadn't been loaded.So, we created a zPostProcessing (notice we append "z" to make sure it is loaded last) folder in App_Config/Include and put any patch files there that need to override settings found in Sitecore configuration files that lived in folders under Include.


Migrate Databases

Great news, we were able to copy the 7.5 MongoDB databases and connect with 8.0 with no issues. This helped a lot with making sure we had all the operational data migrated.

Contact Database

Make sure to create the xyz-analyticscontact database and add to the connectionstrings file. You will have lots of errors in your logs without this setup.

Page Editor

We encountered issues in the page editor due to css conflicts. The issue caused navigation links to become hidden after clicking. In the end we demarcated our styles to be "!important" to override default page editor functionality. Not the ideal solution, but resolved the conflict.

.xzy-navbar .nav > li {

display: block !important;


.xyz-desktop .nav > li {

display: block !important;


We also experienced much slower page editor load times. We have no workaround for this at this time and find that page refreshes seems to generally get us around the issue.

jQuery Collisions

We had to namespace all of our jQuery($ -> $xyz) refrences to eliminate collisions with Sitecore 8.


While both IPU and PU approaches will ultimately work, the benefits of the PU approach signifantly outweighed those of IPU for our team. Having parallel environments to validate existing vs. introduced defects saved us a lot of time and confusion. Also, having our staging/production server environment ready for UAT increased business comfort and reduced risk. I would definitely follow this approach again in a similar situation.