Migrating Solr-based search from HCL Commerce Version 9.1 to Commerce+

Migrate your Solr-based search solution from HCL Commerce Version 9.1 to Commerce+. This is the first step in adopting Commerce+, letting you run your existing customizations on the new runtime with your current database before you optionally move to PostgreSQL.

Before you begin

Complete the following prerequisites before you begin:

  • Install the Commerce+ toolkit environment and configure it with your target database from the start.
  • Port existing customizations to the new toolkit. Review and refactor all existing Solr customizations, and verify dependencies against the newer runtime.
  • Test in the new toolkit together with other runtime dependencies, such as the Transaction server app and the store.
  • Re-integrate Solr directly into the Commerce+ Transaction server (ts app) to ensure backward compatibility with existing V1 search APIs.
  • Align configuration: ensure that jvm.options is updated to handle master and replica roles dynamically, and verify that your Dockerfile uses the correct Open Liberty command JAR files instead of the legacy Liberty runengine JAR files.
Important: You must be running HCL Commerce Version 9.1 before you start the migration to Commerce+. If you are on Version 7, 8, or 9.0, first migrate to the latest supported version of 9.1 by using the official migration paths in the HCL Commerce Version 9.1 documentation.

About this task

Migrating Solr-based search to Commerce+ is the first stage of overall Commerce+ adoption when moving up from HCL Commerce Search Version 9.1. After your customizations are running in the new Commerce+ environment with your existing database type, you can then consider migrating your database to PostgreSQL. Moving to PostgreSQL improves runtime performance and lets you take advantage of the new Commerce+ PBC capabilities later.

What does not change for Solr-based search

The following aspects remain identical between Version 9.1 and Commerce+:

  • Search REST API contract - the storefront-facing search REST APIs remain the same.
  • Search profile structure - the wc-search.xml format, expression provider interface, and pre-processor and post-processor interfaces are unchanged.
  • Index core types - CatalogEntry, CatalogGroup, Unstructured, Price (extension), and Inventory (extension) remain the same.
  • Management Center search tools - search term associations, synonyms, redirect rules, and merchandising rules are unchanged.
What has changed for Solr-based search
  • The runtime moves from IBM Liberty to Open Liberty.
  • The Java runtime is now OpenJDK instead of IBM JDK.
  • The Java version has moved up to Java 21.
  • The Solr runtime has been upgraded to 9.10.1.
  • A dedicated Solr 9 Toolkit is provided for developing and testing customizations.
  • Maven is now the main deployment utility instead of Gradle and WCBD.
  • PostgreSQL database support has been added to allow easier migration to Commerce+ PBC.

Procedure

  1. Migrate your HCL Commerce development environment.
    1. Install the Commerce+ toolkit.
      1. Download the Commerce+ toolkit from the My HCLSoftware portal.
      2. Install the toolkit on a new machine. The Commerce+ toolkit cannot be installed over an existing Version 9.1 toolkit.
      3. Configure the toolkit to connect to your database of choice.
    2. Port your existing customizations.

      All Version 9.1 search customizations reside inside the search-app container. For Solr, the customization categories are:

      • Solr schema and field types
      • Indexing customizations (Preprocess and DIH)
      • Search profiles
      • Expression providers
      • Pre-processors and post-processors
      • Handlers
      • wc-component.xml
      • Custom transformers
    3. Update WCB properties.

      To target Solr 9.x, set solr.version.v9=true in wcbd-build-search.properties.

    4. Test the index build.

      Run a full index build cycle. The indexing steps remain the same as in Version 9.1.

    5. Test search queries.

      Verify the search results.

  2. Update your CI/CD pipeline.

    Because HCL Commerce+ uses Docker-based deployment, the CI/CD pipeline typically involves:

    • Updating Dockerfiles.
    • Updating Helm charts.
    • Building custom images and packaging search customizations by using WCB.
    • Deploying the full Commerce+ environment in QA.
    • Running the test suite.
  3. Migrate your HCL Commerce production environment.

    Because the storefront is already live, plan the swap to Commerce+ carefully.

    1. Complete pre-cutover preparation.
      1. Build and validate all custom Docker images in the QA environment.
      2. Push validated images to the production container registry.
      3. Prepare updated Helm charts or Docker Compose files with the Commerce+ configuration.
      4. Back up the production database.
    2. Plan the maintenance window.
    3. Deploy the Commerce+ containers.
    4. Switch traffic to point to the Commerce+ environment.
    5. Verify search.
    6. Monitor the environment.
  4. Optional: Migrate your HCL Commerce database to PostgreSQL.

    This step is optional. Complete the following Solr search tasks to migrate the database to PostgreSQL.

    Table 1. Solr search: PostgreSQL migration tasks
    Step Task Details
    1 Audit preprocess SQL Review all wc-dataimport-preprocess*.xml files for database-specific syntax.
    2 Create or verify PostgreSQL configurations Verify that wc-data-config-postgres.xml files cover all customizations. Commerce+ ships base files; you must add custom entities and fields.
    3 Audit IndexLoad SQL Review wc-indexload-*.xml files for database-specific syntax.
    4 Update custom transformers Modify for PostgreSQL compatibility.
    5 Update JDBC configuration Configure the PostgreSQL JDBC driver and datasource.
    6 Test preprocess Run di-preprocess against PostgreSQL and verify TI_* table population.
    7 Test index build Run di-buildindex and verify all cores, including extension indexes.
    8 Test delta indexing Verify that delta preprocess and delta buildindex work with PostgreSQL.
    9 Test queries Run a full search regression test.

Results

Your Solr-based search solution now runs on Commerce+ with your existing database type, and optionally on PostgreSQL.