HCMS Release Notes

Changelog for the latest release and all the previous ones.

For version 4.2-b306-gefe7a68

Release 4.2

NEW Array mapping of XML elements ("cs:storage.$path")

It is now possible to use "cs:storage.item", "cs:storage.$xml" , "cs:storage.$path" in an array, to match all elements with the given path.

    "texts": {
      "type": "array",
      "items": {
        "cs:storage.item": "master",
        "cs:storage.$path": "content.text",
        "cs:storage.$xml": "article-content",
        "cs:$string_type": "xml",
        "type": "string"
      }
    }

This possibility is primarily intended for reading, but writing is possible.

NEW Automatic reload of schemas from local directory

When running in a satellite with schemas loaded from a local directory (HCMS_DEFAULT_SCHEMA_DIR, usually /schemas inside docker container), HCMS automatically watches for changes and reloads those schemas on any change. This is equivalent to invoking the RELOAD method on /schema endpoint, but automatic and with no error reporting except the satellite log.

Note that feature is limited to the satellite (server module never does this) and the directory must exist at the time of start.

NEW Customised Direct Download Link

Introduced with HCMS 4.2 the schema can specify a cs:storage.$direct-file-name (only word characters, e.g. "my-thumbnail-file") which is accessible under the same rules as every download but doesn't require the first step to get the downloadLink from another request. So a URL path could loke like /entity/image/54301/storage/my-thumbnail

There is a notable disadvantage though - since the link is permanently defined with the schema clients will recognize only changes when strictly following the caching policy. Web browsers are notoriously bad at this and might miss a required refresh.

NEW External session support via "webhook"

HCMS remains to be completely stateless, but it can participate in a cookie-based session provided by an external system. This external system must provide special HTTP endpoint ("webhook") that answers whether specified cookie value represents a valid session - and in the case it does, what kind of authentication / authorization does this session provide.

This webhook is invoked on each request (with possible short-term cache to improve performance) and can provide roles or variables in a similar way to JWT tokens.

NEW Support for asset type wildcards

Schema asset types can now contain wildcards in the form of type.* or even just * (schema that maps every possible asset). In most contexts, this is equivalent to listing all possible subtypes as an array.

FIX Directive cs:feature.$inline_import is always ignored

• Symptom: Directive cs:feature.$inline_import is completely ignored in the schema.
• Cause: The code does not correctly look for both variants (as it does for other similar directives).
• Workaround: cs:relation.$inline_import must be used, even for features.
• Solution: Correct check for the presence of this directive.

FIX Schema RELOAD endpoint do not remove schemas

• Symptom: When a schema file on local filesystem is removed (or renamed) and then the RELOAD method used to refresh the changes, the old schema still exists. It remains existing until restart.
• Cause: The reload always uses all existing schemas currently active and then just overrides them.
• Solution: The reload logic now ignores all existing schemas with source internal.

FIX Pre-signed link to S3 bucket always forces download

• Symptom: When using S3 as a file storage, pre-signed link always forces Content-Disposition: download. This behavior is different to normal, non-S3 link.
• Cause: The download flag is automatically always enabled
• Solution: The same logic as for normal download is used. To ensure backward compatibility, requests with older versions (before 4.2) still use the old login (ie always download).

Release 4.1.1

FIX GraphQL endpoints fail to provide asset attributes

• Symptom: when the GraphQL query contains properties mapped to asset attributes (typically: censhare:asset.id and censhare:asset.name), it fails for every single entity.
  • The error message is confusing: "message": "Exception while fetching data (/Entities/image/list/result[69]/id) : null"
• Cause: the old code handling asset attributes has been replaced by a unified layer in version 4.1, but the old code remained in one place.
• Solution: old code has been removed.

Release 4.1

NEW Commandline administration tool: special localhost support

The hcms client now detects localhost url (frmis://localhost:30546/corpus.RMIServerSSL) and uses special authorization method with no password. It does not matter what is the configured authentication type of the user being used (internal, external/keycloak, etc).

This is especially useful for "webpack" versions of censhare (2021.2 and higher), where the external authentication via Keycloak is the standard.

NEW Configurable timeout of initial schema load

When the HCMS starts, it tries to find the special asset with schemas and load them (or confirm that no such asset exists). To avoid a period of inconsistent REST API, this operation is done synchronously before the API is really available, with a timeout. This timeout can be now configured by an attribute init-wait-time of the <schemaregistry/> element (value is in seconds) and must not be negative.

Default time (hardcoded in all previous versions) is 5 minutes.

Zero value disable the blocking entirely. Schemas are still loaded as usual, but for a small period of time the API is accessible with no schemas (and thus not entities). Under normal circumstances, this period is less than 100ms.

FIX GraphQL endpoints fail when schemas define non-global keys

• Symptom: When some schema(s) contain custom keys (cs:keys) but none of them is a global view, all graphql endpoints fails with status 500.
  • Log contains following error: Caused by: graphql.schema.validation.InvalidSchemaException: invalid schema: "Views" must define one or more fields.
• Cause: The schema generator adds the Views object as long as there is at least one custom key - without checking that at least one of them is a global view.
• Workaround: At least one of the custom keys must be declared as a global view (ie "global": ).
• Solution: The Views object is added only if there is at least one global key (view).

FIX GraphQL endpoints fail when no schema is available

• Symptom: When the HCMS instance has no schema defined at all, all graphql endpoints fails with status 500.
  • Log contains following error: Caused by: graphql.schema.validation.InvalidSchemaException: invalid schema: "Entities" must define one or more fields. (with full stacktrace).
• Cause: The schema is effectively empty, which is explicitly forbidden by the GraphQL standard.
• Solution: There is no way to make this situation work, the endpoints are obliged to return an error. Now the error is 422 and nothing is logged in the log (because it is not actually an error, it's a valid state).

FIX IP range configuration ignores the end attribute

• Symptom: When using the IP range authorization provider, only the start attribute is used and the provider actually accepts only this one single IP address.
• Cause: Instead of end attribute, the start is read and parsed again.
• Solution: Fixed, both attributes are now read and the range is therefore correctly used.

FIX Media mapping (Dynamic Image Cache) cannot be configured with non-AWS S3 storage

• Symptom: In the configuration of the Dynamic Image Cache (<image> element), it is not possible to set url-override attribute. This means that the S3 support is strictly limited to real AWS environment.
• Cause: Several attributes are missing in the XML Schema, so the configuration fails validation.
• Solution: All actually supported attributes have been added to the schema:
  • url-override: URL to the S3 API, necessary for non-AWS S3-compatible implementations (Minio, Google Cloud, etc)
  • path-style-access: boolean, often needed in conjunction with url-override
  • accelerate: boolean, optional S3 API feature
  • max-connections, request-timeout-ms, socket-timeout-ms, connection-idle-timeout-ms: self-describing parameters of the HTTP pool

Release 4.0

NEW More characters allowed in schema names

Several new characters are allowed to be present in schema name, as represented by regular expression [a-zA-Z_0-9~.:+*^$!]+ (used to be: [a-zA-Z_0-9]+).

NEW Different structure of the graphql api

Starting with version 4.0, the graphql schema is different: the top level (query) contains only one property named any (corresponding to /query endpoint), one property named Entities and optionally also one property named Views. Both Entities and Views then have one property for each schema or view, and the next level contains property single and list.

The old convention of using "plural" names (sometimes grammatically incorrect) is no longer user.

This nested structure lower chance of confusing name conflicts, but more importantly makes space at the top level for future expansions.

NEW Generic query endpoint now allows multiple schemas per asset type

Starting with version 4.0, it is allowed to specify query that contains several schemas with the same asset type. For each such asset found, the schema is chosen according to their declared priority. If there is no explicit priority defined, the choice is not defined.

Using query endpoint with path containing lower version (for example /hcms/v3.2/query) uses the old behavior: any such query is refused with 400 Bad Request and error message "more than one mapping for asset type xxx."

NEW Faceted search of storage item attributes

Storage item attribute mapping now accepts "cs:feature.$faceted": true to enable faceted search. This is possible only when index feature is used either explicitly ("cs:feature.index") or implicitly (selected attributes of master storage item).

NEW POST support for /auth/cookie/set endpoint

The /auth/cookie/set endpoint can be now also used with POST method; instead of query parameter, the token is passed in the request body. This is much more secure than query parameter, which can be often leaked via access logs (for example in proxies).

Note that the Authorization header has been always available and is the best option.

NEW Complex object JWT claims provided as variables

JWT claims with JSON object value are not recursively parsed and each property is available as a special variable with a slash-delimited path. This is especially useful for default Keycloak claim realm_access to directly access list of roles as variable jwt/claim/realm_access/roles (${jwt/claim/realm_access/roles} in queries).

NEW Custom user-lookup (from JWT token)

Aside the standard behavior of parsing the "sub" claim as asset id, HCMS can be now configured to execute custom query and find the user's asset (entity) based on any other information. The intended use case is to use the "sub" claim and compare it to some feature, but the mechanism is much more flexible.

• Queries are standard HCMS queries, except that they are always executed with "all roles".
• There is no enforcing mechanism to actually use parsed JWT claim in the query.
• This feature can negatively affect performance, because the query can be executed for each request.

NEW Permission Group authorization model is disabled by default

All schemas without "cs:permgroups.ignore" direct are considered to have it with value true (in previous versions, it used to be false). This means that the internal Permission Group authorization is never automatically used unless explicitly enabled.

The whole Permission Group Model is considered legacy and not recommended for use.

NEW WWW-Authenticate header in 401 and 403 responses

[RFC 6750] mandates that each response that refuses access to the resource (mainly 401 Unauthorized or 403 Forbidden) MUST include the WWW-Authenticate header. HCMS is now conformant with this requirement.

NEW Multiple directories with local schema, local-schema-only mode

Two new environment variables are now available for the satellite (running in docker container):

• HCMS_DEFAULT_SCHEMA_PATH with multiple directories containing schema files (separated by :)
• HCMS_DEFAULT_SCHEMA_ONLY which disables (when set to true) any schemas deployed via REST API and forces use of only those loaded from the filesystem

FIX Query for value of nested feature with nested subfeatures does not work

• Symptom: When a feature mapping with nested path ("censhare:address/censhare:address.com-email-type") has its own nested sub-features, no match is ever found for its own value. Searching for sub-features still work.
• Cause: In the internal database query, the nesting is duplicated, which means it never matches.
• Solution: Duplicate nesting is prevented.

FIX HTTP protocol broken by a too long ETag header value

• Symptom: Request (usually GET) ends up with 500: Response header too large error, if the entity contains large number of mapped relations or asset references. The limit is usually around one thousand.
• Cause: The etag contains info about all included assets and their revisions. With too many assets, the header is too long and exceeds the default limit of jetty HTTP server, which is 4096 bytes (4KiB).
• Workaround: The HTTP server can be reconfigured to allow longer headers. This might not always help, because HTTP clients usually have their own limits.
• Solution:
  • The etag value is now much more efficient and compressed. It still can potentially reach 4KiB or more, but at much larger values.
  • The ETag header can be completely disabled by setting <api etag="none"/> in the configuration.

Release 3.3

NEW Configurable no-transform flag in Cache-Control: header

New directive "cs:media.no_transform" can be used either to completely disable this flag (false value) or to strictly enforce its sending for all media content (true). When not present, no-transform is present when the cache is disabled.

This default behavior is a change; previous versions always sent no-transform flag regardless of other circumstances.

Note that there is no corresponding control for storage-item mapping (generic download link). This is by design, as those links should be always used for raw byte content. The original file can be still provided via cs:media mapping (storage type).

FIX Server Module query can check existence of filtered-out asset

• Symptom: Searching for an existence of related asset (ie relation or asset reference mapping) checks also assets that don't match configured filter (Output Channel or custom query). The content of those related assets is never serialized though; only the existence can leak this way.
• Cause: The configured filter is applied only at the top level of the queries (and in the code that handles data serialization).
• Solution: Filter is also added inside the query, at each and every place where relation or asset reference is followed.
• Note: Since this fix breaks compatibility and might have potentially serious performance impact, it is possible to disable this (reverting to previous behavior).
  • Existing configurations do not have this fix enabled, so there is no potential breakage.

Release 3.2.1

FIX Logical conjunction & with different values fails to find anything

• Symptom: Query with several equality conditions for the same property and different values does not find anything, even when the property is an array and does contain all the values. Example is keywords="root.A."&keywords="root.B."
• Cause: Database query optimization does not expect multiple values and considers the whole expression "false".
• Solution: Optimization rule removed, multiple different values in a conjunction are now left for the engine to evaluate.

Release 3.2

NEW Management of static headers in commandline tool

The hcms commandline tool now allows setting (adding) and removing static headers, ie headers with static value that are added to each and every response. These headers were already supported since at least version 2.0, but had to be configured by manually editing WebServer.xml

Also, with accordance to OWASP recommendations, all new cluster configurations created by the hcms tool automatically have one such header configured: X-Content-Type-Options:nosniff

NEW Masterdata creation is now disabled by default

In a breaking change, masterdata creation is now not enabled by default and to allow it, it must be enabled in the configuration. Please note that the configuration directives and their logic is still the same, just the default is now true instead of false.

• in the configuration: <schemaregistry no-new-masterdata="false"
  • or via the commandline tool: --no-new-masterdata=false

The corresponding schema directive (cs:$no_new_masterdata) still has the same default (false).

FIX Notification daemon not stopped in some cases

• Symptom: Two (or more) HCMS instances (satellites) are sending notification, even if only one of the is declared the leader.
• Cause: If the cluster control mechanism fails three times, the instance considers itself non-leader... but without stopping the daemons.
• Solution: As long as the instance is not leader, all daemons are stopped.

FIX Commandline tool reports error on Apple M1

• Symptom: On non-Intel Apple notebooks, commandline administration tool (hcms) reports following error. Non-interactive mode still works, but interactive mode is not available nor is the ability to save or use passwords from the keychain.
  TEXT

    INFORMATION: failed to load native library Security
    java.lang.NoClassDefFoundError: Could not initialize class com.sun.jna.Native

• Cause: Old version of the JNA library, does not support M1.
• Solution: Libraries upgraded to the latest versions.

FIX Fulltext search takes only literal values

• Symptom: Any attempt to use variables (${...}) as a parameter to query function ($text("censhare:text.meta", ${query/name}, "en")) fails and reports an invalid query.
• Cause: The syntax of the query parser requires literal value as an argument.
• Solution: Variable expression added to the parser and proper handling is also ensured in the AST processing.

FIX Array values always treated as string in queries

• Symptom: Variables with array values (like ${jwt/claim/roles}) are considered as a string with square brackets around the value. It is not possible to test for each single value separately.
• Cause: Special support for array/list values is missing and the default handling (toString()) is used.
• Solution: Arrays are now correct handled as arrays. The JSON objects are still automatically converted to string, with no access to particular properties.

Release 3.1

NEW New value type for lists: all

New value type in lists and queries values=all provides additional info for each entity, saving additional request. With this query parameter, each item in result is a JSON object with properties:

• entity: the entity value itself
• schema: schema name (useful for generic queries)
• id: entity id
• link: base endpoint of the entity
• etag: etag header value (useful for optimistic locking and in general for change detection)
• assets: list of ids of all assets in this entity (including all assets references by mapped relations)
• Normally obtained by a special endpoint entity/<id>/dependencies

FIX Schemas loaded from local directory are considered "overridden" after restart

• Symptom: After restart, schemas from local directory that were previously marked as internal are now override.
  • Note that this happens only if there is at least one schema uploaded via the REST API (ie repository or override) before the restart.
  • In some cases, especially in clustered environment, this might happen even without restart.
• Cause: Uploading new schema via REST API saves all schemas to the repository asset. After restart (and on a number of other occasions), they are restored and override the ones from local directory.
• Solution: For each schema, its current source status is also stored to the repository asset. When restoring, those with internal source are not actually restored and the internal one is used instead.

FIX Http-Only flag has never been set on cookies

• Symptom: No cookie has the httpOnly flag set, even when appropriate configuration option is enabled (http-only="true").
• Cause: Incorrect parsing of the configuration, incorrect attribute on incorrect element has been read.
• Solution: Configuration parsing fixed, the correct element and the correct attribute are not used.

Release 3.0

NEW Media Mapping: possibility to allow non-current media links

This is a special possibility designed to allow obsolete (but cached) media links. Typically, the related image changes, which means that the media link now represents different asset; such a link is normally treated as invalid (HTTP code 404).

By adding special meta-property "cs:media.friends", links pointing to other assets that the currently attached one are accepted. To ensure that no information can be leaked by forged links, the value contains list of schema names and only the assets that are already available as an entity in one of these assets are actually served.

NEW Custom filename support in non-download link

Raw content links (both storage and media) now support additional segments with custom filename to be part of the url. The format is similar to the download link, in the form of /direct/filename.ext. The only different between /download/ and /direct/ is the Content-Disposition header (which is missing in the latter case).

This allows browsers to automatically detect file type and automatically setup video player (for example).

NEW Faceted search with converted values

With new REST API version (v3.0), values in the faceted search are converted according to the property mapping. This is especially useful for asset references mapped as link.

Value conversion is not done in requests using older version (v2.x or v1.x) and in GraphQL queries.

NEW Server Module: locking

This feature is available only when deployed as part of the censhare server (hcms module).

Entity endpoint (/entity/<schema>/<id>) accepts three additional HTTP methods: LOCK, UNLOCK, ROLLBACK; invoking them does check out, check in or checkout abort on the corresponding asset.

NEW whoami endpoint

New endpoint (/auth/whoami) provides info about authorized user, if there is any.

NEW Localized entities in single locale

As an alternative to full data structures that contain several language variants (typically the article or similar), it is possible to include only one related asset selected by a locale. Such relation mapping must be marked by "cs:relation.$filter.locale": true

Desired locale is selected by a query parameter locale, accepted by all endpoints. The standard Accept-Language header can be used too, but it does not allow full locale (only language).

The same algorithm is also used to find the proper label for enum features marked with "cs:feature.$resolve_enum": true (but not the ones where specific locale is specified).

NEW Changed download links for changed content

Storage items mapped as a links now change every time the content changes. This ensures that any potential old cached value (in browser or CDN) is not used.

The link format stays the same, only the opaque token changes. Old links can be still used, but the downloaded content is always the current one (the links do not represent versions).

NEW Full variants info via the cs:media mapping

Property with cs:media can now be of type object instead of string. When exported, the value of that property is the same as would the default media link be, including all correct sizes. This allows client to save one HTTP request.

NEW Json Pointer as a value of cs:media

The value of cs:media meta-property is now allowed to be a string. It has to be a valid JSON Pointer that resolves to valid object value. This allows schema to contain several media mappings to share variant definitions.

NEW Correct search for pair features' values

It is now possible to search for values of the second value of value pair feature. All operators are supported, but the condition must be always directly combined (via & logical) operator with a similar condition for the first value of pair.

NEW Configurable Cache-Control header of the download link

New special directives "cs:storage.max_age" and "cs:storage.public" can be now used to send Cache-Control: public, max-age= headers of the download (via download link).

NEW Configurable public vs private flag in Cache-Control of media content

New special directive cs:media.public can be now used to send Cache-Control: public, max-age= headers for the rendered images. It is used only when a valid, positive mag age value is set (cs:media.max_age and/or cs:media.changed.max_age).

The default is the old behavior: all Cache-Control headers have the private flag.

NEW More headers exposed via CORS headers

Three additional headers are added as the value of : Content-Disposition, X-Source-Type, X-Cs-OCStatisticsLogger

The last one is especially important for development environments of HCMS Client.

FIX Including schema with mixin sometimes fail

• Symptom: Using "$ref" to include schema with "cs:$mixin" fails (with "Mixins at non-root level!" error) when creating or changing schemas by batch update. The same schema is, however, allowed when the referenced schema is created first, in a separate API call.
• Cause: No mixins are allowed anywhere in schema. This validation is sometimes skipped when the included schema was already previously resolved to effective one.
• Solution: Mixins are now officially allowed when present at the top of schema, even if this schema is actually just included in another one.

FIX Mixin override cannot be deleted

• Symptom: Any attempt to delete used mixin fails with error Cannot delete mixin still used in other schemas, even if the mixin is actually an override and there is a local (default) version that is also a mixin.
• Cause: The check for usages is done before the "revert to default schema" code.
• Solution: The dependencies are checked only when the operation actually results in missing schema, or if the new (default) schema is not a mixin anymore.

Release 2.4.3

FIX Property description is not available for schemas with query-based permissions

• Symptom: Any attempt to get property description (/schema/<schema>/cs-description/<property> or equivalent cs-values) on schema that uses advanced permissions with queries ends up with 401 Unauthorized error.
  • This is inconsistent with the content of /entity/ endpoint, which does list the schema (with the same request authentication).
• Cause: There is no asset to evaluate in this context, so the query is skipped and considered "not matching" (which leads to permission being denied)
• Solution: The query is still skipped, but it is considered "matching" so it does not prevent access grant. Note that this how the /entity/ endpoint works, too.

FIX server module conflicts with cihub server module (censhare version 2021.2)

• Symptom: censhare server with both cihub and hcms modules (the former is part of 2021.2), one of them sometimes fails to start on server restart. The server log contains error message
  TEXT

    2022.04.21-11:28:49.891 WARNING: T035: HttpServerService: masterserver.open: Error adding servlet 'cihub.cihub-20211124-1617-0-servlet-00' : com.censhare.oc.hcms.util.DelegatingHttpServlet
    java.lang.IllegalArgumentException: url pattern '/cihub/*' of servlet 'com.censhare.oc.hcms.util.DelegatingHttpServlet' is already used by another servlet: com.censhare.oc.hcms.util.DelegatingHttpServlet-14063c29

• Cause: Both modules share internal event target identifier, which leads to race condition (duplicate events are processed at the exact same time by two threads).
• Solution: Event target modified changed to include module name.

FIX Configuration validation is too restrictive

• Symptom: Changing order of configuration elements inside <jwt> tag (usually moving the <cookie/> element) prevents HCMS to start. This sometimes happen even with the commandline tool.
• Cause: The XML Schema is quit restrictive due to the limitations of XSD grammar.
• Solution: The XSD has been made much more relaxed and now it accepts any order of sub-elements inside the <jwt> element. It is possible that incorrect configuration is accepted (for example, two <cookie> elements; the second one is ignored), but it's acceptable price for avoiding unnecessary downtimes.

Release 2.4.2

FIX Relation filtering by feature value does not work with attribute

• Symptom: Filter "cs:relation.$filter.feature" defined with feature that is actually an asset attribute (for example domains, language, asset id, asset type) results in value that is always empty.
• Cause: Only full asset feature are handled.
• Solution: Support for asset attributes has been added.

FIX Unhandled error when parsing dates

• Symptom: Passing invalid date or time value in entity PUT or POST request causes generic HTTP 500 error with html result.
  • Note that this does not happen if the JSON schema contains correct validation pattern (because that is always applied first).
• Cause: Correct error handling is missing.
• Solution: Error handling added, the request now correctly returns status code 400 with full description of the error.
• Workaround: The schema can and should contain proper format validation by specifying either "format" (standard ISO formats) or "pattern" (generic regular expression).

FIX cropKey in media mapping without aspectRatio

• Symptom: Media mapping variant defined by width and height always uses flexible crop key, even if explicit cropKey property is defined.
• Cause: The cropKey is actually used only in combination with aspectRatio.
• Solution: Special handling added to use specified cropKey even if no aspectRatio is present.

Release 2.4.1

FIX Faceted fulltext search does not work with reference feature

• Symptom: Any attempt to do fulltext search with face fails, if the fulltext index used contains reference feature (<feature key="..." mode="reference"/>).
• Cause: Unchecked cast inside CDB query engine.
• Solution: The facet marker is wrapped in a compatible data structure.

FIX Searching by a value pair value fails with HTTP status 500

• Symptom: Any attempt to use query that compares value of value-pair feature fails with HTTP 500 and html response.
• Cause: Unhandled exception ArrayIndexOutOfBounds (query expected two values, but only one is specified).
• Solution: When only one value is present (which is the only case allowed by the query language syntax), the second value is not used in search.
• Note: Query with proper condition of both values is still not yet supported at all.

Release 2.4

NEW Allowed update (PUT) in multi-asset schemas

HTTP PUT is now allowed to update entity in schema with multiple asset types (cs:asset.type is an array with more than one value). Entity asset type is left unchanged.

Creating new entities in these schemas is still not allowed (unless default is provided) and any attempt will fail with appropriate error.

NEW Support for creating (POST) of entities in multi-asset schemas

Asset types declaration ("cs:asset.type") now has an advanced form with both asset list and explicitly specified "default" type. By using this form, it is possible to create new entities (assets) even in schema that represents more than one asset type - the default type will be used.

There is also a special support for uploading, allowing automatic asset type choice based on the mime type of the uploaded data (as configured in server masterdata).

NEW Entity link as part of the entity

Entity link is now available as a property in the output JSON. This allows convenient listings with both entity data and entity endpoint, both in search and in relation/reference mappings.

  "link": {
    "cs:entity.link": true,
    "type": "string"
  },

NEW Custom searchable storage item attributes

Storage item attribute can now contain "cs:feature.index" property with feature key. This feature must already exist in masterdata, it must be of a correct single-value type (representable as string), and it must be searchable. This feature is then used to search value from queries (instead of attribute itself). The search is, however, still limited to the master storage item.

Some attribute already have index feature automatically assigned by default (their list is in the documentation). These assignments can now be overridden.

NEW searchable flag in the metadata

The medatata description ("cs:$description") now contains boolean property "searchable" to determine whether the described property can be used for searching or not. Only properties whose description contains "searchable": true can be used in the query language.

NEW Entity lists with preconfigured queries

Each schema can contain preconfigured queries (cs:queries) that are then available at special endpoint (/entity/<schemaName>/list/<queryName>). These endpoints are also available in mixins, allowing convenient search for entities in implementing schemas.

Each schema can also contain property cs:related.queries with the same format. These queries are available at special endpoint for one single entity, having the form: /entity/<schemaName>/<id>/related/<queryName>. These queries can search for any entities (just like the /query endpoint) and the id of the main entity is available as variable ${id}. These endpoints are a convenient way to provide preconfigured queries, for example "all media in a folder" or "all users in a group".

NEW JWT keys from JWKS URL

JWK authorization provider can now use public keys obtained via HTTPS URL, using JWKS standard. THis is especially useful for integration with OAuth2/OpenID authorization server.

<jwks url="https://www.googleapis.com/oauth2/v3/certs"/>

NEW Configurable "roles" JWT claim

JWT provider configuration can specify claim name used to get list of roles, as a replacement of the default "roles" claim. Values in nested structures are also supported.

FIX Graphql schema contains global views only from one schema

• Symptom: Graphql type Views contains global views only from one (unspecified) schema, instead of all of them.
• Cause: Schema generator generated this type for each schema separately, then using the last one instead of merging them together.
• Solution: Only one type Views is created and all global views from all schemas are added to it.

FIX GraphQL query result is missing properties

• Symptom: When several schemas use the same mixin, only one of them will have values of properties from this schema provided in GraphQL output.
  • The GraphQL schema and introspection correctly contain all properties from mixin(s) in all schemas, so it is possible to query for them. The values are, however, missing in query output.
• Cause: Field declaration is shared between schema object types, but the GraphQL library used registers it only once (globally).
• Solution: Field declaration is cloned for each schema.

FIX Asset not deleted in server module

• Symptom: using DELETE method fails with cryptic "foreign key constraint" error, or leaves the asset in place (but deletes its history).
• Cause: Current version of the asset is not properly deleted as part of the transaction.
• Solution: Asset is correctly enrolled in the transaction.

FIX JWT claim "aud" is checked when present

• ## Symptom: JWT token containing "aud" claim is always rejected, with folowing error in log:

```


text
rejected due to invalid claims or other invalid content. Additional details: [[8] Audience (aud) claim [] present in the JWT but no expected audience value(s) were provided to the JWT Consumer. Expected one of [] as an aud value.]

```text

• Cause: JWT checking library uses default setting to check "aud" claim, even if no value to check is given. Effectively it requires the claim to be missing.
• Solution: Check of "aud" claim is explicitly disabled.

FIX Incorrect resolution of $ref in included schema

• Symptom: Resolution of local-schema references ($ref) fail when the schema itself is included from another schema as a relation or asset reference mapping.
• Cause: The resolution incorrectly used the parent schema.
• Solution: Correctly switch active document when including another schema. For backward compatibility, the parent schema is also recorded and can be used as a backup.

FIX hash calcuation for dynamic image variants

• Symptom: the dynamic hash (part of the url) does not change if cropping changes
• Cause: the deprecated feature (censhare:image-crop.key) (should be used on relations, not assets) was not checked directly on the asset, but was used there for some time
• Solution: also check the deprecated feature

Release 2.3.1

NEW Media mapping is now able to retain image metadata

This feature must be explicitly enabled in the configuration, <image copy-metadata="true"

FIX Asset not deleted in server module

• Symptom: using DELETE method fails with cryptic "foreign key constraint" error, or leaves the asset in place (but deletes its history).
• Cause: Current version of the asset is not properly deleted as part of the transaction.
• Solution: Asset is correctly enrolled in the transaction.

FIX Enum values are not available in server version

• Symptom: When used as a server module, metadata of some ENUM and HIERARCHICAL features do not contain any values.
• Cause: Missing handling of feature_value table. Other sources (like domains or languages) are not missing.
• Solution: Values are now properly loaded from the feature_value table.

Release 2.3

NEW Configurable behavior of media mapping cache headers and expiration

Maximum age in Cache-Control header for Dynamic Image Cache images is now configurable by special directives in the cs:media mapping.
The behavior is also described in the documentation (including the reason why the download link cannot be constant).

NEW Versioned schema repository asset

Internal schema repository is now able to create new asset version of the internal storage asset. This allows "rollback" in case of accidental undesired change of some schema.

Versioned storage asset must be explicitly enabled in configuration: <schemaregistry update-as-new-version="true"

NEW Relation filtering by feature value

Relation mapping can be restricted to contain only assets with specified feature value (or one several values). This is especially useful for existing structures where related assets are classified by censhare:asset.category or similar feature.

NEW Full support for element index in Dynamic Image Cache

Media Mapping (cs:media) now fully supports storage items in multiple elements (typically used to represent pages of PDF document). The old (undefined) behavior can be enabled by a compatibility switch (attribute element-idx-compatibility-mode in the configuration xml).

FIX Graphql schema uses reserved prefix __

• Symptom: Graphql client issues warning about __facet and __facet_value, because prefix __ is reserved for graphql introspection.
• Cause: Special prefix __ is used for type name, which is not allowed by GraphQL standard.
• Solution: Special types renamed to _facet and _facet_value, in API version v2.2 and higher.

Note: To achieve full backward compatibility, any URL using older API version (hcms/v1.0/graphql up to hcms/v2.1/graphql) still see the original graphql schema, with types __facet and __facet_value.

FIX SVG and other XML-based files lose their mime type

• Symptom: SVG file uploaded as storage item loses its correct mime type image/svg+xml; generic text/xml is used instead.
• Cause: All xml files are normalized, losing the original mime type.
• Solution: Documents with image/* mime type are always treated as binary files, even if their content is well-formed XML.

FIX Unhandled error when asset key reference target is missing

• Symptom: When serializing entity with asset key reference that points to missing asset, HTTP 500 error is returned.
• Cause: Incorrectly handled "null" value.
• Solution: Any such asset reference is ignored and treated as missing.

FIX Complex JWT configuration overwritten by the cli tool

• Symptom: After invoking some authorization command in the cli tool, complex JWT configuration (more than one key, automatic role, blacklist) is either replaced by much simplier version, or completely removed.
• Cause: Unsupported complex configuration is treated as an invalid one.
• Solution: Unsupported complex configuration is propertly detected and never modified.
  • It is also displayed as enhanced: true in the YAML output.

Release 2.2.1

FIX Ordering by string fails in server module

• Symptom: When requesting ordering by string property, request fails with HTTP code 500.
  • Note that numeric and temporal values (dates) work correctly.
• Cause: Missing locale to use for sorting.
• Solution: Locale is taken from default context, or from system-wide settings.

Release 2.2

NEW Headless CMS server module

Headless CMS is now also available as a module, deployable directly to censhare server.

NEW More properties in descriptive metadata

All applicable metadata (features, relations, enum values, units, etc) now contain following additional properties:

• "enabled" flag, which can be used to detect disabled values
• "sorting" value, which can be used to order displayed data
• "modifiable" flag, which can be used to detect values intended to be read-only

NEW Apply security updates in docker build

Docker build Dockerfile now runs apt-get upgrade -y to apply the latest Debian security updates.

FIX Invalid handling of unsupported query operator

• Symptom: When searching for entities with a query that contains =null condition, the result fails with HTTP error 500 and HTML response body.
  • This happens only if the "IS NULL" condition is not supported for that particular feature (which depends on feature definition and datastore configuration).
• Cause: Missing error handling.
• Solution: Error handling added, the error is now reported as status code 400 and standard JSON response.
  • The underlying issue (checking for null is not always supported) behaves without change. It is recommended to either avoid such conditions, or express them by !=null

FIX Unhandled error when serializing invalid asset references

• Symptom: When serializing asset (HTTP GET) with asset reference feature mapped, missing target asset id causes generic HTTP 500 error with html result.
  • Note that this is always a case of inconsistent data structure; usually, reference type in the mapping on in masterdata is set to incorrect value.
• Cause: Missing null check.
• Solution: Missing value (null) is correctly checked.

FIX Webhooks timeout configuration ignored

• Symptom: Attributes timeout and connection-timeout of the webhooks configuration element are ignored and default values are always used.
• Cause: Incorrect parsing of the configuration file.

FIX Unhandled error when serializing invalid asset references

• Symptom: /entity/ endpoint does not contain schemas in which require query condition to grant access (unless there is some sufficient non-query condition).
• Cause: Query conditions without specific entity (which is not available in this case) are automatically considered false.
• Solution: In this particular case, queries are ignored and considered true. This change does not affect other places.

FIX Limits of internal http client cannot be changed

• Symptom: When creating or updating entities using http link to provide raw data, request fails with one of the following errors:
  • java.io.IOException: downloaded file is too big: over 209715200
  • java.io.IOException: download timeout; 120000 ms elapsed
• Cause: Neither size limit nor timeouts are read from the configuration file. Default values are always used.
• Solution: Values are now read from configuration file, element <api><http-client/>

Release 2.1

NEW Additional query variables

All request values from request logging are now also available in queries, as query variables (${name}).

NEW HttpOnly flag of cookies

JWT cookies can be created with HttpOnly flag. This must be enabled in the JWT configuration.

NEW Variable check in Advanced Permission definition

Advanced permission record (part of cs:permissions declaration) can also define variable (or several variables at once) that needs to be available. This condition part is evaluated before any query, which is especially useful if that query requires variable value.

NEW Support for shared schema storage

Sharing asset schemas between different configurations was actually always supported by Headless CMS, but not by the commandline administration tool (the setup required some manual actions in Java Client). This missing support has been added in this release: it is now possible to configure different groups to use the same asset to store schemas (identified by resource key).

Both configuration create and configuration update now accept option --schema-resource-key ; configurations with the same value effectively share all schemas.

NEW SameSite flag of cookies

JWT cookies can be created with specific value of the SameSite flag. This is required by some browsers if the HCMS requests are invoked by javascript on a different domain.

NEW Signed download links

Generated links for content download are also available in signed form that allows download form non-authenticated clients, but only for a limited amount of time. All downloads links can be signed, but special support of S3 provides direct links to AWS S3 buckets, providing better performance at the expense of less strict security.

This feature is disabled by default and must be explicitly configured to enable it.

FIX Accidental removal of Statistics.xml configuration asset

• Symptom: When using commandline tool, configuration update without --user-tracking true removes any existing statistics configuration asset.
• Correct behavior: Any existing configuration assets should be left as they are.
• Solution: configuration update now always keeps all statistics configuration assets and creates a new one when necessary. No such asset is ever deleted.

Release 2.0

NEW JWT roles blacklist

JWT authorization provider configuration can contain <blacklist> elements that define roles that are not possible to be granted via JWT token. Blacklisted roles can be defined either by exact match (default) or as a regular expression.

NEW Multiple JWT signature configurations

JWT authorization provider configuration can now contain any number of hmac and pem elements with different secrets and key. Token is accepted if it verify with at least one of those secrets/keys.

NEW Request logging

Headless CMS can be configured to log all API requests either to standard log file or to censhare server statistics table (request a special configuration xml stored in asset). Several such loggers can be used at the same time, with different log message configurations.

Each log message is fully configurable and can contain various data from request (including url and its parts, client address, specific headers), response (status, various headers), authentication data (userName, userId) and even some API-specific values (schema, id).

FIX Missing error handling for invalid XML (GET)

• Symptom: For entity with storage item mapped as string, GET on entity endpoint sometimes returns 500 Internal Server Error with html content.
  • Log contains following error: document is not a well-formed xml, despite being declared as text/xml
  • Listing works correctly (error is part of the errors array).
• Cause: Content of storage item is always parsed according to mime type, but failure is not properly handled.
• Solution: Error handling added, entity endpoint now returns correct 519 Export validation failed with JSON response containing error description.

FIX Error creating JWT configuration without secret

• Symptom: When using commandline tool with authorization create --jwt and without both --secret and --pem, command fails with NullPointerException error.
• Cause: Incorrect handling of missing options.
• Solution: This case is now handled by generating random HMAC secret

FIX Support for S3 without access keys

• Symptom: Commandline tool requires keys (-s3accessKey and -s3secretKey) for s3 push configuration, despite them being optional.
• Cause: Incorrect validation, incorrect documentation.
• Solution: Correct validation - keys can be omitted, in case both server and satellite are hosted on EC2 infrastructure and access is provided by roles.

FIX Missing error handling for invalid XML (PUT, POST)

• Symptom: When creating or updating entity with storage item content in form for "data:text/xml,...some invalid xml..." uri, requests ends with 500 Internal Server Error and html content.
  • Log contains following error: document is not a well-formed xml, despite being declared as text/xml
• Cause: Missing error handling of XML parsing error.
• Solution: Error handling added, attempts to set storage item content to text/xml without well-formed xml now produces HTTP 400 Bad Request error.

FIX default-domain2 setting actually sets domain

• Symptom: value from attribute default-domain2 is not used to set domain2, but domain. If both default-domain and default-domain2 are present int he configuration xml, the later one always wins (and default-domain is effectively ignored).
• Cause: Typo.
• Solution: Typo fixed.

FIX Missing error handling for invalid XML (GET)

• Symptom: When asset feature is mapped in both main schema and internal schema and has a provided default value, any attempt to create new entity with corresponding property messing fails with 503 error that contains Transaction commit failed!\njava.lang.IllegalStateException: Unsupported DataObject for commit com.censhare.model.corpus.impl.AssetFeature\n
• Cause: Censhare server requires that any newly created feature is attached to asset at the point of transaction commit - even if the feature is also supposed to be deleted.
• Solution: If the feature is both created and deleted at the same time, it is removed from the transaction.

Release 1.12

NEW All non-readonly asset attributes can be modified

Most features represented by asset attributes can be modified. This includes, among others: censhare:asset.id_extern.

• Special features censhare:asset.creation_date and censhare:asset.created_by can be set only for new entities.
• Special features censhare:asset.modified_date and censhare:asset.modified_by can be changed, but the new value will be immediately overwritten if "update as new version" is enabled.

NEW Operation change in webhook response

Webhook can now replace executed operation by adding new-operation property to the response JSON. The only supported combinations are DELETE for UPDATE request (in this case, new property is ignored) and UPDATE for DELETE request (in this case, new property is required).

NEW Reduced logging of connections terminated by client

HTTP clients (browsers) sometimes forcefully close connection after reading only part of response body. In previous versions, this was handled by logging ERROR message with very long (and completely useless) stack trace.

Form now on, terminated response connection is logged as single-line WARN log message with no stack trace.

FIX Error messages should not contain full stack trace

Error messages still contain stacktrace property, but by default it contains only exception and its message, without any references to code (classes and lines).

Full stacktraces can be enabled in configuration (<api full-stacktraces="true"/>) when needed for troubleshooting.

FIX Adding JWT via commandline tool produces invalid configuration

• Symptom: Headless CMS fails to start after JWT configuration with cookie is added (authorization create --jwt --cookie).
  • Log contains following error: error validating by HeadlessCMSConfiguration.xsd: cvc-complex-type.2.4.a: Invalid content was found starting with element 'cookie'. One of '{role}' is expected.
• Cause: Elements are created in incorrect order.
• Solution: Fixed order of elements (cookie must be the first one).

Release 1.11.2

NEW Security improvement: option to selectively disable Forwarded header

New configuration options are added to Web Server configuration to selectively disable support of load balancer integration mechanism: the de-factor standard of X-Forwarded-For header set and its intended replacement RFC 7239

<!-- disable support of RFC 7239; recommended for many load balancer implementations, including AWS ALB -->
<connector port="8080" forwarded="true" forwarded-levels="1" use-forwarded-header="false"/>
<!-- disable support of X-Forwarded-* family -->
<connector port="8081" forwarded="true" forwarded-levels="1" use-x-forwarded-headers="false"/>
<!-- the default: both standard are supported; load balancer is expected to support them in a secure way -->
<connector port="8082" forwarded="true" forwarded-levels="1" />

Note that the default configuration is secure: all "forwarded" headers are completely ignored and their handling must be explicitly enabled by the forwarded="true" attribute.

This change is actually not in Headless CMS itself, but rather in a component (Web Server) shared with Online Channel, release 2019.3.1.1 Detailed documentation is in separate ecosphere article.

Release 1.11.1

FIX Dynamic Image Cache does not use S3 even when configured

• Symptom: Dynamic Image Cache (media mapping) stores all generated images on local filesystem, when the configuration contains <s3> element with correct AWS S3 configuration.
• Cause: Incorrect lookup of the <s3> element in the configuration file.
• Solution: Configuration parsing fixed.

Release 1.11

NEW Custom keys

Each schema can define custom keys that can be used to identify entity as part of the url. Each key consist of one or more property mappings (usually features) with defined order; URL identifying specific entity must contain key name and all values of the key part in correct order.

Custom keys are also used to define global view: each key can be also define name its globally unique name this creates new endpoint /view/{globalKeyName}. This endpoint is simlar to entity endpoint (it allows list, search, creating of new instances), but with the custom key only.

There is no mechanism ensuring that custom keys are unique and present for each entity; this must be handled by application logic. Asset id remains the only canonical identifier of entity (because it is guaranteed to exist and to be unique in one censhare server).

NEW Notification daemons on single-satellite setup

Cluster can be configured to run in "singleton" mode: each satellite is its own cluster. This is useful if there is only one single satellite or when notification url resolves to different address (for example localhost).

Main advantage of this mode is that no periodic updates of special asset are needed.

Related, but independent setting of notification daemon replaces asset storage item by local files for the purpose of storing persistent data of notification state. This, again, saves significant amount of network traffic - but it means that each satellite has its own independent state.

<cluster control="singleton">
  <notifications storage="file:daemons/notification"/>
</cluster>

NEW Resolved values of enum features

Features of type ENUMERATION or HIERARCHICAL are, by default, represented by the internal representations (keys). It is now possible to use names instead, by adding "cs:feature.$resolve_enum" property (value is either language code, or true to use the default name).

NEW More generic string value transformation

String values can now be transformed by more generic mechanism than just internally added prefix (cs:feature.$value_prefix, now obsolete). Both suffix and prefix is now available, and both internal (added on import, removed on export) and external (added on export, removed on import) ones are possible.

This feature is now also available for references.

NEW Mapping-specific preference for schema in link

When generating reference link, cs:feature.$ref_schema or cs:relation.$ref_schema is used to select the best matching schema. This list has precedence over cs:$priority in the schema themselves, but the priority is still used if no known schema matches or no list is specified at all.

NEW User's domains in webhook invocation

Webhook invocation now contains two additional properties: user-domain and user-domain2. There properties are present only if the request is authorized with valid user (JWT token) and that user is represented by censhare asset.

FIX Incorrect handling of misplaced graphql.type declaration

• Symptom: When cs:graphql.type is declared in the same object as cs:relation.$value_property, query result contains original (parent) asset serialized instead of the child one.
  • Note: this type of declaration is obsolete; cs:relation.$ref_schema should be used instead.
• Cause: Cast done on the wrong asset, before full relation resolution.
• Solution: cs:graphql.type is used at the correct level, just like the cs:relation.$ref_schema is.

FIX Unexpected behavior of single-property inlined relation mapping

• Symptom: Using $ref combined with cs:relation.key in single property (that is, non-array) actually maps the parent object. The same combination inside "items" clause of array mapping works as expected.
• Cause: $ref resolution completely replaces all directives from the referenced schema, discarding all directives including the cs:relation. ones.
• Solution: The effective schema merges $ref target with all cs: properties in the source. In the case of conflict, source value wins.

FIX Fixed size in media mapping

• Symptom: Any request for media variant with width and height crashes with 500 Server Error. Also, request to list all variants fails with the same error if there is at least one such variant defined.
  • Known workaround: define only one size and correct aspectRatio (aspect ratio values are not limited, so there is always one that results in correct dimensions).
• Cause: Image Cache request was created with placeholder "flexible" aspect ratio.
• Solution: Image Cache request is correctly created without any aspect ratio.

FIX Media mapping variant inaccessible if it contains special characters

• Symptom: Media mapping can be created with any name (with no restriction), but only those conforming to [0-9A-Za-z_-]+ regular expression are accessible. All other mappings (with empty name or name containing non-alphanumeric character other than dash or underscore) always return 404 with html error.
• Cause: REST API endpoint declared restrictive regular expression, while the mapping parser had no name validation at all.
• Solution: Both places now use the same restriction [^/]+: only empty names and names containing slash are forbidden (and such schema is refused), other names can be used (although proper url-encoding might be necessary).

FIX Missing curl in docker image

• Symptom: Docker contains is always reported as "unhealthy".
• Cause: curl is no longer present in openjdk image.
• Solution: curl installed as part of the dockerfile.

Release 1.10

NEW External ID can be set when creating new asset

Property mapped to censhare:asset.id_extern feature is now used when importing new asset, allowing Headless CMS to import assets with custom id_extern.

It is still not possible to change id_extern value of existing asset.

NEW Automatically assigned roles by JWT authorization

JWT authorization provider now supports <role> element. Unlike other providers, these roles might be assigned conditionally, based on any claim and its content (matched by regular expression). Unconditional role assignment is also supported.

Release 1.9.1

FIX Download link returns 403 Forbidden

• Symptom: GET operation on correct download link returns 403 Forbidden, even if the link is correct one from entity JSON and the request has proper authorization. This happens only when the schema uses advanced cs:permissions with "query" and the storage item is in related/referenced asset.
• Cause: Query from the cs:permissions is incorrectly evaluated on the asset that contains the storage item, instead of the entity asset.
• Solution: Use correct asset for permission evaluation.

FIX List of media variants available without proper authorization

• Symptom: Direct invocation of media link always returns list of possible variants, even when requested without proper authorization. The variants themselves are not available in this way.
• Cause: Missing permission check.
• Solution: Permission check added.

Release 1.9

NEW New configuration option to disable deployment and code execution from server

Deployment and service calls from server can be disabled if required by restrictive security policy. All bundles and configuration files must be deployed from local directory instead.

FIX Incorrect warnings about notification response

• Symptom: Notification daemon logs full exception stacktrace, claiming invalid http response from the invoked hook ("Premature end of Content-Length delimited message body") - even if the http response is completely correct.
• Cause: Bug in "jersey" library, triggered when the response content is ignored.
• Solution: Notification daemon always reads the response.

FIX Cropping settings are ignored

• Symptom: Cropping settings (feature censhare:image-asset-crop.key) are ignored, even when cropKey is specified.
• Cause: Wrong way to pass alias specified by cropKey was passed to Dynamic Image Cache library (code shared with Online Channel).
• Solution: API call fixed.

Release 1.8

NEW Support of all storage item and asset element attributes

Storage item attribute mapping and asset element attribute mapping can now use most of the undocumented attributes. This can be used access data from legacy project.

NEW Configuration of shared filesystems (CLI)

Commandline client (CLI) now allows configuration of filesystems shared between HCMS instance and censahre-server (AWS S3 only).

NEW Notification daemon ignored changes of internal assets

Internal "Cluster Control" asset and assets used to store subscriptions are now ignored by notification daemon. This significantly reduces number of webhook invocations, because all these assets change periodically.

NEW Support of storage item attributes in queries

Query language now allows expressions using some storage item attributes (all comparison operators). Only limited subset of attributes is supported - the ones that have their own special computed feature (query expression actually uses this special feature).

FIX Attribute timestamp features cannot be mapped as number

• Symptom: Asset attribute of timestamp type (for example censhare:asset.creation_date) can be mapped as "integer", but any attempt to export entity ends with error om.censhare.oc.hcms.schema.importexport.InvalidExportDataException: Invalid value at "creation_date", cannot parse to integer:
• Cause: Asset attributes are always represented by string; timestamp parsing was completely missing.
• Solution: Conversion to/from integer added.

FIX Webhooks configuration require hmac element

• Symptom: If the configuration contains webhook element without nested hcms element, validation fails and HCMS is not started. This is unexpected behaviour, because message signing is completely optional feature.
• Cause: Missing minOccurs flag in XML schema.
• Solution: hmac is now correctly marked as optional.

Release 1.7

NEW Relation features

Asset relation features are now supported, in a similar manner to nested features: relation must be defined as json object and one special sub-property (specified by "cs:relation.$value_property") will contain the relation value itself (asset id, key, or link). All other sub-properties defines relation features.

NEW Support for query parameters on GraphQL endpoint

GraphQL endpoint (/graphql) now supports all officially recommended ways to invoke queries:

• GET with query parameters
• POST with application/json body, optionally also with query parameters
• POST with application/graphql body, optionally also with query parameters (for variables and operation name)

NEW GraphQL reference overrides

For any non-inlined relation or asset reference mapping, list of possible schemas that the target entity belongs to can be declared:

• Declared by special property cs:relation.$ref_schema or cs:feature.$ref_schema.
• Unlike inlined mapping, this declaration can contain schemas that are not yet known and it does allow loops.
• This declaration is completely ignored when validating, exporting or importing entities.
• This declaration is completely ignored ignored in queries; this might change in the future major release.
• This declaration is used in GraphQL schema; if it contains more than one existing schema, intermediate union type is automatically generated.
• When accessing via GraphQL query, permissions from the target schema are correctly evaluated.

NEW Batch operation

REST API now allows batch modification in single transaction: single POST on /entity/ can execute any number of CREATE, UPDATE or DELETE operations.

NEW Domains of the satellite configuration assets (CLI)

It is now possible to specify domain and domain2 of all satellite group and satellite configuration assets. Options --mgmt-domain and --mgmt-domain2 are accepted by both create and update sub-commands. root. is used as a default value for new assets.

If the SatelliteManagementService configuration has any domains filters configured, commandline tool checks that the new assets conform to these filters and fails with error if they do not.

When the SatelliteManagementService is enabled by commandline client (server enabled, first invocation of configuration create) and there is no filter configured yet, root./root. is automatically added. This ensures that the server is properly secured.

NEW Template with initial values for unmapped features

Entity schema can contain object with initial values (cs:template/initialValues) used when creating new asset. These values use special schema (cs:template/schema) that is different from the entity schema itself - this means that even features (relations, storage items, etc) that are not part of entity mapping can have default values.

FIX Asset reference cannot be combined with nested properties

• Symptom: Asset reference feature mapped as reference type INLINE ignores any value of cs:feature.$value_property; all sub-features are mapped as part of the target asset. Other feature attributes (cs:feature.$unit_property, cs:feature.$sorting_property) are ignored too.
• Cause: Internal implementation replaced feature by the resolved asset, completely losing any data about nested features.
• Solution: Improved implementation that allows simultaneous mapping of the resolved asset and the feature itself (nested features, additional attributes).

FIX Missing asset element in satellite configuration assets

• Symptom: Assets created by commandline tool have storage_item but no asset_element.
• Cause: Missing code to ensure asset element is created.
• Solution: When creating storage item, asset element is created first (unless it already exists).

Release 1.6

NEW Full support of all feature value sources in metadata

Metadata of features now provide list of all possible values even for features referencing cached tables (for example domains). This affects all descriptive endpoints: /descriptive, /cs-description and /cs-values

NEW JSON document in storage item

Storage item that contains JSON document (any JSON object) can be simply mapped as "type": "object" and its content is then available directly in the main document (without any need for serialization or deserialization).

NEW HCMS Command Line Interface

The command line interface tool (CLI) simplifies the configuration process for administrators. In addition, the CLI enables the automation of the configuration of the HCMS, for example through shell scripts.

NEW Docker image for HCMS satellite delivery server

A Docker image with a censhare HCMS satellite is now available to make operation easier and more efficient.

NEW Image Cache support in HCMS CLI

The command line interface tool (CLI) now allows configuration of dynamic image cache. Both configuration create and configuration update now supports following options:

• --image-cache-disable to disable dynamic image cache
  • Note that this is now the default for newly created configurations.
• --image-cache-max-size and --image-cache-max-age to specify cache size
  • Both of these options are mandatory.
  • AWS S3 storage can be configuration by --image-cache-s3bucket, --image-cache-s3region, --image-cache-s3accessKey and --image-cache-s3secretKey
  • Several other options are available; see documentation and help (--help) for details.

NEW Switch to OpenJDK 11

The censhare HCMS now requires OpenJDK 11 instead of Oracle Java 8 to run.

FIX Missing Workflow mapping support

• Symptom: Workflow mapping does not work as documented - cs:workflow property is completely ignored.
• Cause: Workflow extension is missing in service initialization.
• Solution: Extension added.

FIX Correct handling of inlined schema with mixins

• Symptom: Any attempt to use inline mapping with referenced schema that contains mixin ends up with "mixin conflict" error.
• Cause: Inline mapping use effective schema, which already contains all properties from mixins; then it tries to apply these mixins again.
• Solution: Effective schema must not inclide cs:$mixin anymore - information about mixins is moved to comment:cs:included-mixin.

Note that this bugfix also allows user to directly use effective schema as a new one, without dependence on mixins.

FIX Inline asset reference query

• Symptom: Querying for entities with conditions on features in an inlined asset reference always returns zero results.
• Cause: The query mapper generates a group instead of relation query part for the asset reference.
• Solution: Generate a relation query part for inlined asset references.

Release 1.5

NEW Filter relations by asset type

The output of linked entities can now be reduced to certain asset types. The admissible types can be specified via the property "cs:relation.$filter.asset_type", either as a single string or as an array of strings.

NEW Global configuration option to disable masterdata creation

The automatic creation of master data can be deactivated centrally in the HCMS configuration. In this case the switches in the individual schemas will be ignored.

NEW Simplified deployment of multiple schemas

A comfort function to deploy larger quantities of schemas quickly and easily. Multiple schemas can be created, updated or deleted in a multipart request without explicitly executing them in the order of their possible mutual references.

FIX LiveQuery used to watch updates eventually stops working

• Symptom: After some large number of updates (can be quite soon on high-traffic installations), no updates of schema repository are received. Any attempt to modify it ends with internal error Concurrent modification: Headless CMS Schemas[950198-v1-c0-tcn55-ccn55] instead of expected 950198-51
• Cause: Each invocation of queryAssets modify its argument (QSelect) in-place, adding new conjunction to the where part. Repeated invocation with the same QSelect instance thus create bigger and bigger tree, which eventually completely breaks query engine (because of limited stack size).
• Solution: Always create new QSelect instance.

FIX Correct handling of invalid link

• Symptom: If the entity data contains invalid reference link, create or update fails with HTTP error 500.
• Cause: Link handler handled error by throwing generic exceptions (IllegalArgumentException or NoSuchElementException). These exceptions are not handled by the REST API layer.
• Solution: Always use correct exception (InvalidImportDataException), which is correctly converted to HTTP 400 error with proper JSON response.

FIX Correct handling of invalid XML in data

• Symptom: Passing invalid string (not well-formed xml) to XML property fails with HTTP 500. This is incorrect, because invalid input data should be always handled by HTTP 400.
• Cause: Missing exception handling in importer.
• Solution: Catch the parsing exception and convert it to InvalidImportDataException which is handled by REST API as HTTP 400 with proper error response.

FIX Correct handling of unsupported feature storage

• Symptom: Any attempt to create schema that uses existing Asset Feature with unsupported storage (typically fulltext storage) fails with HTTP error 500 and misleading BUG: Unsupported storage message in log.
  • This is not correct behavior - such a schema is invalid and should be rejected with HTTP 400.
  • Supported feature storages are:
    • attribute
    • versioned
    • unversioned
• Cause: Mapping factory did no checking and accepted any feature regardless of its storage type, but preparation of GraphQL schema thrown IllegalStateException.
• Solution: Feature storage is now checked when compiling schema (and also on export, to cover server-side changes). Any occurrence of feature with unsupported storage cause InvalidMappingException, which is correctly handled by REST API layer.

FIX Return dynamic image variant directly for AWS S3

• Symptom: Error is returned instead of dynamic image variant if AWS S3 storage is configured.
• Cause: S3 may return the cached not found response to the image service for the newly generated image.
• Solution: Return the newly dynamic image directly instead of reading it from S3.

FIX Include relation and legacy image cropping information in the media link content hash

• Symptom: Changed croppings are not visible in the browser.
• Cause: The relation and legacy image cropping data were not included in the media link content hash.
• Solution: Include all cropping formats in the content hash.

Release 1.4

NEW Relevance attribute of asset feature

Relevance attribute (relevance_percentage) of asset feature can be now mapped in a way similar to other feature attributes like sorting or unit: property cs:feature.$relevance_property contains name of sub-property that is mapped to this attribute. Both number and string JSON types can be used.

NEW Default asset domains

The default values for domain and domain2 can now be configured at service level.

NEW List available media variants

The media mapping now returns the available variants with meta data when retrieving the URL without specifying a variant id.

NEW Mixed query via HTTP POST

The /query endpoint can now be queried and sent as JSON via POST to circumvent the URL length size restrictions.

NEW Faceted search

With the facet search, the search results contain suggestions on how the search can be narrowed down further.

FIX Correct handling of invalid response from notification webhook

• Symptom: When the notification webhook returns HTTP 200 with invalid Content-Length header, error counter is not properly incremented.
• Cause: Error counter is decremented just based on the response code, before reading the content and closing of the response connection. The later fails.
• Solution: Notification is considered success only after full invocation, when the response is read and closed. Also, failure to close response is ignored - http status code itself is enough, response body is not used anyway.

FIX JAXRS life cycle

• Symptom: When the web server service is restarted due to configuration changes or multiple instances of it are started, the HeadlessCMS fails with a IllegalStateException exception and is no longer reachable.
• Cause: The JAXRS application is initialized again for each registration with a new web server service.
• Solution: Initialize/destroy the JAXRS application only once.

FIX Resource assets in cached table

• Symptom: The detail panel in the Java-Client is frequently flickering when the notification system is enabled.
• Cause: The internal asset used by the notification system is causing an update of the cached tables.
• Solution: Exclude internal HCMS resource assets (schemas, cluster and subscriptions) from the cached tables.

Release 1.3

NEW Relation sorting

The element order of arrays mapped to relations can now be retained using the relation sorting attribute by setting the flag "cs:relation.$sorting": true on the mapping.

NEW Prefix Query

The query language now supports the condition operator =^ which allows to filter by a prefix string (e.g. name =^ "A").

NEW AWS S3 Range Requests Optimizations

AWS S3 storage item implementation now contains optimizations for range requests.

FIX Relation query across asset reference with intermediate feature

• Symptom: A relation query across an asset reference feature with an intermediate feature returns no results.
• Cause: The intermediate feature is not taken into account when building the query.
• Solution: Apply intermediate features also for relation queries.

FIX Wrong asset serialized instead of asset-reference feature target

• Symptom: Asset Reference features with "cs:graphql.type" serialized the original, parent asset instead of the target one. Example for query {"query":"{images(query:\"keywords\") {count,result {id,keywords{id}}}}"}:

{
  "data": {
    "images": {
      "count": 2,
      "result": [
        {
          "id": 97098,
          "keywords": [
            { "id": 97098 },
            { "id": 97098 }
          ]
        },
        {
          "id": 97575,
          "keywords": [
            { "id": 97575 }
          ]
        }
      ]
    }
  }
}

• Cause: Resolving of the target asset was implemented only for relations and fully inlined features.
• Solution: Target asset is always resolved for asset reference feature.

FIX Searching by mixin returned empty result on some satellite instances

• Symptom: When querying by query with mixin schema, some instances return completely empty result, while some other ones might return correct non-empty result.
• Cause: Internal data structure tracking mixin usage (ie which real entities use that mixin) was initialized only when some schema changed via API. If the repository was restored from asset storage, this internal structure remained uninitialized.
• Solution: Correctly initialize internal structures when restoring repository from asset storage.

Release 1.2

NEW Add support of feature unit

Before 2018.2, features with units had to have "unit set" defined. Since 2018.2, there is also second option: one unit directly selected in feature definition. These two options are mutually exclusive. Single hardcoded unit is now supported by JSON mapper, with these limitations:

• Value is completely ignored on import (the value set in masterdata is used).
• Unit can be set only via Java Admin Client; there is not way to define hardcoded unit in schema.

NEW Set HTTP content disposition for storage and media downloads

The HTTP content disposition may be set to attachment by appending /download to storage and media URLs. In addition a download file name for browsers may be set by appending it separated by a slash after the /download path segment.

NEW Provide access to censhare server master data metadata

New REST API endpoints are added that allow client to obtain server-side master data metadata ("cached tables"), primarily for purposes of display labels. Descriptions can be obtained either for single JSON property (identified by path) or for all properties at once, in a form of "enhanced" schema. In both cases, specific language version can be requested.

• asset type
• relation type - including parent and child name
• storage file
• mime types - part of description appropriate storage item attribute
• feature
  • label, placeholder, tooltip
  • child and parent name (only for asset-ref features)
  • enum values (only for enum features)
  • unit set with all available units (for features with unit set)
  • unit (for features with hardcoded unit)

All descriptions contain name and optional description.

NEW Workflow mapping

Support for mapping of asset workflow and workflow steps including query as well as value enumeration.

NEW Change notifications

In order to invalidate cached content or trigger synchronizations on content changes in external business logic a push-based change notification system has been added to the HCMS.

FIX Change of inlined schema is not reflected in host schema

• Symptom: When schema is updated, other schemas that include the changed on via "$ref" are not updated and they still use the old version.
• Cause: Automatic refresh of all dependent schemas was supported only or mixins.
• Solution: On schema change, all dependent schemas are refreshed (recompiled).

FIX Incorrect location header for newly created entity

• Symptom: Location header in response to new entity endpoint (POST) always contains schema form request, even if the new entity actually belongs to different schema due to webhook new-schema response.
• Cause: Value of this header is constructed simply as request URL plus id of the new entity.
• Solution: Construct correct link by using standard link-making mechanism.

Release 1.1

NEW Disable permission group checks on per schema basis

Permission group checks can be disabled by adding the directive "cs:permgroups.ignore": true to a schema.

NEW Webhooks

Webhooks are a mechanism that allows developers to provide custom business logic to the Headless CMS that can modify entity data or reject operations on create, update and delete requests. The business logic is invoked by calling a remote URL and can therefor be implemented in wide range of technologies.

NEW Retrieve users permission on entity via OPTIONS request

The authorization for the different entity operations are reflected in the Allow header of the appropriate HTTP OPTIONS request. For example an OPTIONS request for an entity (OPTIONS /hcms/1.0/entity/sample/12345 HTTP/1.1) which the authenticated user may read and update, but not delete, would only announce the actually allowed methods (Allow: GET, HEAD, PUT).

NEW Range request support

Support HTTP byte range requests for storage items mapped using the storage mapping or the media mapping.

NEW Experimental GraphQL support

The Headless CMS provides an experimental GraphQL read only interface to entity data. The interface is intended for evaluation purposes and might be changed or get removed in future releases.

FIX Server responds with server error 519 when a referenced asset is not found

• Symptom: Server error 519 is reported when a asset referenced by a asset-ref feature cannot be found.
• Cause: Referenced asset exists on server, but lacks output channels to be accessible in the HCMS.
• Solution: asset-ref features are ignored in the mapping if the referenced asset cannot be found.

FIX Some relational expression in OR queries yield wrong results

• Symptom: Simple relation expressions (i.e. "relation exists") in disjunctions yield wrong results.
• Cause: The disjunctions are not correctly connected to the context and the result is always true (reference 4023075).
• Solution: Enforce a subqueries to be present on QRelation as workaround.

FIX Authentication cookies and the ETag header field are not available in CORS requests

• Symptom: Authentication cookies and the ETag header field are not available in CORS requests.
• Cause: ETag header and credentials are not specified in the CORS headers.
• Solution: The HCMS CORS handling adds ETag to Access-Control-Expose-Header and sets Access-Control-Allow-Credentials to true. Also the CORS headers are only set for actual CORS requests and the origin matching is done on the server side.

FIX Status 502 Bad Gateway returned on PUT calls to concurrently modified entities

• Symptom: PUT calls to entities that where concurrently modified return HTTP status code 502.
• Cause: Handling of datastore response.
• Solution: The entity PUT operation now returns 409 Conflict for concurrently modified assets and 423 Locked for checked out or otherwise locked assets instead of 502 Bad Gateway.