6.0 to 6.1 Migration

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

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

Module Compatibility with 6.0

If you are using any other Broadleaf modules, then those module versions will need to be updated to be compatible with broadleaf framework 6.1. Here is a compatibility chart listing all of the module versions that are compatible with broadleaf 6.1.

Major feats

• Updated core 3rd-party dependency baselines
  • Spring 5.1
    • 5.0.16.RELEASE -> 5.1.13.RELEASE
    • Spring 5.1 Migration Notes
  • Spring Boot 2.1
    • 2.0.4.RELEASE -> 2.1.12.RELEASE
    • Spring Boot 2.1 Migration Notes
    • Spring Boot 2.1 Configuration Changelog
  • Spring Security 5.1
    • 5.0.12.RELEASE -> 5.1.7.RELEASE
  • Hibernate 5.3
    • 5.2.17.Final -> 5.3.15.Final
    • Hibernate 5.3 Migration Notes
  • Solr 7.7
    • 7.3.1 -> 7.7.2
• Merged the Broadleaf 5.3 line with the 6.x line
• Replaced all Ehcache 2 specific code in favor of JSR-107 (Jcache) APIs
  • This was necessary as Hibernate 5.3 does not support Ehcache 2
  • Ehcache 3 configuration and dependency included by default but can be replaced with any Jcache compliant caching implementation

Hibernate 5.3 updates

• Ehcache 2 support dropped
  • Ehcache 3 now used as default in Broadleaf however any JSR-107 (Jcache) compliant cache implementation can be used
• JPA 2.2 specification support added
  • This was the main feat accomplished in 5.3
  • Most of these changes shouldn't affect Broadleaf projects however for more information please see the Hibernate 5.3 Migration Notes

Framework changes

General changes

Broadleaf 5.3 Features

One of the major feats was merging the specialty 5.3 line of Broadleaf into the main line releases. Below are the features that were added

• Offer enhancements
  • Future Credit
    • This feature allows the platform to give account credits to a customer for buying certain items that can be used on future orders.
  • Offer tier enhancement
    • Previously in order for an offer tier to be active the cart only had to qualify for that tier without having to qualify for all of the tier below it. This functionality can still be used however the default is now that the cart has to qualify for all lower tiers before it can qualify for a higher tier.
  • Offer usage enhancement
    • In addition to limiting the number of times a customer can use an offer, functionality has been added to limit the minimum number of days that need to pass before a customer is able to use an offer again.
• Media assets
  • Ability to bulk delete media assets

For more information please refer to a more comprehensive guide [[here | 5.2 to 5.3 Migration]

Ehcache 3

Ehcache configuration files (i.e. bl-overrides-ehcache.xml) need to be migrated to Ehcache 3 syntax. An example of how to do this is as shown below. Note also that the base element has changed from "<ehcache>" to "<config>".

Ehcache 2

<ehcache>
    <cache
        name="blProducts"
        maxElementsInMemory="100000"
        eternal="false"
        overflowToDisk="false"
        timeToLiveSeconds="86400">
        <cacheEventListenerFactory class="org.broadleafcommerce.common.cache.engine.HydratedCacheEventListenerFactory"/>
    </cache>
</ehcache>

Ehcache 3

<config>
    <cache alias="blProducts" uses-template="hydratedCacheTemplate">
        <expiry>
            <ttl>86400</ttl>
        </expiry>
        <heap>100000</heap>
    </cache>
</config>

Additionally the persistence directory has to be defined as a unique location for each application. For production where each application is on its own node this isn't an issue however for local development it's necessary. The following need to be added to the respective application bl-overrides-ehcache.xml file.

Site

<persistence directory="${java.io.tmpdir}/cache/site"/>

Admin

<persistence directory="${java.io.tmpdir}/cache/admin"/>

API

<persistence directory="${java.io.tmpdir}/cache/api"/>

Custom Caches

If a custom cache has been created, that cache needs to be registered with JCache. Broadleaf has a special registration class to assist with this setup called JCacheRegionConfiguration. A standard Java Configuration class can be used to register the cache.

@Configuration
public class CacheConfiguration {

    @Bean
    public JCacheRegionConfiguration myCacheName() {
        return new JCacheRegionConfiguration("myCacheName", 3600, 100000);
    }

}

Domain changes

5.3 Domain changes

• Account
  • New table BLC_ACCOUNT_ATTRIBUTE
• Advanced CMS
  • New table BLC_EMAIL_HEADER
  • New table BLC_EMAIL_TEMPLATE
  • New table BLC_SMS_TEMPLATE
  • New columns EMAIL_TEMPLATE_ID, NEW_EMAIL_TEMPLATE_ID, SMS_TEMPLATE_ID, and NEW_SMS_TEMPLATE_ID added to table BLC_CONTENT_TARGETING_ACTION
• Broadleaf Framework
  • New table BLC_OFFER_PRICE_DATA
  • New column ACCOUNT_ID added to table BLC_OFFER_AUDIT
  • New column IS_FUTURE_CREDIT added to table BLC_FG_ADJUSTMENT
  • New column IS_FUTURE_CREDIT added to table BLC_ORDER_ADJUSTMENT
  • New columns OFFER_ADJUSTMENT_TYPE, MAX_USES_STRATEGY, MINIMUM_DAYS_PER_USAGE, and USE_LIST_FOR_DISCOUNTS added to table BLC_OFFER
  • New column IS_FUTURE_CREDIT added to table BLC_ORDER_ITEM_DTL_ADJ
  • New columns FOLDERABLE and FOLDERED_BY_DEFAULT added to table BLC_ADMIN_SECTION
• Cart Rules
  • New columns IS_DEFAULT_PRODUCT and ACTION_SKU_ID added to table BLC_CART_RULE_ACTION
  • New column TIMES_PER_CUSTOMER added to table BLC_CART_RULE
• Enterprise
  • New table BLC_ADMIN_FOLDER
  • New table BLC_ADMIN_FOLDER_ITEM

6.1 Domain changes

• Broadleaf Framework
  • Column MARKETING_MESSASGE renamed to MARKETING_MESSAGE for table BLC_OFFER

Migrating Translation data

In 6.1 a fix was added so that Translations added at a catalog or profile level will show up in child sites that inherit from those catalog and profiles. For your existing Translations to work correctly a data migration is necessary. The main point of this data migration is to replace all site_id values which are set to template sites to be set to the profile site id instead. To do so run the following script

select concat('update blc_translation set site_disc=', concat(profile.site_id, concat(' where translation_id=', concat(trans.translation_id, concat('; -- changing from ', concat(template.site_id, concat(' for type ', trans.entity_type)))))))
from blc_translation trans
inner join blc_site template on trans.site_disc = template.site_id
inner join blc_site profile on template.site_id = profile.parent_site_id
and template.site_type = 'TEMPLATE'
and profile.site_type = 'PROFILE';

This will output SQL update statements that will need to be ran in order for the Translations to be updated correctly. If the Translations are still not showing up correctly for some reason then update all of the Translation records that are for Profile entities so that the catalog_id is set to null. Additionally, using the update statements that were generated from the above SQL, identify all Translations for catalog entities and update the site_id to null for all of the records where the site_id is set to a profile. Be sure not to set the site_id to null for any Translations where the site_id is for a standard site otherwise the Translation will not work correctly. These last steps should not be necessary however it will update the records to how they would look if you were to create the Translations through the admin with 6.1. If the Translations are still not working then as a last resort you will need to recreate all of the Translations so that they're guaranteed to be created correctly.

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 contraints 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.1

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

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.1 database we created in step 4.

       changeLogFile: dbchangelog-6.0-to-6.1.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.1?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.1 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.0-6.1.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

The upgrade will require updates to configuration and application classes:

• Email configuration
  • New property added to EmailInfo named emailType that needs to be set. Refer to NotificationEventType for available options
• logging.config property
  • Broadleaf changed how we add our properties to Spring's properties so now the logging.config property is now used unlike before
  • For most applications the property needs to be set to logging.config=logback-spring.xml. The name of the log file can now be changed as long as this property matches the name of the file
• Preview Customer Segment
  • In order to use the new feature to preview customer segments two changes will need to be made to the templates
  • previewCustomerSegment-client.js needs to be added either as part of the JS bundle or wherever JS files are added. Typically this is in footer.html.
  • previewCustomerSegment-client.css needs to be added either as part of the CSS bundle or wherever CSS files are added. Typically this is in head.html.

Performance Caveats

MySQL

In testing we found that the newer com.mysql.cj.jdbc.Driver MySQL driver performs worse than com.mysql.jdbc.Driver especially when it comes to commits. In Broadleaf 6.0 the property database.driver may not be set however if you're using MySQL we recommend setting that property to database.driver=com.mysql.jdbc.Driver. If that property is not set then Broadleaf defaults to using which driver Spring recommends which is the less performant com.mysql.cj.jdbc.Driver.

Solr

For Broadleaf 6.1 we made sure that we support Solr 7.7.2. It should be noted that Solr 7.7.0 and 7.7.1 should be avoided as they contain a bug that interacts with Java 8 poorly where it will infinitely spin up threads causing CPU and RAM thrashing. Solr 7.3.1 can continue to be used at this time however it is recommended that a reindex is done after upgrading to Broadleaf 6.1 and at some point you should upgrade your Solr server to Solr 7.7.2

Hibernate

When performance testing 6.1 we found that because of the Hibernate upgrade from 5.2 to 5.3 it is important to review which cache strategies are being used for all entities and collections. Specifically we found that entities and collections using @Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) need to be reviewed in order to determine if that is the correct cache strategy or if it should be using CacheConcurrencyStrategy.READ_WRITE instead. In previous versions of Hibernate this strategy was not honored very often as whichever entity was defined in Hibernate first for a region determined the cache strategy for the entire region. Since most entities use CacheConcurrencyStrategy.READ_WRITE we never had the poor performance impact we were seeing before reviewing our cache strategies with 6.1. To determine which strategy to use for an entity or collection you need to determine how often that collection, entity, or entity that contains a collection changes. NONSTRICT_READ_WRITE should only be used when the collection, entity, or entity containing the collection is either never changed or very rarely changed. Since NONSTRICT_READ_WRITE is not a read-through cache, a cache entry will not be created when the entity is created and the cache entry will be removed if the entity is updated. Therefore if a customer on the site side has the ability to modify the entity or collection it should use the READ_WRITE strategy. In any case where there's any confusion READ_WRITE should be used as it will continue to be cached as it was in previous version of Broadleaf. Using NONSTRICT_READ_WRITE is a small optimization that makes retrieving from cache faster with the cost of being vulnerable to returning stale data and being evicted very often resulting in cache misses. This change only affects custom entities or collections added in a Broadleaf implementation as all changes needed in the Broadleaf code have already been made.