Overview:
- What’s new in Umbraco Deploy 4.9/10.3/12.1 RCs?
- Content Import/Export with Migrations
- User Resolution in Target Environment
- Control Over Transfer of Public Access Rules
- How to get your hands on the release
The releases are available for solutions based on CMS versions 8, 10, and 12. If you are using the product in Umbraco 8, you can update it to the Deploy 4.9 release. As of Umbraco 10, the major versions of CMS and Deploy are aligned.
The versions for Deploy 10 and 12 are available today. The version for Umbraco 8 - which is Deploy 4 - will be released in the next day or two.
You can also expect these updates in the next release candidate and final version of Deploy 13.
As with previous releases, we are first issuing release candidates so you can evaluate what’s included and, ideally, try them out on your existing solutions. Of course, if you do find any issues, or simply have comments for further improvement on the new features, we welcome any feedback.
How to get access to the new versions and where to submit any comments and report issues, is discussed at the bottom of the post.
Let’s have a look at what you can expect in this latest release 👀
What’s new in Umbraco Deploy 4.9/10.3/12.1 RCs?
Content Import/Export with Migrations
The feature we've spent the most effort on for this release is a new option for the import and export of Umbraco content, files, and schema. We've focussed on this for two reasons.
Firstly, we're aware that, particularly on Azure web apps, which are used by Umbraco Cloud, when carrying out large transfer and restore operations, we can run into platform-imposed limitations. These manifest themselves as failed operations or gateway timeouts, and whilst we have various options available to troubleshoot and apply steps that resolve many of these issues, we, unfortunately, can't completely get around the hard limit imposed by the hosting environment.
Secondly, we want to improve the process for migrations into Umbraco Cloud and between different Umbraco versions.
We've handled both of these needs by introducing a new feature that allows you to select certain content items, trees, or the whole workspace for export to a zip file.
We have also added the ability to import this zip file into another environment, where its contents will be read, validated, and used to update the information in Umbraco.
In testing, we've found that, because this two-step process doesn't require inter-environment communication, it allows us to process much larger batches of information than is otherwise possible. Whilst the existing functionality for content transfer still makes the most sense for daily editorial work, we recommend this new method for one-off, large content transfers.
Importing and Exporting Umbraco Content and Schema
When exporting, you can choose to include associated media files and, if your account has access to the Settings section, the schema information and files as well.
Bear in mind that including media for a large site can lead to a very big zip file. So even with this option, you might want to consider other methods for transferring very large amounts of media - such as direct transfer between Cloud storage accounts.
Umbraco Deploy will then serialize all the selected items to individual files, archive them into a zip file and make that available for download.
That same zip file can be used to import the content, files and/or schema into a new environment. You can upload the file via the browser.
We validate the file before importing. Schema items that content depends on must either be in the upload itself or already exist on the target environment with the same details. If there are any issues that mean the import cannot proceed, it will be reported. You may also be given warnings, that you can review and choose to ignore if they aren't relevant for the action you are carrying out.
The import then proceeds, processing all the items provided in the zip file.
Migrating on Import
The second driver for building this feature is to provide the ability to make changes to the items as part of the import process. For example, you may have taken an export from an Umbraco 8 site, and are looking to import it into Umbraco 10 or 12. In this situation, most content and schema carry over without issue, but 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 - no longer being available in the new version.
Often, there is a similar replacement, and if we could transform the stored content for the obsolete property into that used by the new one, the migration to a content set compatible with the new versions would be complete.
We provide the necessary migration hooks for this to happen, divided into two types - artifact migrators and property migrators.
Artifact migrators work by transforming the serialized artifact of data types on import, via two interfaces:
- IArtifactMigrator - where the migration occurs at the artifact property level
- IArtifactJsonMigrator - 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 editor
- ReplaceNestedContentDataTypeArtifactMigrator
- - migrated from a data type based on the obsolete nested content property editor to the block list.
We've also made available base implementations that you can use to build your own migrations if there is a need to handle the transfer of information between any other obsolete and replacement property editors that you have in your Umbraco application:
- ArtifactMigratorBase<TArtifact>
- DataTypeArtifactMigratorBase
- ReplaceDataTypeArtifactMigratorBase
- ArtifactJsonMigratorBase<TArtifact>.
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
And a base type to help you build your own migrations:
- PropertyTypeMigratorBase
Migrators will only run if you've registered them; hence, you can enable just the ones needed for your solution.
This process and the options available are documented in more detail at the Umbraco documentation website.
Importing from Umbraco 7
Although we haven't backported this feature to a version of Deploy that runs on Umbraco 7, we can still make use of it in migrating content from that version of Umbraco into a more modern one. So long as we can generate an export zip file in the same format as that used by the content import/export feature, we can take that and import it into Umbraco 8 or above. And apply similar migrations to update obsolete data types and property data into newer equivalents.
Fortunately, we can do that via code - by temporarily applying a composer to an Umbraco 7 solution to generate the export file on start-up. Details of this process will shortly be published at the documentation link above.
User Resolution in Target Environment
When an editor working in a staging environment prepares some content and transfers it to production, currently, we are not able to correctly attribute the change to that user. When you look at the audit log in production, for example, you'll see the content has been updated and published by the super-user administrator account.
The reason this is the case is that, unlike most Umbraco data, users and user groups are maintained separately in different environments. This means that a user may or may not have an account in all environments, and even if they do, they likely won't match up by ID.
We're aware, though, that many customers do create user accounts for the same person in multiple environments, and when they do, more than likely, they use the same email address. Given that, we've built a facility to allow users to be resolved on transfers, such that the correct account is associated with the changes made.
Given this will change behavioru, we've made this an option that you can enable by setting the configuration value of ResolveUserInTargetEnvironment to true. We will likely make the default value of this true for Deploy 13 and onwards.
To set this value for Deploy 10+, assuming the use of the standard appSettings.json file for configuration, apply the following:
"Umbraco": {
"Deploy": {
"Settings": {
"ResolveUserInTargetEnvironment": true
}
}
}
Or for Deploy 4 (running on Umbraco 8), apply this update to the UmbracoDeploy.Settings.config file:
<?xml version="1.0" encoding="utf-8"?>
<settings>
<deploy resolveUserInTargetEnvironment="true" />
</settings>
With that in place, when a transfer is carried out, Deploy will look up the user account in the target environment based on the email address of the user that triggered the update. If found, their account will be used instead of the super-user account in the audit log, giving improved information about who has changed what content and when.
Control Over Transfer of Public Access Rules
When deploying content items, public access rules based on member groups are also transferred. We don't though remove any protection configured on a content node in the target environment if it has been removed in the source.
We've had reports from customers that would like to amend this behaviour, so we've provided a configuration option that will give you more control.
By default, and to preserve existing behaviour following upgrades, the default is AddOrUpdate. Further options are:
- None - no public access rules will be transferred
- Remove - public access rules removed a source environment will be removed in the destination
- All - all public access information will be transferred
How to get your hands on the new Umbraco Deploy release
As always, from today, all new Umbraco Cloud projects will be running the latest version of Umbraco Deploy. For existing projects, this upgrade is only 2 minutes away with the minor version upgrade feature.
We’ve wrapped it all up for you, so all you have to do now is follow these steps:
- Add a Development Environment to your project, if you do not already have one (Add a Development environment by clicking “Manage Environments” in the project view)
- Make sure you also restore the content to the Development Environment from your Live.
- When the Development Environment is all set up and you’ve made sure you don’t have any pending changes on the Development Environment - you are now ready to upgrade to the latest version of Umbraco Deploy!
- It's as easy as clicking a button, literally. The "Upgrade Available" button on the Development Environment will start the auto-upgrader and we’ll take care of everything from here! 🚀
- Once it's done, check the Development Environment to make sure everything is looking right.
- When that's confirmed, you are ready to deploy the upgrade to the next environment - Live or Staging, and start taking full advantage of all the new features.
And remember, you can always spin up a new project on Umbraco Cloud to try the latest versions of Umbraco CMS, Forms, and Deploy, either from your existing Umbraco Cloud account or by taking a free Umbraco Cloud trial.
Non-Cloud and release notes:
Release notes can be found on the Umbraco Deploy release notes page at the Umbraco documentation website.
The releases are available from the appropriate NuGet feed:
When is the Public Release?
We’re aiming for a full public release on Monday, December 11, 2023, when the package will be available for new and existing projects on Umbraco Cloud and via NuGet.
A big H5YR 🙌 to everyone who has contributed to these releases by highlighting pain points, reporting issues, providing feedback, and suggesting solutions. And thanks to everyone willing to lend a hand in testing it out.
Bug reports are best handled on the issue tracker, and as always, we welcome you to submit product feedback and questions to product@umbraco.com.