Upgrade 16.8 to 16.9

Overview

This guide describes how to upgrade a Bloomreach Content implementation from version 16.8.x to 16.9.y.

Significant Changes

Version 16.9 introduces new features, performance enhancements, and security fixes. Key updates for developers and implementers upgrading from 16.8 include:

• Folder Document Limits:
  You can now configure a maximum number of items per folder at the workflow level. The default limit is 100. When a folder reaches this limit, editors cannot add more content to that folder. Subfolders are always allowed. Adjust the limit using the repository.folderworkflow.item.limit system property or by setting item-limit properties on the relevant workflow configuration nodes in the JCR. Set the value to -1 to disable the limit. For details, see Folder Item Limit Configuration.

• Taxonomy Performance:
  A new, optional JSON-based taxonomy storage model improves performance for large category trees. This migration is one-way and cannot be reverted. For configuration, migration steps, and considerations, see JSON Tree Introduction in v16.9.

• MIME Type Resolution Service:
  The static MimeTypeMapper utility (introduced in 16.8.1) is replaced by a configurable MIME type resolution service. If your project calls MimeTypeMapper directly, update your code to use the new service. See MIME Type Resolution Configuration and the upgrade steps below.

• Custom Value List Providers (since 16.9.2):
  Selection fields backed by a custom valuelistProvider now render in both the Experience Manager and the CMS document editor, using a shared registry. Existing registrations under cms-services continue to work. Providers that extend Wicket's Plugin require a minor change to appear in the Experience Manager. In 16.9.2 and 16.9.3, these providers were not resolved in the CMS document editor; this is fixed in 16.9.4. See Custom Value List Providers and the upgrade steps below.

For a complete list of changes, refer to the 16.9.0 release notes.

Upgrade Steps

Repository Node Type Definition (CND) Change

This release adds the following property to the node type definition:

• Added property hippotaxonomy:categories (binary) to the hippotaxonomy:taxonomy node type.

Important:
You cannot roll back to a previous version by redeploying an older distribution or swapping binaries after this CND change. To downgrade, restore a full repository backup created before the upgrade.

Perform Generic Minor Upgrade Steps

Follow the generic instructions for minor upgrades.

Review Custom Value List Providers (If Applicable)

If your project implements a custom value list provider (a class implementing org.onehippo.forge.selection.frontend.provider.IValueListProvider and typically registered under /hippo:configuration/hippo:frontend/cms/cms-services), review the following:

• Upgrade to 16.9.4 or later:
  In 16.9.2 and 16.9.3, providers extending org.hippoecm.frontend.plugin.Plugin (including subclasses of DocumentValueListProvider) were not resolved in the CMS document editor. Fields fell back to the default provider or rendered empty. Version 16.9.4 restores this behavior without requiring project changes.

• Experience Manager Compatibility:
  To render the field in the Experience Manager, the provider must be a plain class with a public no-argument constructor and must obtain its JCR session from the getValueList argument. Providers that extend Plugin cannot meet this requirement and are logged at startup as "not Experience Manager compatible." In this case, the field renders as an empty list in the Experience Manager but continues to work in the CMS document editor. To convert a Plugin subclass, make three changes to the class and one to the bootstrap configuration. See Custom Value List Providers for the interface contract, registration format, and migration examples.

If your project does not use a custom value list provider, no action is required.

Migrate Direct MimeTypeMapper Usage (If Applicable)

If your project calls org.hippoecm.frontend.plugins.jquery.upload.MimeTypeMapper (introduced in 16.8.1), update your code to use the new MimeTypeResolutionService. MimeTypeMapper is deprecated and will be removed in version 17.0.

// Before (16.8.1 pattern)

String mimeType = MimeTypeMapper.getMimeType(extension);
copy

// After (16.9.0 pattern)

MimeTypeResolutionService service = HippoServiceRegistry.getService(MimeTypeResolutionService.class);

Set<String> mimeTypes = service.getMimeTypes(extension);
copy

Key differences:

• The return type changes from a single String to a Set containing all known MIME type variants for the extension.
• You must obtain the service from HippoServiceRegistry instead of calling a static method.
• The service requires the mimetype-resolution module to be running (enabled by default).

If your project does not use MimeTypeMapper directly, no changes are needed.

Review Custom Project Code for Library Compatibility

Some third-party libraries have been upgraded and may introduce backward compatibility issues. If your project code fails to build or run, review the changes in the upgraded libraries and update your code as needed.

Additional Release Information

For more details, see the detailed release notes.