Import and Export with Migrations
How to import content and schema while migrating them into newer alternatives
As well as importing the content and schema directly, we also provide support for modifying the items as part of the process.
For example, you may have taken an export from an Umbraco 8 site, and are looking to import it into a newer major version. In this situation, most content and schema will carry over without issue. However, you may have some items that are no longer compatible. Usually this is due to a property editor - either a built-in Umbraco one or one provided by a package. These may no longer be available in the new version.
Often though there is a similar replacement. Using Deploy's import feature we can transform the exported content for the obsolete property into that used by the new one during the import. The migration to a content set compatible with the new versions can then be completed.
For example, we can migrate from a Nested Content property in Umbraco 8 to a Block List in Umbraco 13.
We provide the necessary migration hooks for this to happen, divided into two types - artifact migrators and property migrators.
Artifact migrators
Artifact migrators work by transforming the serialized artifact of any imported artifact, via two interfaces:
IArtifactMigrator
- where the migration occurs at the artifact property levelIArtifactJsonMigrator
- where the migration occurs at the lower level of transforming the serialized JSON itself.
Implementations to handle common migrations of Data Types from obsoleted property editors are available:
ReplaceMediaPickerDataTypeArtifactMigrator
- migrates a Data Type from using the legacy Media Picker to the current version of this property editorReplaceNestedContentDataTypeArtifactMigrator
- migrates a Data Type based on the obsolete Nested Content property editor to the Block ListReplaceGridDataTypeArtifactMigrator
- migrates a Data Type based on the legacy Grid layout into the Block GridReplaceUnknownEditorDataTypeArtifactMigrator
- replaces any unknown editor alias with a label
We've also made available base implementations that you can use to build your own migrations. You may need to handle the transfer of information between other obsolete and replacement property editors that you have in your Umbraco application.
ArtifactMigratorBase<TArtifact>
- migrates the artifact of the specified typeDataTypeArtifactMigratorBase
- migrates Data Type artifactsReplaceDataTypeArtifactMigratorBase
- migrates a Data Type from one property editor to anotherArtifactJsonMigratorBase<TArtifact>
- migrates the JSON of the specified artifact typeReplaceGridDataTypeArtifactMigratorBase
- migrates a Data Type based on the legacy Grid layout into the Block Grid
Property migrators
Property migrators work to transform the content property data itself. They are used in the Deploy content connectors (documents, media and members) when the property editor is changed during an import:
Again we have an interface:
IPropertyTypeMigrator
Implementations for common migrations:
MediaPickerPropertyTypeMigrator
NestedContentPropertyTypeMigrator
GridPropertyTypeMigrator
And a base type to help you build your own migrations:
PropertyTypeMigratorBase
GridPropertyTypeMigratorBase
Property editor changes are determined by comparing the PropertyEditorAliases
dictionary stored in the content artifact to the current Content Type/Data Type configuration. The dictionary contains editor aliases for each content property.
Registering migrators
Migrators will run if you have registered them, so you can enable only the ones needed for your solution.
You can do this via a composer, as in the following example. Here we register two of the migrators shipped with Umbraco Deploy:
Import and migration flow
When an import is started, the following happens:
Artifact signatures are read from the import provider (using
IArtifactImportProvider.GetArtifactSignatures()
).The artifact signatures are sorted based on dependencies with
Ordering
enabled (ensuring dependent items are processed in the correct order, like parent items before children and data types before document types).For each artifact signature:
Check whether the entity type is allowed to be imported.
Publish an
ArtifactImportingNotification
(cancelling will skip importing the artifact).
Publish a
ValidateArtifactImportNotification
:Deploy adds a default handler (
ValidateArtifactImportDependenciesNotificationHandler
) to validate whether all dependencies are either in the import or already present in the current environment. It emits warnings for missing content artifacts, missing or different artifact checksums and errors for missing schema artifacts.The import fails on validation errors or 'soft' fails on warnings if the
WarningsAsErrors
import option is set.
Create a Deploy scope and context (containing the 'owner' user for auditing purposes and cultures to import, in case the user doesn't have edit permissions for all languages).
For each artifact signature:
Create a (readonly)
Stream
for the artifact (usingIArtifactImportProvider.CreateArtifactReadStream(Udi)
).Deserialize the artifact into a generic JSON object (
JToken
).Parse the
__version
and__type
properties and resolve the artifact type (usingIArtifactTypeResolver
).Migrate the JSON object (using
IArtifactJsonMigrator
).Deserialize the JSON object into the artifact type.
Migrate the artifact (using
IArtifactMigrator
).Initialize artifact processing (using
IServiceConnector.ProcessInit(...)
) and track deploy state with next passes.
For each next process pass (starting at the lowest initial next pass):
Process artifact (using
IServiceConnector.Process(...)
).During processing: service connectors for content, media and members migrate property type values if a property editor alias has changed (using
IPropertyTypeMigrator
).When no next pass is required (the deploy state returns -1 as next pass):
Publish an
ArtifactImportedNotification
.Report the import process (using
IProgress.Report(...)
).
The Deploy scope is completed, causing all scoped notifications to be published to handlers implementing
IDistributedCacheNotificationHandler
) and completing the import.
Details of Specific Migrations
Umbraco Deploy ships with migrators to handle the conversion of core property editors as they have changed, been removed or replaced between versions.
Open source migrators may be built by HQ or the community for property editors found in community packages. They will be made available for use and review via the Umbraco.Deploy.Contrib
package.
Grid to Block Grid
The Grid editor introduced in Umbraco 7 can still be used in version 13 but has been removed from Umbraco 14. Its functionality is replaced with the Block Grid editor.
With Deploy migrators we have support for migrating Data Type configuration and property data between these property editors.
You can configure the default migration with the following composer:
The project you are importing into needs to know about any custom legacy Grid editor configurations to migrate to the Block Grid editor correctly. Make sure to either copy the grid.editors.config.js
and package.manifest
(containing grid editors) files or override the GetGridEditors()
method of the artifact migrator to provide this.
These implementations make use of the following conventions to migrate the data:
ReplaceGridDataTypeArtifactMigrator
:Grid layouts are migrated to an existing or new element type with an alias based on the layout name, prefixed with
gridLayout_
(this can be customized by overridingMigrateGridTemplate()
);Row configurations are migrated to an existing or new element type with an alias based on the row name, prefixed with
gridRow_
(this can be customized by overridingMigrateGridLayout()
);Similarly, grid editors are migrated to an existing or new element type with an alias based on the editor alias, prefixed with
gridEditor_
(this can be customized by overridingMigrateGridEditor()
). The available editors are retrieved from thegrid.editors.config.js
files (can be overridden inGetGridEditors()
). Each migrated grid editor will have the following property types added to the element type:The
media
grid editor is migrated to multiple properties: thevalue
property contains the selected media item (using Media Picker v3),altText
the alternate text (using a Textbox) andcaption
the caption (also using a Textbox);The remaining grid editors create a single
value
property that uses the following editors:rte
- the default 'Rich Text Editor', falling back to the firstUmbraco.TinyMCE
editor.headline
- the default 'Textstring', falling back to the firstUmbraco.TextBox
editor.macro
andembed
grid editors are converted into rich text editors.quote
or any other - use falling back to the firstUmbraco.TextArea
editor.
The block label is also updated for the built-in grid editors, ensuring a nice preview is available (the WYSIWYG style previews are incompatible between these editors, so the custom views are not migrated);
Grid settings config and styles are migrated to a new element type with a random alias, prefixed with
gridSettings_
(this can be customized by overridingMigrateGridSettings()
). This is because the migration only has context about the Data Type configuration (not the actual Data Type) and multiple Data Type can potentially use the same configuration (for config and styles), so there's no predictable way to create a unique alias. The migrated settings element type will have the property types added for the config and styles:Each config setting is migrated to a property with an alias based on the key, prefixed with
setting_
and added below a 'Settings' property group;Similarly, each style is migrated to a property with an alias based on the key, prefixed with
style_
and added below a 'Styles' property group;The following property editors are used for these properties based on the config/style view:
radiobuttonlist
- a new 'Radio Button List' Data Type that uses the pre-values;multivalues
- a new 'Checkbox List' Data Type that uses the pre-values;textstring
- the default 'Textstring', falling back to the firstUmbraco.TextBox
editor.mediapicker
andimagepicker
- the default 'Media Picker' (v3, single image), falling back to the firstUmbraco.MediaPicker3
editor.boolean
- the default 'Checkbox', falling back to the firstUmbraco.TrueFalse
editor.number
- the default 'Numeric', falling back to the firstUmbraco.Integer
editor.treepicker
,treesource
,textarea
or any other - the default 'Textarea', falling back to the firstUmbraco.TextArea
editor.
GridPropertyTypeMigrator
:Gets the grid layout and row configuration element types based on the alias prefix/name convention used by the Data Type artifact migrator;
The grid editor values are migrated to the respective properties:
The
media
grid editor converts the value to a media item with crops (based on the UDI or media path), including the focal point (although this needs to be enabled on the Data Type), alternate text and caption;All other values are converted to a text value or otherwise to a JSON string;
If a row or cell contains settings config or styles and the corresponding block has a settings element type configured, the settings config and styles are migrated to their respective properties in a similar way, based on the property editor alias:
Umbraco.MediaPicker3
- removesurl('
from the beginning and')
from the end of the value (commonly used as a modifier and added to the stored value), before trying to get the media item by a path.All other values are returned as-is.
Given the flexibility of the grid editor and Block Grid you may want to take further control over the migration. You can do that by creating your own migrator classes, that make use of our provided base classes. You would then register your own migrators instead of the ones shipped with Umbraco Deploy in your composer.
The base classes provide the following functionality. Methods you should look to override to amend the default behavior have been noted above.
ReplaceGridDataTypeArtifactMigratorBase
- replaces theUmbraco.Grid
Data Type editor alias withUmbraco.BlockGrid
and migrates the configuration:The number of columns is copied over.
Grid layouts, row configurations and grid editors are migrated to blocks:
If multiple grid layouts are configured or if at least one contains multiple sections or isn't the full width, each grid layout will be migrated to a 'layout block' (an element type without properties).
If multiple row configurations are configured or if at least one contains areas that don't allow all grid editors or has a maximum amount of items set, each row configuration is migrated to a block (this is also always done when there are multiple grid layouts, as each layout can configure allowed row configurations).
All grid editors are migrated to blocks (allowing a single grid editor to be migrated to multiple blocks to support DocTypeGridEditor, as that allows selecting different element types).
The settings config and styles are migrated to a single element type (even though each setting can define whether it's supported for rows and/or cells) and used on the blocks that are allowed.
Block groups are added for Layout and Content and used on the corresponding block types.
GridPropertyTypeMigratorBase
- migrates the property data from theGridValue
into theBlockValue
(using theUmbraco.BlockGrid
layout):The related Data Type is retrieved to get the configured blocks.
All grid control values are first migrated into their content blocks.
Settings config and styles for 'grid cells' are stored on the area within a row, but areas in the Block Grid can't have settings, so this is migrated into the first migrated grid control content block instead.
If a layout block can be found for the row configuration name, all grid controls are wrapped into that block.
Similarly, if a layout block can be found for the grid layout name, all items are wrapped into that block.
The JSON serialized
BlockValue
is returned.
Migrating From Doc Type Grid Editor
Doc Type Grid Editor was a community package commonly used with the legacy grid editor. If you are using this with Umbraco 7 and up, you can export and migrate into the Block Grid on Umbraco 13 or above.
Ensure you are running the latest version of Umbraco.Deploy.Contrib
compatible with your Umbraco major version.
In your new project, register the following migrators to add support for the import from Doc Type Grid Editor grids:
The migrators add the following behavior:
ReplaceDocTypeGridEditorDataTypeArtifactMigrator
extendsReplaceGridDataTypeArtifactMigrator
and ensures any DocTypeGridEditor is migrated to blocks using the allowed element types. If the element types aren't found the default implementation will migrate to new element types.DocTypeGridEditorPropertyTypeMigrator
extendsGridPropertyTypeMigrator
and ensures the Doc Type Grid Editor values are mapped one-to-one to the block item data.
The artifact migrator adds the default DocTypeGridEditor configuration (with alias docType
). This can be disabled by setting the AddDefaultDocTypeGridEditor
property to false
in a custom/inherited class. Similar to the base migrator, any custom DocTypeGridEditor configurations must be available to migrate to the Block Grid editor correctly.
Migrating from Matryoshka
Matryoshka was an Umbraco package that added tab support for document types in Umbraco. The feature was subsequently added to the product itself.
We provide a migrator for this package in Umbraco.Deploy.Contrib
.
This adds support for migrating Matryoshka Group Separators into native property groups. It removes the Matryoshka Data Types during import and migrates the document, media and member types. Native property groups are also changed into tabs, similarly to how they were displayed with Matryoshka installed.
To use, you register the migrators:
Source Code Example - Nested Content to Block List
As described above, the nested content to block list migration will occur register the corresponding migrator with your application.
To help write your own migrations, we share the source code of an example that ships with Umbraco Deploy. This migration converts Nested Content to Block List.
First we have the artifact migrator that handles the conversion of the configuration stored with a datatype:
And secondly we have the property migrator that handles restructuring the content property data:
Last updated