Upgrade 17.3 to 17.4

Note: 17.4.0 has a known issue: the CMS console's node editor can fail to open some nodes, and the console can freeze. Upgrade to 17.4.1 instead of 17.4.0. 17.4.1 contains everything in 17.4.0 and the fix.

Overview

This guide describes how to upgrade a Bloomreach Content implementation from version 17.3.x to 17.4.y.

Significant Changes

Version 17.4 gives the CMS agent in the document editor the same interface and experience as AI Perspective, adds search filters and MCP client support to the CMS agent, and gives files that can contain script safer defaults. Key changes for developers upgrading from 17.3 to 17.4 include:

  • AI module changes (action required if you use the AI module): Content attributes are now stored as filterable metadata, so the vector store needs to be re-indexed. Ollama models must now support tool calling. The old assistant artifacts are empty and deprecated. See Step 2.
  • The CMS agent in the document editor shares the AI Perspective interface: no action required. See the CMS agent User Guide.
  • Script-capable binaries get a Content Security Policy header by default: review this if your site serves SVG or HTML files that rely on script or external resources, or if a proxy or CDN in front of your site sets its own Content Security Policy. See Step 3.
  • PDF uploads are checked for active content by default: no action required, unless your editors need to upload PDFs with JavaScript, such as fillable forms. See Image and Asset Upload Validation.
  • Inline upload in document and link pickers is on by default: no action required. You can turn it off per field. See Link Picker Configuration.
  • Time zone settings move to the global CMS settings: action required if your project configures time zones on the login page. See Step 4.
  • New LDAP read timeout (optional): a new property with no default, and a CND change. See Enable LDAP Authentication and Synchronization.
  • Code editor upgrade in the updater and console: the editors now use CodeMirror 6. Review this only if your project extends CodeMirrorEditor. See Step 5.
  • New in API responses: no action required. Content REST API documents now include pubStateSummary. See Document detail resource.
  • Opt-in features: no action required.

For a complete list of changes, see the 17.4.1 release notes.

Repository Node Type (CND) Changes

This release introduces the following node type definition (CND) changes:

  • Added property hippoldap:readtimeoutms (string) to node type hippoldap:securityprovider

Important: These CND changes prevent simple rollback. Downgrading from 17.4.1 requires restoring from a full repository backup taken before the upgrade.

Deprecations

  • The com.bloomreach.xm.ai:content-ai-service-client-assistant-angular artifact and its -l10n artifact are deprecated and empty. They'll be removed in a future major release.
  • In org.hippoecm.frontend.plugins.cms.codemirror.CodeMirrorEditor, the language mode script references (GROOVY_MODE_JS, XML_MODE_JS, JAVASCRIPT_MODE_JS, CSS_MODE_JS, HTML_MIXED_MODE_JS) and the skin and mode hooks are deprecated. See Step 5.
  • org.hippoecm.app.service.dashboard.DocumentRequestStore#isAdvancedSearchAvailable(Session) is deprecated and will be removed in 18.0. Use DashboardConfigStore#isAdvancedSearchAvailable(Session).
  • Configuring show.timezones and selectable.timezones on the login page is deprecated. See Step 4.

Upgrade Steps

1. Perform Generic Minor Upgrade Steps

Follow the generic instructions for minor upgrades before proceeding with version-specific changes.

2. Follow the AI Module Upgrade Instructions (if you use the AI module)

Re-index the vector store, check that your Ollama model supports tool calling, and optionally remove the old assistant dependency. See the 17.4 section of AI Module Upgrade Instructions.

3. Review the Content Security Policy for Binaries (if your site serves SVG or XML binaries)

BinariesServlet now adds a Content-Security-Policy header to binaries a browser could run script from, such as SVG, XML and HTML files, so a file opened directly can't run script on your site's origin. Images embedded with <img> aren't affected. If your site serves SVGs that rely on script, change or turn off the header with the BinariesServlet init parameters. See HST Binary Content Resource Serving (BinariesServlet).

Also review the following:

  • HTML assets and interactive SVGs. When opened directly, in a new tab or in an <iframe> or <object>, these files no longer load images, fonts, stylesheets or frames, including embedded data: images, and can't submit forms or open pop-ups. This affects, for example, HTML5 banners, microsites or exported reports stored in the asset gallery. If your site relies on them, set the contentSecurityPolicy init parameter to a policy that allows what they need, or to an empty value.
  • Cached binaries. Copies cached by a CDN or reverse proxy before the upgrade don't have the header until they're revalidated or expire, which takes up to 30 days with the default expires-headers-max-age. Purge the cache for /binaries after deploying.
  • A proxy or CDN that sets a Content Security Policy. Make sure it adds its header next to the one from BinariesServlet instead of replacing it. Apache Header set, nginx more_set_headers and CDN rules that override response headers drop the policy for binaries; Apache Header add and nginx add_header keep it.
  • A Content Security Policy set by your project. A Content-Security-Policy header that a filter in your project adds is kept: BinariesServlet adds its own header, and the browser enforces both.

4. Move Time Zone Settings to the Global CMS Settings (if you configure them)

If your project sets show.timezones or selectable.timezones on the login page, move them to the global CMS settings at /hippo:configuration/hippo:frontend/settings. See Configure the CMS Languages and Time Zones.

5. Review Custom Code Editor Extensions (if applicable)

If your project extends org.hippoecm.frontend.plugins.cms.codemirror.CodeMirrorEditor, your code still compiles, but the language mode scripts and skin style sheets are no longer used. Select the language by overriding getEditorMode() instead.

17.4 upgrades Spring Boot to 4.1.2, Apache Wicket to 10.12.0 and Angular to 22.2, and updates third-party dependencies with published vulnerabilities. If your project overrides any of these versions, for example a Jackson override added to address a CVE, remove the override after upgrading and use the managed version. Bloomreach doesn't support overriding Jackrabbit versions.

7. Review Custom Project Code for Library Incompatibilities

Third-party library upgrades in this release may introduce backward-compatibility issues. If your project code fails to build or run, review the affected libraries and update your code to use the latest versions.

8. Review the Release Notes

For additional information, see the 17.4.1 release notes.

Share Feedback
Page: /about/upgrade-guides/minor-version-upgrades/v17/upgrade-17.3-to-17.4
Section: About
Category *