Broadleaf Microservices
  • v1.0.0-latest-prod

Marketplace Concepts

When marketplace functionality is enabled, there are some considerations involved in how catalog and application structures are configured.

Domain and Management

  • On Catalog, there is a vendorRef field describing which vendor the catalog and its data should be associated to. This is immutable after creation for security and consistency purposes. A catalog with a value for vendorRef is considered to be a 'vendor catalog', and data associated to that catalog is treated as belonging to that vendor. A catalog with no value for vendorRef is considered to be a 'non-vendor catalog', and data associated to that catalog is treated as not belonging to any vendor.

  • On Application, there is an isMarketplace field describing whether the application is a 'marketplace' application.

  • Vendor catalogs can only be associated to marketplace applications. Furthermore, the relationship between these entities is handled through a separate entity called MarketplaceApplicationCatalog. This is different from the standard Application.isolatedCatalogs mechanism used to associate non-vendor catalogs to applications.

    The primary motivation for separating these mechanisms comes from differences in relationship cardinality. In a standard scenario, an application will have a relatively small number of assigned non-vendor catalogs. On the other hand, there may be thousands of vendor catalogs assigned to an application. The scale of those relationships is better handled by the introduction of the separate MarketplaceApplicationCatalog domain.

    Similar to Catalog and Application, the MarketplaceApplicationCatalog domain is also synchronized from TenantServices to other microservices managing catalog/application discriminated entities.

  • As noted in the documentation for TenantVendorNotificationHandler, a vendor catalog will automatically be created by TenantServices whenever it is notified about the creation of a new vendor. This vendor catalog will also automatically be associated to a marketplace application as documented in MarketplaceDiscoverer.

Vendor Catalog Hierarchy Expectations

There are some key differences in the hierarchical structure expected for vendor catalogs versus non-vendor catalogs. Vendor catalogs do not support the full 'catalog hierarchy' concept the way non-vendor catalogs do.

  • Vendor catalogs cannot have vendor catalogs as parents. All vendor catalogs (even catalogs for the same vendor) are expected to be independent of each other.

  • By definition, a non-vendor catalog cannot assign a vendor catalog as a parent. Non-vendor catalogs are not vendor-discriminated, so allowing them to assign a vendor catalog as a parent would fundamentally leak data from that vendor.

  • There is a limited use-case where a vendor catalog is allowed to assign a non-vendor catalog as a parent. For example, there may be a 'global' non-vendor catalog that defines categories which should be shared across a marketplace.

    • Vendor catalogs would declare this as a parent catalog to be able to assign their products to those categories.

    • The marketplace application would also assign that 'global' non-vendor catalog as one of its standard Application.isolatedCatalogs to ensure the vendor catalog narrowing logic can find the data both from the parent catalog and the vendor catalogs in a marketplace context.

    • However, we would never want the vendor catalogs to be able to directly override or customize data from the global non-vendor parent catalog, and thus only 'REFERENCE' mutability type is allowed for such relationships.