Migrating WebSphere Commerce search from Feature Pack 7 to Feature Pack 8

To migrate from Feature Pack 7 REST-based search deployment to Feature Pack 8 REST-based model, follow this procedure.

In Feature Pack 7, WebSphere Commerce search introduced the REST-based search runtime programming model. It contained a new architecture, deployment strategy, and REST APIs to program against the search server. In Feature Pack 8, WebSphere Commerce search continues to use the new REST-based search runtime programming model.

When you migrate, WebSphere Commerce search updates the existing WebSphere Commerce search cores and configuration files to the latest version of WebSphere Commerce search. Your existing customizations are also considered during the migration steps to ensure that your latest version also contains your earlier changes to WebSphere Commerce search behavior.

Before you begin

If you want to publish a new starter store, you must migrate the WebSphere Commerce search server first, and then publish the new starter store after feature enablement.
Ensure that you complete the following tasks in your lower version of WebSphere Commerce:

About this task

During this task, you perform the following high-level steps:

Prepare your environment for migration by installing the new feature pack version and running the foundation enablement script.
Run the automated search index setup migration utility on all existing master catalog IDs.
Manually compare and copy customized WebSphere Commerce search configuration files into the new search version.
Populate and build the full search index data.
Secure the search server, if your previous version of WebSphere Commerce search had security enabled.
Set price ranges to index and display in starter stores by updating search properties in the component configuration file (wc-component.xml).
Reconfigure clustering and replication, if your previous search deployment is in a clustered environment.
Configure the JVM custom properties for the cluster members, so that the Solr multi-index reader can read resources that are located outside its instance.

During this task, you do not perform any steps to migrate the following areas, as they are automatically migrated:

Storefront features
Search rules

Procedure

Prepare your environment for migration.
1. Install the new feature pack version that you want to use on the WebSphere Commerce server.
2. If you did not enable the foundation feature on your latest feature pack that is installed, then enable foundation. Enabling foundation also enables WebSphere Commerce search. For more information, see Enabling WebSphere Commerce foundation.
3. If you did not enable the starter store enhancements feature on you latest feature pack that is installed, then enable starter store enhancements. For more information, see Enable the starter store enhancements feature.
4. Restart the WebSphere Commerce application server.

Run the search index setup migration utility.

Complete one of the following tasks:
- Log on as a WebSphere Commerce non-root user.
- Log on with a user ID that is a member of the Windows Administration group.
Ensure that your administrative server is started.
For example:
- If WebSphere Commerce is managed by WebSphere Application Server Deployment Manager (dmgr), start the deployment manager and all node agents. Your cluster can also be started.
- If WebSphere Commerce is not managed by WebSphere Application Server Deployment Manager (dmgr), start the WebSphere Application Server server1.
Ensure that the test server is stopped and that Rational Application Developer is not running.
Run the search index setup migration utility:
Important: If you have multiple master catalog IDs, for example, 10001 and 10002, you must migrate all of them separately. That is, if you migrate only 10001, but do not migrate 10002, Solr configuration errors occur when you build the search index.
1. Go to the following directory:
  - WC_installdir/components/foundation/subcomponents/search/bin
  - WCDE_installdir\components\foundation\subcomponents\search\bin
2. Run the search index setup migration utility:
  - migrateSolrSearch.bat -masterCatalogId masterCatalogId
  - migrateSolrSearch.bat -instance instance_name -masterCatalogId masterCatalogId -dbuser db_user -dbuserpwd db_password [-searchServerName searchServerName] [-searchServerPort searchServerPort] [-indexsubtype indexsubtype] [-dbauser dbauser] [-dbauserpwd dbauserpwd]
  - migrateSolrSearch.sh -instance instance_name -masterCatalogId masterCatalogId -dbuser db_user -dbuserpwd db_password [-searchServerName searchServerName] [-searchServerPort searchServerPort] [-indexsubtype indexsubtype] [-dbauser dbauser] [-dbauserpwd dbauserpwd]
  Where:
  instance_name
  
  The name of the WebSphere Commerce instance with which you are working (for example, demo).
  
  masterCatalogId
  
  The ID of the master catalog (for example, 10101).
  
  If you do not know the master catalog ID, run the following SQL:
  SQL: select * from catalog where IDENTIFIER='STORE_IDENTIFIER'
  
  dbuser
  
  The name of the user that is connecting to the database.
  
  The user ID connecting to the database.
  
  dbuserpwd
  
  The password for the user that is connecting to the database.
  
  solrhome
  
  The location of the Solr home directory path that contains the index data of Solr. The value must be an absolute path.
  
  The default value is:
  
  WCDE_installdir/search/solr/home
  
  WC_installdir/instances/instance_name/search/solr/home
  
  WC_instance_root/instances/instance_name/search/solr/home
  
  wasHome
  
  The installation path for WebSphere Application Server.
  
  searchServerName
  
  The search server host name. Required if the search server host name was changed from the default name before migration.
  
  searchServerPort
  
  The search server port. Required if the search server port was changed from the default port before migration.
  
  searchServiceContextRoot
  
  The search service context root. For the Solr related actions such as configSolrCores and configWCforSolr, the default value is /solr.
  
  indexsubtype
  
  Specify -indexsubtype Inventory if you set up the inventory index in an earlier feature pack version.
  
  If specified, the migrateSolrSearch script migrates the catalog entry, catalog group, unstructured, and inventory indexes for the master catalog at the same time.
  
  If not specified, the migrateSolrSearch script migrates the catalog entry, catalog group, and unstructured indexes by default.
  
  dbauser
  
  The name of the DBA user. This parameter is required with the dbauserpwd parameter if you set up workspaces in an earlier feature pack version.
  
  dbauserpwd
  
  The password of the DBA user. This parameter is required with the dbauser parameter if you set up workspaces in an earlier feature pack version.
Clean the test server.
1. Start Rational Application Developer.
2. Right-click the test server. Then, select Clean....

Ensure that the utility runs successfully by reviewing the log file to see the results of the migration. The log file is located is the location that is specified in the migrate-solr-search-logging.properties file.

By default, you can find the log at the following location:

WCDE_installdir\components\foundation\subcomponents\search\config\migrate-solr-search-logging.properties
WC_installdir/components/foundation/subcomponents/search/config/migrate-solr-search-logging.properties

If the utility did not run successfully, you can modify the logging configuration file as needed, specifically the logging level:

Logging configuration file parameters
Parameter	Value
Logging level	INFO The typical logging level to use for the utility. This level also lists all SQL statements that you can use to roll back the migration. FINEST This level lists all details as the utility runs. Use this level if you encounter errors or exceptions during the migration and you need additional information for troubleshooting.
Log file location	java.util.logging.FileHandler.pattern=../log/migrate-solr-search-logging.log

If you deployed the WebSphere Commerce search cluster, ensure that the EAR changes are propagated to all the nodes.

Compare and copy your customized search configuration files into the new search version.
1. If you customized the WebSphere Commerce search preprocessor configuration files:
  1. Go to the following directory:
    - WC_installdir/instances/instance_name/search/pre-processConfig
    - WCDE_installdir\search\pre-processConfig
  2. Manually compare all the files in the MC_masterCatalogId.timestamp directory with the files in the MC_masterCatalogId directory.
  3. Identify all the changed files, and merge the specific Feature Pack 7 changes from the MC_masterCatalogId.timestamp directory to the files with the same names in the MC_masterCatalogId directory.
2. If you customized the default WebSphere Commerce search Solr configuration files:
  1. Go to the following directory:
    - WC_installdir/instances/instance_name/search/solr/home/MC_masterCatalogId/locale_name/indextype
    - WCDE_installdir\search\solr\home\MC_masterCatalogId\locale_name\indextype
  2. For each core, manually compare the solrconfig.xml, wc-data-config.xml, and schema.xml files in the conf.timestamp directory with the files in the conf directory.
  3. Identify all the changed files, and merge the specific previous Feature Pack changes from the conf.timestamp directory to the files with the same names in the conf directory.
Populate and build the full search index data:
1. Complete the following task: Preprocessing the WebSphere Commerce search index data
  Important: You must preprocess both the CatalogEntry index and the CatalogGroup index. That is, ensure that the full-path parameter includes the CatalogEntry index.
  Including CatalogEntry index in the full-path parameter processes the configuration files for both CatalogEntry and CatalogGroup by default.
  The directory that contains the configuration files for CatalogGroup is one level below the directory for CatalogEntry.
2. Restart the WebSphere Commerce search server, then complete the following task: Building the WebSphere Commerce search index.
  Important: You must build the catalog entry index when indexing WebSphere Commerce search. That is, at a minimum, the catalog entry index must be rebuilt when migrating WebSphere Commerce search. That is, ensure that the indextype parameter includes the CatalogEntry index.
  If you do not use the indextype parameter, both the CatalogEntry and CatalogGroup indexes are built by default.
  If the index build fails with multiple languages due to OutOfMemoryError issues, you must increase the search server heap size. For example, increase it to 2 GB. For more information, see Troubleshooting: Out of memory error from building the search index with multiple languages.
If your previous version of WebSphere Commerce search had security enabled, complete the following task: Securing the WebSphere Commerce search server. This ensures that the WebSphere Commerce search server is secured after migration.
Set price ranges to index and display in starter stores:
- Set the Search profiles global defaults property for SearchProfilesPrice to mixed mode (2) in the wc-component.xml file. For more information, see Search properties in the component configuration file (wc-component.xml) (Search EAR).
If your previous search deployment is in a clustered environment:
1. Copy the WC_installdir/components/foundation/subcomponents/search/solr/home/replication-config.xml file to WC_installdir/instances/instance_name/search/solr/home. Then, edit the file to match your master machine and subordinate machine configurations.
2. Manually copy the Solr home directory from the first WebSphere Commerce search application server that is running the search index setup migration utility to all clustered servers. The default Solr home is in the following location:
  - working_dir/search/instance_name/search/solr/home
3. Reconfigure WebSphere Commerce search for replication.
4. Restart your WebSphere Commerce search cluster and WebSphere Commerce cluster.
Configure the JVM custom properties for the cluster members.
This step enables the solr.allow.unsafe.resourceloading flag, which is required for the Solr multi-index reader to read resources that are located outside its instance.
1. Log on to the WebSphere Application Server administrative console for the DMGR profile of the search cluster.
2. Go to Servers > Clusters > WebSphere application server clusters.
3. Click the cluster that you created in this task.
4. Under Additional Properties, click cluster members. All the servers in the current cluster are listed.
5. Set the following JVM custom properties for each server:
  1. Click the server name.
  2. Under Server Infrastructure, go to Java and Process Management > Process Definitions.
  3. Under Additional Properties, click Java Virtual Machine.
  4. Under Additional Properties, click Custom Properties.
  5. Click New and set the following values:
    Custom properties
    
    Name Value
    
    solr.allow.unsafe.resourceloading true
    
    By default, the resource loader does not load files from external servers for security reasons.
  6. Click Apply.
6. Save your changes to the master configuration and ensure that all nodes are synchronized.

Custom properties
Name	Value
`solr.allow.unsafe.resourceloading`	`true`

What to do next

After you complete the migration steps, you can migrate WebSphere Commerce search customization assets. Then, publish a starter store and go to the storefront to confirm that WebSphere Commerce search is functioning correctly.