Sitecore
Sitecore Content Packages
May 11, 2017 Dalibor Kovač

Sitecore is a web content management system and digital marketing platform. In this post I’ll be looking at Sitecore content packages that can be used for copying content between Sitecore instances.

When do we need to use content packages?

There are a couple of usages for Sitecore content packages:

 

Content data migration

Whether you need to copy just one or two items from one Sitecore instance to another, or you need to perform a mass data migration - content packages can come in handy.

 

During development

While developing Sitecore based solutions developers create or modify Sitecore templates, and these template changes need to be installed to test and production Sitecore instances. Content packages can be used for that on smaller projects, but for larger projects it’s recommended to use rel="noopener noreferrer" a specialized tool like Team Development for Sitecore (TDS). TDS can make your life a lot easier by keeping your template changes in sync with the changes in your code.

 

Installing Sitecore modules

Sitecore modules that you develop, rel="noopener noreferrer" or third party modules rel="noopener noreferrer" that you download from Sitecore Marketplace are normally installed using content packages. Besides Sitecore items, packages can also include files, binaries, and installation instructions.

Important note: do not confuse “content packages” with “update packages”. Update packages are issued by Sitecore specifically for upgrading to new versions, they come with a set of installation instructions and they are installed in a different way!

 

Sitecore tools for working with content packages

With every Sitecore installation you get two Development Tools that are used for creating and installing content packages. You have to use the “Desktop” user interface to run them:

 SitecoreContentPackages-IMG1

 

Package Designer is used for exporting data from source instance. In this tool you specify which content items you want to export and create a Sitecore content package. That package is actually a ZIP file that contains all the data about your selected items.

 

Installation Wizard is used for importing data into target Sitecore instance. Using this tool you upload the Sitecore content package (ZIP file created by Package Designer) to your target instance and run the import. The tool is called “installation wizard” because it is also used to install additional modules into your Sitecore instance.

Sitecore content packages can safely be used for migrating content between different versions of Sitecore. For example, if you create content package on Sitecore version 6 you will be able to import it into Sitecore version 8.

 

Designing and exporting content packages

Designing a package actually means creating a package specification that tells the export process which items should be exported. Once created, this package specification can be saved to an xml file and reused to repeat the same export at a later time or perhaps on another Sitecore instance. No items are exported while designing the package – you’re just specifying what needs to be done and the real export starts when you press “Generate ZIP” button.

Inside one package specification you can have one or more sources, and each source specifies a group of items to be exported.

 SitecoreContentPackages-IMG2

Items can be added to sources statically (“Add items statically” button) or dynamically (“Add items dynamically” button). Content export is usually done from Sitecore’s “master” database, but in the first step of adding items to the source you can choose the Sitecore database you want to export from (core, master or web).

 

Adding items statically

When adding items statically you’re picking individual items from Sitecore content tree. When you pick an item you can choose to add it to the package individually, or together with all its subitems (descendants). No matter which of these methods you use, adding items statically to a package always creates a static list of items that will be exported. Even if you have chosen to add the folder item with all its subitems Sitecore will generate a list of all those items as they existed in the moment when package specification was created.

 SitecoreContentPackages-IMG3

If you add some new items to that folder and reuse that static package specification to do the export again these new items will not be exported (because they weren’t included on that original list when package specification was created).

 

On the “Installation Options” tab you can choose in advance how import process will behave if some of the items that need to be imported already exist on target instance (when importing this package). You can choose between Overwrite, Merge, Skip, and Ask User. The default is Ask User and it’s best to leave it that way. In that case the installer will ask you what to do during import.

 

On the “Preview” tab you can preview the list of files that will be included in your generated package, and on the “Name” tab you can just change the source name.

 

Adding items dynamically

Adding items dynamically to a package doesn’t store a list of items. It stores a starting point (search root item) and optional filters to narrow down the selection of items in the sub-tree that descends from the root item. The final list of items to be exported is determined at the moment you do the export (when you click “Generate ZIP”).

 SitecoreContentPackages-IMG4

That way any newly added items will also be exported if you reuse your package specification to do the export at a later point in time.

In dynamic sources, beside search root item, you can also specify various filters. When you start package generation process (“Generate ZIP” button) Package Designer will fetch the items by starting from the search root item, going down the tree, and applying all the filters you defined (if any). Items that satisfy filter conditions will be included into the package. You can set filter conditions by:

  • Item name
  • Creation date
  • Modification date
  • Publish date
  • Template
  • Created by
  • Updated by
  • Language

 

Important note: If you use more than one filter at the same time they will be combined using logical AND. If you want to achieve logical OR effect you need to create two packages with the same search root item but with a different filter. So, you'll do two separate exports, one for newly created items and one for recently modified items. The union of two generated content packages create the logical OR effect that we wanted to achieve. And then you will do two imports into target instance.

If some of your items are included in both packages (because newly created items will also have the update date from the same period) you will be asked to resolve a conflict during import – the import process will ask you what to do. In that case it’s best to choose Merge – Merge option in the dialog that appears.

For example, if you want to export items that have been created OR modified within past 3 days, you would create two packages with the same search root item, but one would have a condition Created within the past 3 days and the other would have a condition Modified within the past 3 days. If both conditions were combined in one source they would produce the condition “Created AND modified within the past 3 days, and that's not what we wanted to achieve.

Wait, but why do I need two packages? Can't I just make one package with two sources – one with “created” filter, and one with “modified” filter? Well, you could, but in that case some of your items that have both Created Date and Updated Date in that period will be included twice in the same content package and on import that would create two identical versions on your item. Because of that it’s best to keep these two content packages separate.

 

So, which source type to use? Static or Dynamic?

Well, that depends on what you need to achieve. If you have a cherry picked list of items you need to export, from different parts of Sitecore content tree – static sources are the way to go. Dynamic sources, on the other hand, are more suitable for exporting whole sub-trees of items. By using filters they can become a very powerful tool for extracting specific content from your Sitecore database.

You can mix static and dynamic sources in one package specification.

 

Importing content packages

Installation Wizard is a much simpler tool than Package Designer. You use it on target instance to import the package previously created on source instance.

 SitecoreContentPackages-IMG5

It allows you to upload the package (or choose the one that was uploaded earlier) and start the import. While importing, if the import process finds that the item that needs to be imported already exists on the instance it will ask you what to do.

 

 SitecoreContentPackages-IMG6

There are 3 options: Overwrite, Merge and Skip, with Merge having some sub-options. These options are very well explained in this blog post by Martijn van der Put, so I will not repeat that here. You can use the chosen option only for the item currently being imported (if you click “Apply” button) or you can use “Apply to all” button to use the chosen option for the current item and all its subitems. If you use “Apply to all” you still might get multiple questions like this, as import process starts importing changes from different branches in your Sitecore content tree.

 

Databases and Publishing

Content import is done into the same Sitecore database from which items were exported (core, master or web). You cannot choose that while importing.

If you have done content export/import in “master” database you need to publish your new or modified items to be able to see the changes on your website (which draws content from “web” database).

I hope you found this blog post useful, and that it will help you master content packages.

Dalibor Kovač
Solution Architecture & Development