Upgrade 14.2 to 14.3

To perform a rolling upgrade of a live multi-node cluster, you must first upgrade to version 14.2.3 before proceeding to 14.3.3. Upgrading directly from 14.2.x to 14.3.3 using a rolling upgrade can cause data corruption. For production environments, always use a blue-green deployment strategy with two separate clusters.

Introduction

Goal

Upgrade a Bloomreach Content project from version 14.2.x to 14.3.y.

Significant Changes

Page Model API 1.0

brXM 14.3.0 includes both Page Model API (PMA) version 0.9 and 1.0. By default, version 0.9 is served for backward compatibility. This behavior will remain for all 14.x releases.

In version 15, the default PMA version will change to 1.0.

Updated Page Model API Support in the SPA SDK

Starting with version 14.3.0, the SPA SDK supports Page Model API version 1.0. You can enable this feature by updating your application configuration. Page Model API 1.0 introduces backward-incompatible changes, so updating to this version may require additional modifications in your application. Existing applications will continue to work, but upgrading to version 1.0 is recommended to ensure compatibility with the next major release.

Enterprise Forms Mail Form Data Behavior Supports Multiple Email Messages

From version 14.3.0, the Enterprise Forms Mail Form Behavior allows configuration of multiple email messages per form. Configuration properties for each message, previously stored on the document's root node, are now stored in child nodes of type eforms:formconfiguration. Existing form documents will be upgraded automatically.

SOLR Support Removed

As of version 14.3.0, Bloomreach Content no longer supports integration with the SOLR search engine.

Upgrade Steps

Perform Generic Minor Upgrade Steps

Follow the generic instructions for minor upgrades.

Update Cargo Log4j Configuration File Path

Log4j 2.13.3 changes the way the Log4j configuration file path is handled in the default cargo.run profile for projects generated from earlier Maven archetypes.

In your project's root pom.xml, within the cargo.run profile, update this line:

<log4j.configurationFile>file://${project.basedir}/conf/log4j2-dev.xml</log4j.configurationFile>

to:

<log4j.configurationFile>${project.basedir}/conf/log4j2-dev.xml</log4j.configurationFile>

Update Project Error Pages

Prior to 14.3.0, default error pages could display internal implementation details on a 500 Internal Server Error. Review your project's error pages to ensure they do not expose sensitive information. For more details, see Handle Error Codes and Exceptions in web.xml.

(Recommended) Enable Page Model API 1.0

Version 14.3.0 introduces Page Model API 1.0, which changes the structure of the JSON response. For backward compatibility, version 0.9 remains enabled by default. If your project uses the Page Model API, enable version 1.0 to prepare for the next major release.

To enable Page Model API 1.0, add the following line to your site's HST configuration properties file, usually located at site/webapp/src/main/webapp/WEB-INF/hst-config.properties:

default.pagemodelapi.version = 1.0

Alternatively, you can specify the Page Model API version per request using the Accept-Version header:

Accept-Version

Set the header to 1.0 to receive version 1.0, or to 0.9 for version 0.9. If the header specifies a non-existent version, the global default.pagemodelapi.version setting is used.

(Recommended) Update SPA for Page Model API 1.0

Configuration

Update your SPA's BrPage component configuration to support Page Model API 1.0.

Previous (14.2) configuration:

import { BrPage } from '@bloomreach/react-sdk';

const configuration = {
  httpClient: axios,
  cmsBaseUrl: process.env.REACT_APP_CMS_BASE_URL,
  spaBaseUrl: process.env.REACT_APP_SPA_BASE_URL,
  request: {
    path: `${window.location.pathname}${window.location.search}`,
  },
};

const mapping = { Banner, Content };

return <BrPage configuration={configuration} mapping={mapping} />;

Updated (14.3) configuration:

import { BrPage } from '@bloomreach/react-sdk';

const configuration = {
  httpClient: axios,
  // Property renamed
  endpoint: process.env.REACT_APP_BRXM_ENDPOINT,
  // Property renamed
  baseUrl: process.env.REACT_APP_BASE_URL,
  request: {
    path: `${window.location.pathname}${window.location.search}`,
  },
};

const mapping = { Banner, Content };

return <BrPage configuration={configuration} mapping={mapping} />;

Update the environment variables in your SPA's .env files and any other relevant files.

Previous (14.2) environment variables:

REACT_APP_CMS_BASE_URL=http://localhost:8080/site
REACT_APP_SPA_BASE_URL=

Updated (14.3) environment variables (note the /resourceapi suffix):

REACT_APP_BRXM_ENDPOINT=http://localhost:8080/site/resourceapi
REACT_APP_BASE_URL=

The updated Page Model API moves the menu model outside the component model. The SPA SDK now provides an abstraction layer for the menu model. Update your menu component to use the new entity.

Previous (14.2) menu component:

import React from 'react';
import { BrComponentContext, BrManageMenuButton, BrPageContext } from '@bloomreach/react-sdk';

function MenuLink({ item }) {
  const page = React.useContext(BrPageContext);
  return <a href={page.getUrl(item._links.site)}>{item.name}</a>;
}

export function Menu() {
  const component = React.useContext(BrComponentContext);
  const { menu } = component.getModels();

  return (
    <ul>
      <BrManageMenuButton menu={menu} />
      { menu.siteMenuItems.map((item, index) => (
        <li key={index} className={item.selected ? 'active' : ''}>
          <MenuLink item={item} />
        </li>
      )) }
    </ul>
  );
}

Updated (14.3) menu component:

import React from 'react';
import { BrComponentContext, BrManageMenuButton, BrPageContext, isMenu } from '@bloomreach/react-sdk';

function MenuLink({ item }) {
  return <a href={item.getUrl()}>{item.getName()}</a>;
}

export function Menu() {
  const component = React.useContext(BrComponentContext);
  const page = React.useContext(BrPageContext);
  const menuRef = component.getModels().menu;
  const menu = menuRef && page.getContent(menuRef);

  if (!isMenu(menu)) {
    return null;
  }

  return (
    <ul>
      <BrManageMenuButton menu={menu} />
      { menu.getItems().map((item, index) => (
        <li key={index} className={item.isSelected() ? 'active' : ''}>
          <MenuLink item={item} />
        </li>
      )) }
    </ul>
  );
}

Image Sets

The updated Page Model API separates the image set model from the document model. The SPA SDK now provides an abstraction layer for this model. Update all components that use images to reference the new entity.

Previous (14.2) content component:

import React from 'react';
import { BrProps } from '@bloomreach/react-sdk';

export function Content(props: BrProps) {
  const { document: documentRef } = props.component.getModels();
  const document = documentRef && props.page.getContent(documentRef);
  const { image: imageRef, title } = document.getData();
  const image = imageRef && props.page.getContent(imageRef);

  return (
    <div>
      { image && <img src={image.getUrl()} alt={title} /> }
    </div>
  );
}

Updated (14.3) content component:

import React from 'react';
import { BrProps } from '@bloomreach/react-sdk';

export function Content(props: BrProps) {
  const { document: documentRef } = props.component.getModels();
  const document = documentRef && props.page.getContent(documentRef);
  const { image: imageRef, title } = document.getData();
  const image = imageRef && props.page.getContent(imageRef);

  return (
    <div>
      { image && <img src={image.getOriginal().getUrl()} alt={title} /> }
    </div>
  );
}

Checker Repository Maintenance Tool

The Checker Repository Maintenance tool has been updated to version 2.4.0. If you use this tool on your servers, upgrade to the latest version.

(Optional) Upgrade Workflow SCXML Customizations

Version 14.3.0 adds a Save as draft option to the document workflow. The SCXML workflow definition and related code have changed.

If your project includes custom SCXML workflow definitions, you can continue using your existing customizations. All workflow code changes are backward-compatible, but the new Save as draft feature will not be available unless you re-apply your customizations to the new default SCXML workflow definition.

(Relevance) Upgrade to Elasticsearch 7

If your project is deployed in Bloomreach Cloud, confirm with Bloomreach support that your stack supports Elasticsearch 7 before upgrading.

Starting with version 14.3.0, the Relevance module supports Elasticsearch 7. If you use the Relevance module and Elasticsearch as a data store, upgrade to Elasticsearch 7 as part of the 14.3.0 upgrade.

Before upgrading Elasticsearch, ensure that no CMS instance is writing data to the Elasticsearch instance. On startup, the upgraded CMS initializes the search index mappings.

Your project must use at least Elasticsearch 6.8 for compatibility with version 7. If needed, upgrade to Elasticsearch 6.8 first.

Update your visits data store configuration by changing the value of targeting:storefactoryclass from com.onehippo.cms7.targeting.storage.elastic6.ElasticStoreFactory to com.onehippo.cms7.targeting.storage.elastic7.ElasticStoreFactory:

/targeting:targeting/targeting:datastores/targeting:visits:
  targeting:storefactoryclass: com.onehippo.cms7.targeting.storage.elastic7.ElasticStoreFactory
  dataSource: elasticsearch/targetingDS

The "dump-restore" tool used for earlier upgrades cannot migrate an Elasticsearch index to version 7.

Share Feedback
Page: /about/upgrade-guides/minor-version-upgrades/v14/upgrade-14.2-to-14.3
Section: About
Category *