Upgrade HST Background Information
Move of HST channels to new location and preview HST configuration model changed
In version CMS 12.0.0 we moved the channels below
/hst:hst/hst:channels
to the hst:configuration where they should had been in the first place. As a result also on the hst:mount nodes the property hst:channelpath has become redundant.
Next to that since version 12.0.0, the preview HST configuration only contains the hst:workspace of the live configuration and does inherit from the live configuration. Thus a typical old setup would look as follows:
+ hst:hst + hst:channels | + myproject | - hst:name = My Project | + hst:channelinfo + hst:configurations | + hst:common | + hst:abstractpages | + hst:templates | + ... + myproject | - hst:inheritsfrom = ../common | + hst:pages | + ... | + hst:workspace | + ... + myproject-preview | - hst:inheritsfrom = ../common | + hst:pages | + ... | + hst:workspace | + ... + hst:hosts | + dev-local | + localhost | + hst:root | - hst:channelpath = /hst:hst/hst:channels/myproject | - hst:mountpoint = /hst:hst/hst:sites/myproject + hst:sites + myproject
As of CMS 12.0.0, the above example would be as follows:
+ hst:hst + hst:configurations | + hst:common | + hst:abstractpages | + hst:templates | + ... + myproject | - hst:inheritsfrom = ../common | + hst:pages | + ... | + hst:workspace | + ... | + hst:channel | - hst:name = My Project | + hst:channelinfo + myproject-preview | - hst:inheritsfrom = ../myproject | + hst:workspace | + ... | + hst:channel | - hst:name = My Project | + hst:channelinfo + hst:hosts | + dev-local | + localhost | + hst:root | - hst:mountpoint = /hst:hst/hst:sites/myproject + hst:sites + myproject
The following changes in the configuration above can be seen:
- The hst:channels node is completely removed. The old channel node myproject has moved to /hst:hst/hst:configurations/hst:workspace/hst:channel. Note that it is located below the hst:workspace. You can also configure it as a sibling of the hst:workspace node but then, the Channel Settings are not editable in the Channel Manager, also see Sites & Channels configuration.
- The hst:mount node /hst:hst/dev-local/localhost/hst:root does not have the property hst:channelpath any more: This propery has become redundant.
- The preview myproject-preview only has a clone of the hst:workspace node of the live myproject configuration, and instead of inheriting from ../common, it now inherits from ../myproject. A subtle result of this is that the hst:workspace now allows more child types, for example hst:templates, hst:abstractpages, etc. These were needed because in older versions, cross channel page copy could result in non-workspace node changes, see Workspace Configuration. This can now never happen any more.
The upgrade tooling ships with tools that do the above conversion for local bootstrap data and for an existing content repository (for example production upgrade).
The above changes however have made one specific setup not possible any more, for which manual steps need to be taken. What used to be possible is the following setup:
+ hst:hst + hst:channels | + myproject | + mysubproject + hst:configurations | + myproject + hst:hosts | + dev-local | + localhost | + hst:root | - hst:mountpoint = /hst:hst/hst:sites/myproject | + sub | - hst:mountpoint = /hst:hst/hst:sites/mysubproject + hst:sites + myproject | - hst:content = /content/documents/myproject + mysubproject - hst:configurationpath = /hst:hst/hst:configurations/myproject - hst:content = /content/documents/mysubproject
The above configuration has two channels, myproject and mysubproject, that both use /hst:hst/hst:configurations/myproject as configuration but both have their own channel. This already used to be quite a funny setup, because the Channel Manager would show two channels, but modifying any of them resulted in changes in both because the sitemap/pages/components etc were shared. With CMS 12.0.0 you cannot have that setup any more, because per channel configuration you can only have one channel. If you would still like to display both channels in the channel manager (because they for example have different content), you need to set it up differently as follows:
+ hst:hst + hst:configurations | + myproject | + hst:channel | + mysubproject | - hst:inheritsfrom = ../myproject | + hst:channel + hst:hosts | + dev-local | + localhost | + hst:root | - hst:mountpoint = /hst:hst/hst:sites/myproject | + sub | - hst:mountpoint = /hst:hst/hst:sites/mysubproject + hst:sites + myproject | - hst:content = /content/documents/myproject + mysubproject - hst:content = /content/documents/mysubproject
The general rule of thumb : If you have more than two or more hst:site nodes that have a hst:configurationpath that is pointing to the same hst:configuration node, you most likely hit this problem. The migration tool will try to correct the configuration for you according the 12.x setup but better if you already do it yourself manually in 11.2.x.
Move of HST channels in Blueprints
If you compare CMS 12.x version of the Blueprints Configuration with the 11.x Blueprints Configuration, you can see the hst:channel moved from being a sibling of the hst:configuration node to be a descendant of it. This is a result of the channel node move, also explained above. The esv2yaml tool should take care of this for you, and when you startup version CMS 12.0.0 for the first time against a repository that has been created with an older version, the hst:channel nodes will be moved. Note that the end location of the hst:channel node is allowed to be a direct child of the hst:configuration or a child of hst:configuration/hst:workspace. Regardless of the location, when the blueprint is used, the hst:channel will be placed in the hst:workspace, also see 12.x Blueprints Configuration.
New Mount property hst:nochannelinfo
A new property hst:nochannelinfo has been introduced which you might need to set manually, typically if you use the JaxrsRestContentPipeline on a mount. This property has been added to avoid, for example, the Channel Manager incorrectly showing a rest mount instead of a site mount if they share the same content root. See Explicitly Hide a Mount in the Channel Manager for more info and if you need to take action.
CMS rest and Template Composer rest configurations are loaded as HST Addon Modules
The CMS rest and Template Composer rest configurations are needed for the Channel Manager to work correctly. For this reason, in general end projects have the files hst-cms-rest.xml and template-composer-rest.xml (though they might have other names!!). They contain in general something like:
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd"> <import resource="classpath:/org/hippoecm/hst/site/optional/jaxrs/SpringComponentManager-rest-jackson.xml" /> <import resource="classpath:/org/hippoecm/hst/cmsrest/SpringComponentManager-cmsrest.xml" /> </beans>
and
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd"> <import resource="classpath:/org/hippoecm/hst/site/optional/jaxrs/SpringComponentManager-rest-jackson.xml" /> <import resource="classpath:/org/hippoecm/hst/pagecomposer/SpringComponentManager-pagecomposer.xml" /> </beans>
This led to several very annoying issues, mainly due to the
<import resource="classpath:/org/hippoecm/hst/site/optional/jaxrs/SpringComponentManager-rest-jackson.xml" />
which could be also loaded by other imports that for example modified some Spring bean in there. The problem however was the order in which the imports were done, see for example HSTTWO-3639 for the issue and HSTTWO-3441 for the solution.
To fix this, we now load the CMS rest and Template Composer rest configuration now via HST Addon Modules meaning you don't need to import them manually any more. You have to remove both
<import resource="classpath:/org/hippoecm/hst/cmsrest/SpringComponentManager-cmsrest.xml" />
and
<import resource="classpath:/org/hippoecm/hst/pagecomposer/SpringComponentManager-pagecomposer.xml" />
Best this can be done by completely removing the files hst-cms-rest.xml and template-composer-rest.xml and move the parts that are custom in them to another file. If you have expose rest via a mount that has the pipeline JaxrsRestContentPipeline or JaxrsRestPlainPipeline, then you most likely need to keep the import of SpringComponentManager-rest-jackson.xml. If your application starts up without Spring wiring errors you know that you did it right.
If you use Channel Filtering by a custom customChannelFilters bean, you have to move the location of the Spring xml configuration from
site/src/main/resources/META-INF/hst-assembly/overrides/addon/org/hippoecm/hst/cmsrest
to
site/src/main/resources/META-INF/hst-assembly/overrides
(note that if the existing file contains non-channel-manager Spring wiring not the entire file needs to be moved but only the customChannelFilters part)
Also see the last paragraph of Channel Filtering.
HST Configuration Editor dropped
The HST Configuration Editor has been dropped in CMS 12.0.0. In older versions, we already recommended to disable to HST configuration editor in production and at least lock inherited configuration nodes in the HST Configuration Editor, see Channel Manager at Recommended: Disable HST configuration editor in production. The reason for this recommendation was that the HST Configuration Editor modifies configuration nodes ouside the hst:workspace. However, these non-workspace nodes are the realm of developers who can bootstrap changes to them. Webmasters changing the same nodes in production through the HST Configuration Editor could easily result in conflicts (and lost changes in the end). This was a fundamental problem. With the structural changes of how a preview configuration is created in CMS 12.0.0 and newer (see above, only the hst:workspace gets cloned to preview), the HST Configuration Editor not only resulted in a bad and brittle pattern, but couldn't write any more to preview configuration at all (the non workspace nodes are not copied from live). As a result we couldn't do otherwise than dropping it entirely....and without much regret because of the earlier mentioned problems. Also, for future plans, we want to leverage the new YAML bootstrapping to leverage much more DTAP support, for example by moving YAML packages up and down the DTAP street. Next to that increase Continuous Delivery beyond the scope we already provided.
There is no way to bring up the HST Configuration Editor in CMS 12.0.0. If you really need to modify non hst:workspace nodes, you have to do this via the /cms/console. If you have some usage of the HST Configuration Editor in older versions, and you wonder whether it is possible in CMS 12.0.0, we can take a look if we can support your way of working with it again. We will investigate some common usages and will try to support these in an upcoming 12.x version.
Other changes (no action required)
URL encoding
The HST now supports encoding and decoding query parameter names (see HSTTWO-3942). As part of that implementation, the HST no longer relies on the container to parse and decode the query string. By default, the HST now uses UTF-8 to encode and decode the URL. In case you had configured your container to use a different encoding, those settings need to be copied to the HST's SpringComponentManager.properties using the parameters:
- uriencoding.default.charset, default is UTF-8, and
- uriencoding.use.body.charset, default is false.