Moving Content Between Umbraco Sites with a Package

This article explains how to move pages and images from one Umbraco site to another with Umbraco’s built-in package feature. The pages keep their keys, their links to each other, and their images. You do not need to copy the database or add a sync tool such as Umbraco Deploy or uSync.

In this article, the source is the site the pages come from, for example staging. The target is the site they go to, for example production.

The steps were tested on two Umbraco 17.6.2 sites. To try them on two throwaway local sites first, see the demo.

What to Expect

When the package carries pages and images only:

• Existing content stays as it is. The install only adds pages and images. Anything the target already has is left unchanged.
• Keys are kept. Each page keeps its key from the source. A key is a Globally Unique Identifier (GUID), the page’s permanent ID. Links between pages keep working when the linked page is in the package or already on the target with the same key. A link to any other page breaks.
• Images keep their paths. Image files arrive at the same paths, so the images inside the pages display.
• Pages arrive unpublished. You choose when they go live, even if they were published on the source.
• Each page is sent once. If the target already has a page with the same key, the install skips that page. A later correction on the source does not replace the target’s copy. For more information, see Sending a Correction.

Prerequisites

• Two Umbraco sites on the same version. The steps were tested on Umbraco 17.6.2.
• Access to the target’s source code, and a way to build and deploy it. Umbraco 17 installs packages through code. There is no install button in the backoffice.
• Python 3, to run package_needs.py. The script needs no extra libraries.

Creating the Package on the Source Site

A package takes one content node and, optionally, all the nodes below it. You cannot pick individual pages, so place everything you want to send under one node, such as a folder page.

The examples in this article send the following page:

Using the Backoffice

For more information, see Creating a Package Schema in the Backoffice in the Umbraco documentation.

1. Navigate to the Packages section.
2. Select Created in the top-right corner of the screen.
3. Click Create package.
4. Enter a name for the package. Package names must be unique on the site, so number them, for example Site Pages 1.
5. Under Content, select the top node and include its child nodes.
6. Under Media, select the images the pages use.
7. Leave every other field empty: Document Types, Media Types, Data Types, Templates, Stylesheets, Scripts, Partial Views, Languages, and Dictionary.
8. Click Create, then Download.

The download is a package.zip file. The ZIP file contains package.xml and the image files.

Using the Management API

You can also create the package with two calls to the Management API. Both calls need an API user’s access token in the Authorization: Bearer header. Send the body of the first call as JSON. The examples leave out the headers.

1. Create the package:

   POST /umbraco/management/api/v1/package/created
   {
     "name": "Site Pages 1",
     "contentNodeId": "<key of the top node>", "contentLoadChildNodes": true,
     "mediaIds": ["<key of each image>"],      "mediaLoadChildNodes": false,
     "documentTypes": [], "mediaTypes": [], "dataTypes": [], "templates": [], "partialViews": [],
     "stylesheets": [], "scripts": [], "languages": [], "dictionaryItems": []
   }

2. Download the package, using the ID from the Location header of the first response:

   GET /umbraco/management/api/v1/package/created/<id>/download

Checking What the Package Needs

Run package_needs.py on the downloaded file:

python3 package_needs.py package.zip

The output looks like this:

Document Types the target must already have:
  jobAid: body
  jobAidFolder: (no properties)
Media Types the target must already have:
  Image: umbracoBytes, umbracoExtension, umbracoFile, umbracoHeight, umbracoWidth
Carries only pages and images: yes

The script reads package.xml and lists:

• Each Document Type the pages use, with the properties they fill.
• Each Media Type the images use.

The last line must say yes. If the last line says NO, also DocumentTypes or similar, the package carries more than pages and images. Clear those fields on the source and create the package again.

Checking the Target’s Document Types

On the target, navigate to Settings > Document Types. For each Document Type the script listed, check that:

• A Document Type with the same alias exists. The key can differ, because the install matches Document Types by alias.
• The Document Type has every property the script listed, with the same aliases. Extra properties on the target are fine.
• Each property uses the same property editor as on the source. For example, both sites use the Rich Text Editor.

Then check each page’s template. In Settings > Templates, check that:

• A template with the same alias as the source page’s template exists.
• The Document Type allows that template.

The script cannot check property editors, because package.xml stores values, not editors. Compare the property editors on the two sites yourself.

The install matches templates by alias, and only uses a template the Document Type allows. Otherwise, the page gets the Document Type’s default template (PackageDataInstallation.cs). The page uses the target’s own template file, not the source’s.

Adding the Package to the Target’s Code

The target installs the package at startup through an automatic package migration. You add two things to the target project once. For later batches, you replace only the package.zip file.

1. Add a class that inherits from AutomaticPackageMigrationPlan:

   // ContentImport/ContentImportPackage.cs
   using Umbraco.Cms.Infrastructure.Packaging;
   
   namespace MySite.ContentImport;
   
   public class ContentImportPackage : AutomaticPackageMigrationPlan
   {
       public ContentImportPackage() : base("Site Pages") { }
   }

2. Save the downloaded file as ContentImport/package.zip, and add it to the .csproj file as an embedded resource:

   <ItemGroup>
     <EmbeddedResource Include="ContentImport/package.zip" LogicalName="MySite.ContentImport.package.zip" />
   </ItemGroup>

The LogicalName must be the class’s namespace followed by .package.zip or .package.xml. Umbraco looks for the package by that name (PackageMigrationResource.cs).

The name passed to base, Site Pages in the example, names the migration. It does not need to match the package name you entered on the source (AutomaticPackageMigrationPlan.cs).

Deploying the Target

Build, deploy, and restart the target. The install runs on its own at startup.

Check the log for these three lines:

Starting package migration for Site Pages
Package migration executed.
Package migration completed for Site Pages

If the lines are missing, see Troubleshooting.

Checking the Result

In the target’s backoffice, open the Content section and check that:

• The pages are there as drafts, in the same structure as on the source.
• The pages contain their text. Open a few pages to check. Opening pages is the only way to find a missing property, because the log does not report one.
• Links between pages point to the right pages.
• Images display.

Publishing the Pages

Publish the pages on the target when you are ready. Umbraco builds each page’s URL from its name.

Sending the Next Batch

1. Create a new package on the source, for example Site Pages 2.
2. Replace ContentImport/package.zip on the target with the new file. Keep the same file name, class, and name passed to base.
3. Build, deploy, and restart the target.

The install runs again because the contents of the file changed. A restart with an unchanged file does not run the install (AutomaticPackageMigrationPlan.cs).

You can send the same folder again with new pages added. The install skips pages the target already has, so only the new pages arrive. Nothing is duplicated.

Sending a Correction

A package cannot update a page the target already has. The install skips any page whose key already exists on the target (ImportPackageBuilderExpression.cs). To send a correction, remove the target’s copy first:

1. Make the correction on the source.
2. On the target, delete the page.
3. Empty the target’s recycle bin.
4. Send a new package that includes the page, as described in Sending the Next Batch.
5. Publish the corrected page on the target.

Troubleshooting

Further Reading

• The Umbraco documentation on Packages and Creating a Package.
• PackageDataInstallation.cs in the Umbraco 17.6.2 source. The file shows what an install does to each kind of item the target already has. For example, the install updates an existing Document Type in place. The package in this article leaves Document Types out for that reason.