Deprecated feature

Separating the store WAR from the WebSphere Commerce EAR

You can separate the store web application archive (WAR) file from the WebSphere Commerce enterprise archive (EAR) file to make developing and updating storefront assets easier. You can separate the store WAR for your WebSphere Commerce instance by running an enablement script and updating the WebSphere Commerce database. When the store separation process completes, a new store EAR is created that contains an copy of the store WAR. The original store WAR within the WebSphere Commerce EAR is disabled. With this separation, the storefront assets for your WebSphere Commerce instance are included either within the store EAR or the WebSphere Commerce EAR and referenced by the store EAR through a shared library.

Note: If your site uses a clustered environment or you are planning to use a clustered environment, you can separate the store WAR from the WebSphere Commerce EAR for this environment. There are two options for enabling this separation for a clustered environment:

Before you begin

Ensure that you complete following tasks:
Note: There are no disablement scripts for store separation. If you want to roll back the separation of the store archive for a WebSphere Commerce instance, you must manually restore your WebSphere Commerce instance.

Procedure

Run the store separation enablement script
  1. Start the WebSphere Commerce server.
  2. In a command-line utility, go to the following directory:
    • SolarisLinuxAIXFor IBM i OS operating systemWC_installdir/bin
    • WindowsWC_installdir\bin
  3. Run the following command to run the store separation enablement script.
    • SolarisLinuxAIXFor IBM i OS operating systemconfig_ant.sh -buildfile WC_installdir/components/common/xml/enableFeature.xml -DinstanceName=instance_name -DfeatureName=store-separation -DdbUserPassword=db_password [-DdbaPassword=administrative_password]
    • Windowsconfig_ant.bat -buildfile WC_installdir\components\common\xml\enableFeature.xml -DinstanceName=instance_name -DfeatureName=store-separation -DdbUserPassword=db_password [-DdbaPassword=administrative_password]
    Where the administrative_password is mandatory only when you are enabling store separation on an authoring environment. The administrative_password is not needed in a hosted environment that is not configured for authoring.
    When you run the store separation enablement script, the enablement process completes the following tasks to separate the store WAR from the WebSphere Commerce EAR:
    • Build a new store EAR by exporting a copy of the store WAR from the WebSphere Commerce EAR.
    • Disable the original store WAR within the WebSphere Commerce EAR.
    • Deploy the new store EAR with the same context root as the original store WAR. By default, the context root is /webapp/wcs/stores.
      Note: If your store uses a different context root than the default /webapp/wcs/stores root, change the generated context root to match the context root for your store. You can change the generated context root for the new store EAR after you enable the store archive separation.
    • Configures two shared libraries. The class path definition of the shared library is on a directory level. One library is for the default WebSphere Commerce directories and assets, and one library is for custom directories and assets.
    • Creates a server level extension class loader for use with the configured shared libraries.
    • Associates the shared libraries with the custom class loader.
    • Updates utilities to use the SharedLibWASEARUpdater EAR updater. By using this EAR updater, utilities such as file upload and quick publish can be configured to add store assets into the new store EAR and the shared library instead of into only the WebSphere Commerce EAR.
  4. Verify that the store separation enablement script ran successfully. After enablement process completes, ensure that the BUILD SUCCESSFUL message displays within the console.
    1. In a file manager, go to the following directory:
      • SolarisLinuxAIXFor IBM i OS operating systemWC_installdir/instances/instance_name/logs
      • WindowsWC_installdir\instances\instance_name\logs
    2. Open the enablestore-separation_timestamp.log file. Ensure that the BUILD SUCCESSFUL message displays within the log file.
    3. Go to the following directory:
      • SolarisLinuxAIXFor IBM i OS operating systemWAS_installdir/profiles/instance_name/installedApps/WC_instance_name_cell
      • WindowsWAS_installdir\profiles\instance_name\installedApps\WC_instance_name_cell
    4. Ensure that new store EAR, WCStores_instance_name.ear, displays within the WC_instance_name_cell directory.
Configure the web server and WebSphere Commerce search to use the new store archive.
  1. Regenerate the WebSphere Application Server web server plug-in configuration file.
  2. Optional: If your web server is remote and the plugin-cfg.xml file is changed, Copy the new generated plugin-cfg.xml file to your remote web server.
  3. Optional: If your web server runs on a separate node than the WebSphere Commerce node, copy your store web assets to the separate web server node.
    1. On the WebSphere Commerce node, go to the WAS_installdir\profiles\instance_name\installedApps\WC_instance_name_cell\Stores_war.ear\Stores.war directory:
    2. Copy the store assets within the Stores.war directory.
    3. On the web server node, go to the WAS_installdir\profiles\instance_name\installedApps\WC_instance_name_cell\Stores_war.ear\Stores.war directory
    4. Add the copied store assets into this directory on your web server node.
  4. Update the configuration file for the web server to map the WebSphere Commerce store alias to the store WAR within the new store EAR web module mapping:
    • IBM HTTP Server
      1. Go to the following directory:
        • SolarisLinuxAIXFor IBM i OS operating systemWC_installdir/instance/instance_name/httpconf
        • WindowsWC_installdir\instance\instance_name\httpconf
      2. Open the httpd.conf configuration file for editing.
      3. Locate the wcsstore alias mapping in the file:
        Alias/wcsstore	"WAS_installdir/profiles/demo/installedApps/WC_instance_name_cell/WC_instance_name.ear/Stores.war"
        Change the value for the wcsstore alias to be the path to the new store WAR location. For example:
        Alias/wcsstore "WAS_installdir/profiles/demo/installedApps/WC_instance_name_cell/WCStores_instance_name.ear/Stores.war"
    • Sun ONE web server
      1. Locate and open the obj.conf web server configuration file for editing.
      2. Locate the following code:
        NameTrans fn="pfx2dir" from="/wcsstore" dir="WAS_installdir/profiles/instance_name/installedApps/
        WC_instance_name_cell/WC_instance_name.ear/Stores.war"
      3. Update the configuration to map to the new store WAR location:
        NameTrans fn="pfx2dir" from="/wcsstore" dir="WAS_installdir/profiles/instance_name/installedApps/
        WC_instance_name_cell/WCStores_instance_name.ear\Stores.war "
    • WindowsInternet Information Services (IIS) Manager web server
      In the IIS Manager, change the value for the physical path to the WebSphere Commerce store, wcsstore, from the following path:
      WAS_installdir\profiles\instance_name\installedApps\WC_instance_name_cell\WC_instance_name.ear\Stores.war"
      To be the path to the new store WAR location. For example:
      WAS_installdir\profiles\instance_name\installedApps\WC_instance_name_cell\WCStores_instance_name.ear\Stores.war
  5. Update the SRCHCONFEXT table to ensure that the web content index points to the new store WAR location.
    1. Open a connection to the WebSphere Commerce database.
    2. Run the following SQL statement:
      select config from srchconfext where indexsubtype='WebContent';
      The results that return can resemble the following values:
      SearchServerName=commerce.wttedns01.usri.ibm.com,BasePath=WAS_installdir\profiles\instance_name\installedApps\
      WC_instance_name_cell\WC_instance_name.ear\Stores.war\Aurora\StaticContent\en_US\,SearchServerPort=3737,StoreId=10101 
      The instance_name\profiles\instance_name\installedApps\WC_instance_name_cell\WC_instance_name.ear\Stores.war path is the original location for the Stores.war archive.
    3. Update the path to the Stores.war archive by running the following SQL statement:
      update srchconfext set config='SearchServerName=commerce.wttedns01.usri.ibm.com,BasePath=WAS_installdir\profiles\
      instance_name\installedApps\WC_instance_name_cell\WCStores_instance_name.ear\Stores.war\
      Aurora\StaticContent\en_US\,SearchServerPort=3737,StoreId=10101' where INDEXSUBTYPE='WebContent'
  6. Restart the WebSphere Application Server.
    By restarting the server, you ensure that the new store EAR does not reference any invalid Enterprise JavaBeans (EJB) references.
  7. Restart the web Server.
Deploy the customization code for the store separation. The customization code is divided into two parts, server side and store side code.
  1. Deploy any server-side customization code to the WebSphere Commerce EAR.
    1. Group all customized EJBs, access beans, data beans, command interfaces, and utilities into JAR files.
    2. Deploy the JAR files into the WebSphere Commerce EAR.
    3. Optional: If a JAR file that you are deploying exists within a file path that is not defined as a part of the shared library configuration, add the JAR files to the custom shared library configuration.
      If your assets are included within a path that configured for the shared library, you do not need to update your shared library configuration. Any new JAR files that you deploy within a configured path for the shared library can automatically be referenced by the shared library.

      By adding the JAR file, the assets in the new store EAR can reference the assets within this WebSphere Commerce EAR JAR file. By default, the custom library is named Customer_shared_lib. Since this shared library is defined at the directories level, any custom JAR files within a folder that is defined in the Shared_lib, does not need to be added into the Customer_shared_lib configuration. If the JAR file exists within a file path that is not a part of the Shared_lib, you must add the JAR file into your Customer_shared_lib configuration. You can update your shared library, Customer_shared_lib by including the JAR file in the class path within the configuration tab for the shared library properties in the WebSphere Application Server Admin Console.

  2. Deploy any store side customization code, such as JSP files and storefront property files into the new store EAR.
  3. Apply any database schema changes from customization directly to the WebSphere Commerce database.

Results

The store WAR for your WebSphere Commerce instance is separated from the WebSphere Commerce EAR. You can deploy any future changes into the appropriate EAR without affecting the other EAR.

What to do next

After you separate the store WAR, update any store functions and processes that use assets that were included within the default store WAR. Update these functions and processes to point to the new location of the store assets in the store EAR.

When your store developers create or change store assets, the assets can be deployed into the new store EAR with the WebSphere Commerce Build and Deployment tool. For more information, see Deploying new and changed store assets into a separated store EAR.