3 - Domains and output channels in Censhare and HCMS

Domains and output channels exist in both Censhare and HCMS. Domains and output channels allow to steer which content is served to the target users.

Introduction to domains and output channels

In a nutshell, domains help to structure access to Censhare assets. Domains are levels in a hierarchy. Users and Censhare assets (and HCMS master data entities) are all assigned at least one domain. If there is a "match" - a user and an asset are assigned the same domain - then the user has access to this asset, also through HCMS and any portal it serves the data to.

Output channels are tags on assets that make sure the assets are passed to a proper HCMS instance and a proper environment (e.g., production or testing). Therefore, output channels can also be organized into hierarchical structures.

Each Censhare system is shipped with a default root. domain and default root. output channel. Assigning an asset to those two will make it available to everybody.

Therefore, the goal of building meaningful domain and output channel hierarchies is usually to delimit access by adding levels below each other and assigning assets and/or users to lower levels.

An example of a domain logic:

root. gives access to everything
root.marketing. limits access to a marketing subdomain, e.g., only assets assigned to it and only users having access to this domain and all its subdomains (if exist), e.g., root.marketing.dach. and root.marketing.uk.

An example of an output channel logic:

root. will send an asset to all channels (i.e., all HCMS instances)
root.hcms1. will send an asset only to a specific output channel and all channels below it in the hierarchy (if any), e.g., root.hcms1.prod. and root.hcms1.test.

Managing domains and output channels can be done either using one of the UIs of the Censhare system - Admin, Java, or Web Client - or using the HCMS CLI. In the CLI you can create, edit, enable/disable, and delete both domains and output channels (except root.). The HCMS CLI does not allow to assign domains to users or assets or tag assets with output channels. Its main purpose is to support HCMS installation and consequent automation.

When managing domains and output channels, you need to keep in mind the following.

Deleting and disabling domains

First of all, be aware of the following consequences. Both deleting and disabling of any domain:

will disable/delete all its subdomains
will not remove assets or master data entities from the HCMS application or Censhare system

Please also be aware about the differences between deleting and disabling of existing domains.

If you do not want any new assets or entities on that domain, but want to keep existing ones assigned to it, you should disable this domain. It will be omitted from any listings (in the CLI tool), and assigning it to assets or entities will become impossible.
If you do not need a domain anymore, you can delete it. The already assigned assets and entities will be automatically moved to the root. domain.
If you want to move existing assets and/or entities to another domain, you can also delete this domain and specify the replacement.

A prerequisite for replacing a domain is that the replacement already exists.

The root. domain can never be deleted.

Deleting and disabling output channels

Consequences and differences between deleting and disabling of existing output channels is similar to that of the domains, but you cannot delete output channels that are being used at least on one asset.

Apart from this, the root. channel can never be deleted.

Sorting of domain and output channel names in the Censhare UI

Using the HCMS CLI or one of the Censhare Clients, you have an opportunity to specify in which order domains and output channels appear in the dropdowns, like these ones:

This can be set by an option upon creating or updating a domain or output channel. You need to specify the exact number that indicates position of a domain/channel in a list of domains/channels of the same level.

E.g., if you have root.marketing. and root.sales., one of them gets 1 and the other 2. For domains/channels on each next level, the count starts anew, e.g., root.marketing.portal1. gets 1 and root.marketing.portal2. gets 2 .

Domains in HCMS by purpose

You need to differentiate between two purposes for which domains are used in HCMS:

to store actual assets that end users will be working with
to store configuration files that ensure the correct work of the satellites (also explained here).

The second "type" of domains is also called management domains in the current documentation. They include a first and a second domain as well. The idea is that those management domains can only be accessed by HCMS administrators. The official Censhare documentation recommends the following structure:

root.cms.satellite. for satellite configuration assets
root.cms.online. for any Online Channel configuration

This structure is not shipped with Censhare by default and needs to be created manually. If you decide to use those (or any other custom domains) as your management domains, you need to make sure that they are hidden from any non-admin user, i.e., only users with admin roles have access to these custom management domains. This is an important security concern.

How to manage domains and output channels

There are multiple ways for managing domains and output channels, depending on what exactly you want to do and if you are first installing HCMS or want to update the exising configuration.

You can use the HCMS CLI tool for creating domains and output channels. The functionality is limited to performing actions essential for a successful installation.
You can create and fine-tune output channels and especially domains using the Censhare Admin Client
Management domains need to be set under Configuration -> Services -> Satellite management service
You can edit the XML files and other configuration assets that store HCMS configuration (full list is available here).

Read vs write channels

An output channel can be of a read or write type, or can also allow both operations.

It is important to have them set correctly in the configuration, to enable HCMS to sync changes on digital assets to the Censhare system.

Further references

HCMS CLI complete reference
For detailed information on the Censhare domain concept, please read this article
A guide to domains in Censhare Dedicated Solutions (the basic Censhare system) can be found here
For information on how to configure output channel and tag assets, please refer to this article.