Update HST Configuration and Workspace Content

Overview

This page describes how to update HST configuration and workspace content in a specific server environment, such as production.

Stakeholders

Developer
Webmaster

Prerequisites

Publish all channel modifications in the target environment before starting the update.
Do not edit any channels in the Experience manager in the target environment during the update process.

HST Configuration and Workspace Content

HST configuration is stored in the repository under /hst:hst. It contains all configuration settings for your publication channels, including websites and mobile sites. Examples include page templates, page components, sitemaps, virtual hosts, and other channel settings.

There are two types of HST configuration:

Fixed configuration (developer-owned): All child nodes of /hst:hst/hst:configuration/[channel_name] except hst:workspace. This is referred to as HST configuration in this document.
Live workspace configuration (CMS user-owned): Stored under /hst:hst/hst:configuration/[channel_name]/hst:workspace. This data is managed by end users and is considered workspace content for repository data updates.

Updating HST Configuration

In most cases, HST configuration does not change in production between deployments. Developers maintain these settings in development environments. When deploying a new release, changes are applied by reloading the affected HST configuration nodes.

Follow these steps to update HST configuration:

Enable the Automatic Export feature in your development environment. This exports HST configuration changes as YAML files in the repository-data/application module.
Before making changes, confirm that the nodes you plan to modify have not been changed in the target environment.
Modify the required HST configuration nodes in your development environment. The changes are exported automatically to the repository-data/application module.
Review the changes in the repository-data/application module and commit them to your version control system.
Package the repository-data/application module with your release artifacts.
Deploy the release artifacts to the target environment. Ensure bootstrapping is enabled. The updated nodes will be applied automatically when the new release starts.

Updating HST Workspace Content

Workspace content changes frequently in production, as webmasters use the Experience manager to update publication channels. Examples include managing components, landing pages, and menus. Because workspace content is dynamic, updating it during deployment is complex.

Recommended approach: Avoid updating workspace content as part of a new project version deployment.

If updates are required:

Apply necessary changes manually after deploying the new project version. Document the required manual actions clearly so they can be repeated in all environments (test, acceptance, production).
For structural changes (such as adding a property to all instances of a specific component type), consider using an Updater script. You can run the updater manually or trigger it automatically by adding it to the Updater Queue.

To automate workspace content updates, use content actions to load, reload, or delete specific content subtrees in the HST workspace. However, this approach risks overwriting changes made in production between content action development and deployment. You can reduce this risk by scheduling a content freeze, but this may not be practical if the release must pass through multiple environments. If you choose to update workspace content automatically, ensure that all relevant production changes are included in the content sources you plan to reload.

Updating Environment-Specific HST Configuration

Configuration under /hst:hst/hst:hosts is typically environment-specific. For example, acceptance and production environments cannot use the same URL. When deploying a new developer-controlled channel, include the corresponding "hosts" nodes as configuration sources in the repository-data/application module.

If webmasters will create new channels from blueprints, treat the corresponding "hosts" nodes as content. To support this, add a .meta:residual-child-node-category: content property to the relevant configuration nodes. This ensures that new child nodes created from blueprints are categorized as content.

Summary

HST configuration includes both fixed configuration and live workspace content. In repository data updates, these are referred to as HST configuration and workspace content.
Developers own HST configuration, which typically does not change in production between deployments.
CMS users own workspace content, which is frequently updated in production.
Keep the repository-data/application module in version control synchronized with the production environment.
Update HST configuration in production by adjusting the relevant YAML source definitions.
Avoid updating workspace content in production by reloading content sources.
Update environment-specific HST configuration by modifying the appropriate YAML source definitions. If your project allows dynamic channel creation, ensure correct categorization of residual child nodes.