Documentation Home
Changelog

4.0 to 5.0 Migration

This document and the embedded linked documents outline the steps for migrating Broadleaf 4.0 to Broadleaf 5.0.

Some disclaimers:

  1. We assume that your project is currently on the most recent 4.0 version of Broadleaf
  2. We assume that you had previously followed all migration and upgrade notes for the latest release version of Broadleaf 4.0
  3. We assume you are running on a Postgres, MySQL, Oracle or SQL Server database
  4. The migration scripts (and related Liquibase changelogs) makes certain assumptions regarding the installed modules which may not apply to your implementation. Therefore some adjustments of the scripts may be required.
  5. This is a migration to Braodleaf 5.0 and is considered a major release. Migrating is a project in itself and will require discovery, database and code updates, and extensive verification. While this guide outlines the key changes needed to migration to 5.0, there will be differences in every migration which may cause deviations from the provided steps.

Create new tables and columns

5.0 introduces several new tables and new columns on existing tables. This step creates those new entities. Liquibase Changelogs and db scripts are available depending on your setup.

  • MySQL Creation (Enterprise) Changelog / DB Script
  • SQL Server Creation (Enterprise) Changelog / DB Script
  • Oracle Creation (Enterprise) - coming soon
  • Postgres Creation (Enterprise) - coming soon

Data Migration Scripts

Some tables have been changes and data moved to accomodate improved features. Data migration is currently only managed with db scripts (not Liquibase Changelogs). Given the variations in database syntax, some scripts have special callouts for the different database platforms. It is recommended that there are worked through carefully and executed in small, managed increments.

Manual Migration

The expression syntax for Rule Builders has changed in 5.0. There is not an automated expression syntax converter utility that migrates from the old syntax to the new syntax. These rules will need to be manually converted from within the admin. The approach is to edit each rule and rebuild it to the new expression syntax. The Match Rule Queries are made available to provide a means to export the existing expressions as a reference point prior to recreating. Additional data beyond the defined select columns may be required based on sandbox state, required reference points, or other needs. There are meant as a starting point.

Project Updates

Once the initial data setup is complete, the project itself can be migrated. The following sections require manual changes for the update process.

Update pom versions

Update your main pom.xml versions to the following 5.0 versions. Omit any modules that you are not currently using, unless otherwise specified. We've deprecated the REST endpoints in core and introduced a new REST Api module​​. This way, going forward, we can make releases to REST endpoints without requiring a core framework release. You will want to migrate existing endpoints to the new module.

<blc.version>5.0.3-GA</blc.version>
<broadleaf-menu.version>2.0.1-GA</broadleaf-menu.version>
<broadleaf-multitenant-singleschema.version>3.0.2-GA</broadleaf-multitenant-singleschema.version>
<broadleaf-theme.version>2.0.3-GA</broadleaf-theme.version>
<broadleaf-pricelist.version>3.0.1-GA</broadleaf-pricelist.version>
<broadleaf-custom-field.version>2.0.1-GA</broadleaf-custom-field.version>
<broadleaf-advanced-cms.version>2.0.4-GA</broadleaf-advanced-cms.version>
<broadleaf-advanced-offer.version>2.0.2-GA</broadleaf-advanced-offer.version>
<broadleaf-account-credit.version>3.0.0-GA</broadleaf-account-credit.version>
<broadleaf-advanced-inventory.version>2.0.1-GA</broadleaf-advanced-inventory.version>
<broadleaf-common-modules-enterprise.version>3.0.3-GA</broadleaf-common-modules-enterprise.version>
<broadleaf-jobs-events.version>2.1.0-GA</broadleaf-jobs-events.version>
<broadleaf-i18n-enterprise.version>2.0.2-GA</broadleaf-i18n-enterprise.version>
<broadleaf-enterprise.version>3.0.3-GA</broadleaf-enterprise.version>
<broadleaf-account.version>2.0.1-GA</broadleaf-account.version>

<broadleaf-enterprise-search.version>2.0.2-GA</broadleaf-enterprise-search.version>
<broadleaf-customer-segment.version>1.0.2-GA</broadleaf-customer-segment.version>
<broadleaf-merchandising-group.version>1.0.1-GA</broadleaf-merchandising-group.version>
<broadleaf-sample-payment-gateway.version>2.0.0-GA</broadleaf-sample-payment-gateway.version>
<broadleaf-api.version>2.0.0-GA</broadleaf-api.version>

Add the following new dependencies

  • Parent pom.xml's dependencies:
<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-customer-segment</artifactId>
    <version>${broadleaf-customer-segment.version}</version>
    <type>jar</type>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-merchandising-group</artifactId>
    <version>${broadleaf-merchandising-group.version}</version>
    <type>jar</type>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.broadleafcommerce</groupId>
    <artifactId>broadleaf-sample-payment-gateway</artifactId>
    <version>${broadleaf-sample-payment-gateway.version}</version>
    <type>jar</type>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-rest-api</artifactId>
    <version>${broadleaf-api.version}</version>
    <type>jar</type>
    <scope>compile</scope>
</dependency>
  • Core pom.xml dependencies:
<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-customer-segment</artifactId>
</dependency>
<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-merchandising-group</artifactId>
</dependency>
<dependency>
    <groupId>org.broadleafcommerce</groupId>
    <artifactId>broadleaf-sample-payment-gateway</artifactId>
</dependency>
<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-rest-api</artifactId>
</dependency>

Admin changes

  • Replace Admin's leftNav.html content with:
<blc_admin:admin_module resultVar="adminMenu" />

<div class="side-nav">
    <ul>
        <li th:each="module : ${adminMenu.adminModules}" th:inline="text">
            <a th:class="${'nav-section ' + module.icon}" th:href="@{${'/overview'}}" th:if="${module.icon == 'blc-icon-blc-leaf'}"></a>
            <a th:class="${'nav-section ' + module.icon}" href="" th:attr="data-toggle=${'#' + module.moduleKey}"
               th:unless="${module.icon == 'blc-icon-blc-leaf'}"></a>
        </li>
    </ul>
</div>

Apply applicationContext changes

SOLR changes

Fix compilation issues

This section will take the most time, and will vary from project to project. The more customizations and extensions that you have, the more compilation issues you will need to address.

  • Remove any Broadleaf provided class named NullPayment*
  • Change calls of solrIndexService.rebuildAllIndexes() to solrIndexService.rebuildIndex()

Fix any startup issues

This should also take some time, but not as much as the previous task.

Verify and test

This is important to do before the final step. Perform full regressions tests across your project to make sure everything is functioning as expected.

Final table and column migration

The final script completes the data migration and handles dropping of columns, removing tables, creating primary keys/constraints, etc. Some of these operations are destructive and appropriate caution should be made.