Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Oct 16, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
5a2800c
Update legacy import composer example (add legacy property type migra…
ronaldbarendse Oct 4, 2024
f0e6620
Add 'Import and migration flow' paragraph
ronaldbarendse Oct 4, 2024
0ad2685
Add note about providing custom grid editor configuration
ronaldbarendse Oct 7, 2024
266d18e
Add note about custom DTGE grid editor configuration
ronaldbarendse Oct 7, 2024
049bcbd
Apply suggestions from code review
ronaldbarendse Oct 15, 2024
37ab97d
Apply suggestions to 14
sofietoft Oct 16, 2024
bb4be99
Apply suggestions to 14
sofietoft Oct 16, 2024
8d473d4
Fix vale error
sofietoft Oct 16, 2024
898c98a
Minor changes to trigger checks
sofietoft Oct 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 15 additions & 12 deletions 13/umbraco-deploy/deployment-workflow/import-export-v7.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand Down Expand 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:

Expand Down Expand 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
Expand All @@ -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:

Expand Down Expand Up @@ -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.
38 changes: 37 additions & 1 deletion 13/umbraco-deploy/deployment-workflow/import-with-migrations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,34 @@
}
```

### Import and migration flow

When an import is started, the following happens:
1. Artifact signatures are read from the import provider (using `IArtifactImportProvider.GetArtifactSignatures()`).
Copy link
Contributor

@sofietoft sofietoft Oct 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before I start working on this list, I need to know: Is it steps that the user needs to go through, or is it an explanation of what happens during a migration/import? 🤔

Copy link
Contributor Author

@ronaldbarendse ronaldbarendse Oct 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an explanation of the things that happen and should give users a better understanding of the (order of) operations.

We also hadn't documented the notifications yet or the fact a default ValidateArtifactImportDependenciesNotificationHandler is added by Deploy. We might want to add a separate section about notifications though, as we also have notifications that happen during export (ArtifactExportingNotification and ArtifactExportedNotification).

Copy link
Contributor

@sofietoft sofietoft Oct 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I wont touch the list then 💪

It would be great to have a new section about notifications.
Let me know what you need from us to set this up!

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.
Expand All @@ -95,7 +123,7 @@

#### 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.

Expand All @@ -118,6 +146,10 @@
}
```

{% hint style="info" %}

Check warning on line 149 in 13/umbraco-deploy/deployment-workflow/import-with-migrations.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words).

Raw Output:
{"message": "[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words).", "location": {"path": "13/umbraco-deploy/deployment-workflow/import-with-migrations.md", "range": {"start": {"line": 149, "column": 4}}}, "severity": "WARNING"}
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`:
Expand Down Expand Up @@ -201,6 +233,10 @@
- `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.
Expand Down
17 changes: 10 additions & 7 deletions 14/umbraco-deploy/deployment-workflow/import-export-v7.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand 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
Expand All @@ -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:

Expand Down Expand Up @@ -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.
Loading
Loading