IBM Support

Migrating WebFacing projects to V7.5.x or V8.0

Question & Answer


Question

How do I migrate my WebFacing project to version 7.5.x or 8.0?

Answer

This document describes how to migrate WebFacing projects to version 7.5.x or 8.0, and includes common problems and workarounds.
Important: WebFacing V7.5.x only supports migration of projects created in V6.0.x and higher, and WebFacing V8.0 only supports migration of projects created in V7.0.x and higher.


Preparing a project for WebFacing migration

You need to perform the following preparatory tasks before running the WebFacing Migration wizard.

  1. Make sure the latest updates and fixpacks for all Rational products are installed using the IBM Installation Manager. This step is very important as it will eliminate many problems you may run into. See Updating installed product packages, Updating the HATS Toolkit installation (V7.5.x), and Updating the HATS Toolkit installation (V8.0) for details.
  2. Make a backup of your projects. Migration cannot be reversed.
  3. Open your old workspace, or import your projects into a new one, and if prompted run the Rational Workspace Migration wizard. Refer to Migrating workspaces and projects from version 6.0.x or version 7.0.x and Migrating workspaces and projects from version 7.5.x or version 7.0.x for instructions.
    • Note: You can ignore the following dialogs if they appear after the Workspace Migration wizard has completed:
      • "Migration validation completed with some errors. See the Migration Results view for additional information." The Migration Results view highlights errors similar to: 'The WebSphere facet "WebSphere Web (Extended) 5.1" is not compatible with the WebSphere runtime "WebSphere Application Server vX.Y"'.
      • "Problem Occurred", with details "Error upgrading WebSphere facets to match the runtime. One or more constraints have not been satisfied. WebFacing 1.0 requires Dynamic Web Module 2.4 or newer. WebFacing 1.0 requires Struts 1.3." These errors will be resolved later in this document.
  4. Ensure that a valid server is selected on the Targeted Runtimes page. This is required if the server originally targeted is no longer supported.
    1. In the Navigator view, right-click your project and select Properties.
    2. Open the Targeted Runtimes page and select the server level where the project will be run.
    3. Click OK.
  5. If your project is at the J2EE 1.2 or J2EE 1.3 level, it needs to be migrated to 1.4 or higher using the Java EE migration wizard before WebFacing migration can proceed. Do not migrate to Java EE 5.0 unless you have RAD V7.5.4 or later, or RBD V7.5.1.4 or later installed. Refer to Migrating the specification level of Java EE projects.
    • Note: If you see a dialog titled "Inconsistent Files" during Java EE migration, click Yes to dismiss it. Similarly, if at the end of the wizard you see the message "Migration finished with errors", click the Details button. The following message can be safely disregarded: "Error: org.eclipse.core.runtime.CoreException: Runtime WebSphere Portal v6.0 stub does not support project facet WebFacing 1.0".
  6. Note: Skip this step if you are migrating to WebFacing 7.5.0.2 or later. If you are migrating a WebFacing Web or HATS/WebFacing Enabled project, after Java EE migration has been completed you need to manually change the Struts facet version from 1.1 to 1.3:
    1. In the Navigator view, right-click your project and select Properties.
    2. Open the Project Facets page and change the version of Struts to 1.3.
    3. Click OK.
  7. Resolve any classpath errors in your project.
    1. Open the Problems view (Window > Show View > Other > Problems).
    2. Check if there are any classpath or build errors reported, for example: "ClassName cannot be resolved [to a type]", "The project cannot be built until build path errors are resolved", or "Unbound classpath variable".
    3. Resolve any such errors as described in the following document: Problems migrating V5.1.2.x WebFacing projects to WDSC V7.0.0.8 or to HATS V7.1.0.x.


Running the WebFacing Migration wizard

Next, use the WebFacing Migration wizard to update your projects. You can no longer migrate projects by re-converting DDS files.
  1. To launch the WebFacing Migration Wizard, right-click your un-migrated project in the WebFacing Projects view and select Migrate WebFacing Project
  2. Click Finish to migrate the selected project.
  3. WebFacing V7.5.0.2 and later only: Click OK if a Results dialog appears notifying you that the Struts version of your project has been changed.
  4. After migration, it is recommended that you re-convert your DDS, especially if you plan to use the Firefox browser with your WebFacing applications.

Note: If the project being migrated is a HATS/WebFacing Enabled project, the corresponding HATS project also needs to be migrated. See Migrating to HATS V7.5 and Migrating to HATS V8.0 for details.



Known Problems and Solutions

The following list describes several known issues which may arise during migration and the workaround for each.

  • Java EE Migration Wizard changes WAS to WPS
    After running the Java EE migration wizard on a WebFacing Web project, the target runtime is incorrectly changed to a version of WebSphere Portal Server.

    This problem can be solved by applying the latest fixpacks to all your Rational products.
    Alternatively, do the following:
  1. In the Navigator view, right-click your project and select Properties.
  2. Open the Targeted Runtimes page and make sure all WebSphere Portal Server instances are deselected.
  3. Select the WAS version where the project will be run, then click OK.
  4. Open each of the following files, and if there are any lines containing "wps" or "portal", remove them. For example:
    • .settings\org.eclipse.wst.common.project.facet.core.xml
      <runtime name="wps.base.v60"/>
    • .settings\org.eclipse.jst.common.project.facet.core.prefs
      classpath.helper/org.eclipse.jst.server.core.container\:\:com.ibm.etools.portal.runtime.provider.v6\:\:wps.base.v60/owners=jst.web\:2.3
    • .classpath
      <classpathentry kind="con"
      path="org.eclipse.jst.server.core.container/com.ibm.etools.
      portal.runtime.provider.v6/wps.base.v60"/>

  • Java EE Specifications Migration Wizard finishes with errors for portlet projects created in V6.x or earlier
    During Java EE migration, errors are reported similar to "org.eclipse.core.runtime.CoreException: Runtime WebSphere Portal v6.0 does not support project facet JSR Portlets on WebSphere Portal 6.1" and "Setting of target server failed".
This problem can be solved by applying the latest fixpacks to all your Rational products.
Alternatively, edit the file <project>\org.eclipse.wst.common.project.facet.core.xml as follows:
  1. Remove the following lines:
    <fixed facet="jsr.base"/>
    <fixed facet="jsr.portal"/>
    <installed facet="jsr.base" version="1.0"/>
    <installed facet="jsr.portal" version="6.1"/>


  2. Insert these lines:
    <installed facet="ibmportlet.base" version="1.0"/>
    <installed facet="ibmportlet.struts" version="6.0"/>
    <installed facet="portlet.webfacing" version="1.0"/>


  • "This portlet is unavailable" error is displayed when trying to run a portlet project migrated from V6.x or earlier.

    This problem can be solved by applying the latest fixpacks to all your Rational products.

    Alternatively, create a new portlet project, and copy over the files wp.struts.tlds.common.jar, struts-legacy.jar, and wp.struts-commons-logging.jar from the WebContent\WEB-INF\lib directory to the same location in your original project.
  • Error 500 message appears when trying to run migrated project
    When trying to run a migrated project, an error message similar to the following is displayed: "Error 500: javax.servlet.jsp.JSPException: Missing message for key "index.closeAlert" in bundle "(default bundle)" for locale en_CA".

    This problem can be solved by applying the latest fixpacks to all your Rational products.

    Alternatively, to fix this problem:
  1. Open <project>\WebContent\WEB-INF\web.xml
  2. Click the Source tab.
  3. Make sure the <servlet> and <servlet-mapping> entries look like in the following example (they are usually at the bottom of the file). Make any necessary changes, then save the file.

    <servlet>
         <servlet-name>action</servlet-name>
         <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>
         <init-param>
              <param-name>config</param-name>
              <param-value>
                /WEB-INF/struts-config.xml, /WEB-INF/struts-wfinv.xml
             </param-value>

         </init-param>
         <init-param>
              <param-name>config/webfacing</param-name>
              <param-value>/WEB-INF/struts-wf.xml</param-value>
         </init-param>
         <init-param>
              <param-name>config/webfacing/services/invocation</param-name>
              <param-value>/WEB-INF/struts-wfinv.xml</param-value>
         </init-param>
         <init-param>
              <param-name>config/webfacing/services/report</param-name>
              <param-value>/WEB-INF/struts-wfreport.xml</param-value>
         </init-param>
         <init-param>
              <param-name>debug</param-name>
              <param-value>0</param-value>
         </init-param>
         <init-param>
              <param-name>detail</param-name>
              <param-value>0</param-value>
         </init-param>
         <init-param>
              <param-name>validate</param-name>
              <param-value>true</param-value>
         </init-param>
         <load-on-startup>2</load-on-startup>
    </servlet>

    <servlet-mapping>
         <servlet-name>action</servlet-name>
         <url-pattern>*.do</url-pattern>
    </servlet-mapping>

  • "Unbound classpath container: 'JRE System Library [JRE WebSphere vX.Y]' in project 'prj'" error appears in the Problems view for projects created in V7.0.x
    To workaround the error, specify a target runtime to either WebSphere Application Server V6.0 or V6.1.
    • In the Project Explorer view, right-click the project, select Properties > Targeted Runtimes, and under the Runtime list select one of the below server check box:
      • WebSphere Application Server v6.0
      • WebSphere Application Server v6.1
      • WebSphere Application Server v6.0 stub
      • WebSphere Application Server v6.1 stub
      Tip:  If none of the above server options are available under the Runtime list, click the New button to add a new server runtime that supports the specification-levels of the migrated projects.  Under the Runtime list, verify the WebSphere Application Server v6.0 or v6.1 check box is clear.  Click Apply and then select the WebSphere Application Server v6.0 or v6.1 check box under the Runtime list.
    • Click OK in the Targeted Runtimes page to apply the changes.

    • Note:  If the projects belong to an EAR module, then all Targeted Runtime changes done at the EAR project level will propagate to the child modules, such as the Web and EJB projects. If the projects do not belong to an EAR module, you must repeat this step for each migrated project.

  • "No start tag" errors appear in the Problems view
    These are incorrectly reported and will be resolved after WebFacing migration. For more details, see Unmigrated V5.1.2.x WebFacing projects cannot be published to the WebSphere 6.0 or 6.1 test server due to validation errors.

  • Build errors appear in the Problems view
    For details and a resolution of this problem, see Problems migrating V5.1.2.x WebFacing projects to WDSC V7.0.0.8 or to HATS V7.1.0.x.

[{"Product":{"code":"SSXKAY","label":"IBM Host Access Transformation Services"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Component":"WebFacing Tool","Platform":[{"code":"PF033","label":"Windows"}],"Version":"7.5;7.5.1;8.0","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]

Document Information

Modified date:
02 August 2018

UID

swg21383510