Overview of HCMS configuration assets

For the purpose of changing HCMS-related configuration, it is useful to understand which assets store which configuration and how they are related to each other.

If you are looking how to change satellite configuration, this article is also for you.

What is HCMS configuration group

HCMS configuration group stands for all configuration that is required for normal functioning of an HCMS instance as a content delivery application and as an implementation of a given business logic.

A configuration group usually represents one project: the data is stored on a Censhare Server and consumed by an external third-party application. Such application can be "just" a frontend or be a an independent backend application, with its own frontend on top of it or without it.

One Censhare Server can store data for multiple such applications. Each "cluster" of data - usually demarcated throughdomains and output channels - is delivered through its own HCMS instance.

Each HCMS configuration group is represented through its own Censhare asset, with satellite groups and more specific configurations - e.g., datastore configuration - linked to it as child assets.

By cloning the whole asset structure, you can create a complete HCMS configuration for a new environment within the same project or for re-using in a different project.

Configuration assets

Asset structure

The structure of configuration assets is defined by two intertwined hierarchies:

• Censhare masterdata, with asset types defined by hierarchically built dot-delimited pathes;

• a custom asset hierarchy, used for HCMS projects, represented through parent-child relationships between assets.

On the diagram above you see a related snippet from the Censhare master data on the left side and on the right side the actual structure with parent-child relationships. Please read the next section to understand them better.

Configuration asset types from the master data

The native Censhare asset hierarchy - the HCMS-related part - is outlined in the table below.

Note Even though it starts with module., this is a structure for standalone HCMS installations, not for HCMS as aServer module.

Some of those assets have "attachments" - master files in Censhare terminology - which are used by the application code on its runtime. Whereas others have no such files, and configuration is stored on them directly.

Note Each Censhare asset has an XML representation, accessible only to admins. Please do not confuse this XML representation with master files in the same XML format! Those are two different things.

Main configuration assets

The core HCMS configuration is stored in the following assets.

Satellite configuration

The asset of type module.satellite.configuration., UI name "Satellite configuration", is the parent asset for all other configuration and even non-configuration assets that are required for an HCMS instance to work. "Satellite configuration" is what is called HCMS configuration group throughout the documentation.

Satellite OSGI configuration

The asset of type module.satellite.osgi.configuration., with UI name "Satellite OSGI configuration", can have the following XML configuration files as master file and therefore represent various configurations.

HeadlessCMS.xml

HeadlessCMS.xml is the main configuration file, exists only once per configuration group and represents the core configuration, such as domains, output channels, authorization providers, etc. Pretty much everything that the CLI toolcan do.

Sometimes, HeadlessCMS.xml is not present in the HCMS configuration group. More often than not, when a satellite is deployed as a custom Docker container, the HeadlessCMS.xml will be inside the container and not visible on the Censhare Server.

Note Such setup requires you to combine instructions from theDocker-based installation with thelocal-only setup.

DataStore.xml

DataStore.xml is the configuration file for definingshared filesystems. Multiple configurations can exist for the same configuration group.

WebServer.xml

WebServer.xml stores configuration for the Jetty delivery server of the satellite, e.g., connector configuration, headers, etc. You can have many of them in the same configuration group.

Statististics.xml

Statististics.xml is an optional configuration for logging and user tracking and exists once per HCMS instance/configuration.

Satellite instance group

A satellite instance group or simply a satellite group asset, module.satellite.instance.group., does not store any configuration. It serves as a parent for the certificate asset and also provides an ID.

Multiple ones per HCMS instance/configuration are possible.

Satellite instance

Alternatively to satellite groups, standalone satellite instances can be used. They are represented through module.satellite.instance. assets that are similar to the satellite group assets.

Certificate asset

module.pkix.certificate., certificate asset(s), is a child asset of either a satellite group or a standalone satellite, only one per such parent.

Other assets

Full list of satellite configuration assets can be found here.

Bundles

The deployable Java code (of a satellite server) is also stored in Censhare assets of type module.satellite.osgi.bundle., UI name "Satellite OSGI bundle".

Creating a new HCMS configuration group

The recommended way is to use HCMS CLI tool as explainedhere. A simple configuration create command will populate all files/assets, including a satellite group and a basic HTTP authorization, and fill them with default values using a minimum input.

Using the out-of-box HTTP authorization, you can adjust the newly created configuration using the same CLI tool. However, available commands are limited to essentials.

You can also create a very custom configuration straight away, especially, if you already have one that you can just clone.

Last but not least, you can change configuration assets manually as described in the next section.

Manual changes on configuration assets

Apart from using the CLI tool, it is possible to change configuration by editing configuration assets in the Censhare system using either the Java Client or the Web Client.

Searching for configuration assets

You can search for configuration assets using any of the search terms: dot-delimited pathes or UI names. You can use the so-called Quick search (the free text search) and then filter your results later.

Editing configuration assets

Master files have to be downloaded, edited locally, and uploaded to assets again, as a new master file. Assets without a master file can be edited either in Web or Java Client, as long as you have enough permissions for editing them.

Creating new configuration assets

Creating new assets requires you to go through the master data defined hierarchy:

Once you selected the correct asset types "at the bottom of the hierarchy", you can start editing it. Keep in mind where you create a new such asset; it must be attached to the correct parent, otherwise, it won't work even if its contents are correct.