Migrating customized IBM Websphere Commerce Version 7 Feature Pack 6 web applications to Struts 2

You can migrate projects that used Struts 1.x to Struts 2. Many features can be translated directly using the strutsmigration.jar utility. For more complex projects, a comparison of Struts 1 and 2 features and APIs is provided.

About this task

Use the following procedure to convert Struts 1 projects to Struts 2.
Important: In HCL Commerce Version 9, Store preview is not supported for Struts 2 migrated Local stores.

Procedure

  1. Export the customized web application from previous version of development environment.
    1. Open the previous version of HCL Commerce Developer.
    2. Switch to the Enterprise Explorer.
    3. Right-click the web application that you want to migrate, and select Export > WAR file.
      A web archive (WAR) file is created.
  2. Copy the WAR file to your version 9 development environment.
  3. Create a backup copy of your version 9 web application.
  4. Import the WAR file into your workspace and overwrite the existing project.
  5. Using a file comparison application, determine the differences between your version web application and the version 9 web application. Manually merge the differences into your web application.
  6. Modify any custom web pages if they use EJB entity beans. See Migrating IBM Websphere Commerce Version 8 EJB entity beans to Java Persistence API.
  7. Migrate struts configuration files.
    1. Copy strutsmigration.jar to your development environment.
    2. Create a folder and copy struts-config-ext.xml and all of the customized struts configuration XML files from WCDE_installdir\workspace\web-application\WebContent\WEB-INF\
    3. Convert your Struts 1.x configuration files to version 2. Run the following Java 1.8 command: 
      java -jar strutsmigration.jar  struts2-package-name  struts-1-config-file-directory  struts2-config-file-directory
      where the web applications map to Struts 2 package names as follows:
      Web application Struts 2 package name
      Commerce Accelerator wcs-accelerator
      Organization Administration wcs-orgadmin
      Site Administration wcs-adminconsole
      Store wcs-stores
      For example:
      java -jar strutsmigration.jar  wcs-accelerator W:\accelerator-struts-custom\input\  W:\accelerator-struts-custom\output 
 java -jar strutsmigration.jar wcs-stores W:\store-struts-custom\input\ W:\store-struts-custom\output
    4. Copy the new converted Struts 2 configuration files to W:\WCDE_V9\workspace\{web application}\src.
    5. Check the Struts 2 configuration file in the web application project to ensure that all of the Struts configuration files are referenced in it. For example, for the Stores project, check to see whether you have any customized Struts configuration files besides struts-config-ext.xml in W:\WCDE_V9\workspace\Stores\src. Ensure that all such Struts configuration files are referenced in struts-store.xml using the syntax in the following example. 
      <include file="struts-wcs-accelerator-custom.xml"></include>
<include file="struts-wcs-stores-custom.xml"></include>
      The mapping between the web application and Struts 2 configuration file name is as follows:
      Web application Struts 2 configuration file
      Commerce Accelerator WCDE_installdir\workspace\CommerceAccelerator\src\struts-accelerator.xml
      Organization Administration WCDE_installdir\workspace\OrganizationAdministration\src\struts-orgadmin.xml
      Site Administration WCDE_installdir\workspace\OrganizationAdministration\src\struts-siteadmin.xml
      Store WCDE_installdir\workspace\Stores\src\struts-stores.xml
      Note: The included files are loaded in sequence. Ensure that custom files are included after default files. Add them before <include file="struts-wcs-accelerator-custom.xml"></include>.
  8. Manually merge the changes in your previous version of web application web.xml file into the file in HCL Commerce Version 9. If there are no customizations in web.xml, copy the web.xml from the backup you created in step 3 to \Stores\WebContent\WEB-INF\.
    CAUTION:
    • You cannot have actions and results in different child packages. This includes flows where you begin with a REST action, and are then forwarded to a JSP page. For example, the result of an error. The REST action and JSP page result must be in a single child/parent package.
    • Do not override the following settings:
      • Servlet-class settings.
        For example:
        <servlet-class>com.ibm.commerce.struts.v2.ECActionServlet</servlet-class>
      • Filters and filter mappings.
        For example:
        <filter>        
<filter-name>struts2</filter-name>        
<filter-class>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter</filter-class>                
...
</filter>
  9. (Optional) If you have the following configuration in Struts 1, modify the struts-wcs-xxx-custom.xml configuration file.
    1. Override the action parameters.
      In Struts 1, struts-config-ext.xml is merged automatically by the Struts Configuration Manager. In the following example, we add a new property "https" to an action.
      In the file struts-config.xml:
      <action path="/RequisitionListsView" type="com.ibm.commerce.struts.BaseAction"> 
<set-property property="credentialsAccepted" value="0:P"/> 
</action>
      In the file struts-config-ext.xml:
      <action path="/RequisitionListsView" type="com.ibm.commerce.struts.BaseAction"> 
<set-property property="https" value="0:1"/> 
</action>
      In runtime, the action will have two properties defined: https, and credentialsAccepted.

      In order to add new parameters in Struts 2, however, the complete action has to be defined in a child package. For example:

      In the file struts-wcs-xxx.xml:

      <action class="com.ibm.commerce.struts.v2.BaseAction" name="RequisitionListsView"> 
<param name="credentialsAccepted">0:P</param> 
</action>

      In the file struts-wcs-xxx-custom.xml:

      	<package extends="wcs-stores" name="wcs-stores-custom" namespace="/">
		... ...
		<action class="com.ibm.commerce.struts.v2.BaseAction" name="RequisitionListsView">
           		<param name="https">0:1</param>
			<param name="credentialsAccepted">0:P</param>
        	</action>
	</package >
    2. Add a new forward (result).
      In Struts 1, the global-forward in struts-config-ext.xml is merged automatically by the Struts Configuration Manager. For example,
      In the file struts-config.xml:
      <action parameter="com.ibm.commerce.catalog.commands.TopCategoriesDisplayCmd" path="/TopCategoriesDisplay" type="com.ibm.commerce.struts.BaseAction">
 ... ...
</action>
      In the file struts-config-ext.xml:
      	<action parameter="com.ibm.commerce.catalog.commands.TopCategoriesDisplayCmd" path="/TopCategoriesDisplay" type="com.ibm.commerce.struts.BaseAction">
            	... ...
        </action>
	
In file struts-config-ext.xml
	<global-forwards>
		<forward className="com.ibm.commerce.struts.ECActionForward" name="TopCategoriesDisplayView/10001" path="/ShoppingArea/CatalogSection/CategorySubsection/TopCategoriesDisplay.jsp"/>
		<forward className="com.ibm.commerce.struts.ECActionForward" name="TopCategoriesDisplayView/10002" path="/ShoppingArea/CatalogSection/CategorySubsection/TopCategoriesDisplay.jsp"/>
	</global-forwards>
		… …

	<action parameter="com.ibm.commerce.catalog.commands.TopCategoriesDisplayCmd" path="/TopCategoriesDisplay" type="com.ibm.commerce.struts.BaseAction">
            	... ...
        </action>

      In runtime, two forwards, TopCategoriesDisplayView/10001 and TopCategoriesDisplayView/10001 are available to the action TopCategoriesDisplay.

      To add a new global result to Struts 2, and make it available to default actions, the actions have to be defined in a child package.

      In the file struts-wcs-xxx.xml:
          	<package extends="struts-default" name="wcs-stores" namespace="/">
			… … 
		<action class="com.ibm.commerce.struts.v2.BaseAction" name="TopCategoriesDisplay">
            		... ...
        	</action>
	<package
      In the file struts-wcs-xxx-custom.xml:
      	 <package extends="wcs-stores" name="wcs-stores-custom" namespace="/">
		<global-results>
           		<result name="TopCategoriesDisplayView/10001">
                				... ...
            		</result>
			<result name="TopCategoriesDisplayView/10002">
                				... ...
            		</result>
		</global-results>
		<action class="com.ibm.commerce.struts.v2.BaseAction" name="TopCategoriesDisplay">
            					... ...
        	</action>
	</package >
      Important: The store ID in your production environment might differ from your previous installation. Ensure that the store ID referenced in this file matches your environment before you deploy it.
  10. Compile and deploy your project.

What to do next

If you are using the verification codes feature, do the following:
  1. Open the file Stores/src/ComponentPlugins.xml in an editor.
  2. Add the following plugin to the file.
     <ComponentPlugins> 
...
<plug-in className="com.ibm.commerce.struts.v2.VerificationCodePlugInImpl" 
storeId="0" 
verCodeValidationClassName="com.ibm.commerce.verification.ChinaStoreVerificationCodeValidation"/>
The default storeId is 0. This value means that verification codes with be enabled for all stores. You can specify individual stores with this parameter to enable verification for those stores only.