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.
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.
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 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
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:
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.
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
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
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
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:
- They must supply a parameter (jspPageFrameJSP) to indicate what JSP to call to return the desired content.
- 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:
- Download the JSPPageIntegration6.0.zip or JSPPageIntegration6.1x.zipfile; see the Downloads section of this article.
- Unzip the file to a temporary directory.
- Copy the contents of the wps.war directory into the wps.war directory on the server:
- Modify the domain name for the cookie in the <xxx>/wps.war/jspPageTest/remoteApp.jsp file to match your domain. The default value is ibm.com.
- Start or restart the portal server.
- 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.
- 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.
- 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.
- 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.
- Create a portal page in the Manage Pages administration portlet.
- 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.
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
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
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
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.
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 content frame (Frame 3) uses the DOM to set the window title (window.top).
Figure 7. 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
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/mod_proxy.so - - - - - - - - - - # 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 </Proxy> - - - - - - - - - - # Add the following directives to define the proxy mappings ProxyPass / APPL http://server.domain.com:10080/ APPL ProxyPassReverse / APPL http:// server.domain.com:10080/ 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
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.
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
Overcoming obstacles: Security restriction
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.
- Participate in the discussion forum.
- Refer to the developerWorks WebSphere Portal zone.
- Refer to the WebSphere Portal Support site.