6.1 to 6.2 Migration

These migration notes assumes that you are going from Broadleaf Framework 6.1 to 6.2. There might be additional migration steps necessary for your particular implementation of Broadleaf. If so, please let us know through our Gitter, or by submitting a pull request to this documentation repo at https://github.com/BroadleafCommerce/docs.

Overview of new features in the 6.2.0-GA release are detailed within 6.2.0-GA Release Notes.

Module Compatibility with 6.2

The version for each of the Broadleaf module is defined in broadleaf-bom. If you are using any particular version of any modules, either remove or update it. Here is a compatibility chart listing each of the module and version that is compatible with Broadleaf Framework 6.2.

Major feats

• Updated core 3rd-party dependency baselines
  • Spring 5.3
    • 5.1.16.RELEASE -> 5.3.8
    • Spring 5.3 Migration Notes
  • Spring Boot 2.4
    • 2.1.12.RELEASE -> 2.4.7
    • Spring Boot 2.4 Migration Notes
    • Spring Boot 2.4 Configuration Changelog
  • Spring Security 5.4
    • 5.1.7.RELEASE -> 5.4.7
  • Hibernate 5.4
    • 5.3.15.Final -> 5.4.32.Final
    • Hibernate 5.4 Migration Notes
  • Solr 8.9
    • 7.7.2 -> 8.9.0
    • Version of zookeeper compatible with solr : 3.7.0
  • EhCache 3.9.0
    • 3.6.3 -> 3.9.0
• Simple transition
  • Simple transition workflow process is now enabled by default. It can be controlled by the following property sandbox.lifecycle.strategy.simple.enabled

Caching Provider

Broadleaf continues to use ehCache 3 as a caching provider. It is now optional dependency, so if you want to continue using it as a cache provider you will need to add ehCache dependency to your core pom.xml.

<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>ehcache</artifactId>
</dependency>

Cache Region Refactor

Refactored entity cache regions in order to facilitate more granular performance tuning. Migration is not needed for this however these changes will require cache settings to be reevaluated as new regions will be created and existing regions will be changed. Check release notes for each module to find specific regions related to the module. In general, these are the regions that were broken down:

• blStandardElements
  This region has been used as a catch-all. Even though the hit ratio tends to be quite high in this region there also tends to be a very high amount of misses. By splitting this region up into more specific regions it can be tuned more specifically in order to optimize fetching entities which are causing a lot of the misses
  Additionally, the majority of all search entities are in this region. Search entities are used extremely frequently and there's typically not a lot of them so it's something that should be entirely cached in order to improve typeahead, search, and category pages

• blProducts
  This region houses a lot of entities around products and skus. The downside of having a region containing products, skus, and additional relationships is that for remotely large catalogs, it is not able to cache a substantial amount of products or skus at a time. By moving everything out of this region other than product and skus it'll be able to cache a higher percentage of the catalog which, in turn, should increase performance on search, category, and product pages

• blCategories
  This region houses a lot of entities around categories. For a region designed to cache categories, it's often difficult to fully cache categories even though the number of categories and category xrefs are typically quite low to where they should be able to be cached. By moving out other entities sharing this space it can cache most, if not all, categories and category xrefs thus increasing performance on every page for implementations that use the category structure for their menu

• blOrderElements
  In General this region is fine but it's ideal time to move out anything not strictly dealing with aspects of an order. This cache has to be turned off for API implementations that use a stateless session. By moving out elements that don't have to be in this region it'll allow API implementations to operate as efficiently as possible as more entities will be cached.

• blCustomerElements
  Same reasons as noted for blOrderElements above.

Framework changes

Domain changes

Note: All sql statements below are for MySql. Make sure to change the sql syntax and column types for any other databases accordingly.

• Broadleaf Framework
  • Add column DEFAULT_LOCALE to BLC_SITE

    ALTER TABLE BLC_SITE ADD COLUMN DEFAULT_LOCALE varchar(255) DEFAULT NULL;
    ALTER TABLE BLC_SITE ADD CONSTRAINT SITE_LOCALE_FK FOREIGN KEY (DEFAULT_LOCALE) REFERENCES BLC_LOCALE(LOCALE_CODE);

• Enterprise
  • Add tables for simple transition

    CREATE TABLE BLC_SNDBX_WRKFLW_CHG_DTL (
    WRKFLW_CHG_DTL_ID bigint NOT NULL,
    CATALOG_DISC bigint DEFAULT NULL,
    DERIVED_TABLE varchar(255) DEFAULT NULL,
    RELATED_TO_TABLE varchar(255) DEFAULT NULL,
    SHORT_VAL varchar(5000) DEFAULT NULL,
    SITE_DISC bigint DEFAULT NULL,
    SITE_ID bigint DEFAULT NULL,
    TARGET_ID bigint DEFAULT NULL,
    TRANSITION_TYPE varchar(255) DEFAULT NULL,
    PRIMARY KEY (WRKFLW_CHG_DTL_ID),
    KEY CHG_DTL_TARGET_IDX (TARGET_ID)
    );

    CREATE TABLE BLC_SNDBX_WRKFLW_CHG_DTL_REF (
    DETAIL_REF_ID bigint NOT NULL,
    DETAIL_ID bigint DEFAULT NULL,
    WRKFLW_SNDBX_ID bigint DEFAULT NULL,
    PRIMARY KEY (DETAIL_REF_ID),
    KEY CHG_DTL_TARGET_REF_IDX (DETAIL_ID),
    KEY CHG_DTL_WRKFLW_REF_IDX (WRKFLW_SNDBX_ID)
    );

    CREATE TABLE BLC_SNDBX_WRKFLW_CHG_DTL_VAL (
    CHG_DETAIL_VAL_ID bigint NOT NULL,
    VALUE varchar(5000) DEFAULT NULL,
    CHG_DETAIL_ID bigint DEFAULT NULL,
    PRIMARY KEY (CHG_DETAIL_VAL_ID),
    KEY FK1C1BCEA980E73722 (CHG_DETAIL_ID),
    CONSTRAINT FK1C1BCEA980E73722 FOREIGN KEY (CHG_DETAIL_ID) REFERENCES BLC_SNDBX_WRKFLW_CHG_DTL (WRKFLW_CHG_DTL_ID)
    );

Postgres is not configured for implicit casting of boolean by default. Use the following to configure:

UPDATE pg_cast set castcontext ='i' where castsource=23 and casttarget=16;

• Theme
  • Create index for PATH column in BLC_THEME_FILE table

      ALTER TABLE BLC_THEME_FILE ADD INDEX (PATH);

• Enterprise search
  • Remove column BLC_TYPE_AHEAD_CONFIG

    ALTER TABLE BLC_TYPE_AHEAD_CONFIG DROP COLUMN SUGGESTION_LIMIT;

Creating Schema Changelog

As with all Broadleaf upgrades, it is recommended to create your own Liquibase changelog as a sanity check that all indexes, columns, tables, and constraints are there. The steps to do so are as listed

1. Generate a database for the existing codebase
2. Upgrade the application to Broadleaf 6.2

3. Set the following properties in default-shared.properties

       blPU.hibernate.hbm2ddl.auto=create
       blEventPU.hibernate.hbm2ddl.auto=create
       blSecurePU.hibernate.hbm2ddl.auto=create
       blCMSStorage.hibernate.hbm2ddl.auto=create
   

4. Start up and then shut down the site application after it fully starts up

5. Download the Liquibase command line tool here. Make sure the version is 4.3.1 or above.

6. Copy the database connector JAR from your ~/.m2/repository to the download directory of Liquibase. For MySQL it will be ~/.m2/repository/mysql/mysql-connector-java/5.1.46/mysql-connector-java-5.1.46.jar

7. Create a file named liquibase.properties and add the following changing the properties according to your database setup. The reference properties all pertain to the 6.2 database we created in step 4.

       changeLogFile: dbchangelog-6.1-to-6.2.xml
       driver: com.mysql.jdbc.Driver
       url: jdbc:mysql://localhost:3306/broadleaf?characterEncoding=utf8&useUnicode=true&serverTimezone=UTC
       username: un
       password: pass
       referenceDriver: com.mysql.jdbc.Driver
       referenceUrl: jdbc:mysql://localhost:3306/broadleaf_6.2?characterEncoding=utf8&useUnicode=true&serverTimezone=UTC
       referenceUsername: un
       referencePassword: pass
       classpath: mysql-connector-java-5.1.46.jar
   

8. Run liquibase diffChangeLog which will write the changelog needed to migrate the schema from your previous database to the 6.2 database

9. Add the changelog to your changelogs if you're using Liquibase for schema changes. Otherwise run liquibase --changeLogFile=<what your changeLogFile property is set to> updateSQL > dbchangelog-6.1-6.2.sql which will generate the SQL equivalent to the XML and output it to that SQL file which then can be used to migrate the database.

Code, Template, and Property Changes

Disable Spring Boot default resource handling

Due to catch-all nature of AdminBasicEntityController, it is required to disable Spring Boot default resource handling. The property to disable has changed so it needs to be updated. Replace spring.resources.add-mappings with the property below:

spring.web.resources.add-mappings=false

Admin Presentation Overrides Removed

The deprecated admin presentation overrides and associated classes have been removed. They are likely to cause problems by loading certain classes before Broadleaf's class transformations are applied. Use AdminPresentationMergeOverride instead.
Removed classes:

AdminPresentationAdornedTargetCollectionOverride
AdminPresentationCollectionOverride
AdminPresentationDataDrivenEnumerationOverride
AdminPresentationMapOverride
AdminPresentationOverride
AdminPresentationOverrides
AdminPresentationToOneLookupOverride

Type Adhead Suggestion Limit

The type ahead limits were set inconsistently. Some were set by suggestionLimit on TypeAheadConfigurationImpl and some with properties. The field suggestionLimit has been dropped in favor of properties which can be set as follows:

typeahead.keywords.limit=8
typeahead.products.limit=5
typeahead.categories.limit=5