Merge pull request #6533 from ronaldbarendse/deploy/import-operation-order

Document Deploy legacy property type migrators, import and migration flow and clarify grid editor configuration

Author: sofietoft

13/umbraco-deploy/deployment-workflow/import-export-v7.md

@@ -1,17 +1,17 @@
 ---
 meta.Title: Migrating from Umbraco 7
-description: How to export content and schema from Umbraco 7 and import into a newer version
+description: How to export content and schema from Umbraco 7 and import them into a newer version
 ---
 
-### Migrating from Umbraco 7
+# Migrating from Umbraco 7
 
-The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from there in the same way.
+The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from the backoffice or use the service.
 
-We can use this feature to help migrate from Umbraco 7 to a supported major version. However, it requires additional logic to be added to the Deploy Contrib project.
+However, you can still use this feature to help migrate from Umbraco 7 to a supported major version. This requires adding additional logic to your Umbraco 7 project to create an export ZIP archive similar to newer versions.
 
-#### Exporting Umbraco 7 content and schema
+## Exporting Umbraco 7 content and schema
 
-We can generate an export archive in the same format as used by the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project. This archive can then be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.
+You can generate an export archive in the same format as the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project (that already has Deploy and Deploy Contrib installed, see below). This archive can be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.
 
 This is possible via code, by temporarily applying a composer to an Umbraco 7 project to generate the export archive on start-up:
 
@@ -88,7 +88,7 @@ public class DeployExportApplicationHandler : ApplicationEventHandler
 
 </details>
 
-#### Importing Umbraco 7 content and schema
+## Importing Umbraco 7 content and schema
 
 To import this archive into a newer Umbraco project, you need to install either of these packages:
 
@@ -150,6 +150,9 @@ internal class LegacyImportComposer : IComposer
         builder.DeployArtifactMigrators()
             .AddLegacyMigrators()
             .Append<ElementTypeArtifactMigrator>();
+
+        builder.DeployPropertyTypeMigrators()
+            .AddLegacyMigrators(); // Available from Deploy Contrib 13.3.0 and 14.2.0+
     }
 
     private class ElementTypeArtifactMigrator : ElementTypeArtifactMigratorBase
@@ -167,23 +170,23 @@ internal class LegacyImportComposer : IComposer
 It is recommended to start by importing only the schema and schema files (by deselecting 'Content' and 'Content files' in the dialog). Then, you can proceed with importing all content and schema together. The order in which the artifacts are imported depends on their dependencies. By importing the schema first, we ensure that the schema is updated before any content is processed.
 {% endhint %}
 
-#### Obtaining Umbraco Deploy for Umbraco 7
+## Obtaining Umbraco Deploy for Umbraco 7
 
 Umbraco Deploy for Umbraco 7 is no longer supported and was only available on Umbraco Cloud. It was not released for use on-premise.
 
 As such if you are looking to migrate from an Umbraco Cloud project running on Umbraco 7, you already have Umbraco Deploy installed.
 
-If you have an Umbraco 7 on-premise website, you can use this guide to migrate from on-premise to Umbraco Cloud. Or to upgrade to a newer Deploy on-premise version. You will need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.
+If you have an Umbraco 7 on-premises website, you can use this guide to migrate from on-premises to Umbraco Cloud. Or to upgrade to a newer Deploy On-premises version. You need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.
 
 The export feature can be used without a license.
 
 {% hint style="info" %}
 
-A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or an on-premise one.
+A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or a Deploy On-premises one.
 
 {% endhint %}
 
-Use this guide to migrate from on-premise to Umbraco Cloud or to upgrade to a newer Deploy version on-premise.
+Use this guide to migrate from on-premises to Umbraco Cloud or to upgrade to a newer Deploy On-premises version.
 
 1. Download the required `dll` files for Umbraco Deploy for Umbraco 7 from the following links:
 
@@ -226,4 +229,4 @@ Use this guide to migrate from on-premise to Umbraco Cloud or to upgrade to a ne
 
 4. Export Content.
 
-- **Export** your content, schema, and files to zip.
+- **Export** your content, schema, and files to zip.

13/umbraco-deploy/deployment-workflow/import-with-migrations.md

@@ -87,6 +87,34 @@ internal class ArtifactMigratorsComposer : IComposer
 }
  ```
 
+### Import and migration flow
+
+When an import is started, the following happens:
+1. Artifact signatures are read from the import provider (using `IArtifactImportProvider.GetArtifactSignatures()`).
+2. 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).
+3. For each artifact signature:
+   1. Check whether the entity type is allowed to be imported.
+   2. Publish an `ArtifactImportingNotification` (cancelling will skip importing the artifact).
+4. 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.
+5. 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).
+6. For each artifact signature:
+   1. Create a (readonly) `Stream` for the artifact (using `IArtifactImportProvider.CreateArtifactReadStream(Udi)`).
+   2. Deserialize the artifact into a generic JSON object (`JToken`).
+   3. Parse the `__version` and `__type` properties and resolve the artifact type (using `IArtifactTypeResolver`).
+   4. Migrate the JSON object (using `IArtifactJsonMigrator`).
+   5. Deserialize the JSON object into the artifact type.
+   6. Migrate the artifact (using `IArtifactMigrator`).
+   7. Initialize artifact processing (using `IServiceConnector.ProcessInit(...)`) and track deploy state with next passes.
+7. For each next process pass (starting at the lowest initial next pass):
+   1. Process artifact (using `IServiceConnector.Process(...)`).
+   2. During processing: service connectors for content, media and members migrate property type values if a property editor alias has changed (using `IPropertyTypeMigrator`).
+   3. When no next pass is required (the deploy state returns -1 as next pass):
+      1. Publish an `ArtifactImportedNotification`.
+      2. Report the import process (using `IProgress.Report(...)`).
+8. 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.
@@ -95,7 +123,7 @@ Open source migrators may be built by HQ or the community for property editors f
 
 #### Grid to Block Grid
 
-The grid editor introduced in Umbraco 7 has been removed from Umbraco 14. It's functionality is replaced with the 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.
 
@@ -118,6 +146,10 @@ internal sealed class DeployMigratorsComposer : IComposer
 }
 ```
 
+{% hint style="info" %}
+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.
+{% endhint %}
+
 These implementations make use of the following conventions to migrate the data:
 
 - `ReplaceGridDataTypeArtifactMigrator`:
@@ -201,6 +233,10 @@ The migrators add the following behavior:
 - `ReplaceDocTypeGridEditorDataTypeArtifactMigrator` extends `ReplaceGridDataTypeArtifactMigrator` 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` extends `GridPropertyTypeMigrator` and ensures the Doc Type Grid Editor values are mapped one-to-one to the block item data.
 
+{% hint style="info" %}
+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.
+{% endhint %}
+
 #### Migrating from Matryoshka
 
 [Matryoshka](https://our.umbraco.com/packages/backoffice-extensions/matryoshka-tabs-for-umbraco-8/) was an Umbraco package that added tab support for document types in Umbraco. The feature was subsequently added to the product itself.

14/umbraco-deploy/deployment-workflow/import-export-v7.md

@@ -5,13 +5,13 @@ description: How to export content and schema from Umbraco 7 and import into a n
 
 ### Migrating from Umbraco 7
 
-The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from there in the same way.
+The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from the backoffice or use the service.
 
-We can use this feature to help migrate from Umbraco 7 to a supported major version. However, it requires additional logic to be added to the Deploy Contrib project.
+However, you can still use this feature to help migrate from Umbraco 7 to a supported major version. This requires adding additional logic to your Umbraco 7 project to create an export ZIP archive similar to newer versions.
 
 #### Exporting Umbraco 7 content and schema
 
-We can generate an export archive in the same format as used by the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project. This archive can then be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.
+You can generate an export archive in the same format as the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project (that already has Deploy and Deploy Contrib installed, see below). This archive can be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.
 
 This is possible via code, by temporarily applying a composer to an Umbraco 7 project to generate the export archive on start-up:
 
@@ -150,6 +150,9 @@ internal class LegacyImportComposer : IComposer
         builder.DeployArtifactMigrators()
             .AddLegacyMigrators()
             .Append<ElementTypeArtifactMigrator>();
+
+        builder.DeployPropertyTypeMigrators()
+            .AddLegacyMigrators(); // Available from Deploy Contrib 13.3.0 and 14.2.0+
     }
 
     private class ElementTypeArtifactMigrator : ElementTypeArtifactMigratorBase
@@ -173,17 +176,17 @@ Umbraco Deploy for Umbraco 7 is no longer supported and was only available on Um
 
 As such if you are looking to migrate from an Umbraco Cloud project running on Umbraco 7, you already have Umbraco Deploy installed.
 
-If you have an Umbraco 7 on-premise website, you can use this guide to migrate from on-premise to Umbraco Cloud. Or to upgrade to a newer Deploy on-premise version. You will need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.
+If you have an Umbraco 7 on-premises website, you can use this guide to migrate from on-premises to Umbraco Cloud. Or to upgrade to a newer Deploy On-premises version. You need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.
 
 The export feature can be used without a license.
 
 {% hint style="info" %}
 
-A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or an on-premise one.
+A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or a Deploy On-premises one.
 
 {% endhint %}
 
-Use this guide to migrate from on-premise to Umbraco Cloud or to upgrade to a newer Deploy version on-premise.
+Use this guide to migrate from on-premises to Umbraco Cloud or to upgrade to a newer Deploy On-premises version.
 
 1. Download the required `dll` files for Umbraco Deploy for Umbraco 7 from the following links:
 
@@ -226,4 +229,4 @@ Use this guide to migrate from on-premise to Umbraco Cloud or to upgrade to a ne
 
 4. Export Content.
 
-- **Export** your content, schema, and files to zip.
+- **Export** your content, schema, and files to zip.