Integrating Web applications with WebSphere Portal V6 and V6.1: The JSPPage custom theme

This article shows you how to integrate existing frameset and non-frameset applications into IBM® WebSphere® Portal V6.0 and V6.1. By utilizing a custom portal theme, the external application can be integrated into a portal on its own page with few to no changes in the application. The single custom portal theme can be used to integrate several different applications in the same installation.


John De Binder (, Senior Managing Consultant, IBM

John De Binder is a Senior Managing Consultant with IBM Software Services for Lotus at IBM Research Triangle Park in Raleigh, North Carolina. John started consulting with IBM Smalltalk customers in 1996 when the Services group began and has since worked many years with VisualAge® for Java, WebSphere Application Server, and, most recently, WebSphere Portal. You can reach John at

29 June 2009 (First published 20 January 2009)

Also available in Spanish

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.


The objective of WebSphere Portal is to provide a single point of access to all the information and tools for users in a specific user community. To accomplish this goal, many applications must be integrated into the portal. Some applications already have portlets. For the applications that do not, often the only integration option is to simply link to the application and provide single sign-on (SSO) integration.

This solution is for those existing applications that would like to be integrated with the portal, be displayed along with the portal banner and navigation, but would be too costly to rewrite into a portlet or a portal user interface (UI) and back-end layered approach.

Integration options

There are many ways to integrate applications into WebSphere Portal. Some of the approaches are outlined here in the order of their implementation effort. This section is intended only as an introduction to each of these topics. You are encouraged to read more about any of these topics on IBM developerWorks®, another Web site, or your favorite book..


Links are the quickest way to integrate an application, though this approach can barely be called integration. The most common way links are used is to have a portlet that lists many tools that the user has access to and that relate to the subject matter of the portal. Links can also be provided in the main navigation of the portal by creating a URL instead of a page or a label in the navigation hierarchy.

The application can be made to look a little more like the portal by using a common UI design for the banner and providing a link to return to the portal.

The advantages of using links are these:

  • The process is quick.
  • No coding is needed.

The disadvantage, though, is considerable:

  • You are giving users an obvious jump to another Web site or tool.

iframe portlet

An HTML iframe tag is the second most common way to quickly integrate an application into the portal. This integration is usually done with an iframe portlet or a portlet that uses an iframe tag that references the application. Therefore, the application is displayed on a portal page, with the portal banner and with portal navigation.

The iframe tag has inherent problems. You are forced to specify a width and a height. Although these dimensions can be specified in percentages, if the content exceeds what is specified, the iframe automatically provides scroll bars. These extra scroll bars are a detriment to the user experience.

The advantages of using iframe portlets are these:

  • The process is quick.
  • No coding is needed.
  • The iframe portlet makes the application look like part of the portal because the banner and navigation are shown.

The disadvantages are these:

  • The iframe tag can introduce scroll bars.
  • Applications can take over the top window.

JSPPage custom theme

This custom theme is a new approach and is the subject of this article. The JSPPage custom theme is a customized version of the IBM portal theme. It enables Javaâ„¢ developers to control the contents of a portal page with their own JavaServer Pages (JSP), offering many integration options. The examples presented in this article are integration with a frameset application and integration with a non-frameset application.

The advantages of the JSPPage custom theme are these:

  • It is easy to integrate portal navigation into many different Web application types.
  • It maintains the portal state with embedded navigation.

The minor disadvantage is:

  • You must code at least one JSP.

Web Application Integrator

The Web Application Integrator (WebAppIntegrator) is a new offering in the IBM WebSphere Portal Business Solutions Catalog. It enables any application to embed the portal banner and top navigation into its Web page. This integration is accomplished by having the WebAppIntegrator administration portlet generate a bit of JavaScript and including that JavaScript at the top of the application’s HTML page.

The JavaScript calls the portal server, receives the banner and navigation, and dynamically embeds them into the application’s Web page. The page is completely owned by the integrated Web application, and the portal navigation is embedded in the browser.

The one drawback to this integration is that the user loses much of the portal state. In recent releases, WebSphere Portal has been embracing the REST architecture, in order to support the browser's back button and the bookmarking of portal pages. Therefore, much of the portal state (last page visited, portlet window modes, and so on) is encoded into the portal URL. The WebAppIntegrator administration portlet generates a single static URL for the application; therefore, it cannot contain the user’s current portal state. When the user navigates to the integrated application and returns to the portal, the portal state reverts to the default state for all portlets. NOTE: The portlet session information is not lost unless the session times out.

The advantages of the Web Application Integrator are these:

  • It is easy to use.
  • It adds portal navigation to your Web application.
  • It supports integrating several applications with a single installation.

Its disadvantages are these:

  • It requires a change to the application’s HTML output.
  • Users lose portal state information.

Web Clipper portlet

The Web Clipper portlet is the modern day screen scraper. It provides a way to expose an HTML application through the portal without having the user’s browser go directly to that application. The Web Clipper portlet acts as a proxy and treats the application as a back-end application. To do this task, all URLs in the application’s HTML are rewritten to flow back through the Web Clipper portlet so that the user does not lose the context of being inside the portal. One challenge here is that any URL that is embedded in JavaScript is not recognized and therefore not rewritten.

It is also possible to configure the Web Clipper portlet to manage cookies, transmit existing SSO information, and even transform or rearrange the HTML that is received from the application before it is displayed on the portal page.

The advantages of the Web Clipper portlet are these:

  • It is built into WebSphere Portal.
  • It is easy to learn the scripting language used to manipulate HTML.

Its main disadvantage is this:

  • URLs hidden in JavaScript cannot be processed.

Summary portlet

With the summary portlet approach, a new portlet is written to implement the most commonly used functions of the application. For the less commonly used or more complex functionality, a link is provided to the application.

Its advantage is this:

  • The summary portlet provides the most common application function fully integrated into the portal.

Its disadvantage is this:

  • You must code the new portlet.

Full-function portlet

The full-function portlet approach represents a full commitment to writing all user interfaces in the portal. The application can be represented in a single portlet or in multiple portlets. The business logic should be separated from the UI by providing a set of remote services. The services can be implemented with a servlet, session Enterprise JavaBeans (EJB), or Web services interface.

Its advantage is that it is fully integrated into the portal.

Its disadvantage is that you must code new portlets and possibly services.

The custom theme: JSPPage

This integration approach is accomplished by implementing a custom portal theme. This theme controls what part of the HTML page is supplied by the portal and what part of the page is supplied by your application. The objective is to display the portal banner and navigation in the browser with the integrated application.

What is a portal theme?

The look and feel of your WebSphere Portal implementation are controlled by the portal themes and skins. The theme controls the overall look of the page, and the skins control the decoration and tool icons around each portlet. The theme is responsible for defining the banner, navigation, and footer and for using the <portal-core:screenRender/> tag to allow the portal page aggregator to include all the portlets on the page.

Themes are defined by a directory containing JSP and JSP fragment files. Usually a theme directory is contained in the <wps.ear>/<wps.war>/themes/html/ directory. Refer to the WebSphere Portal Information Center for more information on portal themes and skins.

The JSPPage theme is a custom theme. A custom theme is usually created by copying the default IBM theme directory, giving it a new name, and changing the theme in the copied directory to meet your custom needs.

Using the JSPPage custom theme

You use the JSPPage custom theme by creating a new portal page and assigning this custom theme to it. You might also want to use a custom theme policy like the sample JSPPage theme policy.

For example, assume that you have a frameset application that you want to integrate into the portal. The original frameset application normally displays a page like the one shown in figure 1.

Figure 1. The page displayed by the original frameset application
The page displayed by the original frameset application

Let’s also assume that the menu in the left frame and the content in the right frame constitute 80 percent of the functionality of the application and that this is all that we need to integrate into the portal. We want the application to look like the page shown in figure 2 when it is integrated into the portal.

Figure 2. The page displayed when the frameset is integrated into the portal
The page displayed when the frameset is integrated into the portal

How it works

The JSPPage custom theme works by implementing additional logic in the Default.jsp file. Default.jsp is the entry point to all portal themes. A normal Default.jsp file includes the parts of the page (banner, navigation, page body, and footer) by including JSP fragments. In this custom theme, Default.jsp is called multiple times to display the page. The first time it is called, it must respond with the HTML to lay out the page (the frameset). The subsequent calls to the theme are responsible for referencing another custom JSP to supply the contents of a frame within the frameset, such as the top navigation or footer. Because the page body is not composed of portlets, the theme never calls the screenRender tag. The first custom JSP or one of the subsequent JSPs is responsible for rendering the application in the page body. Figure 3 depicts this process.

Figure 3. How the JSP theme works
How the JSP theme works

This approach can also be extended to other types of applications as we see in a later example.

To determine which JSP to display, the Default.jsp file in the JSPPage custom theme depends on parameters, that is, HTML parameters and page parameters. HTML parameters are associated with the incoming URL, and page parameters are associated with the portal page through the portal administration tools. When users first select the page that uses the JSPPage custom theme, they select a link in the navigation bar. These links have no HTML parameters. This step represents the first pass in the diagram shown in figure 3. In this case, Default.jsp looks for a page parameter named jspPageCustomJSP. The value of that page parameter indicates which custom JSP to return for the page.

The first custom JSP must set up the page, determine where to include the portal navigation and/or footer, and generate the URLs to get them. There are two requirements for these URLs:

  1. They must supply a parameter (jspPageFrameJSP) to indicate what JSP to call to return the desired content.
  2. They must be generated by the portal API so that they include the portal state string.

You can create as many custom JSPs in the theme as necessary to integrate different applications.

Installing the JSPPage theme

Follow these steps to install the JSPPage custom theme on a stand-alone portal server:

  1. Download the or JSPPageIntegration6.1x.zipfile; see the Downloads section of this article.
  2. Unzip the file to a temporary directory.
  3. Copy the contents of the wps.war directory into the wps.war directory on the server:
  4. Modify the domain name for the cookie in the <xxx>/wps.war/jspPageTest/remoteApp.jsp file to match your domain. The default value is
  5. Start or restart the portal server.
  6. Copy the contents of the XMLAccessScripts directory into the <wp-install> directory on the server (<xxx>/WebSphere/PortalServer).
    • Modify the user and password parameters to match your environment.
    • You might have to modify the port in the URL parameter. The default port for WP 6.0 is 10038, and the default port for WP 6.1 is 10040.
  7. Create the JSPPage theme policy with XMLAccess by using the files ImportJSPPagePolicy.bat and ImportJSPPagePolicy.xml in the XMLAccessScripts directory. This needs to be done only once for WebSphere Portal V6.1.
  8. Create the JSPPage custom theme and the test pages with XMLAccess by using the files ImportJSPPagePages.bat and ImportJSPPagePages.xml in the XMLAccessScripts directory.

To install the JSPPage custom theme in a cluster, follow the instructions for Deploying customized themes and skins in the WebSphere Portal Information Center.

If you want to have theme JSPs automatically recompiled when they change, follow the instructions for Enabling automatic JSP reloading in the WebSphere Portal Information Center.

Extending the theme for your application

The JSPPage custom theme is a generic theme that allows integration of many applications. To integrate an application, you must supply at least one custom JSP.

The following steps are necessary to integrate your own application into the portal using the JSPPage custom theme.

  1. Create your custom JSP and add it to the JSPPage theme directory.
    • Your initial custom JSP might reference additional JSPs. These also must be added to the JSPPage theme directory.
    • Use a naming convention to be able to easily recognize your custom JSPs in the directory.
  2. Create a portal page in the Manage Pages administration portlet.
  3. Add a page parameter to your new page to identify the initial custom JSP:
    jspPageCustomJSP = <your custom JSP name>

Integrating frameset applications

The preceding discussion illustrated one way to integrate a frameset application into the portal. Following are three examples of frameset application integration that are supplied with the JSPPage theme.

Most of this information is easy to use, but there are a few obstacles. Framesets are a powerful and useful tool, but they do have limitations and sometimes cause undesirable UI behavior.


There are three frameset example integration pages that can be imported with the ImportJSPPagePages.xml file as stated in the "Installing the JSPPage theme" section. They are all children of the JSPPage Prototypes page in the launch menu. The following sections describe these three pages.

Sample: frameset1.jsp

This page illustrates a simple application that can be integrated in a single frame. It is assumed that the application is well formed and does not try to replace the _top window.

This kind of application can also be integrated with an iframe portlet, but the JSPPage frameset integration scenario is less likely to have the problem of too many vertical scroll bars. Also, with the frameset HTML, it is possible to have the top and bottom frames fixed and to have the middle frame resize with the window. See figure 4.

Figure 4. Integrating a simple frameset application
Integrating a simple frameset application

Sample: frameset2.jsp

The frameset2.jsp sample illustrates the scenario described at the beginning of this article. See figure 5.

Figure 5. Integrating two frames of a frameset application
Integrating two frames of a frameset application

Sample: frameset3.jsp

The third frameset example is an extension of the second. This example is for an application that must have a toolbar in addition to the left and right frame. The application probably has a standard banner, header, and toolbar that is displayed in the top frame. Including both the portal and the standard application header, though, would take up too much room.

The solution is to re-implement only the required parts of the toolbar in the portal header as shown in figure 6.

Figure 6. Combining the application tool bar with the portal navigation
Combining the application tool bar with the portal navigation

Overcoming obstacles

You might encounter obstacles, especially when integrating frameset applications. The following sections ("Launch menu," "Fluid design," and "Security limitations") describe obstacles that we have seen and offer a way to solve them.

Launch menu

A frameset reserves a certain amount of space on the HTML page for each frame. When the portal navigation is displayed in the top frame of the frameset, the size is either specified by the frameset or calculated based on the initial display size.

The launch menu is a Web 2.0 feature that is initially of size zero. When the user presses the button to display the menu, the menu is retrieved, placed in a div, and the div automatically resizes. This process causes a problem in the frame because the frame is not large enough to display the menu. The menu gets truncated.

To work around this obstacle, you must disable the display of the launch menu by creating a new theme policy. The only difference between this policy and the default policy is that the renderMainMenu policy value is set to false. An example policy (JSPPagePolicy) was created for this article.

Fluid design and framesets

The JSPPage custom theme is copied from the default IBM theme. This theme is designed to be fluid. In other words, it reflows the objects on the page when the browser window is resized, at least on Microsoft® Internet Explorer.

Because the frame for the top navigation needs to be a fixed size, the content of the frame is truncated when it is reflowed because it takes up more vertical space. To prevent this obstacle, the theme would have to be modified so it does not reflow.

Security limitations in frameset

Another major obstacle with framesets is that the browser implements security protections when different frames access different Web servers. If the application is referenced from another server and the code in one of the application frames merely tries to access the title of the portal frame, the browser throws an access violation.

The following describes a specific example of this problem and is further illustrated in figure 7:

  • The menu frame (Frame 2) contains JavaScript that uses the Document Object Model (DOM) to query the name of its parent’s parent (the top most frame).
  • The content frame (Frame 3) uses the DOM to set the window title (
  • Because the parent window is from the portal server and the application frames are from the application server, this configuration is considered a security breach and the browser throws a JavaScript error: Access Denied.
Figure 7. Integrated frameset application with a security problem
Integrated frameset application with a security problem

To defeat the browser security mechanisms, the source of all content must seem to originate from the same server. The solution is to access the portal and the integrated application through a reverse proxy as shown in figure 8.

  • The IBM HTTP Server or a WebSphere Edge Server can be used as a reverse proxy.
  • The application URL is directed to the reverse proxy.
  • The application context root (APPL) is configured to be served by the remote application server.
Figure 8. Solving the security problem with a reverse proxy
Solving the security problem with a reverse proxy

To briefly summarize, in the reverse proxy setup, the changes shown in listing 1 are made to the Web server httpd.conf configuration file.

Listing 1. Changes to the httpd.conf file
# Uncomment the following line
LoadModule proxy_module modules/
       - - - - - - - - - -
# Add the following command to turn off the forward proxy
ProxyRequests Off

# Add the following proxy directive to define the proxy namespace and permissions
<Proxy * >
Order deny,allow
Allow from all
       - - - - - - - - - -
# Add the following directives to define the proxy mappings
ProxyPass / APPL APPL
ProxyPassReverse / APPL http:// APPL

Integrating non-frameset applications

The JSPPage custom theme can also be used to integrate non-frameset applications. In this scenario, the objective is to get the application’s servlet or JSP to include the portal navigation at the top of the page. The application owns the whole page and provides the content for the rest of the page, but in the user’s eyes the application is now part of the portal. See figure 9.

Figure 9. Non-frameset application integration
Non-frameset application integration

An example of this integration is shown on the fourth sample page and is implemented in the sample/remoteApp.jsp file.

Because the application’s servlet or JSP does not reside on the portal server, it can not use the portal APIs to generate the correct URL back to the portal to display the current navigation. To accommodate this situation, the remoteApp.jsp file sets a cookie and redirects to the application’s URL. This cookie contains a base URL pointing to the page that represents the application and also includes the portal state.

When the application is invoked, it detects this cookie. Instead of displaying its own banner and navigation, or in addition to it, it embeds JavaScript into its HTML page to include the portal navigation. When this JavaScript runs on the user’s browser, it calls the portal to get the portal navigation using the base URL from the cookie. The navigation can then be placed into a DIV tag at the top of the page.

By using the base URL that is generated when the user initially displays the integrated application’s page, the correct page is highlighted in the navigation and all the other navigation links include the current portal state. Figure 10 illustrates this flow.

Figure 10. Flow diagram for integrated application
Flow diagram for integrated application

Overcoming obstacles: Security restriction

The XMLHTTPRequest object is used in the JavaScript to make the call to the WebSphere Portal server to retrieve the portal navigation. This object has a security restriction. It allows a call only to the same server that supplied the current page. The application that you are integrating into the portal probably resides on a different server so its page is not allowed to retrieve the portal navigation.

The solution to this problem is the same as the solution for the security restriction mentioned in the frameset application integration. A reverse proxy must be used so that the URLs for both the application and the portal server have the same server name.

If the application and the portal are both JEE applications, then there is now a problem with the JSESSIONID cookie. Because all JEE applications use the same cookie name by default and the two applications now look as if they are on the same server, this cookie name must be changed for one of the applications.


This article reviewed several ways to integrate applications into WebSphere Portal. In addition, we have presented the implementation of a custom theme that can integrate both frameset applications and non-frameset applications into the portal without the need to use any portlets. The integration is accomplished directly in the theme with the help of a custom JSP.

Even though this solution requires a custom theme and some JSP coding, it is not a difficult task, and this article shows some specific examples. This solution is flexible enough to be integrated into any other custom theme that you might have. It requires only that you modify a few files.


Code sampleJSPPageIntegration6.0.zip2.05MB
Code sampleJSPPageIntegration6.1x.zip2.44MB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Integrating Web applications with WebSphere Portal V6 and V6.1: The JSPPage custom theme