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.
Module Name | Version | Migration Notes |
---|---|---|
broadleaf-menu | 3.3.x | - |
broadleaf-multitenant-singleschema | 4.3.x | - |
broadleaf-theme | 3.3.x | - |
broadleaf-pricelist | 4.3.x | - |
broadleaf-custom-field | 3.3.x | - |
broadleaf-advanced-cms | 3.3.x | - |
broadleaf-advanced-offer | 3.3.x | - |
broadleaf-account-credit | 4.3.x | - |
broadleaf-advanced-inventory | 3.3.x | - |
broadleaf-common-modules-enterprise | 4.3.x | - |
broadleaf-jobs-events | 3.3.x | - |
broadleaf-i18n-enterprise | 3.3.x | - |
broadleaf-enterprise | 4.3.x | - |
broadleaf-account | 3.3.x | - |
broadleaf-enterprise-search | 3.3.x | - |
broadleaf-sample-payment-gateway | 3.3.x | - |
broadleaf-customer-segment | 2.3.x | - |
broadleaf-merchandising-group | 2.3.x | - |
broadleaf-api | 3.3.x | - |
broadleaf-oms | 3.3.x | - |
broadleaf-cart-rules | 2.3.x | - |
broadleaf-common-presentation | 1.3.x | - |
broadleaf-thymeleaf-presentation | 2.3.x | - |
broadleaf-product-type | 2.3.x | - |
broadleaf-catalog-access-policy | 2.3.x | - |
broadleaf-quote | 2.3.x | - |
broadleaf-marketplace | 2.3.x | - |
broadleaf-process | 2.3.x | - |
broadleaf-export | 2.3.x | - |
broadleaf-import | 3.3.x | - |
broadleaf-importer | 2.3.x | - |
broadleaf-affiliate | 2.3.x | - |
broadleaf-contenttests | 3.3.x | - |
broadleaf-data-feed | 2.3.x | - |
broadleaf-subscription | 3.3.x | - |
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
- Spring 5.3
- Simple transition
- Simple transition workflow process is now enabled by default. It can be controlled by the following property
sandbox.lifecycle.strategy.simple.enabled
- Simple transition workflow process is now enabled by default. It can be controlled by the following property
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 pagesblProducts
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 pagesblCategories
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 menublOrderElements
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
All sql statements bellow are for MySql, if you are using another DB you need to adapt sql syntax and column types for your DB
- Broadleaf Framework
- Add column
DEFAULT_LOCALE
toBLC_SITE
- Add column
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 inBLC_THEME_FILE
table
- Create index for
ALTER TABLE BLC_THEME_FILE ADD INDEX (PATH);
- Enterprise search
- Remove column
BLC_TYPE_AHEAD_CONFIG
- Remove column
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
- Generate a database for the existing codebase
- Upgrade the application to Broadleaf 6.2
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
Start up and then shut down the site application after it fully starts up
Download the Liquibase command line tool here. Make sure the version is 4.3.1 or above.
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
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
Run
liquibase diffChangeLog
which will write the changelog needed to migrate the schema from your previous database to the 6.2 databaseAdd 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