Upgrade 14.2 to 14.3

Introduction

Goal

Upgrade a Bloomreach Experience Manager implementation project from version 14.2.x to 14.3.y.

Significant Changes

Page Model API 1.0

Bloomreach Experience Manager 14.3.0 ships with both Page Model API (PMA) version 0.9 and 1.0. By default, when requesting the PMA, version 0.9 is served for backward compatibility reasons. This will also be the case for subsequent 14.x releases.

In Bloomreach Experience Manager 15, the default PMA version will change from version 0.9 to 1.0.

Updated Page Model API support in the SPA SDK

As of version 14.3.0, the SPA SDK supports the updated Page Model API version 1.0. The feature can be enabled by updating your application configuration. The Page Model API 1.0 has some backward-incompatible changes, and therefore switching to this version may require some additional changes in the application. All the existing applications will remain working, but it is recommended to upgrade to the next version to guarantee compatibility with the next major release.

Enterprise Forms Mail Form Data Behavior Supports Multiple E-mail Messages

As of version 14.3.0, the Enterprise Forms Mail Form Behavior supports configuring multiple e-mail messages for a form. The configuration properties for each e-mail 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 Dropped

As of version 14.3.0, Bloomreach Experience Manager no longer supports SOLR search engine integration.

Upgrade Steps

Perform Generic Minor Upgrade Steps

Follow the generic instructions for minor upgrades.

Update Cargo Log4j Configuration File Path

An update to Log4j 2.13.3 breaks the Log4j configuration file path configuration in the default cargo.run profile in projects generated from previous versions of the Maven archetype.

In the root pom.xml of your project, in the cargo.run profile, update the following 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

Before 14.3.0, the default error pages added to a project could show internal implementation details if a 500 Internal Server Error occurred. Validate the project error pages do not display any unwanted information. For more information see Handle Error Codes and Exceptions in web.xml.

(Recommended) Enable Page Model API 1.0

Bloomreach Experience Manager 14.3.0 introduces version 1.0 of the Page Model API, making significant changes to the structure of the JSON response data. For backward compatibility, version 0.9 of the Page Model API is still enabled by default. However, if your implementation project uses the Page Model API, it is recommended to upgrade to the Page Model API version 1.0 now to ensure compatibility with the next major Bloomreach Experience Manager release.

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

default.pagemodelapi.version = 1.0

Alternatively, instead of switching the default version globally for an entire site webapp, the returned Page Model API version can also be specified per request through the header:

Accept-Version

Adding the Accept-Version header with value 1.0 serves version 1.0, setting 0.9 serves 0.9. A non-existing version will default to the global default.pagemodelapi.version.

(Recommended) Update SPA for Page Model API 1.0

Configuration

In your SPA, update the BrPage component configuration to enable setup with the Page Model API 1.0.

Old 14.2 component 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} />;

New 14.3 component configuration:

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

const configuration = {
  httpClient: axios,
  // Note: Property renamed!
  endpoint: process.env.REACT_APP_BRXM_ENDPOINT,
  // Note: 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} />;

Similarly, update the environment variables in your SPA's .env file(s) and any other files where these variables are referenced.

Old 14.2 environment variables:

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

New 14.3 environment variables (with appended /resourceapi):

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

Menu Component

In the updated Page Model API, the menu model has been moved outside the component model. On top of that, the SPA SDK implements an abstraction layer on top of the menu model. Therefore, the menu component should be updated to use the updated entity. 

Old 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>
  );
}

New 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

In the updated Page Model API, the image set model has been separated from the document model. The SPA SDK provides an abstraction layer on top of the model. Therefore, the all the components using images should be updated to use the updated entity.

Old 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>
  );
}

New 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, latest version now 2.4.0.
If you have an installation of it on your servers, please upgrade to that version.

(Optional) Upgrade Workflow SCXML Customizations

Bloomreach Experience Manager 14.3.0 introduces a new Save as draft option to the document workflow. Related code as well as the SCXML workflow definition have changed.

If your implementation project contains customizations of the SCXML workflow definition, you may continue to use your existing, customized SCXML. All workflow code modifications are backward-compatible with existing SXCML. However, the new Save as draft option won't be available in this scenario.

To enable the new Save as draft option in your customized workflow, you must re-apply your customizations to the new default SCXML workflow definition.

(Relevance) Upgrade to Elasticsearch 7

As of Bloomreach Experience Manager 14.3.0, the Relevance module supports Elasticsearch 7. If your implementation project uses the Relevance module and the Elasticsearch data store, it is recommended to upgrade to Elasticsearch 7 when upgrading to 14.3.0. 

Make sure your project currently uses at least version 6.8 of Elasticsearch to ensure compatibility of the index with version 7. If necessary, upgrade to Elasticsearch 6.8 first.

In your configuration for the visits data store, change the value of the 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