Changing the portal URI after migrating to IBM WebSphere Portal versions 7.0 and later 

Introduction

We discuss two context roots in this article, the Portal context root and the themes context root. When WebSphere Portal is migrated to versions 7.0 and later, the Portal context root is changed during the process because the Portal migration must migrate the themes from the wps Enterprise Application and ensure that the WebSphere Portal will function as designed.

During the theme migration (which is a part of the Portal migration), the context root of the theme remains associated with the theme. If you decide to change the portal URI back to the original value, you must change the migrated Portal themes at this time because there will be a conflict between the portal and theme context roots, if they are the same.

Information on changing the portal URI can be found in the WebSphere Portal product documentation topic, “Changing the portal URI,” along with valuable information on such topics as Importing a theme and Deploying a theme.

We first provide an overview of the planned process, followed by the detailed steps to change the Portal URI, and conclude the article with general troubleshooting tips and recommendations.

Assumptions and recommendations

It is assumed that, prior to changing the Portal URI, WebSphere Portal has been successfully migrated, the environment has been backed up, and the context root has been modified to original-context-root_migrated; for example, wps_migrated, where wps is the original Portal context root. In our example, we use a standalone server with “wps” as the original Portal context root.

Changing the Portal context root after migration is not required, but it is recommended for users who want to revert the context root to the original value. If you choose to keep the modified Portal context root, WebSphere Portal will still function as designed.

For example, before migration, you would render Portal with http://hostname:10039/wps/portal. After migration it is changed to http://hostname:10039/wps_migrated/portal. If you leave the portal context root at wps_migrated, WebSphere Portal will work as designed.

Overview of the planned process

Here are the basic steps we will execute:

1. Follow the instructions in the “Changing the portal URI,” product documentation topic.
2. Use xmlaccess to change the migrated theme(s) context root.
3. Use the WebSphere Application Server (WAS) Console to change the migrated_themes Enterprise Application context root.
4. Verify the configuration.

Changing WebSphere Portal URI

Here are the steps from the WebSphere Portal product documentation for changing the Portal URI, with our case-specific annotations in italics:

1. Stop the WebSphere Portal server.
2. Locate the wkplc.properties and wkplc_comp.properties files in the wp_profile_root/ConfigEngine/properties directory and create backup copies before changing any values.
3. Use a text editor to open the wkplc.properties file and enter the appropriate value for your environment in the WpsContextRoot property. For this exercise, we set it from “wps_migrated”, back to “wps”.
4. Save and close the file.
5. Use a text editor to open the wkplc_comp.properties file and enter the appropriate value for your environment in the following properties:

WsrpContextRoot

WpsPersonalizedHome
WpsDefaultHome

NOTE: Do not use the same value for WpsPersonalizedHome and WpsDefaultHome.

Actually, this step is optional in the case of a migrated Portal, as the Portal migration does not alter these properties.

6. Save and close the file.
7. Start server1 in a standalone environment, or start the deployment manager and nodeagent in a clustered environment.
8. Open a command prompt and change to the wp_profile_root/ConfigEngine directory.

Perform the following steps to change the WebSphere Portal URI:

1. To change the context root for the values that you entered in the WpsContextRoot, WsrpContextRoot, WpsPersonalizedHome, and/or WpsDefaultHome properties, run the following task:

• UNIX: ./ConfigEngine.sh modify-servlet-path -DPortalAdminPwd=password -DWasPassword=password
• Windows: ConfigEngine.bat modify-servlet-path -DPortalAdminPwd=password -DWasPassword=password
• IBM i: ConfigEngine.sh modify-servlet-path -DPortalAdminPwd=password -DWasPassword=password

NOTE: Check the output for any error messages before proceeding with the next task. If any of the configuration tasks fail, verify the values in the wkplc.properties and wkplc_comp.properties files. An average time of completion is 10 minutes.

2. Restart the server1 and the WebSphere_Portal servers.

OPTIONAL: Perform the following steps if you also want to modify the context root for the portlets:

NOTE: The modify-servlet-path only modifies the Portal enterprise applications with the new context root. If you have a business requirement to have a consistent context root, including when portlets load, you should run the modify-servlet-path-portlets task as well. The modify-servlet-path-portlets task modifies the PA_* applications.

• UNIX: ./ConfigEngine.sh modify-servlet-path-portlets -DPortalAdminPwd=password -DWasPassword=password
• Windows: ConfigEngine.bat modify-servlet-path-portlets -DPortalAdminPwd=password -DwasPassword=password
• IBM i: ConfigEngine.sh modify-servlet-path-portlets -DPortalAdminPwd=password -DWasPassword=password

NOTE: Check the output for any error messages before proceeding with the next task. If any of the configuration tasks fail, verify the values in the wkplc.properties and wkplc_comp.properties files.

This step is optional in the case of a migrated Portal, as the Portal migration does not alter the context root for portlets.

Perform the following steps if you are using an external Web server, such as an HTTP Server:

1. Choose the option applicable to your WebSphere Portal environment:

For a standalone configuration:

a) Copy the following script from the plugin_root/bin directory to the wp_profile_root/bin directory on your WebSphere Portal server:

• UNIX: ./configurewebservername.sh
• Windows: configurewebservername.bat
• IBM i: configurewebservername.sh

where webservername is the Web server definition name you defined previously when configuring the HTTP Server for WebSphere Portal; for example, configurewebserver1.bat.

b) Execute the following command, from the wp_profile_root/bin directory:

• UNIX: ./configurewebservername.sh
• Windows: configurewebservername.bat
• IBM i: configurewebservername.sh

For a clustered configuration:

a) Copy the following script from the plugin_root/bin directory to the dmgr_profile/bin directory on your Deployment Manager server:

• UNIX: ./configurewebservername.sh
• Windows: configurewebservername.bat
• IBM i: configurewebservername.sh

where webservername is the Web server definition name you defined previously when configuring the HTTP Server for WebSphere Portal, for example: configurewebserver1.bat.

b) Execute the following command on the Deployment Manager server:

• UNIX: ./configurewebservername.sh
• Windows: configurewebservername.bat
• IBM i: configurewebservername.sh

2. Regenerate the Web server plug-in in WebSphere Application Server. If you are using a remote Web server, copy the generated plugin-cfg.xml file to the remote server.

Important: These steps should not be used if you are only changing the WSRP Producer URI.

3. Restart the Web server, and restart server1 and the WebSphere_Portal servers.

Perform the following steps if you are using the Resource Manager portlet to manage your site and you changed the portal URI:

1. Open a command prompt and change to the directory where WebSphere Portal is installed, on the corresponding operating system; for example, in the wp_profile_root/ConfigEngine directory.
2. Enter the following command:

UNIX: ConfigEngine.sh enable-http-basic-auth-tai-sitemgmt -DWasPassword=password
Windows: ConfigEngine.bat enable-http-basic-auth-tai-sitemgmt -DWasPassword=password
IBM i: ConfigEngine.sh enable-http-basic-auth-tai-sitemgmt -DwasPassword=password

3. Restart server1 and the WebSphere_Portal servers.

Perform the following steps to configure the Syndicated Feed portlet on an alternate context root:

1. Log on to the WAS administrative console.
2. Navigate to Applications – Application Types – WebSphere enterprise applications.
3. Search for the PA_wp.feedspace application, using the filter function, and then open it.
4. Click Class Loading and update detection settings.
5. Make the following changes to the settings:

• Classes loaded with parent classloader first
• Single classloader for application

6. Click Apply and then click Save to save the settings.
7. Clustered environment only: Resynchronize the nodes and restart the cluster.

Perform the following steps on each additional node within your cluster to create WebSphere environment variables needed by IBM Web Content Manager (WCM):

1. Locate the wkplc.properties and wkplc_comp.properties files on the additional nodes in the wp_profile_root/ConfigEngine/properties directory and create backup copies before changing any values.
2. Use a text editor to open the wkplc.properties file and enter the appropriate value for your environment in the WpsContextRoot property. Save and close the file.
3. Use a text editor to open the wkplc_comp.properties file and enter the appropriate value for your environment in the following properties:

• WsrpContextRoot
• WpsPersonalizedHome
• WpsDefaultHome

4. Save and close the file. Then run the following task to create the WebSphere environment variables for WCM:

• UNIX: ./ConfigEngine.sh create-wcm-servletpath-variables -DWasPassword=password
• Windows: ConfigEngine.bat create-wcm-servletpath-variables -DWasPassword=password
• IBM i: ConfigEngine.sh create-wcm-servletpath-variables -DWasPassword=password

NOTE: Check the output for any error messages before proceeding with the next task. If any of the configuration tasks fails, verify the values in the wkplc.properties and wkplc_comp.properties files.

5. Restart server1 and the WebSphere_Portal servers.

At this point in the exercise, WebSphere Portal will start but will not render properly where the Migrated Themes are used. An error in the SystemOut.log will also surface:

As explained in the Introduction section above, there is a conflict between the portal and theme context roots, since they are now the same. The next sections describe how to eliminate the conflict and resolve the error in log.

Using xmlaccess to change the context root of migrated theme(s)

To do this:

1. Using Portal xmlaccess, export the WebSphere Portal themes, using the following steps:

a) Save this script as an .xml file, exportThemes.xml, for exporting the themes (see listing 1).

Listing 1. Script to save as .xml file

b) From the <PortalHome>/bin, execute the command:

c) Verify the export completed successfully.

2. Modify the exported .xml, changing the Migrated Themes context root from /wps to /testMTheme:

a) Open the exportedThemes.xml file.

b) Replace the context root for the Migrated Themes from /wps to /testMTheme. For example:

c) Save the file.

3. Import the theme and skins, using the modified .xml, where the MigratedThemes context root was changed:

a) From the <PortalHome>/bin, execute the command:

b) Verify the import completed successfully.

Using WAS Admin Console to change the Enterprise Application context root

To do this:

1. Launch the WAS Admin Console and log in, using the WAS Admin credentials that you used to install WAS (see figure 1).

Figure 1. Admin console log-in window



2. After logging in, select Applications – Application Types – WebSphere enterprise applications (see figure 2).

Figure 2. WebSphere enterprise applications



3. Select the “MigratedThemes” WebSphere enterprise application from the list (see figure 3).

Figure 3. Enterprise Applications list



4. In the next window, click the “Context Root For Web Modules” link; click OK (see figure 4).

Figure 4. Context Root For Web Modules link



5. In the next window, enter the new context root value for the MigratedThemes Web module (see figure 5). This value should be the same value used above in Step 2b of Section 3, “Using xmlaccess to change the context root of migrated theme(s).” Click OK.

Figure 5. Context Root for Web Modules window



6. Choose to “Save directly to the master configuration” (see figure 6).

Figure 6. Save to the master configuration



7. Restart WebSphere Portal servers:

• If using a standalone environment, restart server1 and the WebSphere_Portal servers.
• If using a cluster, resynchronize the nodes and restart the cluster.

Verify the configuration

To verify the environment, do the following:

1. Access WebSphere Portal with the new context root.
2. Access pages with migrated theme(s).
3. Check that portlets and pages render properly.
4. Check the logs for context-root change-related errors.

Troubleshooting tips

In this section we describe the issues we encountered during the migration process, and how we resolved them.

(1) After completing this exercise and starting WebSphere Portal for the first time, you may encounter a 404 HTML error when initially rendering a page with the migrated theme. This is an intermittent issue that is associated with changing the Migrated Themes context root to /wpsXXXX. To avoid the issue, simply rename the Migrated Themes context root to something that does not start with /wps.

(2) After changing the context roots, it has also been reported that some labels or icons can be missing (see figure 7). You can resolve this by manually updating the theme's jspf. This issue is also associated with changing the Migrated Themes context root to /wpsXXXX. You can resolve this by renaming the Migrated Themes context root to something that does not start with /wps, or by manually updating the theme's jspf.

For example, to correct the “??????” shown in the title bar of figure 7:

a) Edit the file, {WebSphere Portal 7 Server Home}/installer/wp.ear/installableApps/wps_theme.ear/wps_theme.war/themes/html/Portal/head_title.jspf

b) Change the value of the line

to

c) Save the file and restart the server.

Figure 7. Missing label example

Conclusion

The process recommended in this article retains the previous WebSphere Portal environment in production and reduces the amount of downtime during a migration. By following the steps described here on all JavaTM Content Repository (JCR)-related and Release databases, you can save time, and the troubleshooting tips can help solve potential problems.

Resources

WebSphere Portal Family wiki article, “Changing or consolidating the IBM WebSphere Portal / Web Content Manager context root:”
http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Changing_or_consolidating_the_WebSphere_Portal__WCM_context_root

IBM DB2 Tools information:
http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.db2tools.doc/db2toolhome.htm

WebSphere Portal Server Version 7.0 Product Documentation:
http://www-10.lotus.com/ldd/portalwiki.nsf/xpViewCategories.xsp?lookupName=IBM%20WebSphere%20Portal%207%20Product%20Documentation

developerWorks WebSphere product page:
http://www.ibm.com/developerworks/websphere/

WebSphere Portal Family wiki:
http://www-10.lotus.com/ldd/portalwiki.nsf

WebSphere Portal Discussion forum:
http://www.ibm.com/developerworks/forums/forum.jspa?forumID=168

About the author

Adrian B. Jordan currently works as a Staff Software Quality Engineer on the WebSphere Portal System Verification Test (SVT) team. He tests several areas of the product, focusing primarily on WebSphere Portal Server migration. You can reach him at adrianj@us.ibm.com.