Update HST Configuration and Workspace Content

Goal

Update HST configuration and workspace content in a particular server environment (e.g. production).

Stakeholders

Developer, Webmaster

Prerequisites

All channel modification in the target environment must be published before the update.

No channel may be edited in the Experience manager in the target environment during the update.

Configuration vs. Workspace Content

HST configuration, stored in the repository under /hst:hst, contains all configuration settings for your publication channels (websites, mobile sites, etc.). Examples of HST configuration include page template, page components, sitemap, virtual hosts and other channel settings.

HST configuration can be split into two groups:

• 'Fixed' configuration owned by developers - all child nodes of /hst:hst/hst:configuration/[channel_name] except hst:workspace. It is referred to as HST configuration in the rest of this document.
• 'Live' workspace configuration owned by CMS users - stored under /hst:hst/hst:configuration/[channel_name]/hst:workspace. Because this is live data owned by end-users, workspace configuration must be classified as content within the context of repository data updates. Therefore, it is referred to as workspace content in the rest of this document.

Reloading Updated HST Configuration

Typically, HST configuration does not change in a production environment between subsequent deployments. Therefore, it can be maintained by developers in their development environments and when deploying a new release in an environment, any changes are automatically applied by reloading the affected HST configuration nodes.

The procedure is as follows:

1. Enable the Automatic Export feature in your development environment to automatically export any changes to your HST configuration as YAML sources in the repository-data/application module.
2. Before you make any changes, verify that the nodes you want to modify, have not been modified in the target environment.
3. Make the required modifications to the HST configuration node(s) in your development environment. The changes will be automatically exported to the project's repository-data/application module.
4. Verify the changes in your repository-data/application module and commit them to your Version Control System.
5. Package the repository-data/application module with your release artifact(s).
6. Deploy the release artifact(s) in the target environment. Make sure bootstrapping is enabled. The affected node(s) will be automatically adjusted when the newly deployed release is started.

Reloading Updated HST Workspace Content

Typically, Workspace Content is under constant change in the production environment, because webmasters make changes to publication channels using the Experience manager. Examples of such changes include the management of components (inside containers), the management of (landing) pages and the management of menus. Because of the dynamic nature of Workspace Content, updating it on deployment of a new release is complex.

The best strategy is to try to avoid the need to update Workspace Content upon deployment of a new project version.

If you cannot avoid that need, the next best/simplest thing is to apply the necessary changes manually, immediately after deploying the new project version. This will require a set of manual actions to be repeated on all deployment environments (test, acceptance, production), and it should be controlled through a piece of documentation clear (and accessible) enough for the person deploying the new project version to follow. If structural changes need to be applied to the Workspace Content, f.e. to add a new property of all instances of a specific component type, you should consider running an Updater, which can be started manually (at the appropriate moment in a sequence of actions), or automatically by bootstrapping the Updater into the "Updater Queue".

If you rather not depend on manual (after deployment) steps, you can consider automating the necessary actions as content actions, loading, re-loading or deleting specific content sub-trees of the HST workspace(s). However, this comes with the danger of wiping/reverting changes made in production between the moment the content actions were developed and the moment the deployment to production happens. This risk may be mitigated through a "content freeze" period on production, but if your new project version first has to pass through a test and acceptance environment, a content freeze might not be feasible due to its long duration. If you still choose to update Workspace Content automatically, you will have to make sure that all relevant changes on the production environment Workspace Content are accounted for in the content sources you are about to reload.

Updating Environment-Specific HST Configuration

Typically, the configuration under /hst:hst/hst:hosts is environment-specific: you cannot use the same URL for accessing an acceptance and a production environment simultaneously. If a new project version intends to deploy a new (developer-controlled) channel, we recommend to account for the corresponding "hosts" node(s) through config sources in your project's repository-data/application module. If you intend to have webmasters create new channels based on channel blue-prints, the corresponding "hosts" node(s) should be treated as content. For this to work well, make sure to add a .meta:residual-child-node-category: content property for the appropriate config nodes, such that new child nodes created as a result of creating a new channel from a blue-print below such a node categorizes these nodes as content.

Summary

• HST configuration consists of 'fixed' configuration and 'live' Workspace Content. In the context of repository data updates, they are referred to as HST configuration and Workspace Content, respectively.
• HST configuration is owned by developers and, by nature, does not change in production environments between subsequent deployments.
• Workspace Content is owned by CMS users and, by nature, is constantly being modified in the production environment.
• It is best to keep the repository-data/application module in the Version Control System in sync with the production environment.
• HST configuration in the production environment can be automatically updated by adjusting the appropriate YAML source definitions.
• Workspace Content in the production environment can best not be updated by reloading content sources.
• Environment-specific HST configuration can be updated by adjusting the appropriate YAML source definitions. Make sure to get the categorization of residual child nodes right, if your project supports the dynamic creation of channels.