How Sitecore Upgrades Work

I will start this post by what Sean Holmesby concluded in his post The Truth about Sitecore Upgrades:

“Really, there isn’t one single truth that covers everything. Everyone has their own opinions on upgrades….everyone has learnt something different from their own experiences. Take every opinion with a grain of salt, collect the thoughts and experiences and make your own decision.”

I’m very happy that the Sitecore community has that much interest in upgrading Sitecore, especially if people have different opinions on how to walk the path. It means that the learning experience for everyone will be deeper, people will challenge each other’s theories and experiments, and that will benefit the whole Sitecore community. Personally I learned a lot from the articles I read and the upgrades I did.

Sitecore Upgrades: Two Sides To Every Story

Sitecore provides upgrade packages that upgrades your content and copies new files, then you have some instructions to modify your existing configuration files. Those upgrade packages can only upgrade your Sitecore version one point at a time, for example, from Sitecore 7.1 to Sitecore 7.2.

I have already shared my experience in The Art of Sitecore Upgrade, where I presented a different approach, it isn’t Sitecore endorsed but its building blocks are the same building blocks of Sitecore itself. I’m not using any third party tools and I didn’t have a problem opening Sitecore support tickets because of this approach.

What I would like to do now is to go deeper and explain how I got to my approach and the theory behind it along with some examples. I chose the same examples from Sean’s post to show how it can be done using my approach in comparison to the standard approach.

The Big Picture

First, let’s talk about the big picture of a Sitecore upgrade. Sitecore upgrades are not all the same, but they do have a lot in common. Focusing on those common aspects can go a long way.

There are a number of upgrades that we talk about when we say “Sitecore Upgrade”; no matter what approach you’re taking:

  1. Sitecore Content Upgrade.
  2. Sitecore Configuration Upgrade.
  3. Solution Upgrade.

Regardless of the upgrade approach, usually there are some manual steps that follow; for example, WFFM conversion. Those are different from one solution to another and have to be treated on a case by case basis. I will exclude those from this analysis.

Sitecore Content upgrade

With each new version, Sitecore may add items, modify items, modify database schema… The standard upgrade package should be running scripts that do all that as well as any other post upgrade scripts.

One great thing about Sitecore is the hierarchy it uses for templates and items, every item or template we create is based on a Sitecore template. And that’s what I used to save myself the trouble of running all those upgrade packages.

Let’s take this example where upgrading from Sitecore 6.4 to Sitecore 6.5 added a new field “Placeholder Key” to the “Placeholder” template and the post step script populated the value of that new field in the existing placeholder items. That’s the standard approach.

Alternatively, if you serialize an arbitrary placeholder item in Sitecore 6.4, you don’t have a “Placeholder Key” field; but you do have the “Placeholder” template.

7-19-2015 6-00-02 PM

Instead of upgrading to Sitecore 6.5, let’s say you went straight to a fresh Sitecore 8 install and deserialized that item. Because you will be creating a new item based on the “Placeholder” template (but in this case it is in Sitecore 8), you will get the new “Placeholder Key” field. The “Placeholder Key” field will be populated with the standard value ($name). Your new item in Sitecore 8 will look like this:

7-19-2015 6-10-38 PM

That’s exactly the same end result you would get if you follow the upgrade packages from 6.4 to 8.0, you only saved yourself running through eight upgrade packages and all the possible human errors and script errors that come with that. Also, that’s the same Placeholder item you would get if you are creating a new one in Sitecore 8, in this case it’s populated and linked to where you would want it to be.

Another example would be templates and items that had Rules fields before Sitecore 7.1. An example of a serialized Rules field on a Sitecore 6.6 item would be like this.

7-19-2015 6-44-42 PM

The way you configure the rules and add new rules have changed in Sitecore 7.1, as described here. In Sitecore 7.1 or later, to create new rules you need to assign sources to the Rules fields in your templates; but you can still have the existing rules in the existing items unchanged, just serialize the item and copy it over. This is how the serialized Rule 1 would look like in Sitecore 8.

7-19-2015 6-43-13 PM

Finally, serializing your content and migrating that to your target version isn’t just blindly copying everything over. You have to know what items you are moving over and in what order (the serialization paths I talked about in the earlier post). You also want to make sure that you’re not overwriting Sitecore items, so don’t just click revert tree on an item that has a mix of Sitecore and user defined items; you shouldn’t have something like this in your tree in the first place. Sean suggested using RAZL to compare the Sitecore databases, I didn’t get a chance to try that myself but it seems like a good option in some cases; if you have customizations to Sitecore base items for example.

Sitecore Configuration upgrade

While the configurations files can be a gold mine of information about the specifics of how Sitecore works, I wouldn’t use that as an excuse to make the changes for each point upgrade by hand. For me, it sounds like the learning the experience I would get from reinventing the wheel. If you’re interested in learning more about Sitecore’s new configuration files, just go ahead and read the comments on each file in your target version, they are very well documented.

Another reason why I wouldn’t do that is that I don’t want to have any Sitecore configuration file as part of my solution or have it in source control. I have patch files for everything I patched in Sitecore and that should be enough, Sitecore files should only be coming from Sitecore zip.

Solution Upgrade

I haven’t heard any voices call for a solution upgrade for the intermittent versions during an upgrade. I will assume that we can all agree that it’s best to upgrade your solution once to be compatible with the target version of your upgrade.

I Want The Truth!

The truth is that we are all learning, including Sitecore developers who are working on the ‘Express Upgrade’. My expectation for ‘Express Upgrade’ is that it will be following along the *start fresh* line, that’s just my expectation though!

This is my version of how Sitecore Upgrades work and this is how I got there. These are my experiments, those are not Sitecore endorsed; but as I said earlier, they are all based in Sitecore operations and I didn’t have any problem working with Sitecore support on any of the upgrade projects I worked on using this approach.

If you have any questions, or want to share some of your experiments, please don’t hesitate to comment on this post.


2 thoughts on “How Sitecore Upgrades Work

  1. Hey Mark,
    Great post on your experiences. Thanks for taking the time to share your findings.
    Here are some of the issues and workarounds I noticed when trying this process myself.

    I see the Placeholder Settings items will work with the Placeholder Key fields, because of the $name token you mentioned. Good catch. However this means it’ll only work for items that are in the root of the Placeholder Settings folder.
    In the example on my post,, the item is nested in ‘Test Folder’, and therefore receives the complete relative path from the root node in the key field. (‘/Test Folder/Test Item’).
    Using the $name token, we’d only get ‘Test Item’, which wouldn’t have worked in the same way.
    That’s how Sitecore 6.4 worked with placeholder keys (way back in the day), but I agree, you’ll be fine, as long as your items aren’t nested.

    With the Rules field, as you mentioned the value of the rules fields will still work (i.e whatever has been set in them will still remain once serialized over). The issue is that the sources of the fields won’t get translated correctly, so editors/marketers won’t be able to add more custom rules to those fields.
    It’s hard to explain, so I’ll use an example where after the move to post-Sitecore-7.1, an editor creates a new item of the same template.
    They then wouldn’t be able to add the same custom rules that were on the existing item to that new item. This is because Sitecore would think those conditions and actions were outside of the restricted rules available (because of the empty source).
    There are ways to manually fix this (, and the same could be said for the placeholder keys…. But you would need to know they’re broken in order to fix them, and that’s where a lot of devs might not be aware of these things. In that case, I believe it’s better just not to break them in the first place.

    Also, these are just the areas that we know about. There could easily be other item updates that we miss, and quietly break (for now) that we don’t know about, but its different for every upgrade and solution…so people can get lucky with their upgrades if they don’t happen to use any of the items that are updated.

    And finally you make a great point about keeping your config changes separate from Sitecore’s (in App_Config/Include) and keep Sitecore ones out of source control. We do the same, and it makes upgrades so much easier!
    Care still needs to be taken with custom configs though. XML node names change, as do structures, and even folder paths. The nested App_Config/Include folders in Sitecore 8 mean your existing configs might get patched too early (the same way issues have been seen with SwitchMasterToWeb.config,

    Again, it’s another thing that people might not get stung by, but should be aware of.

    Nevertheless, I feel it’s best to know as much as possible about the upgrade process before choosing either the full upgrade process, or the ‘start from 8’ process, and it’s discussions like these that help advance our knowledge as a whole community.


    1. Thanks a lot Sean for sharing your findings, I think this is exactly what we need to enrich the whole Sitecore community.
      I agree with a lot of your points here, mainly that we should be aware of the specifics of both the solution and the upgrade process to be able to make sound decisions.
      Also, I would like to add a bit of clarification to the issues you mentioned here:
      1. For the placeholders, going by the $name should be enough in most cases. The only time where this can be a problem if you have nested placeholders with the same name. For example, (Test Folder/Test Item) and (Another Test Folder/ Test Item). Zooming out from the specific issue; my assumption is that if there is a standard value for a new field, it can be safely used since it will be used anyway with new items.
      2. For the Rules, I think that the manual approach to assigning the source is better. Setting those manually according to business logic means that you have control on the rules to be added, which is the purpose of this change in the first place and this is what you would be doing for new items. The alternative provided by the upgrade package is that the source would be assigned based on the current rules, which will probably need to be changed anyway to fit the business logic. For example, if you currently have a single rule based on that field, the source would be assigned based on that as well; which is probably not what you need.

      Again, these are just different solutions to the same problem, each would have its cost, benefit and risk.

      I hope to see you soon, probably at #sugcon 🙂


Leave a Reply to Mark Adel Saad (@MarkAdel1) Cancel reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s