Headless CMS Configuration

This XML Schema also serve as a documentation.

Warning: Headless CMS Configuration is stored in asset of type module.satellite.osgi.configuration.
(Module/Satellite/Satellite OSGI/Satellite OSGI configuration), connected to parent asset of type module.satellite.configuration.
(Module/Satellite/Satellite configuration).

TEXT

            The real XML content must start with correct factory ID:  

              `<factorypid>com.censhare.oc.hcms.service.impl.HeadlessCMSServiceImpl%</factorypid>`  


            The asset usually have name `HeadlessCms.xml`, but that is actually irrelevant.

Element: config

Attributes:

@version [ required | fixed: 1 ]

Children:

all of these elements:
- [1, 1] '→datastore'
  » Configuration of the datastore backend; required, because storing data is primary function of Headless CMS.
- [1, 1] '→schemaregistry'
- [0, 1] '→cluster'
- [0, 1] '→webhooks'
- [1, 1] '→hostmappings'
  » Reference to Web Server configuration.
- [1, 1] '→api'
  » REST API configuration.
- [1, 1] '→auth'
  » Authentication and authorisation configuration. Details are described in Headless CMS documentation.
- [0, 1] '→image'
  » Image Cache configuration; copied from ImageCacheService configuration.
- [0, 1] '→cache'
  » Configuration of some caches.

Inner element: config/cache

Configuration of some caches.

Children:

all of these elements:
- [0, 1] '→media-link'

Inner element: config/cache/media-link

Attributes:

@size [ required ] ↦ positiveInteger
@expiration [ required ] ↦ positiveInteger

Element: datastore

Attributes:

@name [ required ] ↦ string
Datastore used by the Headless CMS: must be instanceid of existing datastore configuration.
@default-domain ↦ string
Default domain (1st domain) of newly created assets.
@default-domain2 ↦ string
Default domain2 (second domain) of newly created assets.
@update-as-new-version [ default: true ] ↦ boolean
Should each update create new asset version or not?
This flag can be specified as part of schema, this value is used only when there is no such declaration present.

WARNING: Enable only when connected to censhare server version 2019.2 or newer. In older versions, this feature does not always work correctly!

Element: schemaregistry

Attributes:

@resourcekey [ required ] ↦ string
Value of the "censhare:resource-key" feature, used to identify asset used as schema storage. This asset is automatically created if it does not exist yet.

TEXT

        All Headless CMS instances usually have their own **unique** value to ensure that they have their own set of schemas. It is generally possible to use special setup with shared schema  
        storage; in that case all satellites must either use the same output channel, or the storage asset must be prepared in advance with all output channels set.

@outputchannel [ required ] ↦ string
Output channel assigned to all newly created assets (schema storage and all created entities). This value must be present in datastore configuration!
@namespace ↦ string
Prefix used for all created masterdata entities (asset types, features, relation types, etc).
Should be in the form of dot-path (missing dot at the end is automatically added).
The real prefix is also extended by schema name, to avoid conflicts between them.

TEXT

        Default value is `hcms.`, different values should be set when one server is used as a backend for several Headless CMS instances.

@no-new-masterdata [ default: true ] ↦ boolean
Setting this attribute to true is the same as adding "cs:$no_new_masterdata": true to all schemas:
no new masterdata records are created, ever.

TEXT

        Default is `true` = masterdata creation is **NOT** allowed.

@update-as-new-version [ default: true ] ↦ boolean
Should each schema change create new version of the internal storage?
Disabled by default.

Note that server versions older than 2019.2 contain a bug in the implementation so it should not be enabled.

@init-wait-time [ default: 300 ] ↦ nonNegativeInteger
How long should the initialization wait for schema repository content (in seconds). Default is 5 minutes.
Zero value disable the wait completely.

@semi-hidden-regex ↦ string
Regular expression for schema name. Matching schemas are be hidden from lists (entity/ and schema/ endpoints) and GraphQL schema, but all other endpoints work as usual (so with correct permissions, it is possible to get the schema, all entities, etc).

@unauthorized-list [ default: compatibility ] ↦
Behavior of the entity list endpoint invoked without necessary authorization. In older version, it returned empty list. Added in 4.3, older versions always use "compatibility". Optional. Values: "compatibility", "empty", "401", "404".

Element: cluster

Configuration of HCMS cluster and cluster daemons. Cluster is disabled by default and enabled when this element is present.

TEXT

    In HCMS cluster, there is always one "leader" that run all the daemons. If this leader stops or crashes, another cluster member takes over this role and runs all the daemons.

Attributes:

@control [ default: asset ] ↦ { disabled | asset | singleton }
Type of the cluster management: asset-based (default) or singleton (each satellite is its own single cluster).
@control-key ↦ string
Value of the "censhare:resource-key" feature, used to identify asset used for cluster control. This asset is automatically created if it does not exist yet.

TEXT

        Optional; if missing, it is created from schema repository resource key. Empty value completely disables clustering (just like missing "cluster" element or type "disabled").

@heartbeat-seconds ↦ string
Heartbeat interval, in seconds. Default value is 60 = one minute; lower values are possible, but not recommended. Minimum is 10s.

Children:

all of these elements:
- [0, 1] '→notifications'

Element: notifications

Attributes:

@subscription-asset-type ↦ string
Asset type of subscription notification assets. Optional; when missing or empty, subscription notifications are found only by key prefix and
new ones are created with "module." asset type.

@subscription-key-prefix ↦ string
Prefix of the resource key, used to identify subscription asset. Optional; by default, it's derived from the schema registry key.
@delay [ default: 300 ] ↦ string
Maximum delay between change and notification, in milliseconds. This delay is used to gather all changes in this time interval and send them as a batch.
@min-snapshot-interval [ default: 5 ] ↦ string
Minimal interval between persistent datastore snapshots, in minutes.
Higher value means higher chance that notifications will be repeated on restart or redeploy;
lower value means more storage traffic to/from server.

@max-errors [ default: 5 ] ↦ string
Number of failed invocations before the subscription queue is suspended.
While suspended, no more attempts to deliver notification is made.
Suspended state is not indefinite, btu last only 'errors-recheck-interval' minutes (5 by default).

TEXT

        Must be at least 1, maximum value is not limited.

@errors-recheck-interval [ default: 5 ] ↦ string
Maximum duration of "suspended" state, in minutes. Subscription is suspended after 'max-errors' (default 5) failures, but after this time interval it is tried again.
Only values in range of 1 to 1440 (24 hours) are accepted.

@storage ↦ anyURI
Where to store persistent data (snapshots); by default (missing attribute), everything is stored in assets.
The only supported value for now is "file:" schema with directory path. The directory is automatically created, if needed.

Element: webhooks

Webhooks notifications: optional configuration of base url, http client and the HMAC security.

Attributes:

@connection-timeout [ default: 500 ] ↦ int
@timeout [ default: 6000 ] ↦ int

Children:

sequence of these elements:
- [0, 1] choice of these elements:
  - [1, 1] '→hmac'
- [0, 1] '→base-url'

Inner element: webhooks/hmac

Attributes:

@secret [ required ] ↦ string
@size [ default: 256 ] ↦ { 256 | 512 }

Inner element: webhooks/base-url

content: anyURI

Element: api

Attributes:

@etag [ default: auto ] ↦ { none | long | packed | auto }
What kind of etag values are generated: "long" is the old-style (potentially too long for HTTP), "packed" is the compressed one (inefficient for single entities), "auto" choses the best option, "none" disables the header completely.

@full-stacktraces [ default: false ] ↦ boolean
Enable or disable full stacktraces in error responses. Stacktrace can be very helpful for troubleshooting, but it is often considered security risk (due to possibility of data leak).

TEXT

        Optional, default is `false`.

@defaultPageSize ↦ int
Default page size of listing endpoints, used when no limit query parameter is used.

TEXT

        Optional, **100** is used when this attribute is not present in configuration file.

@allowedOrigins ↦ string
Value of the Access-Control-Allow-Origin header in response (CORS).

TEXT

        Should be set to proper value of caller domain (depending on application setup), or empty value to completely disable CORS.  

        Special value `*` is suitable for development, but not for production (and cannot be combined with cookies).

@maxAge ↦ int
Value of Access-Control-Max-Age header in CORS response. Negative value or zero disables this headers.
Note: ignore when allowedOrigins is empty.

TEXT

        Not enabled by default.

Children:

all of these elements:
- [0, 1] '→request-logging'
  » Request logging configuration.
- [0, 1] '→signed-link'
  » Use JWT keys signed by one of the HMAC algorithms, with shared secret (password).
- [0, 1] '→http-client'
  »
  Http client used to download external content. This feature is rarely used and setting non-default values must be tied to proper server setup.

Inner element: api/request-logging

Request logging configuration.

Children:

sequence of these elements:
- [1, n] choice of these elements:
  - [1, 1] '→log'
    » Logging by standard logging mechanism.
  - [1, 1] '→statistics'
    » Request logging configuration.

Inner element: api/request-logging/statistics

Request logging configuration.

Attributes:

@service [ required ] ↦ string
Service ID of the statistics service configuration (com.censhare.oc.statistics.StatisticsService).
@group [ required ] ↦ string
Group ID used to log statistics; must be defined int he given service configuration.
@strict [ default: false ] ↦ boolean
Strict mode: when enabled and the configured service/group is not available or invalid, each request fails.
@response-header [ default: false ] ↦ boolean
Report result in reponse header: enabling this flag adds status header in response (X-Cs-OCStatisticsLogger) with value in form of groupname=logged|unavailable|failed|skipped

Children:

sequence of these elements:
- [0, n] '→condition'

Inner element: api/request-logging/statistics/condition

content: logFilterCondition

Inner element: api/request-logging/log

Logging by standard logging mechanism.

Attributes:

@level [ required ] ↦ positiveInteger
Log level as defined by java4 logging; 1000 = ERROR, 800 = INFO, 500 = DEBUG
@logger ↦ normalizedString
Logger name; if missing, default class name is used.
@format ↦ string
Format string, with placeholders using curly bracers: {name} or {name:default} or {name:default:size} (use negative size to align left).

Children:

sequence of these elements:
- [0, n] '→condition'

Inner element: api/request-logging/log/condition

content: logFilterCondition

Inner element: api/signed-link

Attributes:

@max-days [ default: 2 ] ↦ positiveInteger
Maximum validity of signed links, in days. All requests are silently capped by this value.

Children:

sequence of these elements:
- [0, n] choice of these elements:
  - [1, 1] '→hmac'
    » Use JWT keys signed by one of the HMAC algorithms, with shared secret (password).

Inner element: api/signed-link/hmac

Use JWT keys signed by one of the HMAC algorithms, with shared secret (password).

Attributes:

@secret [ required ] ↦ string
Shared secret (password) used to sign JWT tokens. It is treated as UTF-8 byte sequence.

Inner element: api/http-client

TEXT

          Http client used to download external content. This feature is rarely used and setting non-default values must be tied to proper server setup.

Attributes:

@connection-timeout [ default: 1000 ] ↦ positiveInteger
Connection timeout, in milliseconds. This value is important to avoid waiting for wrong url.

@read-timeout [ default: 5000 ] ↦ positiveInteger
Read timeout, in milliseconds. This value is used to detect broken connection.

@timeout [ default: 120000 ] ↦ positiveInteger
Total timeout, in milliseconds. Longer value is necessary to download larger file, but care must be taken to raise other timeouts (

@max-size [ default: 200 ] ↦ positiveInteger
Maximum size

Element: hostmappings

Children:

sequence of these elements:
- [1, n] '→hostmapping'
  » One or more web server instances (port, prefixes) serving this REST API.

Element: hostmapping

Attributes:

@name [ required ] ↦ string
Reference to the web server configuration, with optional prefix. Value can have two forms:

Just the name of the web server host configuration. Headless CMS will be available at the configured host, port and path /hcms/v2.0/code>
Name and prefix, separated by slash (name/prefix).
Headless CMS will be available at the configured host, port and path /prefix/hcms/v2.0/code>

TEXT

      In any case, Web Server Configuration must contain appropriate `<hostid name="name"/>` element.

Element: auth

Children:

[0, n] choice of these elements:
- [0, 1] '→disable-security'
  » This (empty) element completely disables security checks: all requests have all roles.
- [0, n] '→ip'
- [0, n] '→basic'
- [0, n] '→jwt'

Inner element: auth/disable-security

This (empty) element completely disables security checks: all requests have all roles.

Element: ip

IP-based role provider: intended to be used in combination with other providers, to allow full access from localhost.

Children:

sequence of these elements:
- [1, n] '→range'
  » Range of IP addresses.

Inner element: ip/range

Range of IP addresses.

Attributes:

@start [ required ] ↦ string
Lower bound of the IP range, inclusive. Both IPv4 and IPv6 addresses are accepted.

@end [ required ] ↦ string
Upper bound of the IP range, inclusive. In other words: highest IP address that still match. Both IPv4 and IPv6 addresses are accepted.

Children:

sequence of these elements:
- [1, n] '→role'
  » Role assigned to all requests from these IP addresses (there might be more than one).

Inner element: ip/range/role

content: token

Role assigned to all requests from these IP addresses (there might be more than one).

Element: basic

Simple http-basic authentication with passwords directly in configuration. Only for development and testing, not recommended for production.

Children:

sequence of these elements:
- [1, n] '→user'
  » Role assigned to request with this username and password (there might be more than one).

Inner element: basic/user

Attributes:

@name [ required ] ↦ string
Username. There is no validation, any string can be valid username (http clients, however, usually have some limitations).
@password [ required ] ↦ string
Password. Password can be any string, just like username.

Children:

sequence of these elements:
- [0, n] '→role'
  » Role assigned to request with this username and password (there might be more than one).

Inner element: basic/user/role

content: token

Role assigned to request with this username and password (there might be more than one).

Element: jwt

JWT token containing "roles" claim

Attributes:

@roles-claim-name [ default: roles ] ↦ token
Name of the JWT claim that contain array of roles. Default is "roles".
@roles-claim-separator ↦ token (length: 1)
Separator used in "roles-claim-name" attribute to specify content of nested claims. Slash or dot characters are the most convenient, but any character can be used - remember that there is no escaping mechanism.
No separator is used by default, which means that whole claim is used as a string.

Children:

sequence of these elements:
- [1, n] choice of these elements:
  - [1, 1] '→cookie'
  - [1, 1] '→hmac'
    » Use JTW keys signed by one of the HMAC algorithms, with shared secret (password).
  - [1, 1] '→pem'
    » Public key used to validate JWT tokens, in PEM format. Note that this is not a certificate, it is a PEM public key!
  - [1, 1] '→jwks'
    » Public key(s) published at HTTPS URL, typically open OpenID-compliant auth server.
  - [0, n] '→user-lookup'
    » Subject configuration: custom mapping of the "sub" claim to entity/asset. Necessary for OpenID-Connect integration
  - [1, 1] '→blacklist'
    » Blacklisted claim: any role in JWT that matches this value is completely ignored. By default, exact string match is used; regular expressions can be used instead.
    Note that this black is evaluated BEFORE automatic roles and this blacklisted role can be added by those rules!
  - [1, 1] '→role'
    » Role assigned to all requests with valid JWT token (when used without attributes), or all requests with specified claim.

Inner element: jwt/jwks

Public key(s) published at HTTPS URL, typically open OpenID-compliant auth server.

Attributes:

@url [ required ] ↦ anyURI
URL where the keys are published.
@cache-keys [ default: 3600 ] ↦ positiveInteger
Default cache duration for the keys, in seconds. Can be changed (but not disabled) by a corresponding HTTP header.
@cache-error [ default: 0 ] ↦ integer
How long should be any error (network, HTTP error code, parsing error) cached, before it is tried again; in seconds. Default is zero, which means that there is no cache - requests will be tried again and again until success.

Inner element: jwt/pem

Public key used to validate JWT tokens, in PEM format. Note that this is not a certificate, it is a PEM public key!

Children:

[1, n] choice of these elements:
- [0, n] '→user-lookup'
  » Subject configuration: custom mapping of the "sub" claim to entity/asset. Necessary for OpenID-Connect integration
- [0, n] '→blacklist'
  » Blacklisted claim: any role in JWT that matches this value is completely ignored. By default, exact string match is used; regular expressions can be used instead.
  Note that this black is evaluated BEFORE automatic roles and this blacklisted role can be added by those rules!
- [0, n] '→role'
  » Role assigned to all requests with valid JWT token (when used without attributes), or all requests with specified claim.

Inner element: jwt/pem/role

content: jwt-role

Role assigned to all requests with valid JWT token (when used without attributes), or all requests with specified claim.

Inner element: jwt/pem/user-lookup

content: jwt-user-lookup

Subject configuration: custom mapping of the "sub" claim to entity/asset. Necessary for OpenID-Connect integration

Inner element: jwt/pem/blacklist

content: jwt-blacklist

Blacklisted claim: any role in JWT that matches this value is completely ignored. By default, exact string match is used; regular expressions can be used instead. Note that this black is evaluated BEFORE automatic roles and this blacklisted role can be added by those rules!

Inner element: jwt/hmac

Use JTW keys signed by one of the HMAC algorithms, with shared secret (password).

Attributes:

@secret [ required ] ↦ string
Shared secret (password) used to sign JWT tokens. It is treated as UTF-8 byte sequence.

Children:

[1, n] choice of these elements:
- [0, n] '→user-lookup'
  » Subject configuration: custom mapping of the "sub" claim to entity/asset. Necessary for OpenID-Connect integration
- [0, n] '→blacklist'
  » Blacklisted claim: any role in JWT that matches this value is completely ignored. By default, exact string match is used; regular expressions can be used instead.
  Note that this black is evaluated BEFORE automatic roles and this blacklisted role can be added by those rules!
- [0, n] '→role'
  » Role assigned to all requests with valid JWT token (when used without attributes), or all requests with specified claim.

Inner element: jwt/hmac/role

content: jwt-role

Role assigned to all requests with valid JWT token (when used without attributes), or all requests with specified claim.

Inner element: jwt/hmac/user-lookup

content: jwt-user-lookup

Subject configuration: custom mapping of the "sub" claim to entity/asset. Necessary for OpenID-Connect integration

Inner element: jwt/hmac/blacklist

content: jwt-blacklist

Blacklisted claim: any role in JWT that matches this value is completely ignored. By default, exact string match is used; regular expressions can be used instead. Note that this black is evaluated BEFORE automatic roles and this blacklisted role can be added by those rules!

Inner element: jwt/blacklist

content: jwt-blacklist

Blacklisted claim: any role in JWT that matches this value is completely ignored. By default, exact string match is used; regular expressions can be used instead. Note that this black is evaluated BEFORE automatic roles and this blacklisted role can be added by those rules!

Inner element: jwt/user-lookup

content: jwt-user-lookup

Subject configuration: custom mapping of the "sub" claim to entity/asset. Necessary for OpenID-Connect integration

Inner element: jwt/role

content: jwt-role

Role assigned to all requests with valid JWT token (when used without attributes), or all requests with specified claim.

Configuration of cookie support: cookie is accepted in addition to Authorized header and set in response. It can be also set or removed by invoking special endpoints.

TEXT

    Note: by default, cookie support is fully configured (with cookie named `access_token`)!

Attributes:

@name ↦ string
Name of the authorization cookie, or empty string to disable cookie support completely.

TEXT

        Default cookie name is `access_token`.

@maxAge ↦ int
Maximum age of the cookie, in seconds. Negative value and missing attribute means that cookies never expire.
@insecure ↦ string
This attribute is used to disable the "secure" flag in cookies. Value is not actually ever used, the very presence is enough.

TEXT

        By default, all cookies are `secure` and thus never sent by browser over unencrypted `http`.

@http-only [ default: true ] ↦ boolean
This attribute is used to enable the "HttpOnly" flag in cookies. Value can be both true or false, with default being false

@same-site ↦ { Lax | None | Strict }
SameSite flag for the new cookies; default is None, because this is REST API that is often requested from different domains.

Element: image

Attributes:

@storage-item [ default: preview ] ↦ string
@storage-path [ default: images ] ↦ string
@thread-pool-size [ default: 2 ] ↦ positiveInteger
@max-cache-size-in-mb [ required ] ↦ positiveInteger
@max-age-in-minutes [ required ] ↦ positiveInteger
@default-filetype [ default: png ] ↦ { jpg | png }
@auto-detect-type [ default: true ] ↦ boolean
@element-idx-compatibility-mode [ default: true ] ↦ boolean
@copy-metadata [ default: true ] ↦ boolean

Children:

all of these elements:
- [0, 1] '→s3'
  » Obsolete region declaration; use s3-region instead, for OC compatibility.

Inner element: image/s3

Children:

sequence of these elements:
- [0, 1] '→region'
  » Obsolete region declaration; use s3-region instead, for OC compatibility.
- [0, n] '→s3-region'

Inner element: image/s3/region

content: s3-region

Obsolete region declaration; use s3-region instead, for OC compatibility.

Inner element: image/s3/s3-region

content: s3-region