Friday, January 12, 2018

Planning, preparing and performing a Sitecore upgrade

With the feature set of the Sitecore Experience Platform continuing to grow and improve with each new version, you definitely wont want to get left behind. It's also worth noting that the longer you leave the upgrade (the further you get behind) then the longer in terms of time, cost and difficulty the upgrade is likely to be.

This post is going to be a general overview of the upgrade process that will contain learnings from the Sitecore upgrades I have undertaken.

Planning the upgrade path

The first step is to head over to the Sitecore developer site, and locate the upgrade guide for the version of Sitecore you wish to upgrade to.

Sitecore upgrade guide download
In this case I am looking to upgrade from version 8.1 (initial) to 9 (update 1), so I download the upgrade guide for Sitecore version 9 (update 1). Then take a look at the prerequisites:

Sitecore upgrade prerequisites
In this case, I can upgrade directly from my current version. If however I was on version 8.0, then I would need to upgrade to 8.1 before going to 9 (again the upgrade guide would be downloaded for 8.1). This will then give us the upgrade path for the CMS. Effectively you are working backwards from the version you wish to end up on until you hit your current version.

The same can be done with any modules which may be installed (WFFM, EXM, SXA, etc.).

Preparing for the upgrade

Before undertaking the upgrade there are a few steps that need to be completed:
  1. Download the upgrade guide for each Sitecore version and module to be installed.
  2. Download and extract upgrade packages for each Sitecore version and modules to be installed.
  3. If required download an upgrade files required for Sitecore upgrade packages (such as SQL scripts or configs).
  4. If required download the update package for the update installation wizard.
  5. Backup the environment (database and servers) to be upgraded.
  6. Create a source control branch for the version of Sitecore you are upgrading to. Once you upgrade to a given version on your local environment, you will need to update custom code to work with that version (DLL and code changes).
You can now create an organized folder structure of the packages to install:

Top level folder structure for Sitecore upgrade
Expanded folder structure for Sitecore upgrade
In the case of the production upgrade, you may wish to clone the production environment, and simply switch the DNS once the upgrade has been validated.

Complete the upgrade

The upgrade guide will cover the required steps to upgrade the Sitecore CMS or a given module, however the likely process will be as follows (at a high level):
  1. Run a SQL script on the Sitecore databases.
  2. Install an update for the update installation wizard. This is the tool which takes the update file and runs through it - yes it update itself.
  3. Install the update package.
  4. Fix any conflicts (such as a configuration file which was edited manually and needs to be replaced with the upgraded one).
  5. Deploy any custom code.
  6. Perform a full publish.
These steps will need to be followed on all servers in a given environment (CD or CM, etc.). Once you have installed the Sitecore CMS update, then you would install all the required update packages for any module(s) you have.

Tips for a Sitecore upgrade

  1. Create backups of the IIS web site root along the way.
  2. With major upgrades there may be a lot of code changes required in your custom solution.
  3. Third party tools such as Glass Mapper or TDS may also need to be upgraded (in your code solution).
  4. When you have two identical servers (such as two CD servers behind a load balancer) you can upgrade one and copy the update web root to the other. Ensure there are no differences between the web roots first.
  5. Always leave extra time in any estimates you make, something you don't consider is likely to come up.
  6. Always upgrade a local development environment first, this also gives you a chance to upgrade your custom code solution.
  7. Check the logs after an upgrade for anything that may have arisen.
  8. Check for any broken links after an upgrade - using the admin tool.
  9. Depending on the size/complexity of an upgrade a smoke test right through to a full regression test may be needed. 
  10. Progress the upgrade through each environment (development -> staging -> production ...), testing along the way.


This was a short and simple post to cover off several areas which should assist someone in completing their first upgrade. Practice makes perfect, so don't be afraid to back up a local Sitecore environment and give it a go - if all else fails you can blow it away and restore the backup.

Sitecore SXA page appearing as $name in navigtation

A strange error came up on a Sitecore web site built using the Sitecore Experience Accelerator. A footer navigation item was appearing as $name (the display text), and linked off correctly to the page.

Looking at the page in the content editor, a yellow message appeared saying: If you publish now, the selected version will not be visible on the web site as it is unpublishable.

Sitecore item unpublishable
This can be resolved (assuming the item should be published and appear in the footer) by going to the publish ribbon item and selecting change.

Publish ribbon > Change
Then once the popup modal appears, ensure that the publishable checkbox is checked. Then publish the item and the $name issue is resolved.

Publishing Settings

Tuesday, January 9, 2018

Sitecore SQL Server timeout on full publish

After completing a Sitecore upgrade, and attempting to run a full publish, it would not complete and instead ended up with the following error:
Job started: Publish to 'web'|#Exception: System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.Data.SqlClient.SqlException: Execution Timeout Expired.  The timeout period elapsed prior to completion of the operation or the server is not responding. ---> System.ComponentModel.Win32Exception: The wait operation timed out
   --- End of inner exception stack trace ---
Sitecore full publish times out
Inside the Sitecore.config file (Website\App_Config) is a setting called DefaultSQLTimeout. In my case this was set to 5 minutes, by increasing this (temporarily) to 15 minutes the full publish was able to complete without any issues.

Thursday, December 14, 2017

Sitecore EXM error after upgrade

After upgrading a Sitecore instances version of the Email Experience Manager (EXM) to version 3.5, the following error appeared when attempting to load the site:
Could not find configuration node: "exm/eds/senderManager"

This can be solved by ensuring the Sitecore.EDS.Core.config (located in \Website\App_Config\Include\EmailExperience) configuration file is enabled.

However if the error is appearing on a content delivery instance, the configuration file above should not be enabled. You should check that only the following email campaign/email experience DLLs are present in the bin folder:
  1. Sitecore.EmailCampaign.Cd.dll
  2. Sitecore.EmailCampaign.Content.dll
  3. Sitecore.EmailCampaign.dll
  4. Sitecore.EmailCampaign.Model.dll
  5. Sitecore.ExM.Framework.dll
It's also worth checking that only the following configurations are enabled in the \Website\App_Config\Include\EmailExperience folder:
  1. Sitecore.EmailExperience.CommitSession.config
  2. Sitecore.EmailExperience.ContentDelivery.config
  3. Sitecore.EmailExperience.Core.config
  4. Sitecore.ExM.Framework.config
  5. Sitecore.ExM.Framework.ContentDelivery.config
Either of the above solutions should solve the error for you.

Wednesday, December 13, 2017

Sitecore TDS error during solution deploy

When attempting to deploy a Sitecore (Habitat) solution to a local instance, the following error was appearing for a number of TDS projects:
The "DeploySitecoreItems" task was not given a value for the required parameter "ProjectId".
Several steps were undertaken in attempting to solve this issue:

  • Restart IIS
  • Close and re-open visual studio (and ensure it's running as administrator)
  • Testing the connection on one of the TDS projects to ensure it's configured correctly.
Sitecore TDS test connection
After trying all of these steps the solution would deploy as expected.