Insights

Package Installation Options In Sitecore

Visual Guide To Sitecore Package Installation Options

Depiction of a Sitecore dev hoping nothing breaks after choosing merge-merge during every single package installs

Fig 1. Depiction of a Sitecore dev hoping nothing breaks after choosing merge-merge during every single package installs.

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

Example of a Sitecore message to perform the merge - clearing the matching items but not subitems

Example of a Sitecore message to perform the merge - appending any matching items

Example of a Sitecore message when performing a merge of the items and different versions of the package

1.2 Overwrite

Example of a Sitecore message showing the overwrite option to install a package

1.3 Skip

Example of a Sitecore message showing the skip option to install a package

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.

Example of the original version of the package in Sitecore before it is merged

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.

Example of a modified version of the original item being prepped for installation into Sitecore

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

Example of all versions of the original item being replaced by the new versions in Sitecore

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

Example of the Sitecore message when the new item's versions are all merged and no data is lost

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

Example of performing a merge of the items and different versions of the package

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.

Hey, Developers!

We're on the look out for talented developers to join our team.

Think you have what it takes?