Upgrade 17.2 to 17.3

Overview

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

Significant Changes

Version 17.3 introduces a new AI Perspective, expands the supported model-providers and integration options, and adds default database connection timeouts. Key changes for developers upgrading from 17.2 to 17.3 include:

Default database connection timeouts (recommended action for existing projects): For new projects and new Bloomreach Cloud environments, a default JDBC socket/connect timeout is now set on the repository database connection, bounding the impact of a database hang. This does not retroactively change an existing project's configuration — see Step 2 below to apply it to your project.
AI Perspective added: A new standalone AI workspace for CMS Agent for searching, creating and editing content is available. It's registered automatically and gated by the existing xm.chatbot.user role. There is no separate step to enable it, and no project-level action is required to keep the existing AI Content Assistant working.
Content Delivery MCP (incubating): If you want to expose Bloomreach Content as an MCP server for published content. See the Content Delivery MCP documentation.
New AI platform provider and model support: AWS Bedrock is now a supported model provider (no new Maven dependency required — it ships in the core AI service implementation artifact), and the OpenAI integration supports reasoning models. Both are opt-in; existing provider configuration is unaffected. If your project explicitly configures temperature for the OpenAI provider, no action is needed — see Step 3 below for what does need review.
Custom Relevance collector plugins can declare their own Alter Ego/Segments editor: opt-in, no action required for existing collectors — unless your project worked around the previous limitation by reusing a built-in collector's ID, in which case see Develop a Collector Plugin (Angular) or Characteristics documentation.

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

Repository Node Type (CND) Changes

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

Added property frontend:iframeAllow (string) to node type frontend:uiExtension

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

Deprecations

org.onehippo.cms7.resourcebundle.ResourceBundlePlugin.MISSING_VALUE is deprecated. Use org.onehippo.cms7.resourcebundle.data.Resource.MISSING_VALUE instead.

Upgrade Steps

1. Perform Generic Minor Upgrade Steps

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

2. Add Database Connection Timeouts (recommended for existing projects)

For new projects and new Bloomreach Cloud environments, a default JDBC socket/connect timeout is now set on the repository database connection, bounding the impact of a database hang. If your project's context.xml (or equivalent DataSource configuration) predates this release, it does not pick up the new defaults automatically — add the appropriate connectionProperties to your repository definition.

Find more information in the specific database configuration documentation:

3. Review OpenAI Provider Configuration (if applicable)

If your project uses the AI Content Assistant with the OpenAI provider, review the following:

temperature is no longer implicitly defaulted to 0.0. It's now opt-in — only sent when you configure it explicitly. If your project relied on the previous deterministic default, set spring.ai.openai.chat.options.temperature=0.0 explicitly. Leave it unset for reasoning models (gpt-5 and later), which reject an explicit temperature.
max_tokens is superseded by max-completion-tokens. The provider now sends the token limit as max_completion_tokens, as required by reasoning models. The legacy spring.ai.openai.chat.options.max-tokens still works — its value is used when the new spring.ai.openai.chat.options.max-completion-tokens is unset — but no action is required unless you want to adopt the new property name.
If you're configuring a reasoning model (gpt-5 and later), set spring.ai.openai.chat.options.reasoning-effort. This is new in 17.3 and, unlike the properties above, is not just a tuning knob — CMS Agent's tool calling does not work on a reasoning model until this is set (for example, to none where supported), and that includes every surface built on CMS Agent: AI Content Assistant's Search Agent, and (once you're on 17.3) AI Perspective's Navigator and Composer. Classic models (gpt-4.x) reject this parameter, so leave it empty for those.

4. Review Custom Relevance Collector Plugins (if applicable)

No action is required — collectors that already work on 17.2 continue to work unchanged. Review this step only if a custom collector plugin was given the ID of a built-in collector (groups, documenttypes, engagement, dayofweek, returningvisitor, tracking, referrer, pageviews, or geo) purely as a workaround to inherit that collector's Alter Ego/Segments editor. That workaround supported at most one custom collector per built-in ID and is no longer necessary — revert it:

Give the collector its own, distinct ID.
Set frontend:editorType on the collector's plugin configuration node (checkbox-group, radio-group, property-names, or page-views).
Register the selectable values under an option named after the collector's own ID in enrichFrontendOptions().
Review Custom Project Code for Library Incompatibilities

5. 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 Detailed Release Notes

For additional information, see the detailed release notes.