Customizing error pages in IBM WebSphere Portal and IBM Web Content Manager applications in a multi-site environment

Introduction

When a user generates a GET request to an incorrect URL, such as http://mysite.com/wps/myportals, instead of going to that address, the application server typically responds with a generic message such as:
Incorrect URL resources are handled and processed within the IBM® WebSphere® Application (WAS) security layer and, in order to allow a custom error page to display, you must modify the IBM WebSphere Portal configuration.

Figure 1 depicts a logical schema of the error-handling configuration in which WebSphere Portal installed. In this scenario there are multiple Web sites and intranets to customize the error page for your Web site. This article is a simplified guide to customize these error pages.

Figure 1. Error-handling process

Solution overview

We have two possible scenarios, a cluster environment and a standalone environment, and our solution is tested and verified in both. The scenario in which we do the configuration is shown in figure 2.

Figure 2. Configuration scenario

Our objectives

If we request a page from a particular brand site and there is an error event, we receive an error page with the same brand. When browsing a Web site, or following a link to a blog or a mapped access to a resource that does not exist, we want to receive a courtesy page containing an informative error and proposing an alternative, ideally in keeping with the layout of the site itself.

In other words, we don't want a page that provides only a useless message such as:
Instead, we want to receive a courtesy page like that shown in figure 3.

Figure 3. Example courtesy error page

Configuration steps

Cluster environment 24x7

The applications involved are wps.ear and wcm.ear, and the following steps reflect making the application with the goal of customizing error conditions using a specific page. To do this we must edit the web.xml of the application:

Prepare your HTTP Server
1. Create a custom page for every Web site to display to the user, for example, create the directory "ep" (Error Page root) under your DocumentRoot, such as <IHS InstallPath>/www/<YourSiteDocumentRoot>/ep/, as follows:
2. Optional: In accordance with the rewrite rule configuration, insert the following in your definition:

where the re404.html page is similar to:

This page is necessary when the broken link is in part of the URL; for example, when you call http://<fqdn>/wps/wcm/brokenConnection/..., the system shows you the custom page but does not change the URL in the browser. If the user sees the original request, then the URL rewrite is not necessary.

3. Restart the HTTP Server.

Customize the WebSphere Portal application
Now let's work in the Deployment Manager environment to customize the Portal application:

1. In the web.xml file deployed and used by WAS,
2. Edit this file, inserting between these lines the specification for error handling; for example:

where the error code is “clear”, and the location indicates where the customized page is.
If this page is used only for redirection to the HTTP standard error page; then we would insert the following tag:

3. Save the file.

Now we edit the same file in the wcm.ear, which is used when you synchronize the node:

1. In the web.xml that you find in
2. Insert between these lines the following specification for error handling:

3. Save the file, and update all the .ear files.

Customize WCM application
Now we work in the Deployment Manager environment for customizing the IBM Web Content Manager application:

1. In the web.xml that you find in
2. Insert between these lines the specification for error handling, for example:

where error code is “clear”, and location indicates where the customized page is. If this page is used only for redirection to the HTTP standard error page, we would insert the following tag:

3. Save the file.

Now we edit the same file into the wcm.ear, which is used when you synchronize the node:

1. In the web.xml that you find in
2. Insert between the lines the following specification for error handling:

3. Save the file, and update all the .ear files.

Create redirection page
Now we insert the custom page in wps.war (the same we have now modified):

1. Create the directory /ep, and create the html page to redirect:
2. Synchronize all Portal nodes and restart your Portal Server.

Standalone environment

The applications involved in this case are wps.ear and wcm.ear, and the following steps reflect making the application with the goal of customizing error conditions using a specific page. To do this, you must edit the web.xml of the application.

Prepare your HTTP Server
1. Create a custom page for every Web site to display to the user, for example, create the directory "ep" (Error Page root) under your DocumentRoot, such as /www//ep/ as follows:

e404.html
e409.html
e500.html

2. Optional: In accord with the rewrite rule configuration, insert the following in your definition:

RewriteEngine on

# RewriteLog /logs/rewrite.log" #(uncomment if you want the trace log)

# RewriteLogLevel 3 #(uncomment if you want the trace log)

RewriteCond %{REQUEST_URI} ^/wps.*$

RewriteCond %{REQUEST_URI} !./connect.*$

RewriteCond %{REQUEST_URI} !./myconnect.*$

RewriteRule ^/(.*) /ep/re404.html [PT,NC,L]

where the re404.html page is similar to:

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<META HTTP-EQUIV="Refresh" CONTENT="0;URL=/ep/e404.html"> <title>Not Found</title>

</head>

<body>

</body>

</html>

This page is necessary when the broken link is in part of the URL; for example, when you call http:///wps/wcm/brokenConnection/..., the system shows you the custom page but does not change the URL in the browser. If the user sees the original request, then the URL rewrite is not necessary.

3. Restart the HTTP Server.

Customize the Portal application
1. In the web.xml in

/wp_profile/config/cells/applications/wps.ear/deployments/wps/wps.war/WEB-INF/web.xml

which is the web.xml file deployed and use by WAS, find the following tag sequence:

</mime-mapping>
<resource-ref>

2. Insert between the lines the specification for error handling; for example:

<error-page>

     <error-code>404</error-code>

     <location>/ep/e404.html</location>

</error-page>

where error code is “clear”, and the location indicates where the customized page is. If this page is used only for redirection to the HTTP standard error page, we insert the following tag:

<error-page>

    <error-code>404</error-code>

    <location>/ep/e404.html</location>

</error-page>

<error-page>

    <error-code>500</error-code>

    <location>/ep/e500.html</location>

</error-page>

<error-page>

    <error-code>409</error-code>

    <location>/ep/e409.html</location>

</error-page>

3. Save the file.

Now we edit the same file in the wcm.ear, which is used when you synchronize the node.

1. In the web.xml in

/wp_profile/config/cells/applications/wps.ear/wps.ear/wps.war/WEB-INF/web.xml

find the following tag sequence:

</mime-mapping>
<resource-ref>

2. Insert between the lines the following specification for error handling:

<error-page>

    <error-code>404</error-code>

    <location>/ep/e404.html</location>

</error-page>

<error-page>

    <error-code>500</error-code>

    <location>/ep/e500.html</location>

</error-page>

<error-page>

    <error-code>409</error-code>

    <location>/ep/e409.html</location>

</error-page>

3. Save the file, and update all .ear files.

4. Now we insert the custom page in wps.war (the same we have now modified):

create the directory /ep
create the .html page to redirect
e404.html
e409.html
e500.html

for example, you can use this .html code:

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<META HTTP-EQUIV="Refresh" CONTENT="0;URL=/ep/e404.html"> <title>Not Found</title>

</head>

<body>

</body>

</html>

Note that you must use a relative URL to ensure that your request is redirected to your site independently of any FQDN you request.

5. Restart the Portal Server.

Customize the WCM Application
1. In the web.xml in

/wp_profile/config/cellapplications/wps.ear/deployments/wps/wps.war/WEB-INF/web.xml,

which is the web.xml file deployed and used by WAS, find the following tag sequence:

</mime-mapping>
<resource-ref>

2. Insert between the lines the specification for error handling, for example:

<error-page>

     <error-code>404</error-code>

     <location>/ep/e404.html</location>

</error-page>

where error code is “clear”, and location indicates where the customized page is. If this page is used only for redirection to the HTTP standard error page, we insert the following tag:

<error-page>

    <error-code>404</error-code>

    <location>/ep/e404.html</location>

</error-page>

<error-page>

    <error-code>500</error-code>

    <location>/ep/e500.html</location>

</error-page>

<error-page>

    <error-code>409</error-code>

    <location>/ep/e409.html</location>

</error-page>

3. Save the file.

Now we edit the same file in the wcm.ear, which is used when you synchronize the node:

1. In the web.xml in

/profiles/Dmgr01/config/cellsapplications/ wcm.ear/ilwwcm.war/ WEB-INF/web.xml,

find the following tag sequence:

</mime-mapping>
<resource-ref>

2. Insert between the lines the following specification for error handling:

<error-page>

    <error-code>404</error-code>

    <location>/ep/e404.html</location>

</error-page>

<error-page>

    <error-code>500</error-code>

    <location>/ep/e500.html</location>

</error-page>

<error-page>

    <error-code>409</error-code>

    <location>/ep/e409.html</location>

</error-page>

3. Save the file, and update all .ear files.

Create the redirection page
Now we insert the custom page in ilwwcm.war and in the deployed ilwwcm.war found in:

/wp_profile/installedAppwcm.ear/ilwwcm.war

1. Create the directory /ep, and create the .html page to redirect:

e404.html
e409.html
e500.html
for example, you can use the following .html code:

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<META HTTP-EQUIV="Refresh" CONTENT="0;URL=/ep/e404.html"> <title>Not Found</title>

</head>

<body>

</body>

</html>

Note that you must use a relative URL to ensure that your request is redirected to your site independently of any FQDN you request.

3. Restart the Portal Server.

This configuration is verified and tested in WebSphere Portal server versions 6.1.5.x and 7.0.x.

Resources

WebSphere Portal Infocenter

IBM Http Server Forum

Apache Http Server Project

About the author

Andrea Fontana currently works as a System Architect, defining, organizing, and configuring complex IBM product-based solutions. In particular he works with WebSphere Portal and its collaborative environment including Domino 8.0.x, 8.5, IBM Connections 3.01, Lotus Quickr 8.0.x, and IBM Sametime, with respect to setting up SSO Kerberos integration solutions and configuring systems with a R-proxy solution with SSL integration. His past experience includes roles as an Application Developer, Database Administrator, and Project Manager in a wide variety of business applications. He graduated from the ITIS Zuccante C., Mestre (Venice), specializing in Industrial Electronics. You can reach Andrea at a.fontana@net2action.com.