Package Installation Options In Sitecore

Visual Guide To Sitecore Package Installation Options

Goal

Provide visual explanation of what happens for each Sitecore package install options and be a good reference for Sitecore devs.

Pre-requisite

Basic understanding of Sitecore package installation. If you are not familiar with package installation, please refer to Creating A Package In Sitecore by Ashwinder Manhas.

Scope

A single Sitecore item with versions will be considered. Behaviours of its children will not be visualized in this blog.

1. Overview

Let's look at all the installation options, ordered by the most vague description, to least vague.

1.1 Merge

1.2 Overwrite

1.3 Skip

Overwrite and skip are really straight forward, but the description provided for merge is really cryptic. One major source of confusion is: "What exactly is being merged?" What Sitecore really means, is it's trying to merge the VERSIONS of the item. So, we should be looking at how the versions of an item behave when installing packages.

2. Preparation

2.1 Original Item (Item That Currently Exists In Sitecore)

For the purpose of illustration, I prepared a test item with 3 versions. The red text on the right represents an arbitrary text field that will be used to track which version remains after package install.

2.2 Modified Item (Item That Will Be Installed By The Package Installer)

A slightly modified version of the original item has also been prepared, which will be installed. Note that version 1 has been removed and 4 has been added. Here the single quote is added to create distinction between original and modified.

3. Results

I now present the results of installing the modified item in 2.2 to the item in 2.1. Only the results of merge are shown. (Overwrite and skip are a bit trivial to show).

3.1 Merge - Clear

Perhaps the clearest (also the deadliest to original item's versions) of all merge options. All versions from the original item are gone and are replaced by the new item's versions. Note that the version numbers on the left are not preserved, but are mapped like so: (4, 3, 2) -> (3, 2, 1). It's not hard to see that new version numbers start from 1.

3.2 Merge - Append

As the name suggests, it simply stacks new item's versions on top of old item's versions. ALL versions survive the install. This is definitely the option to use if you do not want any loss of data.

3.3 Merge - Merge

Wherever there was overlap (version 2 and 3), it has been replaced by the new item's versions. If no overlap (version 1 and 4'), they were simply carried over. This is perhaps the most versatile of all the merge options, but can lose vital data if used improperly.

Conclusion

Hopefully this blog removes some of the ambiguities around Sitecore package installs. This simple test case by no means is a representative of all installation scenarios and edge cases. I intend to cover more depths and cases in future blogs.

Thank You.