Broadleaf Microservices
  • v1.0.0-latest-prod

Upgrade to 2.1.0

The 2.x versions are Spring Boot 3 compatible.
If coming from a version prior to 2.0.0-GA, then see the 2.0.0 upgrade guide.


  • Java 17 is required since 2.0.0-GA.

Notable Changes

Fixes for override determination in direct-to-production CUD operations.

In most cases, create/update/delete (CUD) operations in Broadleaf occur in a sandbox context by default and are subsequently promoted/deployed to production. In some cases, however, it’s possible for CUD operations to directly target a production context and bypass the promote-deploy flow. For example, it’s possible to import products directly into production.

The logic to determine whether a change is an override (ex: application-catalog-level override of a tenant-catalog-level product) was not correct specifically in the direct-to-production flow.

This led to unexpected 'override' labels appearing in the admin for such operations.

There were also issues observed with 'delete' overrides not being correctly created in direct-to-production flows, both for sandboxable and non-sandboxable entities.

Addressing this issue required breaking changes to a few method signatures, outlined in Data Tracking 2.0.2 release-notes.
  • If you have access to an exploded/generated project based on a 2.0.x manifest

    • Edit the pom file in your manifest directory. Change the parent element version for broadleaf-microservices-flex-parent to 2.1.0-GA.

    • Edit the manifest.yml file. Set project.starterParentVersion to 2.1.0-GA. If using the broadleaf-microservices-starter-heatclinic extension, change the version to 1.1.1-GA.

    • At the command line in the manifest directory, execute mvn flex:generate to update the project to the latest configuration

    • This should update all your poms to use the latest flex parent for 2.1.0-GA

    • This should update all your Docker related artifacts to use the latest approach (Documented here).

  • If you do not have access to an exploded project based on a 2.0.x manifest, do not wish to update your project structure using mvn flex:generate, or are not using a manifest

    • Edit pom files and change the parent element version for broadleaf-microservices-flex-parent to 2.1.0-GA

    • Add/Edit docker related artifacts for your dockerized modules. Review Docker Config Examples for more information.

    • If not customizing gateways, you map optionally reference the new Broadleaf generated Alpine versions where applicable (these remain 2.0.1-GA for 2.1.0-GA release train):



    • If not customizing auth and not using a manifest-based project, you may optionally reference the new Broadleaf generated Alpine version where applicable (these remain 2.0.1-GA for 2.1.0-GA release train):


    • If not customizing config server, you may optionally reference the new Broadleaf generated Alpine version where applicable (these remain 2.0.1-GA for 2.1.0-GA release train):


  • Two new manifest.yml properties are available:

    • project.useAlpineJavaImages - Whether Alpine Linux Temurin java images should be used for flexpackage image generation, as well as for config server and gateway image references. Alpine images will be the most secure with the fewest OS vulns. Optional. True by default. Note, the Alpine Linux Temurin Java image is available only in amd64, so arm64-based machines must be capable of emulating (e.g. qemu or rosetta2). Such a situation is suitable for development. However, if an arm64 processor is being used in production, then this setting should be set to false for the performance benefit.

    • project.upgradeOSOnBuild - Whether an OS upgrade command should be executed during the Dockerfile construction for a module (e.g. apk upgrade). Optional. False by default, which will avoid unnecessary layer churn.

Notable Changes

Introduced Application-Specific Search Settings

Introduced support for Application-Specific Search Settings. Additionally, the Product Browse view will now retrieve results from Search rather than Catalog and will make use of Search Facets rather than the typical filters. One of the key improvements made has been to allow different Applications to have distinct Facets and Sort Options as well as to distinguish between the Storefront and the Admin applications. Therefore, the Facet shown for Products in the Admin will be different from those on the Storefront. There is a Tenant-level set of defaults that can be overridden per Application.

You should perform a full Solr reindex after upgrading to allow indexing Products regardless of the online and searchable flags and to include new Business Type search field. These Products are still filtered for Storefront requests by way of a query-time filter (rather than index-time), but are visible in the Admin.

Required Migration

Upgrading requires migration scripts to be added in your project:

  • Add db/sql/search-migration.sql (or db/sql/search-migration-oracle.sql for Oracle) to search.flexdemo.postgresql.changelog-master after any scripts that currently load Field Definitions. This script will:

    • Create Facets and Field Sort Options for all existing Field Definitions as appropriate

    • Set up Search Settings for each Tenant and Application

    • Migrated existing Facets and Sort Options to the appropriate Facet and Sort Groups for Storefront and Admin Settings.

    • Add a new Field Definition for Business Types to support using Search Service to power the Product Browse list grid instead of Catalog Service.

  • Add db/sql/tenant-search-group-migration.sql (or db/sql/tenant-search-group-migration-oracle.sql for Oracle) to tenant.flexdemo.postgresql.changelog-master after any scripts that currently load Tenants and Applications. This script will:

    The 2.1.0 Tenant Services migration scripts have some issues which were resolved in Tenant Services 2.1.1. Please see Tenant Services 2.1.0 docs for more information.
    • Create a new Search Group type Catalog for each Tenant and Application.

    • Create the notifications for those Catalogs so that they will be synced on next application start up.

    • Tenants and Applications created via APIs in the future will automatically have new Search Groups created.

Introduced Bulk Operation Services

Introduced a new orchestration microservice for handling Bulk Operations along with several out of box operations for Products in Catalogs Services. This comes with a few out-of-box sample Bulk Operations for Products for Adding Advanced Tags, Removing Tags, Archiving, and modifying Active Date Ranges.

See Also:

Introduced Negotiated Quotes

Quotes are a new type of Cart that may be submitted by registered Customers and reviewed by CSRs. They have a new set of statuses specific to negotiating a quote with a seller. CSRs may then make changes to the requested Quote and publish them for the Customer to accept and checkout with or submit additional requests. Quotes also support notes and requesting non-catalog Items such that could represent services and Products that they could not find.

Along with this release we have introduced Cart Services Metadata for displaying a Quote list grid in the Admin for CSRs to use to navigate to the storefront. All actual management of Quotes is expected to be done from the storefront for both buyers and sellers.

Quotes are disabled by default. To enable:

  • Set broadleaf.quotes.enabled=true for Cart Operations Service or its containing flexpackage, e.g., Cart.


  • Add the following to your Metadata Service or Supporting flexpackage pom.xml to include the new Cart Services Metadata library.

  • Set broadleaf.cart.metadata.enable-quote=true to your Metadata Service or Supporting flexpackage.

See Also:

Introduced Catalog Access Policies

Introduced new Catalog Access Policies feature. Functionality overview and upgrade details outlined in Catalog Services 2.1.0 Release Notes. Catalog access policies allow merchandisers to restrict the contents of a catalog that are visible to customers in the storefront. See this guide for more details. This feature is enabled by default.

See Also:

Frontend Compatibility and Release Notes

Microservices release 2.1.0 is congruent with:

Service-level Release Notes

Common Libraries