Enabling WebSphere Commerce foundation

The WebSphere Commerce foundation feature adds new groups of services to the WebSphere Commerce Server.

The enablement script adds new services and updates the existing services that are required to support feature pack features.

If you are using a self-signed certificate (dummy certificate) in the staging or authoring environment, you might encounter SSL handshake exceptions in store preview after you apply Fix Pack 9. The exceptions occur only if you applied Fix Pack 9 using one of the following methods:

You first applied Fix Pack 9, then created an instance, and then enabled foundation on Feature Pack 7 or earlier
You first created an instance, then applied Fix Pack 9, and then enabled foundation on Feature Pack 8

To fix the SSL handshake issue, see Troubleshooting: SSL handshake exception in store preview

To enable the WebSphere Commerce foundation for Feature Pack 7 or later, see Enabling WebSphere Commerce foundation.

Introduced in Feature Pack 2 Enabling WebSphere Commerce foundation enables WebSphere Commerce search by default. WebSphere Commerce search is a core runtime component in WebSphere Commerce, with many features tightly integrated with the search component. For more information about WebSphere Commerce search dependencies, see Integrating WebSphere Commerce with third-party search engines.

Before you begin

Ensure that you are logged on as the WebSphere Commerce non-root user.
Ensure that you are logged on as a user that has *SECOFR authority.
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.
Review the prerequisite steps in Enabling features.
Ensure that the test server is stopped and that Rational Application Developer is not running.
If you use a staging server, you must ensure that your production server and staging server stay synchronized. To keep them in sync, you must perform the following steps before you enable the feature on the staging server:
1. Optional: It is recommended that you run the stagingprop utility:
  To ensure that stagingprop is run successfully:
  1. Check the stagingprop log file.
  2. Check the STAGLOG table in the staging database and confirm that no unprocessed records exist. An unprocessed STAGLOG record is a record in which the STGPROCESSED column has a value of 0.
2. Stop all activities on the staging server. Any data changes on the staging server are not captured or propagated from this point until feature enablement is completed.
3. Issue the following SQL statement and make note of the number of the latest record in the STAGLOG table in the staging database
```
SELECT MAX(STGRFNBR) FROM STAGLOG
```
If you use a staging server, you must conduct more steps at the end of the procedure to enable the feature. Ensure that you first enable your feature on the staging server, then on the production server.
Determine how you are going to deploy the WebSphere Commerce search server:
- Deploying the WebSphere Commerce search server locally in the standard configuration, or
- Deploying the WebSphere Commerce search server remotely in the advanced configuration

Procedure

Log on with appropriate authority:
- A WebSphere Commerce non-root user.
- A user ID that is a member of the Windows Administration group.
- A user profile that has *SECOFR authority.
Go to the following directory:
- WC_installdir/bin
- WCDE_installdir\bin
If you encounter a file error message, as the WebSphere Commerce non-root user, increase the file handle limit.
- Increase the file handle limit with the command: ulimit -n 8192
- As the root user grant USE authority to the non-root user. Switch to the non-root user and issue the command: ulimit -n 8192. You can also issue the command as the root user, then switch to the non-root user.
Run the enablement script:
- ```
config_ant.bat -buildfile WC_installdir/components/common/xml/enableFeature.xml 
-DinstanceName=instance_name -DfeatureName=foundation -DdbUserPassword=db_password [-DdbaPassword=dba_password] 
[-DSolrWASAdminUser = solr_wasadminuser] [-DSolrWASAdminPassword = solr_wasadminpassword] 
[-Dscchost=HostForScheduledJobs] [search_server_config] 
[-DsearchPort=searchPort]
```
- ```
./config_ant.sh -buildfile WC_installdir/components/common/xml/enableFeature.xml 
-DinstanceName=instance_name -DfeatureName=foundation -DdbUserPassword=db_password [-DdbaPassword=dba_password] 
[-DSolrWASAdminUser = solr_wasadminuser] [-DSolrWASAdminPassword = solr_wasadminpassword] 
[-Dscchost=HostForScheduledJobs] [search_server_config] 
[-DsearchPort=searchPort]
```
- ```
./config_ant.sh -buildfile WC_installdir/components/common/xml/enableFeature.xml 
-DinstanceName=instance_name -DfeatureName=foundation -DdbUserPassword=db_password  
[-DSolrWASAdminUser = solr_wasadminuser] [-DSolrWASAdminPassword = solr_wasadminpassword] 
[-Dscchost=HostForScheduledJobs] [search_server_config] 
[-DsearchPort=searchPort]
```
- enableFeature.bat -DfeatureName=foundation [-DdbaPassword=dba_password]
Where:
instanceName

The name of the WebSphere Commerce instance with which you are working (for example, demo).

featureName

The name of the WebSphere Commerce feature to enable (for example, foundation).

dbUserPassword

The password for the user who is connecting to the database.

dbaPassword

The dbaPassword is mandatory when you are enabling the feature on an Authoring server.

SolrWASAdminUser
The WebSphere Application Server administrator user ID for the Solr cell. This parameter is mandatory only if all three of the following conditions are met:

You enabled a previous version of Search from an earlier WebSphere Commerce feature pack

You enabled WebSphere Administration Server administrative security on the Search server

You are not specifying remoteSearchEngine=true
SolrWASAdminPassword
The WebSphere Application Server administrator password for the Solr cell. This parameter is mandatory only if all three of the following conditions are met:

You enabled a previous version of Search from an earlier WebSphere Commerce feature pack

You enabled WebSphere Administration Server administrative security on the Search server

You are not specifying remoteSearchEngine=true
scchost

The name of the host (server) on which the scheduled job runs. Use this parameter if your organization chooses to schedule jobs to run only on a specific host.
The WebSphere Commerce scheduler runs the RefreshRegistry command to ensure that the latest data from the CMDREG table is used by the WebSphere Commerce CommandRegistry. The job runs only if the CMDREG table was modified. It runs only once, shortly after enablement is completed. By default, this scheduled job run is set to run on any host. If you want to run on a specific host, use this parameter to define the specific host.
Note: The search server is deployed when the foundation feature is enabled.

remoteSearchEngine

Use this parameter with a value of true when you are deploying Solr search server on a remote machine.
Important: The remote web server is created under a different node than the local WebSphere Commerce server. If you are using the Deployment Manager (DMGR) to federate WebSphere Commerce, you must also federate the remote search server node that contains the web server definition.
The search_server_config options help automate updating the web server configuration for IBM HTTP Server. If you do not use this option, you must manually configure your web server after you run the enablement script, as described in the next step. When the search_server_config options are used, WebSphere Commerce search helps automate creating the web server configuration. This automation is achieved by passing in more configuration parameters when you run the enablement scripts.
Important: The automated web server configuration supports IBM HTTP Server (IHS) only. That is, it does not support or include steps for configuring non-IHS web servers such as IIS and SunOne. For other types of web servers, consult the documentation that is provided by the web server vendor to update the configuration.
This approach includes the following considerations:
- The WebSphere Commerce search web server's httpd.conf file is automatically created.
- You can set up a valid configuration where the WebSphere Commerce search and WebSphere Commerce web servers have separate configuration files. That is, you do not need to manually update the plugin-cfg.xml files.
- If preferred, you do not need to install another copy of IBM HTTP Server. The same installation can be shared with the WebSphere Commerce web server.
  A second IHS process is started to handle search HTTP requests that use the same IHS installation. A second process ensures that the configurations do not collide, while it eases configuration and maintenance.
Important: You can skip updating the web server configuration if you previously enabled the feature foundation and passed in the search_server_config parameters during the enablement. You can also skip the update if your Solr web server is already configured.
The following list shows the available parameters with brief explanations of each. Examples can be seen in the following task, along with more-detailed descriptions of each parameter and when it is needed and not needed:
- ../../com.ibm.commerce.developer.doc/tasks/tsdsearchwebserver.html
The scripts validate the values that are provided for any mandatory parameters. If values for mandatory parameters are blank, the scripts do not proceed. The error message indicates which values must be specified. An example of such an error can be viewed in the following troubleshooting reference:
- Troubleshooting: Ant properties error occurs during feature enablement
Where search_server_config includes the following parameters that help automate updating the web server configuration for IBM HTTP Server:
searchPort

The WebSphere Application Server virtual host port number to listen on for the WebSphere Commerce search application.

The value must be a valid and available TCP port.

The default value is 3737.
If the script runs successfully:
- The message BUILD SUCCESSFUL is displayed in the console and in the WC_installdir/instances/instance_name/logs/enablefoundation_timestamp.log file. For more information, open the file and review the contents.
- The message BUILD SUCCESSFUL is displayed in the console and in the WC_instance_root/instances/instance_name/logs/enablefoundation_timestamp.log file. For more information, open the file and review the contents.
- The message enableFeature.bat completed is displayed in the command window. For more information, see the WCDE_installdir\logs\enableFeature.log file.
Configure the Web server for the Solr application
The following configuration options are available, depending on your web server and WebSphere Commerce Feature Pack version:
- WebSphere Commerce search deployment tasks include steps to manually update the web server configuration for IBM HTTP Server (IHS).
  This approach includes the following considerations:
  
  You created the WebSphere Commerce search web server httpd.conf file.
  
  A directive to listen on the search virtual host port is added.
  
  The web server plug-in is installed on the web server host.
- WebSphere Commerce search deployment tasks include steps to help automate updating the web server configuration when you use IBM HTTP Server (IHS). This automation is achieved by optionally passing in more configuration parameters when you are running the enablement scripts during the previous step. For more information, see the previous step.
- For configuring non-IHS web servers such as IIS and SunOne, consult the provided documentation to update the configuration.
If the server is configured with an LDAP server, restart your WebSphere Commerce Server after you verify a successful enablement.
Republish the application:
1. Open WebSphere Commerce Developer and switch to the Enterprise Explorer view.
2. Right click LOBTools and select OpenLaszlo Migration > Compare Customizations.
3. Rebuild any projects that need to be rebuilt in the workspace.
  For example:
  - Rebuild LOBTools. Right-click LOBTools, then select Build OpenLazlo Project
4. Start the WebSphere Commerce Test Server.
  Some errors are displayed in the console. These errors can be safely ignored.
5. In the Servers view, right-click the test server then click Publish.
6. Wait for the application to finish publishing and to restart. Ensure that no errors are displayed.
7. If you customized a previous version of Management Center, see Migrating Management Center to migrate those customizations to the most recent Management Center version.
Verify that the application starts successfully.
1. Access the following URL: http://hostname:8007/webapp/wcs/component/member/services/MemberServices
  The following page is displayed:
```
{http://www.ibm.com/xmlns/prod/commerce/9/member}MemberServices
Hi there, this is a Web service!
```
If the server where you are installing the feature uses staging tools or is a staging server, complete the following steps:
Note:
- This step is not applicable for WebSphere Commerce Developer.
- This step does not apply if you set the stagingcopy utility -instance parameter.
- Perform these steps once, even if you enable and disable the feature multiple times.
- These steps must be performed cumulatively up to the most recently installed feature pack. In the following examples, fep<n> represents the feature pack. Applicable feature packs are fep1, fep2, fep3, fep4, and fep5.
- These steps are applicable to all components. In the following examples, comp represents the component. Applicable components are foundation and location-services.
- In the following steps, dbtype represents the database-type in use. Applicable database-types are db2, oracle, and os/400.
1. Back up the following base-staging SQL files:
  - WC_installdir/schema/dbtype/wcs.stage.trigger.sql
  - WC_installdir/schema/dbtype/wcs.droptrigger.sql
  Where dbtype is your database type. For example, oracle or db2.
2. Append the contents of WC_installdir/components/component_name/schema/fep<n>/dbtype/wcs.stage.trigger.component_name.sql to the end of WC_installdir/schema/dbtype/wcs.stage.trigger.sql.
  Where
  - component_name is the name of the component that you are backing up. For example, foundation.
  - fep<n> is the Feature Pack version of your WebSphere Commerce instance. For example, fep2.
  - dbtype is your database type. For example, oracle or db2.
3. Append the contents of WC_installdir/components/component_name/schema/fep<n>/dbtype/wcs.stage.trigger.component_name.drop.sql to the end of WC_installdir/schema/dbtype/wcs.droptrigger.sql.
  Where
  - component_name is the name of the component that you are backing up. For example, foundation.
  - fep<n> is the Feature Pack version of your WebSphere Commerce instance. For example, fep2.
  - dbtype is your database type. For example, oracle or db2.
  Note: By default, all staging triggers for the PX_CDPOOL database table are dropped and re-created. Ensure that you do not drop the triggers for this table twice in the wcs.droptrigger.sql file. Replace the triggers that were introduced in WebSphere Commerce Feature Pack 1 with the Feature Pack 6 version of these triggers that are included in the wcs.stage.trigger.sql file. This replacement, can help ensure that you do not duplicate these triggers in your SQL files, which can cause a database error.

If you have both a staging and a production environment, you must conduct the following steps:

Option Description

If you are enabling the feature on the staging server

Option	Description
If you are enabling the feature on the staging server	Mark all STAGLOG records inserted during feature pack enablement `UPDATE STAGLOG SET STGPROCESSED=1 where STGRFNBR > lastnum` where `lastnum` is the number of the last record, which was determined in the prerequisite steps required on the staging server. As the staging server database is updated during feature pack enablement, staging triggers are fired, and changes are captured in the STAGLOG table. If these captured changes are not cleaned up, duplicate-key exceptions occur on subsequent invocations of the stagingprop utility, since the production server database will have the same data after feature pack enablement is completed there. Return to Step 1 to enable the feature on the production server.
If you are enabling the feature on the production server	By default, Access Control Policy tables are not staged. If you manually add Access Control Policy tables to the Staging Configuration tables, you must run the stagingcopy utility to copy data from the Access Control Policy tables to corresponding tables on the staging server database. If you encounter problems with stagingcopy, complete the following steps: Update the STMTHEAP database configuration parameter for both staging and production server databases, `db`, to a higher value. For example: `db2 update database configuration for db using stmtheap 240000` Similarly, update the APPLHEAPSZ database configuration parameter for both staging and production server databases, `db`, to a higher value. For example: `db2 update database configuration for db using applheapsz 3000` Disconnect all users from both staging and production server databases. Run the stagingcopy utility.

Mark all STAGLOG records inserted during feature pack enablement
```
UPDATE STAGLOG SET STGPROCESSED=1 where STGRFNBR > lastnum
```
where lastnum is the number of the last record, which was determined in the prerequisite steps required on the staging server.
As the staging server database is updated during feature pack enablement, staging triggers are fired, and changes are captured in the STAGLOG table. If these captured changes are not cleaned up, duplicate-key exceptions occur on subsequent invocations of the stagingprop utility, since the production server database will have the same data after feature pack enablement is completed there.
Return to Step 1 to enable the feature on the production server.

If you are enabling the feature on the production server

By default, Access Control Policy tables are not staged. If you manually add Access Control Policy tables to the Staging Configuration tables, you must run the stagingcopy utility to copy data from the Access Control Policy tables to corresponding tables on the staging server database.

If you encounter problems with stagingcopy, complete the following steps:

Update the STMTHEAP database configuration parameter for both staging and production server databases, db, to a higher value. For example:
db2 update database configuration for db using stmtheap 240000
Similarly, update the APPLHEAPSZ database configuration parameter for both staging and production server databases, db, to a higher value. For example:
db2 update database configuration for db using applheapsz 3000
Disconnect all users from both staging and production server databases.
Run the stagingcopy utility.

What to do next

If you completed this procedure as a part of migrating WebSphere Commerce search, then continue with the migration process:

Otherwise, for more information about other features that you can enable, see First steps after enabling features.