Broadleaf Microservices
  • v1.0.0-latest-prod

Catalog Release Notes for 2.2.0-GA

Tip
The 2.x versions are Spring Boot 3 compatible.

Requirements

  • JDK 17 is required for Broadleaf release trains 2.0.0-GA, and beyond.

New Features & Notable Changes

  • Added a new readAllDataDrivenEnumTypes endpoint to retrieve distinct DataDrivenEnum types with additional service and repository implementations.

  • Added support for fetching parent Category hierarchies.

    • Added caching configuration for the DefaultCategoryService#readCategoryParentHierarchy method, which defaults to 30 minutes.

    • Added a categoryIdsWithParents field to ProductDetails and ProductDetailsContext to support Offer and Pricing flows with Category restriction targeting a parent Category.

    • Added native SQL queries to build the Category hierarchy.

  • Enhanced the Add Product/s feature in the Products tab for a Category to be able to add Category Products via the configured Product Membership Rule.

  • Updated the Attribute Choice Allowed Values grid entries to be orderable and hid the Display Order field from the Allowed Values grid.

  • Added caches for efficiency during marketing message retrieval.

  • Expose the individually sold flag for BUNDLE typed products.

    • This is to support a more dynamic setup for Free Gift offers, e.g. a bundle product that consists of 2 itemA and 3 itemB can be created solely for the purpose of being free gifts, and the bundle product itself should not be individually sold nor searchable.

  • Added the persistence and visibility of displayOrder on the Product Options grid for Products.

  • Usages of forceCatalogForFetch were updated to use forceFilterByCatalogIncludeInheritance.

  • Introduced support for bulk operations for the new Category membership type of AUTO_INCLUDE which will add CategoryProducts automatically when a Product qualifies according the Product membership rules.

  • Updated the Import of Products with assets so that a sorting value is added onto assets upon import.

  • Introduced support for a new drag-and-drop component for Product Assets.

    • Introduced a listener and job that will update the sorting on all product assets, as this is required for the drag-and-drop functionality to work as you cannot sort an unsorted asset.

    • The drag-and-drop functionality is disabled by default, and can be enabled via configuration:

    How to enable drag-and-drop for Product Assets
    broadleaf:
      catalog:
        metadata:
          drag-and-drop-assets-enabled: true
  • Introduced three new Bulk Operations:

    • Set Product(s) as Searchable

    • Add Product(s) to Category(s)

    • Remove Product(s) from a Category

  • Allow for Facet translations to take affect when viewing product list grid by adding the localeOverrideForFacetAndSortLabels parameter to the Products grid, whose value is expected to be the locale desired to override the default locale.

  • Updated the BusinessType domain to contain a new attributes map to hold custom additional attributes. Admin metadata has also been updated to introduce this field.

    Note
    See the Schema Changes section below for more information on migration.
  • Updated BusinessTypeService and BusinessTypeRepository to introduce a method that can find BusinessType by ID as well as additional RSQL filters

  • Refactored logic that built BusinessType instances from DefaultProductType values into its own DefaultProductTypeBusinessTypeBuilder component. BusinessTypeEndpoint now injects and uses this component instead of having the logic inline within itself.

  • For BusinessType instances built for DefaultProductType values, added logic to set a reserved corresponding ID for BusinessType.id instead of keeping it blank. The ID mapping is defined in DefaultProductTypeBusinessTypeBuilder.

  • Introduced Product Characteristics.

  • Introduced the ability to define available terms for Products.

  • Introduced support to be able to add Products with a rule-based Category Item Choice Product Option to cart.

  • Introduced the ability to Sync Characteristics and translations for any missing Characteristics for Product Business Types and default any values as applicable.

  • Added priceDataViewType as a property in CatalogMetadataProperties to dictate changes in the metadata for Products and Option Templates to either display default views or recurring/subscription-specific views.

  • Introduced a new /product-types/all endpoint in BusinessTypeEndpoint to serve the purpose of returning all non-paginated BusinessType records.

    • Deprecated the previous conflicting request mapping at /product-types

    • Updated the BusinessType metadata configuration to use the new endpoint path instead of the old one.

    • Updated the BusinessType metadata configuration to remove the narrowedPaging() configuration when using the endpoint, since neither the previous nor current implementation of that endpoint support pagination.

  • Added a new GET endpoint to fetch BusinessType records, replacing a now-deprecated endpoint.

    • Previously, there were several different GET operations mapped to the same /product-types path, distinguished only by request parameters. While technically functional, the operations deserved to be more clearly disambiguated due to their differing semantics and response schemas. Thus, this existing mapping has been deprecated:

      • GET /product-types?includeDefaults=(boolean)&includeTemplates=(boolean), returning List<BusinessType>

    • The replacement endpoint is:

      • GET /product-types/all?includeDefaults=(boolean)&includeTemplates=(boolean), returning List<BusinessType>

    • The BusinessType admin metadata configuration has been updated to use the new endpoint path instead of the old one. Furthermore, the narrowedPaging() configuration has been removed when calling this endpoint, as neither the previous nor current implementation of the endpoint supports pagination.

  • Refactored Product Characteristic value handling and updated Characteristic field labels to fix issues with default values and labels.

Added Configuration Properties

  • broadleaf.catalog.cache.byCategoryParentHierarchyTtl

    • Description: Time-to-live for reading categories' parent hierarchy for product-details requests

    • Default Value: 30 minutes

Bug Fixes

Fix CatalogEntityDeletedEventHandler Failures with Deactivated Applications

CatalogEntityDeletedEventHandler implementations would fail on a security validation when run against data from a deactivated application (see Application.deactivated). To address this, each of the out of box implementations have been updated to disable security policy validation before invoking any CRUD methods to find/remove data. This is a safe change, as the cleanup handlers are always run internally by the system (rather than by any user/client). Almost all policy validations are skipped in such an environment already, but the Application.deactivated check is an exception, and the CatalogEntityDeletedEventHandlers are a rare case which actually attempt to deal with deactivated applications. Thus, explicitly bypassing security validation in this flow is necessary.

The changes:

  • Introduce a new doWithoutPolicyValidation() method in AbstractCatalogEntityDeletedEventHandler

  • Update all out of box implementations of CatalogEntityDeletedEventHandler to wrap their CRUD service invocations with the new doWithoutPolicyValidation() method

Note
If you have introduced your own CatalogEntityDeletedEventHandler or customized one of the out of box implementations, you may want to check that your custom code flows also bypass security validation.

Removal of Sandbox Behavior from BusinessType

The BusinessType domain was always meant to be non-sandboxable, and all operations against this domain from the Broadleaf admin have been 'production' level accordingly. However, the Trackable configuration of JpaBusinessType did not explicitly exclude sandbox behavior. This meant that theoretically, it was possible to create sandbox-level records for this domain if requests were made by a custom API caller.

With this release, JpaBusinessType has been explicitly annotated with @TrackableExtension(TrackableBehavior.APPLICATION), which excludes it entirely from supporting sandbox behavior.

Clients who have exclusively been managing this domain from the Broadleaf admin will not be impacted by this change, as the Broadleaf admin has always affected this domain at the production (non-sandbox) level.

For clients that believe they may have sandbox-level BusinessType records, here are some recommended steps:

  • First, examine the change summaries in the BLC admin’s 'Application Updates' section. From here, you can audit and manage (deploy/reject/etc) any changes to BusinessType domains until there are no more pending changes.

  • At this point, all that should be left in the CatalogServices database are production level records and 'obsolete' sandbox level records. The goal now is to find and remove those obsolete records.

    Note
    Technically, this step to remove obsolete sandbox records is optional. However, we include it in case clients find it helpful.
    • You can run the following SQL to see the BusinessType records who exist in the datastore with a sandbox-archived state

      SELECT id, context_id, name, trk_level, trk_sandbox_archived
      FROM catalog.blc_product_business_type
      WHERE trk_sandbox_archived = 'Y'
      • Inspect these results and verify that these obsolete records are indeed okay to remove

    • You can run the following SQL to see the Notification State records that would become orphaned if those business types were deleted:

      SELECT id
      from catalog.blc_notification_state
      WHERE entity_type = 'com.broadleafcommerce.catalog.provider.jpa.domain.product.type.JpaBusinessType'
        AND container IN (SELECT id
                          FROM catalog.blc_product_business_type
                          WHERE trk_sandbox_archived = 'Y')
    • If everything looks fine to remove, then you can first execute a DELETE on the blc_notification_state table with the same criteria as above, and then execute a DELETE on the blc_product_business_type table, again with the same criteria as above.

Additional Bug Fixes

  • Show a correct change type for bulk operations in the My Changes view.

  • Fixed an issue where Products from Catalogs with a PENDING status could not be exported.

  • Fix visibility of products from marketplace catalogs with pending status in storefront and admin

  • Added a PostMapperMember to fix or adjust the currencies on Variants to ensure that they use their parent product’s currency by default, rather than some other currency.

  • Fixed an issue where some products would be unable to correctly be added to a category.

  • Fixed issue where custom fields for Business Types were not showing up in Query Builders due to the showInQueryBuilder field value for custom fields not being persisted.

  • Fixed issue with Option Template by adding default filtering by selected type for product or variant when configuring Item Choices.

    • Additionally added a similar fix for Product Options.

  • Fixed issue where archived Categories were being included when hydrating Category onto a Product being fetched.

  • Fixed issue where exporting Products with filters applied were not processing correctly — updated the labels and help text of the Product Export grid to explain the Export modal sections and updated the processing to utilize the new information so filtering can be correctly applied.

  • Fixed issue where cloning a Product causes a validation error due to its minimum and maximum cardinalities to both having default values of 1, because its characteristics are not hydrated prior to the cloning.

  • Fixed issue where duplicate skus were being displayed for Products with only one variation when creating price data.

  • Fixed issue where not returning a default SKU for a non-Variant Product leads to the Price Data grid being disabled.

  • Fixed issue where fetching Data Driven Enums would return archived entries.

  • Fixed issue where propagating the deletion of a Product through child catalogs includes the implicit catalog of deactivated applications, which causes deployment and indexing failures — updated CatalogEntityDeletedEventHandlers to skip policy validation in specific cases.

  • Fixed issue where adding a Single Variation Product Choice to a Standard Product results in an error — added single specific Variant check onto the Variant contributor.

  • Fixed issue where certain fields and entries in grids related to Product Options would be cleared when entering and exiting Customize Form mode.

  • Fixed issue where translations were allowed on numeric characteristic values.

API Changes

Characteristics

Table 1. New Endpoints
Path Description

GET /characteristics

Read a page of Characteristics, accepting RSQL filters and a name (q) filter.

POST /characteristics

Create a new Characteristic.

GET /characteristics/{id}

Read a single Characteristic by ID.

PATCH /characteristics/{id}

Patch a single Characteristic by ID.

PUT /characteristics/{id}

Replace a single Characteristic by ID.

DELETE /characteristics/{id}

Delete a single Characteristic by ID.

PUT /characteristics/{id}/translations/{locale}

Replace the translations for a single Characteristic by ID for a given locale.

Business Types

Table 2. New Endpoints
Path Description

GET /variant-permutations?typeKey={typeKey}

Read all VARIANT_OPTION Characteristics by BusinessType typeKey to facilitate configuring which characteristic values to use when creating new Products of that type.

Schema Changes

The database schema has changed as part of this version.

'Create/Update' Changes

Create/update changes (new tables, new columns, etc) are automatically included in the updated *changelog-master.xml after you upgrade to the new Catalog Services JAR. The new changesets inside will run automatically to migrate existing data.

Database Platform Create/Update Changelog File Name

PostgreSQL

db/changelog/catalog.postgresql.changelog-master.xml

MariaDB

db/changelog/catalog.mariadb.changelog-master.xml

MySQL

db/changelog/catalog.mysql.changelog-master.xml

Oracle

db/changelog/catalog.oracle.changelog-master.xml and db/changelog/catalog.oracle.short.changelog-master.xml

YugabyteDB

db/changelog/catalog.yugabytedb.changelog-master.xml