Broadleaf Microservices
  • v1.0.0-latest-prod

Catalog Search Integrations

Overview

Catalog Services provides additional facilities to support search engines' needs for indexing catalog data, primarily Products. Out-of-the-box Broadleaf provides a Search microservice that integrates with Catalog Services and Apache Solr to enable searching Product data.

Retrieving Products for Indexing

The entry-point for indexing requests is the ProductEndpoint. The ProductEndpoint supports two requests of relevance for gathering products to index:

  1. #readAllProductIdsIgnoreNarrowing: This endpoint allows an search indexer to request large batches of the IDs for the products to be indexed, and it then breaks them into smaller batches to use to fetch the actual Products.

    • This improves the overall efficiency of indexing and keeps batch sizes smaller (byte-wise).

    • The usage pattern for this endpoint is to provide a max size and then use RSQL filters to specify the cursor position.

    • See the OpenAPI documentation for this endpoint

  2. #readAllProductsIgnoreNarrowingHydrated: This endpoint allows fetching the actual Products to be indexed along with all of the data from its relationships (like its parent Categories) in a single request.

Tip
See the Search Service’s indexing documentation for the particulars of how Broadleaf handles indexing out-of-box.

ConsolidatedProduct

The #readAllProductsIgnoreNarrowingHydrated endpoint will return a list of ConsolidatedProducts. A ConsolidatedProduct contains all of the fields of a Product along with the following:

  • variants: All of the product’s Variants

  • primaryCategory: The product’s primary parent Category

    • Contains an object with the id, name, and URL of the category

  • explicitCategories: The product’s other parent Categories that reference it explicitly

    • This is a list of objects with the id, name, and URL of each category

  • categories: Categories that contain this product directly or indirectly such as through their own sub-categories.

    • This is a list of objects with the id, name, and URL of each category

  • dataDrivenEnums: All of product’s Data Driven Enums, which include product’s brand, merchandising type, and target demographic.

    • This is a list of objects with the id, type, value, and display value of each data driven enum

  • productSortingWithinCategories: Maps a parent Category’s ID to the relative sort order of the product therein compared to the ordering of the other product’s in the category.

  • catalogOverrides: The IDs of descendant catalogs in which this context version of the product has been overridden.

    • If this product is in catalog "A", and catalog "B" inherits this product from catalog "A" but contains a local change for this product, then the catalog "A" version product will contain the ID B in its catalogOverrides.

  • sandboxAwareCatalogOverrides: This is similar to catalogOverrides, except the values within are encoded with additional information about the sandbox state of the override.

    • If there is an override of this record at a user sandbox level, it will follow the format: catalogId;sandboxId;sandboxOwner, where catalogId is the ID of the descendant catalog containing the override, sandboxId is the ID of the sandbox containing the override, and sandboxOwner is the author of the user-level change.

  • catalogOmissions: The IDs of descendant catalogs in which this context version of the product has been omitted as a result of one or more filters.

    • If this product is in catalog "A", and catalog "B" inherits this product from catalog "A" but contains a filter that removes it from the view of catalog "B", then the catalog "A" version product will contain the ID B in its catalogOmissions.

  • creatingApplicationId: The ID of the Application which owns the Product, if it exists. If not owned by an Application, this value will be null.

    • This is designed to be the same as the value in Tracking.creatingApplicationId.

  • sandboxOverrides: The IDs of descendant sandboxes in which this context version of the product has been overridden.

    • If this product is in sandbox "A", and sandbox "B" inherits this product from sandbox "A" but contains a local change for this product, then the sandbox "A" version product will contain the ID B in its sandboxOverrides.

  • catalogAwareSandboxOverrides: This is similar to sandboxOverrides, except the values within are encoded with additional information about the catalog state of the override.

    • If there is an override of this record at a user sandbox level, it will follow the format: sandboxId,sandboxOwner;catalogId, where sandboxId is the ID of the sandbox containing the override, and catalogId is the ID of the catalog containing the override, and sandboxOwner is the author of the user-level change

  • translations: Translations for the product and all translatable fields in the consolidated objects.

    • local: Locale wherein the translation is applicable

    • entityType: The type of entity the translation belongs to

  • archived: Whether this product has been archived in the request’s context.

  • advancedTags: References to all the AdvancedTags related to the product via ProductTags. The refs contain the following properties

    • id: ID of the advanced tag

    • name: Name of the advanced tag. This is what normally is indexed for faceting and searching.

    • type: The type of the advanced tag. This can be used to group the tags into separate facets such as a "Feature" facet or a "Discount Type" facet. The Search Field for the facet can take advantage of our support for JSON path syntax when setting the property path, e.g., advancedTags[?(@.type == "FEATURED")].name.

    • searchableByName: Whether the tag is also supposed to be searchable as a term and not just used for faceting. Similar to type, a Search Field can be set up with this property to include only searchable tags: advancedTags[?(@.searchableByName)].name.

  • sandboxOwner: The owner of the sandboxed product if it’s in a user sandbox.

  • requiredOptionInfos: If the product has required options, this will be populated with a ConsolidatedProductRequiredOptionInfo for each, summarizing the information about them for indexing.

    • By default, this only applies to merchandising products since their prices are determined by the choices so additional information may be necessary for correct pricing.

    • Since Catalog Service 2.1.5, Release Train 2.1.5.

ConsolidatedProductRequiredOptionInfo

Important
Since Catalog Service 2.1.5, Release Train 2.1.5.

This class is used to summarize the information about required options for merchandising products. This is used to make it easier for search indexers to index the related information and for their callers to determine the correct pricing when using an external Pricing Service.

  • pricingKey: The pricing key of the ItemChoice.

  • targetType: The target type of the ItemChoice.

  • overridePrice: The override price of the ItemChoice.

  • minimumQuantity: The minimum of the ItemChoice. Should be 1 or more.

  • defaultChoicePricingKey: The pricing key of the default SpecificItemChoice.

  • defaultChoiceUnderlyingSku: The SKU code of underlying Product or Variant of the default SpecificItemChoice.

  • defaultChoiceUnderlyingPricingKey: The pricing key of the underlying Product of the default SpecificItemChoice.

  • defaultChoiceOverridePrice: The override price of the default SpecificItemChoice.

  • defaultChoicePrice: The price of the default SpecificItemChoice.

    • This may be the same as defaultChoiceOverridePrice or else it is the underlying item’s default price.

  • defaultChoiceUnderlyingDefaultTerm: The default ProductTerm of the underlying item of the default SpecificItemChoice.

ProductConsolidationService

This service is responsible for retrieving and building the the ConsolidatedProducts. By default it defers the work of consolidating the different relationships of a Product together to the ProductConsolidationContributors. Then, it uses the ConsolidatedProductPostProcessor for any additional data hydration.

  1. The process starts by retrieving the products, including any that are archived.

  2. Then, all of the Categories that these products belong to are retrieved.

  3. Next, the catalog inheritance lines are computed. These are computed from the top-down and bottom-up to determine inherited properties, overrides, and omissions.

  4. Then, the ProductConsolidationContributors are invoked to handle hydrated additional relationships owned by the Catalog Services onto the ConsolidatedProduct.

  5. Last, the ConsolidatedProductPostProcessor is invoked to perform any additional setup or hydration based on the consolidation performed previously.

ProductConsolidationContributors

These services are responsible for contributing a subset of information for a ConsolidatedProduct such as the product’s Variants. They provide a simple means of adding in additional augmentations to the ConsolidatedProduct response by registering a new contributor.

The contributors provided out-of-box are, in order they are run:
  1. OptionTemplateProductConsolidationContributor: This contributor is responsible for retrieving the option templates referenced by this product’s options as well as their translations.

  2. PrimaryAssetProductConsolidationContributor: This contributor is responsible for retrieving the product’s primary Asset.

  3. CategoryProductConsolidationContributor: This contributor is responsible for setting the product’s various Category relationships.

  4. VariantProductConsolidationContributor: This contributor is responsible for retrieving the product’s Variants.

  5. TranslationProductConsolidationContributor: This contributor is responsible for retrieving the translations for all the displayable text fields on the various entities involved in the resulting ConsolidatedProduct.

    • It is important for this to run last so that all relevant translations can be gathered.

  6. ItemChoiceAvailabilityConsolidationContributor: This contributor performs logic to handle if a product with required item choices has all item choices available for purchase.

    • This handles item bundles to determine if the product has enough available items in order to.

    • Deprecated since Catalog Service 2.1.5, Release Train 2.1.5. RequiredOptionInfoProductConsolidationContributor is used instead.

      • Set broadleaf.catalog.product.consolidation.required-option-info.enabled=false to re-enable. .RequiredOptionInfoProductConsolidationContributor: This contributor performs logic to handle ProductOptions with required ItemChoices.

    • In particular this checks if all the required item choices are available for purchase, whether all bundle items are available, and hydrates ConsolidatedProductRequiredOptionInfo for Merchandising Products.

    • The logic in this consolidator is such that it will make the fewest number of queries possible to read all the related products and variants the must be hydrated.

    • It reads all the relations by their IDs that are production-level or within a sandbox that matches one of the Consolidated Products being consolidated.

    • It does not currently generate new overrides but only hydrates the existing ones.

    • This supersedes the ItemChoiceAvailabilityConsolidationContributor and is run in its place.

    • Since Catalog Service 2.1.5, Release Train 2.1.5.

  7. ProductTagConsolidationContributor: This contributor is responsible for retrieving the product’s related ProductTags.

    • This will also contribute the translations for the related tag since they are not catalog discriminated, so the normal process used by TranslationProductConsolidationContributor will not work—translations are owned by AdvancedTags.

    • This should be run after TranslationProductConsolidationContributor so that the translations are not overwritten.

  8. DataDrivenEnumConsolidationContributor: This contributor is responsible for retrieving the product’s Data Driven Enums as well as their translations, which include product’s brand, merchandising type, and target demographic.

    • Unlike Assets and Variants, Data Driven Enums are independent of Product and don’t have a direct relationship with it like other entities do. Therefore, the consolidation of their translations is done here instead of TranslationProductConsolidationContributor.

    • This should be run after TranslationProductConsolidationContributor so that the translations are not overwritten.

Additionally, an abstract class, ContextualProductConsolidationContributor, is implemented to support common behaviors of the contributors dealing with ContextStateAware entities, which in the default case is all of the contributors.

Note

ContextStateAware marks a projection domain as having additional sandbox, catalog, or tenant tracking information that a caller may be interested in. A business domain’s ContextState is only populated when coming out of the repository domain that maps into a projection domain. This is not designed to be used in other scenarios.

ConsolidatedProductPostProcessor

This service is responsible for any additional setup or hydration necessary for the ConsolidatedProduct. By default, it handles setting [catalogOverrides], [catalogOmissions], and [sandboxOverrides].