Migrate HST Channels

Due to structural changes to HST's channels, and due to the nature and complexity of these changes, the esv2yaml tool has not been extended to migrate the HST channels automatically. However, we have automated the needed changes by running specific migration code at repository startup to migrate the HST channels, in combination with using auto-export for exporting these changes to the project's configuration sources (YAML).

Prerequisites 

You need to have migrated your bootstrap resources from XML to YAML sources, and you must have upgraded the Auto-Export configuration to make sure HST configuration nodes get classified correctly. Also make sure to remove the '-preview' nodes below /hst:hst : If you don't, they will be removed automatically by the HstChannelPostMigratorToV12. Once you start up the production repository, the HstChannelPreMigratorToV12 will remove the -preview hst configuration nodes automatically. 

We recommend that you check any pending changes in to your VCS: This way you can see the changes resulting from the migration of the channels and check those in as a separate change. 

Re-allow Auto-Export Service

Earlier in the Upgrade Project Files step you (should have) disallowed the Auto-Export Service from running. Now this needs to be reverted to be able to proceed with the next step.

From the cargo.run profile in your root pom.xml, remove the repo.autoexport.allowed property with value false (its default, within the cargo.run profile, is true).
So remove the following property definition as introduced in Upgrade project Files:

<profile>
  <id>cargo.run</id>
  <properties>
    <repo.autoexport.allowed>false</repo.autoexport.allowed>

Migrating HST Channels

At this point your project has been converted to YAML bootstrap sources and your Auto-Export configuration is such that Auto-Export is enabled and correctly configured. Your YAML bootstrap sources now need to be transformed to have the hst:channel nodes moved to the correct new locations. See  HST Changes Background for more information.

For this migration to take place, start up the application locally with a new, empty repository:

$ rm -rf target && mvn -P cargo.run -Drepo.path=target/storage

This will trigger a migrator (HstChannelPostMigratorToV12) to move all hst:channel nodes to the correct location in the repository, after which Auto-Export will make sure the YAML sources get adjusted.  Look out for WARN or ERROR messages from org.onehippo.cm.model.migrator.HstChannelPostMigratorToV12. If Auto-Export is not enabled or cannot be started correctly, the migrator will throw a MigrationException, causing the startup of the repository to abort and exit. After the repository has start up correctly, all hst:channel nodes should have been relocated and the /hst:hst/hst:channels node should have been deleted.

Please note that the migrator may add empty nodes (such as hst:pages) that did not exist in the original configuration. You will notice these changes later on when using the Configuration Verifier.