Upgrade 16.8 to 16.9

Goal

Upgrade a Bloomreach Experience Manager implementation project from version 16.8.x to 16.9.y.

Significant Changes

This minor release introduces a number of new features, targeted performance improvements, and security fixes. The most significant updates for developers and users moving from 16.8 to 16.9 include:

• Folder Document Limits: A configurable item limit per folder is now enforced at workflow level, defaulting to 100. When the limit is reached, editors cannot create additional content in that folder. Subfolders are always permitted. The limit can be set via the system property repository.folderworkflow.item.limit, or via JCR item-limit properties on the relevant workflow configuration nodes. Set to -1 to disable. See Folder Item Limit Configuration.

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

• MIME Type Resolution Service: A new configurable MIME type resolution service replaces the static MimeTypeMapper utility from 16.8.1. Projects that call MimeTypeMapper directly must migrate to 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 the Experience Manager as well as in the CMS document editor, resolved through one registry shared by both. Existing registrations under cms-services continue to work. Providers that extend Wicket's Plugin need a small change to appear in the Experience Manager, and were briefly not resolved in the CMS document editor either which is fixed in 16.9.4. See Custom Value List Providers and the Upgrade Steps below.

See the 16.9.0 release notes for a full list.

Upgrade Steps

Perform Generic Minor Upgrade Steps

Follow the generic instructions for minor upgrades.

Check Custom Value List Providers (if applicable)

Applies to projects with a custom value list provider: a class implementing org.onehippo.forge.selection.frontend.provider.IValueListProvider, typically registered under /hippo:configuration/hippo:frontend/cms/cms-services. If your project has none, no action is needed.

Upgrade to 16.9.4 or later. In 16.9.2 and 16.9.3, providers that extend org.hippoecm.frontend.plugin.Plugin, including any subclass of DocumentValueListProvider, were not resolved in the CMS document editor, so their fields fell back to the default provider or rendered empty. 16.9.4 restores this with no project change required.

To render the field in the Experience Manager, the provider must be instantiable without Wicket: a plain class with a public no-argument constructor, taking its JCR session from the getValueList argument. A Plugin subclass cannot satisfy this and is logged at startup as "not Experience Manager compatible"; its field renders an empty list in the Experience Manager while continuing to work in the CMS document editor. Converting one is three mechanical changes to the class plus one bootstrap change. See Custom Value List Providers for the interface contract, the registration format, and before/after migration examples.

Migrate Direct MimeTypeMapper Usage (if applicable)

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

// Before (16.8.1 pattern)

String mimeType = MimeTypeMapper.getMimeType(extension);

// After (16.9.0 pattern)

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

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

Key differences:

• The return type changes from a single String to a Set containing all known MIME type variants for the extension

• The service is obtained from HippoServiceRegistry rather than called statically

• The service requires the mimetype-resolution module to be running (which it is by default)

If your project does not call MimeTypeMapper directly, no action is needed.

Check Custom Project Code for Incompatibilities With Upgraded Libraries

Because of third party library upgrades that may introduce backward compatibility issues, there's a chance that project code doesn't build or run well any more. In that case, look into the specifics and adjust the project code to use the latest library correctly.

Detailed Release Notes

See also the detailed release notes for more information.