Setting up the WebSphere Commerce search index structure for a specific master catalog remotely

You can deploy your search index structure on your remote machine and configure WebSphere Commerce to use the Solr index by running the search index setup utility. This utility ensures that your index is built successfully by using your WebSphere Commerce master catalog data. It can be deployed on a separate WebSphere Application Server machine from WebSphere Commerce, or in a WebSphere Application Server cluster. This setup involves performing steps on both the WebSphere Commerce machine, and the remote machine.

Feature Pack 6 You can reset the search cores on the WebSphere Commerce and Solr machines by running the search index setup utility, after a search index has already been previously setup. For more information and usage, see the action parameter values defined in this task.

Feature Pack 7 or later To set up the search index in REST-based search deployment, see Setting up the WebSphere Commerce search index structure for a specific master catalog locally.

New feature for Feature Pack 8 To set up the search index in the managed configuration, see Setting up the WebSphere Commerce search index structure for a specific master catalog in the managed configuration.

Before you begin

Ensure that the test server is stopped and that Rational Application Developer is not running.
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 your server has one of the following feature packs installed to support WebSphere Commerce search:
- If your server is at the WebSphere Commerce Feature Pack 2 level, you can use this procedure to set up a catalog entry index for your master catalog.
- If your server is at the WebSphere Commerce Feature Pack 3 level, you can use this procedure to set up both a catalog entry index and a category index for your master catalog. You can set up both indexes at the same time by including multiple values for the indextype parameter (see steps 1.c and 2.c).
Ensure that you have completed the following task:
- Deploying the search server
  Note: You can skip setting up the search index structure (setupSearchIndex utility) on the repeater, as you can copy the Solr home directory from the master search server to the repeater. The default Solr home is in the following location:
  - working_dir/search/instance_name/search/solr/home
Ensure that the QEJBSVR user profile has WRITE authority for the following directory: QIBM/UserData/CommerceServer70/instances/instance_name/temp
Example
```
CHGAUT OBJ('/QIBM/UserData/CommerceServer70/instances/demo/temp') USER(QEJBSVR) DTAAUT(*RWX) SUBTREE(*ALL) SYMLNK(*NO)  
```

Procedure

Perform the following steps on your WebSphere Commerce machine:

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.
- Log on with a user profile that has *SECOFR authority.
Navigate to the following directory:
- WC_installdir\components\foundation\subcomponents\search\bin
Run the search index setup utility:
- setupSearchIndex.bat -instance instance_name -action action -masterCatalogId masterCatalogId -dbuser db_user -dbuserpwd db_password -searchServerName searchServerName -searchServerPort searchServerPort -searchServiceContextRoot searchServiceContextRoot [-indextype indextype] [-setupWebContent true | false] [-dbauser dba_user] [-dbauserpwd dba_userpwd] [-createAll true | false] [-indexsubtype indexsubtype] [-searchQueryServerName searchQueryServerName] [-searchQueryServerPort searchQueryServerPort]
- setupSearchIndex.sh -instance instance_name -action action -masterCatalogId masterCatalogId -dbuser db_user -dbuserpwd db_password -searchServerName searchServerName -searchServerPort searchServerPort -searchServiceContextRoot searchServiceContextRoot [-indextype indextype] [-setupWebContent true | false] [-dbauser dba_user] [-dbauserpwd dba_userpwd] [-createAll true | false] [-indexsubtype indexsubtype] [-searchQueryServerName searchQueryServerName] [-searchQueryServerPort searchQueryServerPort]
- setupSearchIndex.bat -setupMode remote -action action -masterCatalogId masterCatalogId -searchServerName searchServerName -searchServerPort searchServerPort -searchServiceContextRoot -searchServiceContextRoot [-indextype indextype] [-setupWebContent true | false] [-indexsubtype indexsubtype] [-searchQueryServerName searchQueryServerName] [-searchQueryServerPort searchQueryServerPort]
Where:

action

Prepares the search index on the Websphere Commerce machine. The following actions are supported:

configWCforSolr

Sets up search on the WebSphere Commerce machine when you are setting up the search index remotely.

configWCforReset

Resets search cores on the WebSphere Commerce machine, after a search index has already been previously setup.

When search cores are reset, all core-related information, such as XML configuration files and database information is deleted.
masterCatalogId
Required: 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'
To find the master catalog ID for an Extended Site store:

Find the store ID:
select * from storeent where IDENTIFIER='STORE_IDENTIFIER'

Use the storeent_id as the store_id in the following SQL to find the catalog asset store ID of this Extended Site store:
select * from storerel where store_id=XXXXXX and streltyp_id=-4 and relatedstore_id not in (XXXXXX)
Where XXXXXX is the storeent_id from the SQL in step 1.c.i when building the search index.

Get the master catalog ID:
select * from storecat where storeent_id=YYYYYY and mastercatalog='1'
Where YYYYYY is the relatedstore_id from step 1.c.ii when building the search index.
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.

indextype

Optional: Indicates the search engine index to set up. Valid values:

CatalogEntry

Sets up the index for catalog entries in the master catalog.

CatalogGroup

Sets up the index for categories in the master catalog.

If you do not use the indextype parameter, both the CatalogEntry and CatalogGroup indexes are built by default.

indexsubtype

Optional: Indicates the search engine index subtypes to set up. Valid values:

Inventory

Sets up the index for inventory data.

The inventory index supports only stores by using the non-ATP inventory system.
Important: When specified, the utility skips updating the wc-search.xml file. Therefore, you must first setup the master catalog index before setting up the inventory index.

searchServerName

This is the host name of the Solr web server, if Solr uses a web server. If Solr does not use a web server, set searchServerName to the host name of the Solr server.

searchServerPort

The search server port.
The default value is:

3737
searchServiceContextRoot

The search service context root. For the Solr related action such as configSolrCores and configWCforSolr, the default value is /solr.

setupWebContent

The flag that indicates whether to prepare the basepath and storeid for building the site content index. If false, the basepath and storeid are not added to the config column in the SRCHCONFEXT table. The default value is true.
Note: Exceptions might occur if your site contains a large number of extended sites and you run setupWebContent. To avoid this issue, enable autoIndex within the droidConfig.xml file. For more information, see Troubleshooting: Large number of extended sites causes exceptions when you set up the search index.

dbauser

The name of the DBA user.

This parameter is paired with the dbauserpwd parameter to create the workspace indexes. Otherwise, the workspace indexes are not created.

dbauserpwd

The password of the DBA user.

This parameter is paired with the dbauser parameter to create the workspace indexes. Otherwise, the workspace indexes are not created.

createAll

Indicates whether to create cores for all available workspaces, including non-allocated workspaces. Otherwise, cores are only created for allocated workspaces.

The default value is false, where cores are only created for allocated workspaces.

dbURL

¹ The database URL the utility uses to connect to the database. If not provided, the utility constructs a database URL based on the default database value.

searchQueryServerName

The name of the query server (workload balancer) when WebSphere Commerce search is setup in a clustered environment with a repeater.

If not specified, the SearchServerName value is used.

searchQueryServerPort

The port of the query server (workload balancer) when WebSphere Commerce search is setup in a clustered environment with a repeater.

If not specified, the SearchServerPort value is used.

Ensure that the utility runs successfully.

Consult the following table for the utility results:

Search setup utility results
Results	Description
Search index setup successfully completed without errors.	The utility ran successfully.
Search index setup successfully completed with warnings. Check the log file for more information.	The utility ran successfully but with warnings. Some warnings might be generated during the setup index process, however, they might not be important such as the utility skipping existing cores that have already been previously created.
Search index setup successfully completed with errors. Check the log file for more information.	The utility ran successfully but with errors. The job has not finished setup, and the log files should be checked to see where the problem occurred.
Search index setup not successful. An unrecoverable error has occurred. Check the log file for more information.	The utility did not run successfully. The log files should be checked to see where the problem occurred.

You can find the log file in the following location:

WC_installdir/components/foundation/subcomponents/search/log/wc-search-index-setup.log

You can get more logging information by updating the logging level from INFO to FINEST:


# Default global logging level, INFO
.level=FINEST

For more information about the log file, and to enable more logging details, see Enabling tracing and logging for WebSphere Commerce search.

Perform the following steps on your remote machine:

Complete one of the following tasks:
- Log on as a non-root user.
- Log on with a user ID that is a member of the Windows Administration group.
- Log on with a user profile that has *SECOFR authority.
Navigate to the following directory:
- working_dir/search/bin
Run the search index setup utility from the working_dir/search directory:
Note: You might encounter an error that resembles the following form if your remote machine does not contain a WebSphere Commerce installation:
```
/usr/bin/sh: bad interpreter: No such file or directory
```
To resolve this issue, you must manually create a symbolic link to the /bin/sh directory on your remote machine. This enables the remote machine to be aware of the shell location, and is otherwise performed automatically during a WebSphere Commerce installation.
- setupSearchIndex.bat -instance instance_name -setupMode remote -action action -masterCatalogId masterCatalogId -dbuser db_user -dbuserpwd db_password -wcServerName host_name -wcServerPort wcServerPort [-wasHome WAS_home] -solrhome solrhome [-dbserver dbserver] [-dbport dbport] [-dbtype dbtype] [-dbname dbname] [-indextype indextype] -dbauser dba_user -dbauserpwd dba_userpwd -createAll true | false [-indexsubtype indexsubtype]
- setupSearchIndex.sh -instance instance_name -setupMode remote -action action -masterCatalogId masterCatalogId -dbuser db_user -dbuserpwd db_password -wcServerName host_name -wcServerPort wcServerPort [-wasHome WAS_home] -solrhome solrhome [-dbserver dbserver] [-dbport dbport] [-dbtype dbtype] [-dbname dbname] [-indextype indextype] -dbauser dba_user -dbauserpwd dba_userpwd -createAll true | false [-indexsubtype indexsubtype]
- setupSearchIndex.bat -instance instance_name -setupMode remote -action action -masterCatalogId masterCatalogId -dbuser db_user -dbuserpwd db_password -wcServerName host_name -wcServerPort wcServerPort [-wasHome WAS_home] -solrhome solrhome [-dbserver dbserver] [-dbport dbport] [-dbtype dbtype] [-dbname dbname] [-indextype indextype] [-indexsubtype indexsubtype]
Where:

action

Prepares the search index on the remote Solr machine. The following actions are supported:

configSolrCores

Sets up the search cores on the Solr machine when you are setting up the search index remotely.

configSolrCoresReset

Resets search cores on the Solr machine.

When search cores are reset, all core-related information, such as XML configuration files and database information is deleted.

If masterCatalogId is set to all, all Solr cores are reset.
setupMode

Indicates the setup mode for the setup search index script. This is required when you are running the script on a remote machine, where the value is set as remote.

wcServerName

The WebSphere Commerce web server name (host_name).

wcServerPort

The WebSphere Commerce web server port. For example, 80.

WAS_home

The installation path for WebSphere Application Server.

Pass in this value to avoid missing Java version errors.

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
dbserver

The database server name to be connected.

dbport

The database port to be connected.

dbtype

The database type. For instance, Cloudscape, db2, or oracle.

dbname

The database name to be connected.

Ensure that the utility runs successfully.

Consult the following table for the utility results:

Search setup utility results
Results	Description
Search index setup successfully completed without errors.	The utility ran successfully.
Search index setup successfully completed with warnings. Check the log file for more information.	The utility ran successfully but with warnings. Some warnings might be generated during the setup index process, however, they might not be important such as the utility skipping existing cores that have already been previously created.
Search index setup successfully completed with errors. Check the log file for more information.	The utility ran successfully but with errors. The job has not completely finished setup, and the log files should be checked to see where the problem occurred.
Search index setup not successful. An unrecoverable error has occurred. Check the log file for more information.	The utility did not run successfully. The log files should be checked to see where the problem occurred.

You can find the log file in the following location: working_dir/search/config/logging.properties

You can get more logging information by updating the logging level from INFO to FINEST:


# Default global logging level, INFO
.level=FINEST

Restart the search server.
1. Navigate to the following directory:
  - WAS_installdir/profiles/Solr_profiledir/bin
  - WAS_installdir\profiles\Solr_profiledir\bin
  where Solr_profiledir is the directory created for the WebSphere Application Server profile that is used by a WebSphere Commerce search instance.
2. Stop the server.
  - ./stopServer.sh solrServer
  - stopServer.bat solrServer
3. Start the server.
  - ./startServer.sh solrServer
  - startServer.bat solrServer

What to do next

After setting up the search index structure for a specific master catalog, you must preprocess the search index data.

You must apply the interim fix for APAR #JR44514 to use this parameter.