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.
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.
- Install the new feature pack version that you want to use on the WebSphere Commerce server.
- 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.
- 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.
- 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.
- Go to the following directory:
- WC_installdir/components/foundation/subcomponents/search/bin
- WCDE_installdir\components\foundation\subcomponents\search\bin
- 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.
- Start Rational Application Developer.
- 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.
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.
- If you customized the WebSphere Commerce search preprocessor
configuration files:
- Go to the following directory:
- WC_installdir/instances/instance_name/search/pre-processConfig
- WCDE_installdir\search\pre-processConfig
- Manually compare all the files in the MC_masterCatalogId.timestamp directory
with the files in the MC_masterCatalogId directory.
- 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.
- If you customized the default WebSphere Commerce search
Solr configuration files:
- 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
- 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.
- 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:
- 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.
- 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:
- If your previous
search deployment is in a clustered environment:
- 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.
- 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
- Reconfigure
WebSphere Commerce search for replication.
- 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.
- Log on to the WebSphere Application Server administrative
console for the DMGR profile of the search cluster.
- Go to .
- Click the cluster that you created in this task.
- Under Additional Properties,
click cluster members. All the servers in the
current cluster are listed.
- Set the following JVM custom properties for each server:
- Click the server name.
- Under Server Infrastructure, go to .
- Under Additional Properties, click Java
Virtual Machine.
- Under Additional Properties, click Custom
Properties.
- 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.
- Click Apply.
- Save your changes to the master configuration and ensure
that all nodes are synchronized.
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.