SXA Upgrade Tool

Reading time ~3 minutes

Upgrade Tool helps you start using the newest version of SXA with no pain! You don’t have to worry about problems with your old content after upgrade.


Sitecore Experience Accelerator 1.3 introduced an interesting feature called Upgrade Tool. This is an upgrade wizard build with Sitecore PowerShell Extensions. It will do automatically everything that you would normally have to do manually, after each SXA version upgrade.

How it works

When you open a Content Editor/Experience Editor after installing new version of SXA you will notice a warning message.

This means that your instance was not fully upgraded yet.

Once you click Upgrade button, a new window will pop up.

You will see a list of potential upgrade steps that have to be executed in order to upgrade your current content version to the newest one.

Next, if you click Upgrade button located in the ListView ribbon, upgrade procedure will start.

Info: You cannot select which step to invoke first. This is a list of all (valid for current version) upgrade scripts which will be executed one by one with presented order.

Upgrade steps

Each upgrade step is a PowerShell script that has some work to do.

Upgrade Tool checks whether step should be executed or not. If your items meets certain criteria:

  • missing base templates
  • obsolete items
  • missing content items

then upgrade script will be invoked, otherwise next script from the queue will be processed.

Once Upgrade Tool finds some step which reports that there is something that have to be fixed, user will be prompted for an approve before execution.

Most of the scripts will present only small info window with step’s name and description, but some of them might require additional interaction with a user, so you can expect additional windows with options.

Dry Run

When checked particular upgrade step will be run in ‘safe mode’. Nothing will be altered in your content, until you run it normally (not in dry run mode). During this mode, script will display what changes will be performed once you decide to run it.

If you are ready to execute an upgrade step just click Process

After you invoke all upgrade steps you should see following message (empty list view with no upgrade steps)

This means you are ready to go. Your content has been successfully upgraded and you can use new SXA features.


This section aggregates useful information.

Can I postpone upgrade?

The main goal of Upgrade Tool is to make your existing content compatible with newest version of SXA. In theory you should be able to use all new features of SXA without any problems but only on new sites. You should treat old sites as “locked” sites.

Warning: After this upgrade you have to do it. Your old sites will stop working due to serious changes in grid systems.

Upgrade Tool defines an order of upgrade scripts

You cannot do anything with that. Some upgrade scripts might depend on different steps thus an order is strictly defined by SXA team

Upgrade procedure can be executed in several steps

You are not forced to execute everything at once. If you feel uncomfortable you can backup your solution after each step. You can stop upgrade at any time (between scripts, doing it when script is running can produce unexpected results)

Which versions I can upgrade?

Upgrade Tool supports upgrade from SXA 1.2+ version only.

Upgrade - single run

In the future, you don’t have to upgrade your SXA step by step (1.2->1.3, 1.3->1.4).

You can skip steps in between and do everything in a single run. Upgrade Tool will automatically detect all necessary steps (valid in the current upgrade context) and run them.


I hope your upgrade procedure will work fine. For me it did. You can expect the next version of XA.Reference site very soon.

For more information about upgrade please refer to Sitecore Experience Accelerator Upgrade Guide

Sitecore Utilities: Cache Viewer

Utility used to scan Sitecore cache. You can inspect cache details and view or remove particular cache entries. Continue reading

Sitecore Utilities: Unicorn Packaging

Published on January 29, 2019

SXA Health Check

Published on October 22, 2018