Lotus Domino App Portlet Configuration-Redp3917

Front cover
IBM Lotus Domino no Application Portlet

Configuration and Tips
Configuration and authentication Parsers and rulesets
Examples and sample code
Thomas Delahunty Kornelius Elstner James Ryan Katherine Sewell
ibm.com/redbooks
Redpaper
International Technical Support Organization IBM Lotus Domino Application Portlet Configuration and Tips December 2004
Note: Before using this information and the product it supports, read the information in Notices on page v.
First Edition (December 2004) This edition applies to Version 1.0 and Version 1.1 of the Domino Application Portlet
Copyright International Business Machines Corporation 2004. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Chapter 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.1 Setup if you have installed Domino Extended Product portlets . . . . . . . . . . . . . . . 1.2 Configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.1 Source and Display tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.3 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.4 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 Edit options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 2 3 3 4 5 6 6
Chapter 2. Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.1 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.2 No authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.3 Basic authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.4 Session based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5 Single sign on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.1 Single sign on setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.6 Credential vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.6.1 System slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.2 Shared slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.3 Private slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Chapter 3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Types of caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Cacheable objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 Cache size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5 Using caching to improve DAP performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4. Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1 Regular expression parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.1 Input expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.2 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.3 Output expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.4 Blocks within the expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.5 Process for applying regular expression rules . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 HTML parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.1 Input expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.2 Output expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.3 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.4 Process for applying HTML rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Correlation between the rulesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 16 16 18 19 19 21 22 22 23 24 24 25 27 28 28 28 29 30
Copyright IBM Corp. 2004. All rights reserved.
iii
Chapter 5. Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 Setting up Domino. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 Setting up DAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1 Install portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.2 Create page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.3 Add portlet to page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.4 Initialize portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 Exploring the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4 Fixing the icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.5 TCP/IP trace proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.6 Fixing the greedy information page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.7 Switching to the HTML parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.8 Escalating security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.9 Another sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 6. Updates to Domino Application Portlet 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . 6.1 Debug tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Error reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 Customized rule sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4 Support for Domino Web Access (iNotes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5 Selective MIME types for Rules tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.6 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.7 Performance improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.8 Default to users mail file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.9 New URL re-writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix A. Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.1 Anonymous access issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2 Maximize portlet issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.3 Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.4 Language version issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.5 New window opening in Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.6 Alignment in BIDI language configuration and edit modes . . . . . . . . . . . . . . . . . . . . . . A.7 Richtext applet icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.8 Configuration performance (WPS 5.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.9 Configuration performance (WPS 4.1.2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.10 Load issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.11 Table properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.12 Domino Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33 34 34 34 34 34 35 36 37 39 40 41 42 44 49 50 51 52 52 52 52 53 53 54 55 56 56 56 56 56 57 57 57 57 57 57 58
Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 61 61 61 61
iv
IBM Lotus Domino Application Portlet: Configuration and Tips
Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:
ibm.com iNotes Domino IBM Lotus Redbooks Redbooks (logo) WebSphere Workplace
The following terms are trademarks of other companies: Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.
vi
Preface
This IBM Redpaper discusses the Domino Access Portlet. WebSphere Portal is a complete portal solution. It provides customers with integrated content and applications in addition to a unified, collaborative workplace. Domino is a comprehensive application platform. Customers have invested heavily to exploit the power of Domino in developing proprietary applications. As a result they are understandably reluctant to start again and move towards the benefits of a portal environment. The main question asked by such customers is how do we move our Domino applications into a portal. Domino Application Portlet (DAP) provides the solution. It facilitates the easy integration of Domino Web Applications into a portal server. This paper will describe DAP in detail and will give practical examples on configuring and customizing this portlet.
Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us! We want our papers to be as helpful as possible. Send us your comments about this Redpaper or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an email to:

redbook@us.ibm.com
Mail your comments to: IBM Corporation, International Technical Support Organization Dept. JLU Mail Station P099 2455 South Road Poughkeepsie, New York 12601-5400
vii
viii
Chapter 1.
Introduction
The Domino Application Portlet (DAP) integrates the content and technology of existing Domino Web Applications into the Portal environment. It allows customers to insert these existing applications into portlets and display them on a portal server with minimal development effort. Most importantly, it renders the portlets of the Domino Web application within the context of the portal, thereby keeping the user within the context and navigational scheme of the portal. The Domino Application Portlet acts like a reverse proxy, proxying the content from the back end servers through to the browser. It appears to the browser to be the real content server. The Domino Application Portlet (DAP) channels all requests from the user client (browser) through the portal and on to the Domino HTTP server in the back end. The portlet contains an iframe with an embedded servlet that is responsible for the actual connection and display of the Domino content. It manages cookies, caching, user authentication, and framing. Rules-based parsers rewrite the content produced by the Domino HTTP server. This document explores the setup and configuration of DAP. The rest of this chapter examines the basic setup and gives an overview of the configuration options available. This is followed by a number of sections that provide a detailed examination of these options. Chapter 5, Samples on page 33 contains two concrete examples that show how to setup DAP and write rules that tailor it for your own application. Chapter 6, Updates to Domino Application Portlet 1.1 on page 49 discusses specific improvements and updates which have been made in Version 1.1 of DAP, released in September of 2004. Finally there is a description of some known problems we have discovered.
1.1 Setup
DAP is setup like any other portlet, the WAR file is installed and then the portlet is added to a page1. To install DAP onto the portal server you must be logged in with administrator rights on the Portal. An example of installing and setting up DAP is given in 5.2, Setting up DAP on page 34.
Figure 1-1 Initial DAP window
1.1.1 Setup if you have installed Domino Extended Product portlets

The Domino 6.5.1 Extended Products portlets are an enhancement to the existing WebSphere Portal Collaboration Center portlets and therefore offer the ability to integrate the application functionality of the Domino 6.5.1 platform into a intelligent common user interface served up by WebSphere Portal Server. One of the key portlets included with the Extended Products Portlets included the Domino Application Portlet. Figure 1-2 on page 3 illustrates the tabs where you would see the Domino Application portlet and shows a sample Domino Web application being rendered through DAP. Attention: If you want to learn more about installing and configuring the Domino Extended Products portlets, refer to Chapter 8 within the redbook Domino 6.5.1 and Extended Products: Integration Guide, SG24-6357. http://www.redbooks.ibm.com/abstracts/sg246357.html
1 This is true for the standalone version available from the portlet catalog. However in Lotus Workplace DAP is installed with all the other portlets.
My Workplace Tab - access to fully integrated collaborative portlets Domino Application Portlet
Figure 1-2 Domino Application Portlet included as an Extended Product Portlet
1.2 Configuration options

To configure the Domino Application Portlet you must have administrator access rights. The configuration menu may be accessed by clicking the wrench icon in the upper right hand corner of the portlet. To configure the Domino Application portlet, complete the following steps: 1. Click the Configure portlet properties icon in the top-right area of the portlet window. This icon looks like a wrench. It contains four main tabs, which are: Source and Display Authentication Caching Rules
1.2.1 Source and Display tab

The source and display tab allows the user to define which Domino server and database the portlet is to display (Domino Source Server options). In addition to this it also allows the user to direct DAP to look for the Domino content via a proxy server. This is a useful feature if the user wants to see what requests are being made by the portlet to the Domino server. Finally this tab also lets the user configure the iframe in which the DAP portlet displays the Domino content. The show in edit mode check box permits some of these options to be made
Chapter 1. Introduction
available to a normal portlet user in edit mode. So for example, a normal user could configure a DAP portlet to point to his/her mail database without having to have administrator rights for the portlet.
Figure 1-3 Source and Display UI
1.2.2 Authentication
The authentication settings may be modified on the authentication tab of the configuration menu. These settings define the model DAP will use to authenticate with the Domino server and also where in the Credential Vault the username and password may be found. A number of options may be set including storage in the Credential Vault or use of Single Sign On. Note if a user is required to enter a password (for example in Basic Authentication) this will need to be done in the Edit settings. A more in-depth description of Authentication may be found in Chapter 2, Authentication on page 9.
Figure 1-4 Authentication UI
1.2.3 Caching
Within the Caching tab settings that affect the storage of cached objects from DAP may be set. While the browser has its own caching a user may also define a number of caching mechanisms for the DAP portlet. Essentially these mechanisms define where and how objects that are passed between Domino and DAP are stored. This caching takes place on the Portal server and use of caching here prevents unnecessary calls to the Domino server. A detailed description of the options here may be found in Chapter 3, Caching on page 15.
Figure 1-5 Caching UI
1.2.4 Rules
The rules tab defines the rules that are used to transform URLs and links in the Domino content so that they point to DAP instead of to the Domino server. These rules come in two forms that are mutually exclusive, Regular Expression Rules or HTML Rules. While there is too much detail to go into here and a detailed explanation is given in Chapter 4, Rules on page 21, the essential difference between the two is that Regular Expression Rules are very flexible, but complicated. while HTML rules are simpler and faster, but less flexible.
Figure 1-6 Rules UI
1.3 Edit options

The edit options may be accessed by selecting the pencil icon in the top right hand corner on the DAP portlet page.
Figure 1-7 Edit UI
The edit page is where a user must enter their Domino username and password if they are using Basic or Session based authentication. This page also contains any of the options that the Administrator decided to allow a normal user to configure. These may include the Domino Database settings and the display settings.
Figure 1-8 Edit UI
Chapter 2.
Authentication
This chapter describes authentication models that the Domino Application Portlet (DAP) can use to authenticate with the target Domino server. The following topics are addressed in detail: No authentication Basic authentication Session based authentication Single sign on Credential vault
2.1 Authentication
To modify the authentication settings click the wrench icon and then the authentication tab. There are four different authentication models that the Domino Application Portlet (DAP) can use to authenticate with the target Domino server. They are none, basic, session, and Single Sign On (SSO).
Figure 2-1 Authentication UI
Domino may require either basic, session-based, or SSO authentication. It is possible to authenticate by configuring the Domino Application Portlet with a lower model than the Domino server requires. For example, you can authenticate against a Domino server configured for single-session authentication by specifying Basic authentication in the Domino Application Portlet. However, you should generally match the portlet authentication model with the Domino server it is accessing.
2.2 No authentication
If the target server and database application does not require any authentication then the none radio button should be selected. When selected, a DAP user will not be required to enter their username and password in the portlet edit mode.
2.3 Basic authentication

Basic password authentication, also known as name-and-password authentication, uses basic HTTP authentication schema to ask users for their names and passwords and then verifies the accuracy of the passwords by checking them against a secure hash of the password stored in Person documents in the Domino Directory. When set up for this, Domino asks for a name and password only when a client tries to access a protected resource on the server. When connecting to Domino, DAP retrieves the username and password specified in the edit mode of the portlet. It may also retrieve these values from a credential vault system slot, if this type of slot is selected. Refer to 2.6.1, System slot on page 14 for further information regarding this. It then creates a header in the following format:
Header name: Header value: Authentication Basic: Ghy753Jk03==??}
The header value contains the authentication model being used together with the base64-encoding of the string username:password.
10
Upon receiving the request, Domino base64-decodes the string to reveal the username and password, which it then validates.
2.4 Session based authentication

DAP also provides for session authentication. Session-based authentication differs from basic password authentication in that the user name and password is replaced by a cookie. The user name and password is sent over the network only the first time the user logs in to a server. Thereafter the cookie is used for authentication. When connecting to Domino, DAP constructs a URL using the connection settings specified in the edit or config mode of the portlet.
Protocol Host http:// dominoserver.lan Port :80 Path and filename /mail/userA.nsf
If session based authentication is enabled, then the initial request to Domino is modified to append the username and password in the URL. The URL then becomes:
http://dominoserver.lan:80/mail/userA.nsf?Login\&use\\rname=userA\&password=password\&re directto=/mail/userA.nsf
When Domino receives this request, it validates the username and password and sends back a cookie called DomSessAuthId. This cookie is then used to authenticate the user on further requests from DAP.
2.5 Single sign on

Single sign on (multi-server session-based authentication) allows Web users to log in once to a Domino or WebSphere server, and then access any other Domino or WebSphere servers in the same DNS domain that are enabled for single sign on (SSO) without having to log in again. User Web browsers must have cookies enabled since the authentication token that is generated by the server is sent to the browser in a cookie. You can set this up by creating a domain-wide configuration document -the Web SSO Configuration document - in the Domino Directory. You initialize the configuration document by importing LTPA keys from WebSphere (you will need the password specified when generating the keys in WebSphere). When SSO is enabled, the user will not be required to specify their credentials in edit mode of the portlet.
2.5.1 Single sign on setup

To configure SSO for WebSphere follow these steps: 1. Log on to the WebSphere Application Server Console.(Start IBM WebSphere Application Serverv5.0 Administrative Console) 2. Go to Security Authentication Mechanisms and click LTPA, as shown in Figure 2-2 on page 12. 3. Enter the password to be used, and a file name that will contain the exported key. 4. Press Export keys button.
Chapter 2. Authentication
11
Figure 2-2 WebSphere LTPA Configuration
To configure Domino follow these steps: 1. Launch the Domino Administrator application. 2. Open the current server document. 3. Press the Create Web (R5)... button then select SSO Configuration as shown in Figure 2-3.
Figure 2-3 Domino SSO Configuration
4. Press the Keys... button, then select Import WebSphere LTPA Keys. 5. Specify the location of the key file that you exported the WebSphere LTPA key in the previous step. (You may need to correct the LDAP realm, by adding a \ (backslash) before :389. See technotes Setting up SSO -- 1098010 Troubleshooting SSO -- 1158269). 6. Enter in a value for the DNS Domain value, (e.g., .domain.com"). 7. Enter in the value for the Domino Server Names. This should contain the name of the current Domino server. 8. Give the SSO configuration a name (e.g., LtpaToken"). 9. Press the Save & Close button. 10.In the Current Server Document select the Internet Protocols tab, and then the Domino Web Engine tab, as shown in Figure 2-4 on page 13.
12
Figure 2-4 Domino Server Configuration
11.For Session Authentication select Multiple Servers (SSO). For Web SSO Configuration, select the name you entered in Step 8. 12.Save the document. Finally, restart the Domino server, Application server, and Portal server. SSO is now enabled between the WebSphere and Domino servers.
2.6 Credential vault

The Domino Application Portlet uses the WebSphere Portal credential vault to handle authentication if the authentication model in Domino is basic or session-based. In such cases, you will need to enter the slot type to be used. In addition, for system slots you must also provide the slot name (identifier). If no authentication is used in Domino (anonymous access) no credential vault settings are required. If single sign on (SSO) is used in Domino, access is inherent in the SSO framework and no credential vault settings are needed.The credential vault is organized as follows: The portal administrator partitions the vault into several vault segments. Vault segments can be created and configured only by portal administrators. Each vault segment contains one or more vault slots. Vault slots are the drawers where portlets, such as Domino Application Portlet, store and retrieve a user's credentials (for example, login details). Each slot holds one credential.Domino Application Portlet uses the default segment only. There are three different types of slots where credentials can be stored and retrieved by DAP.
Chapter 2. Authentication
13
2.6.1 System slot

The credentials that are stored in a system slot can be accessed by all users and by all portlets. The administrator sets the username and password in a new slot via the portlet settings, as shown in Figure 2-5. (Note - this is from WebSphere Portal 5.0.)
Figure 2-5 Credential Vault Settings
To edit the Credential Vault settings: Go to Administration Access Credential Vault Select the option Add a vault slot. Please ensure that Vault slot is shared is checked. Whatever slot name is used to create the slot must be entered as Slot identifier in the Domino Application Portlet configuration display as shown in Figure 2-6.
Figure 2-6 System slot
2.6.2 Shared slot

Credentials that are stored in a shared slot are accessible by all Domino Application Portlet instances for a given user. Users enter login information using the portlet's Edit mode. Credential changes in one portlet instance are reflected in all other portlet instances for that user.
2.6.3 Private slot

Credentials that are stored in a private slot are not accessible by all Domino Application Portlet instances for a given user. They are only accessible by the user whilst accessing the portlet instance that stored the credentials.
14
Chapter 3.
Caching
This chapter discusses caching options for the Domino Access Portlet. It discusses the following topics in detail: Access Cacheable objects Cache size Using caching to improve DAP performance
15
3.1 Types of caching

To modify the caching settings click the wrench icon and then click the caching tab. The manner in which cached objects are accessed in DAP depends on the caching type selected. The different caching types include: User and application (most secure) Cached objects can be accessed only by the user who put them into the cache, and only while accessing the current application. User Cached objects are shared by all applications, but can be accessed only by the user who put them into the cache. Application Cached objects can be accessed by any user, but only while using the application that put them into the cache. Shared (least secure) Cached objects can be accessed by any user or application, regardless of which application or user put them into the cache.
3.2 Access
Figure 3-1 on page 17 shows how objects are accessible by different applications and users depending on how they were cached. In this diagram there are three instances of DAP on a particular server, D1, D2 and D3. On each instance of DAP there are various users accessing them. For example, there are two users UserA (UA) and UserB (UB) accessing DAP instance D1. D1 - UA - The object is only accessible by user A whilst accessing DAP instance D1. D1 - UA and D1 - UB - The object is accessible by user A or user B whilst accessing DAP instance D1. D1 - UA and D2 - UA The object is accessible by user A whilst accessing either DAP instance D1 or D2.
16
Figure 3-1 Caching
Chapter 3. Caching
17
3.3 Cacheable objects

Here we choose what type of objects can be stored, and the part of the cache to store them. The part of the cache to store the object is determined using the mime-type of the object, and in the case of shared caching, the string defining the URL of the object. This helps you to limit shared caching to objects that are common to all users. For example, you might enter /icons to ensure that only objects whose URLs contain "/icons" will be stored in the shared cache. The user also has an option to specify user-defined mime-types, in the situation that the list provided is insufficient. The default caching configuration for DAP is shown in Figure 3-2.
Figure 3-2 Caching
Shared caching is selected. All objects that have an image mime-type, and have an applet mime-type (not shown) are cached in this part of the DAP cache. There is a maximum of 100 objects in the cache. This is the maximum for all objects in all parts of the DAP cache inclusive. The maximum size of each object in the cache is set to 250 kb. It is possible to select more than one part of the cache to be used, e.g., by selecting shared and application caching. If an object qualifies to be cached into more than one part, order will be used to decide.
18
The order is: 1. 2. 3. 4. User and Application User Application Shared
For example, if both "User and Application" and "Application" caching are selected, and an object qualifies to be cached in both, "User and Application" will be chosen. This is because it is more secure than "Application" caching.
3.4 Cache size

The maximum size of both the cache and the cached objects are configurable. The cache operates in a Most Recently Used basis, whereby when the size of the cache has reached its maximum, the object with the oldest accessed date is removed before adding a new object. DAP also provides a Clear Cache button, which allows for the contents of the cache to be deleted.
Figure 3-3 Clear Cache button
3.5 Using caching to improve DAP performance

The primary way to improve DAP performance using caching is to make use of the Shared cache. The Shared cache will store objects that are accessible to all users on all DAP portlet instances. For example, once a frequently requested image from Domino is stored in DAPs Shared cache by a particular user on a DAP instance, this image will be accessible by all subsequent users on any DAP instance without the need to retrieve it from Domino again. If we compare this with deciding to store objects in the user and application cache, a lot more overhead is required. For each user accessing the same resource we must request it from Domino and keep a copy of it in memory. Another way to improve performance using caching is to carefully configure the maximum size of the contents of the cache, and the maximum size of each object in the cache. Since the objects are effectively cached in the Portal server's memory, allocation should be carefully assigned if space is an issue.
Chapter 3. Caching
19
20
Chapter 4.
Rules
The Domino server provides the ability to allow users to browse Domino databases over the Internet. Unfortunately, accessing Domino data through a Portal server does not work in the same way as directly accessing it through an Internet browser. References to resources, such as graphics and applets, and links to other pages are generally relative to the Domino database. In order to access this data correctly through a Portal server these resources and links need to be redirected through the portlet. The Domino Application Portlet uses a parser to configure the content returned by Domino. There are currently two available parsers: a Regular Expression parser and a HTML parser. Each parser uses a set of rules to define the appropriate data transformations necessary to redirect the application through the Portal. The supplied rules are designed to cater to the four supported applications: mail, discussion, teamroom and reservations. However, these rules can be configured, by the portlet administrator, in order to tailor the portlet to support a new database application. In this chapter, these topics are discussed in detail: Regular expression parser HTML parser Correlation between the rulesets
21
4.1 Regular expression parser

The Regular Expression Parser makes use of the Jakarta regular expression parsing engine. It treats the entire input (from Domino) HTML page as plain text and tries to match each position to one of the defined rules. The regular expressions are composed of an input expression and an output expression. The input expression defines the content each rule is to search the text for.
4.1.1 Input expressions

The first component of a Regular Expression rule is the input expression. This expression defines what the rule is to search for within the given input. Input expressions can either be plain text, which will look for an exact match, or a regular expression to match when the content you are trying to match can change. For example, an input expression of:
parent.window.location
This will only match that exact text. However, in most cases we are less sure of what the exact text will be and need to use regular expression to deal with:
action="/mail/user1.nsf/83997d314a7eae6?ReadForm" action="/mail/user2.nsf/83997d314a7eae6?ReadForm"
A separate rule is required for each case. However, this input expression:
action="(.*?)"
This will match all strings of the type action="<some text here>", which gives us much more flexibility and power when writing rules.
Regular expressions
The main matching operators used in the current ruleset are: ( . * ? ) | [] ^ Start a grouping of operators Match any character Zero or more times Use minimum (reluctant) matching End the grouping of operators Logical OR Character class Beginning of a string. If within character class, then signifies logical NOT Actually, the exact input expression parent.window.location,will not match instances of "parent.window.location" within the input text. This is because the input expression contains reserved regular expression characters - the dots. To include any of the regular expression characters in the text part of an input expression you must precede them with a backslash1. So the actual input expression to match cases of "parent.window.location" is: parent\.window\.location
1 For more details on regular expression composition see the Jakarta Regular Expression API http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html
22
4.1.2 Output functions

In situations where outputting a static string is insufficient to properly deal with the proxying, a function is required. Output functions are used to perform complicated rule transformations, usually taking the matched text as input. The most commonly used functions are the pair of @transform functions. These functions transform URLs found within the Domino input, redirecting them from the Domino server through the Domino Application Portlet. These methods therefore form the basis of the Domino Application Portlet's reverse proxying capabilities.
@transform_uri_abs
This function only transforms URLs whose path is absolute (beginning with a forwardslash /).It transforms URLs so that they begin with the servlet path and end with an encrypted and encoded string that references the original URL. In this way the servlet used within the Domino Application Portlet can identify the Domino database to access and the corresponding path of the required resource.
@transform_uri_all
This function operates in a similar manner to transform_uri_abs, but it transforms the URL whether it is absolute (beginning with a forwardslash / ) or relative to the current path. For example, if the current path is http://dominoserver.ibm.com/mydb.nsf/myfolder then a URL of "mail.gif" would be appended to this path, resulting in a URL of http://dominoserver.ibm.com/mydb.nsf/myfolder/mail.gif. This functionality is maintained by the transform_uri_all function, which generates URLs of the type http://portalserver/wps/PA 11 0/rproxy/$$cGDdv$$.nsf/myfolder/mail.gif.
@proxypath
Returns the servlet path that is used to replace the link to the Domino server. An example result of applying this function is /wps/PA 1 0 69/rproxy. This path would then be used to construct a transformed URL.
@host
Returns the name of the Domino Server machine on which the current application is located [e.g.dominoserver.ibm.com.].
@protocol
This function returns the protocol used by the Domino Server (e.g., http or https).
@port
This function returns the port number used by the Domino Server (e.g., 80).
@param(n)
[where n is an integer] This function returns a string corresponding to the nth block (parenthesized expression) in the input expression. The first block is 1, the second 2 and so on. The whole of the matched text is 0. This is described in greater detail in 4.1.4, Blocks within the expressions on page 24.
@parencount
Returns the number of blocks (parenthesized expressions) within the input.
Chapter 4. Rules
23
@baseurl
This is a function dealing with occurrences of URLs within the base tag and is not generally required. These functions are used in the Output Expressions described in 4.1.3, Output expressions on page 24.
4.1.3 Output expressions

For each input expression for example:
action="(.*?)"
There is a corresponding output expression, which defines the transformations to perform on the text matched by the input expression. The output expression may be plain text, such as:
action="/mail/user3.nsf/83997d314a7?ReadForm"
Which will, given the input string:

action="<some text>"
This will replace all occurrences of <some text> with /mail/user3.nsf/83997d314a7?ReadForm. In order to deal with the more general case where we want to transform the string based on the input string, an output function (as described in 4.1.2, Output functions on page 23) is required. This rule uses two output functions @param(1)and @transform uri all().
action="@transform_uri_all(@param(1))"
The result of applying this rule to action="<some text>" is:

action="wps/PA_1_0_V9/rproxy/__PC_7_0_18L_PI_432667__/<some text>"
4.1.4 Blocks within the expressions

The input expression is divided up according to the groups of parentheses it contains. Staying with the input expression defined in 4.1.1, Input expressions on page 22:
action="(.*?)"
We see that this expression has one set of parenthesis. Since there may be more than one set per input expression, the blocks are identified by number. In this example, there is only one set so it is referred to as block 1. Subsequent parentheses blocks would be identified by in a similar fashion by the number 2, 3 etc. These block numbers are used in the output expressions to identify the parts of the string to transform. A specific output function:
@param(block_number)
This is used to reference the individual blocks. So given an input string of:
<form name="myForm" action="/mail/user1.nsf/83997d316273?ReadForm">
This will match our rule, action="(.*?)", as follows:

action="/mail/user1.nsf/83997d316273?ReadForm"
The regular expression within the parentheses of the input expression matches the URL:
/mail/user1.nsf/83997d316273?ReadForm
24
In order to refer to the URL within the output expression, we would use the following function call:
@param(1)
Using a more complicated example, the input expression:

<applet name="myApplet" (.*?) codebase="(.*?)" (.*?)>
This will match all instances of applets called myApplet. For one such instance:
<applet name="myApplet" width="250" height="100" codebase="/code" archive="Sample.jar">
The resulting blocks, returned using the @param() function are shown in Figure 4-1. There is also a default block, 0, which refers to the whole matched string.
@param(1) width=250 height=100 @param(2) /code @param(3) archive=Sample.jar Figure 4-1 Constituent Blocks
4.1.5 Process for applying regular expression rules

The Regular Expression rules are processed according to the order which they appear in the Domino Application Portlet Configuration page. A given piece of text can be transformed only once, by the first rule that matches it. This process means that text is only processed by one rule since once the parser matches a rule, the text is transformed and the parser skips on to the text after the matched input. The process for applying regular expression rules is as follows: 1. Begin at the first character of the input text. 2. Beginning with 1st rule, apply each rule in turn looking for a match. a. If a match is found, do not process further rules. Go to Step 3. b. If no match is found move to the next character in the input text. Return to Step 2. 3. Transform the found text according to the output model for the rule. Move to the character in the input text that is immediately after the found text. Return to Step 2.
Ordering of rules
Due to the method in which the rules are processed, the most specific rule must appear first in the ruleset. Since only one rule can match a given portion of text, if the specific rule appears after a more general one then it will never be hit. This is only an issue for similar rules, which may match a subset of the text matched by other rules. Both of the rules src="(.*?)_gif" and src="icon (.*?)_gif" would match the text src="icon print.gif". Since the first rule that matches is applied, the most specific rule should be placed highest in the list of rules. If a different transformation is required for images starting with the text icon, then this rule needs to be before the more general src="(.*?)_gif", otherwise it will never be applied.In this manner there may be several specific rules to deal with specialized cases and then one general rule to catch all other occurrences of the given text.
Chapter 4. Rules
25
Figure 4-2 Configuration Page Showing Regular Expression Rules
Rules to skip over text

Another feature of the rule processing is that rules can be designed to make the parser skip over portions of the text. A rule may be written which matches the text but that does not modify it. Since only one rule can match a given portion of text, no subsequent rules can be applied and the text remains unchanged. As described in 4.1.4, Blocks within the expressions on page 24, there is a default block (0), which refers to the entire matched string. Using the output function @param in conjunction with this block reference allows us to obtain the matched text. By outputting the matched input text, there is no change to the text. For example, if an input expression is:
src="special_icon(.*?)gif"
And the output model is:

@param(0)
Then the matched input text, e.g.,

src="special_icon65.gif"
This will remain unchanged in the output, even if there is a more general rule, such as src="(.*?)", further down the list.
26
Figure 4-3 Configuration Page Showing Case-Sensitive Box
Case-sensitivity
Regular expressions in the Domino Application Portlet are not case-sensitive by default, but you can select case-sensitivity for the input expression of any rule. In some circumstances we do not want to apply rules to specific pieces of text. The rule shown in Table 4-1 will match any possible capitalization of href (e.g Href, HREF,..) but will always produces a lowercase output. However if the case-sensitive box is selected beside the rule in the portlet configuration then only the case given in the input expression will match.
Table 4-1 Regular Expression Rule Showing Input & Output Expressions Input href=(.*?) Output href=@param(1)
Note: The input text must match the input expression exactly, including spaces.
4.2 HTML parser

In addition to the Regular Expression parser, a HTML parser has been provided which parses the input text based on its HTML structure. This parser also uses a set of rules for data transformation. However due to the complexity of the rules required for the Regular Expression parser, the rules used by the HTML parser are designed to be a more user-friendly alternative. Since most HTML pages also contain portions of JavaScript, the HTML parser must also deal with them. However, since JavaScript is not structured in the way that HTML is, the HTML parser cannot deal with the scripts itself. A dedicated JavaScript parser is planned for a future release, but currently when the HTML parser encounters JavaScript it calls out to the Regular Expression parser to parse the script. As with the Regular Expression rule structure discussed in 4.1, Regular expression parser on page 22, the HTML rules are divided into an input expression and an output expression. However these two expressions have been split into smaller constituent parts.
Chapter 4. Rules
27
4.2.1 Input expression

The input expression has been subdivided into three components: Tag Input Attribute Input Value The Tag component specifies the particular HTML tag that this rule is applied to. By specifying the Tag name, rules are only applied if that tag is found within the input HTML page. The input expression requires two additional components which identify the particular tag attribute/value pairs to search for. The Input Attribute specifies the attribute, of the given tag, that the rule is to be applied to. As a final level of detail, we can specify the value of the given attribute using the Input Value component. Since the HTML rules were designed to be easier to read, negating the need to understand regular expressions, we tried to keep each component as simple as possible. However, to allow some flexibility one wildcard character is allowed - the *. This is either used to signify any within one of the input components, or, in the case of Input Value, in conjunction with some text to signify any text beginning with. If all three components of the input expression match the input string then the rule is applied.
4.2.2 Output expression

Due to the structure of the HTML rules, a rule may transform the value of a particular attribute of a particular tag. Once a match has been found the attention switches to the output expression to decide what transformations to invoke. The output expression for the HTML rules is in two parts: Output Attribute Output Value HTML Rules are not allowed to search for attributes of one tag and then modify the values of different tags so there is no need to have a Tag component in the output expression. If such rule functionality is required then the Regular Expression parser must be used. The Output Attribute specifies the attribute name for the output. Often this is the same as the input attribute name, but this is not a requirement. For example, a rule specified on the param tag may use the name attribute to locate the appropriate portion of HTML, but it is the value attribute that will require modification. An illustration of this is shown in Table 4-2. The Output Value specifies the value for the output attribute. It comprises text optionally combined with a single output function.
Table 4-2 Sample HTML Rules Tag Input attr param a name href value data * Output attr value href value @transform uri all @transform uri abs
4.2.3 Output functions

The output functions provided for use with the HTML parser are mostly consistent with those available for the Regular Expression Parser.The functions listed below have been described in 4.1.2, Output functions on page 23. @transform_uri_abs 28
@transform_uri_all @host @proxypath @protocol @port @baseurl The @param(n) and @parencount output functions are specific to the Regular Expression parser and are not available for use with the HTML parser. There is one output function which is specific to the HTML parser, the @script function. This function is used to call out to the Regular Expression Parser when JavaScript is located within the HTML page. An example of using this function is shown in Table 4-3, where for any tag if an attribute called onclick is found, then the value of that attribute is transformed using the @script function. This rule is used to transform the JavaScript value of the onclick attribute.
Table 4-3 Sample HTML rule using the @script function Tag Input attr * onclick value * Output attr onclick value @script
4.2.4 Process for applying HTML rules

For a given Tag, Input Attribute and Input Value combination, only one rule can be applied. This mirrors the functionality of the Regular Expression parser, where only one rule can be applied to a given portion of input text. In the case that more than one rule matches a given combination, the most specific rule available is applied. The more detail a rule gives, the more specific it is. For example, a rule which uses the wildcard * to signify any tag is very general. In contrast, a rule which specifies the tagname is more specific. This applies to the attribute and value components as well.
Table 4-4 Example rules Rule Rule A Input value: Rule B Input value: Rule C Input value: Rule D Input value: Value Database Database* Data* *
If four rules are identical except for the Input attribute values shown in Example 4-4, then Rule A is the most specific, while Rule D is the least specific. Rule A will only match the exact text Database, all variants of this text will be ignored. Rule B is slightly more flexible, it will match all text beginning with Database. This means that Database2 and Database list will also match. Rule C is similar to Rule B, but since more of the text has been replaced by the wildcard it is more general. It will match Database, Database list and Data form. Finally, Rule D is the most general since any value will match. This is usually used in cases where the value will have to be modified, such as the value of a href attribute. Table 4-5 on page 30 illustrates some possible text matches based on the rules described in Table 4-4 If rules are identical, except for their Output Attribute and/or Output Value, the rule that appears first in the configuration is used, see Figure 4-4 on page 30.
Chapter 4. Rules
29
Table 4-5 Example text matches for rules in Table 4-4 on page 29 Text Database Database list Data form MyString Matched Rule A B C D
Figure 4-4 Configuration Page Showing HTML Rules
4.3 Correlation between the rulesets

As described in 4.1, Regular expression parser on page 22 and 4.2, HTML parser on page 27, the Regular Expression and HTML parsers function in different ways and so the rulesets for each one are structured differently. This has led to some differences in the rulesets. However, as a whole there is a general correlation between the rules as the parsers are basically performing the same function. For example, the Regular Expression rule shown in Table 4-6 is equivalent to the HTML rule shown in Table 4-7 on page 31. Both of these rules search for the HTML attribute src with any value and output the result of applying the transform uri abs function.
Table 4-6 Regular Expression rule Input src=(|)(.*?)\1 Output src=@param(1)@transform uri abs( @param(2))@param(1)
30
When the rules are compared in this way, it is easy to see the relative simplicity of the HTML rules versus their Regular Expression counterparts. However, this simplicity also means a lack of flexibility when defining a new rule. For this reason, the decision over which parser best suits your needs may depend on the complexity level of the rules you will need.
Table 4-7 Equivalent HTML rule Tag Input attr * src value * Output attr src value @transform uri abs
Chapter 4. Rules
31
32
Chapter 5.
Samples
Now that you have acquainted yourselves with the theoretical aspects that underlie the workings of DAP, you are ready to delve into a practical application. In order to complete the following tutorial you will need the following: 1. A Domino 6.X server (in this document well give it the fictitious name domino.domain.com) 2. A portal server (this one we call portal.domino.com) We will host a sample application, called Sample.nsf (supplied with this document), on the Domino server and configure DAP so that the same application will be visible through the portal. We aim to cover as many features of DAP as possible, so we will gradually increase the complexity of the setup.
33
5.1 Setting up Domino

The sample database (Sample.nsf) needs to be copied into the Data folder of the Domino server. This should be enough to expose the application through http://domino.domain.com/Sample.nsf. Initially, we will keep all authentication off. We will then enable this later, once weve verified that all other parts work as intended.
5.2 Setting up DAP

The portal server needs to have DAP installed, verify that this is the case through the administrative console. To check this, log into the portal as an administrative user through http://portal.domain.com:9081/wps/myportal. Note that we are connecting to the portal directly, depending on your setup you may omit the port and connect to the portal via the HTTP server. Navigate to the Administration section, then select Portlets -> Manage Portlets; the list should include an entry for a Domino Application Portlet. If that is the case you can go ahead and create a page to host the portlet, otherwise you have to install the portlet first.
5.2.1 Install portlet

To do that you will need a copy of the standalone portlet archive (dap.war); under Portlets click Install, browse to the archive, click Next, and finally confirm the action by clicking the Install button. You should see a message that confirms the installation of the portlet.
5.2.2 Create page

Now we need a page to host the portlet, to do this click Portal User Interface and then Manage Pages on the navigation bar on the left. We suggest you create the new page under the MyPortal label. Most out-of-the-box portal installations will have this section set up by default. So click the MyPortal link followed by the New Page button, give it a nice name, for example Sample Domino Application and confirm with OK.
5.2.3 Add portlet to page

To add the portlet to the page you click the pencil icon in the page list of the MyPortal section, this will lead you to the portal layout editor, keep the default layout for the page and click the Add Portlet button, you will be presented with a list of all the available portlets. Chances are that there are a lot of portlets installed on your system, so the easiest way to find DAP is to reduce the list by entering some search criteria. By searching for the word domino in the portlet titles, the list should reduce to a handful of portlets, tick the selection box next to Domino Application Portlet and click OK. The system should confirm the success of the last operation and to complete the addition of DAP to the page click the Done button. You can now look at a running instance of DAP by navigating to the MyPortal section and then to Sample Domino Application Page; you should see a window similar to Figure 5-1 on page 35.
34
Figure 5-1 Working DAP setup, portlet not yet configured
5.2.4 Initialize portlet

All that remains to do is to point DAP to the sample application on the Domino server, click the pencil icon and on the following page enter domino.domain.com (or rather, the actual name of the Domino server that you are using) as the host and Sample.nsf in the path and filename box. Click first on Save, then on the Close button. You must also check that authentication is set to None, to do that click the wrench icon to enter the portlet configuration mode and select the Authentication tab. DAP defaults to Basic authentication so you will probably have to select the None option. If you made any changes here click Save and then Close. Now you should see a window similar to Figure 5-2 on page 36. If that isnt the case, ensure you followed all the steps outlined above.
Chapter 5. Samples
35
Figure 5-2 Sample application as seen through DAP - note how the applet images failed to load
5.3 Exploring the application

You should also make yourself familiar with the application as seen directly from the Domino server, as there are a couple of issues with the one seen through the portal. The base rules that the portlet ships with will ensure that most of the application will work, yet we will focus on the bits that do not to illustrate DAPs modus operandi. So point your favorite browser to http://domino.domain.com/Sample.nsf and notice how there are some icons in the applets view area (Figure 5-3 on page 37), compare this with the portalized application (Figure 5-2). Also observe the behavior of the Info button of the sample application both when seen through DAP and when seen directly from Domino. In the following paragraphs we hope to introduce you to the art of rule-making, as you will see it will require a good dose of instinct and plenty of experience to successfully identify the fragments of a page that require some translation to be viewed through DAP.
36
Figure 5-3 The sample application as seen directly from Domino
5.4 Fixing the icons

As we mentioned the application viewed through DAP is missing two icons, being an applet the initial strategy is to inspect the applets tags both when viewed directly on Domino and when viewed through DAP. To view the markup of the two pages, right-click the frame and select View Source. This is what we saw on our test servers: From Domino: (Example 5-1)
Example 5-1 Example of code shown through Domino <applet width="250" height="100" codebase="/Sample.nsf/b2a27ff60012977280256eaf004e2b87/$FILE" code="myPack/TestApplet1.class" name="myApplet" archive="testApplet/Sample3.jar"> <param name="URL1" value="/icons/abook.gif"> <param name="URL2" value=""> </applet>
Chapter 5. Samples
37
Through DAP: (Example 5-2)

Example 5-2 Example of code shown through DAP <applet width="250" height="100" codebase="/wps/PA_1_0_69/rproxy/__PC_7_0_CL_PI_751987__/$$U2 FtcGxl$$.nsf/b2a27ff60012977280256eaf004e2b87/$FILE" code="myPack/TestApplet1.class" name="myApplet" archive="testApplet/Sample3.jar"> <param name="URL1" value="/icons/abook.gif"> <param name="URL2" value=""> </applet>
As you can see the codebase attribute of the applet tag is successfully reverse-proxied, and we urge you to find the corresponding rule in the standard ruleset that is responsible for this translation. You should also note that the URL1 parameter that is passed to the applet obviously refers to a resource on the Domino server, namely the abook.gif icon in the /icons folder. When the page is viewed through the portlet it will request the /icons/abook.gif image from the Portal server which will of course fail. What we need is a rule that will reverse-proxy the value of the URL parameter; click the spanner icon of the portlet and select the Rules tab. Ensure that the rule type is set to Regular Expression. Scroll to the bottom of the page and click the insert rule icon (Figure 5.4) of the last rule. Enter the following in the newly created boxes:
Figure 5-4 Insert Rule Icon
Regular expression:
<param name="URL1" value="(.*?)"
Output model:
<param name="URL1" value="@transform_uri_all(@param(1))"
Now click Save followed by Close, you should now see a small book icon in the applets box. If you look at the frames markup you should see that it has been reverse proxied:
<applet width="250" height="100" codebase="/wps/PA\_1_0_69/rproxy/__PC_7_0_CL_PI_714731__/$$U 2FtcGxl$$.nsf/b2a27ff60012977280256eaf004e2b87/$FILE" code="myPack/TestApplet1.class" name="myApplet" archive="testApplet/Sample3.jar"> <param name="URL1" value="/wps/PA_1_0_69/rproxy/__PC_7_0_CL_ PI_714731__/$$aWNvbnMvYWJvb2suZ2lm$$"> <param name="URL2" value=""> </applet>}
Unfortunately the second icon did not appear. A second more thorough look at the frames markup should identify the following section towards the end of page in need of translation:
... } function go() { document.applets["myApplet"].setImage2("/icons/actn001.gif"); } </script>
38
...
Clearly the applet is being modified programmatically and we need to reverse-proxy the string that is being passed to it through the setImage2 method. Append the following rule to the ruleset: Regular expression:
\.setImage2$"(.*?)"$
Output model:
.setImage2("@transform_uri_all(@param(1))")
After saving you should see both icons in the applets box, as shown in Figure 5-5.
Figure 5-5 Display of both icons in applets box
5.5 TCP/IP trace proxies

Admittedly this example is quite simple, you will find that generally it is considerably trickier to identify the text that requires processing by the parser. During development of the portlet we found that TCP tracing utilities are exceedingly useful for debugging purposes. These utilities act as a proxy and let you view a trace of all the request and responses between the browser and the portal and also between portal and the Domino server. WebSphere Studio Application Developer includes a special type of server a TCP Monitor which you can use as a tracer but you can also find freeware utilities on the Internet that offer the same functionality. Refer to the WebSphere Studio documentation to set up a TCP Monitor. A typical test setup would look like the one shown in Figure 5.6, assuming that the workstation that you are working on is computer.domain.com.
Figure 5-6 Set-up to capture HTTP traces with the use of proxy trace utilities
Chapter 5. Samples
39
You will need to configure your browser to route its requests to a proxy. Typically you would run the trace utility on your local machine, thus you would point your browser to localhost and whatever port you have configured your proxy trace utility to listen at. Note also that most Domino applications make use of applets which may make their own network requests. So make sure your plugin is configured to route HTTP requests to the proxy. Internet Explorers JVM does not support this but Suns Java plugin does, you can find the relevant options in the Java plug-in control panel under the Proxies tab. DAP, like a browser, can be configured to route all its requests to a proxy, this option is available in the configuration view under the Source and Display tab where you can specify the Proxy Source Server. For the above example setup we would set the proxy source server host to computer.domain.com and the port to 8081. We cant stress enough how useful a HTTP trace can be when debugging a DAP-ed application. For example if the applet of the sample application used a default location to find its icons it would not be immediately obvious that the icon is even being requested. If a proxy trace is in place we would see something like:
GET http://portal.domain.com:9081/icons/actn001.gif HTTP/1.1 cookie: JSESSIONID=000026kWPj0CPiVpb9-ZtxEeZgU:-1 User-Agent: Mozilla/4.0 (Windows 2000 5.0) Java/1.4.2 02 Host: portal.domain.com:9081 Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Proxy-Connection: keep-alive
Failing with:
HTTP/1.1 404 Not Found Server: WebSphere Application Server/5.0 Content-Type: text/html Content-Length: 159 <H1>Virtual Host or Web Application Not Found</H1><BR><H3> The web group /icons/actn001.gif has not been defined</H3><BR> <I>IBM WebSphere Application Server</I>
The mere presence of a 404 indicates that something is amiss. There is also a whole group of other problems that would be very hard to diagnose without the help of a trace, for instance it is often necessary to inspect data that is posted as a consequence of a form submission or it may happen that the wrong output model function is used to transform a particular URI which in turn results in some funny requests that without a trace would remain undetected.
5.6 Fixing the greedy information page

One thing you might not have noticed is that when you click the Info page of the application through DAP it will grab the entire page and seemingly leave the portal. We will have to look at what exactly happens when the Info button is clicked, here is what the buttons tag looked on our test setup:
<input type="button" onclick="var pathname = window.location.pathname; var path = pathname.substring(0,(pathname .lastIndexOf(\singlequote .nsf\singlequote )+5)); var myurl3=path+"/Info"; window.open(myurl3,"_top");" value="Info">
40
Obviously a series of JavaScript instructions are executed upon a click which assemble a URL from the current location and then the browser is then sent to it. Notice how the target frame for this operation is top. This is not quite what we want; instead we want the target to be ifa which is the IFRAME containing the reverse proxied page. Thus by adding the rule: Regular expression:
_top
Output model:
ifa
We will obtain the desired behavior. The above example is somewhat contrived, and the rules used to fix far from ideal. The problem is that the rule top is very general and it may well match some text that we do not want to translate. If the text top appears anywhere in the markup it will be translated, for example if elsewhere on the page we had a script with a variable named about to topple that would be transformed into about to ifaple which will in all likelihood prevent the page from working correctly. Sometimes it will prove too difficult to come up with regular expressions that are sufficiently discriminating, in this case you will have to provide pass-through rules for all the instances in which it matches something it shouldnt. In the example above, we would have to add a rule with about to topple as both regular expression and output model with a higher priority than the top-only rule to prevent it from being garbled.
5.7 Switching to the HTML parser

The three rules above have of course corresponding rules in the HTML parser. To try these out switch to the HTML parser and add the following rule: Input match:
Tag param Input attribute name Value URL1
Output:
Output attribute Output value value @transform_uri_all
This is the dual of the first rule we added for the regular expression parser. The other two rules are identical as they are processed by the javascript parser, so you can append them verbatim into the Java Script Rules section of the HTML parser configuration.
Chapter 5. Samples
41
Figure 5-7 Requiring authentication, Anonymous access is set to No Access
5.8 Escalating security

To start off with we had no security enabled. We will now proceed and ensure users are authenticated when they access a database through DAP. Using the Domino Administrative console modify the ACL so that Anonymous access is disabled for the Sample.nsf database (see Figure 5-7) and add one of your Domino users to the ACL1. Also ensure that session authentication is disabled in the server document under Internet Protocols Domino Web Engine. You should now see an error message when viewing the database through DAP (Figure 5.8).
1 If you get insufficient rights when modifying the ACL you may need to modify it locally before starting the Domino server
42
Figure 5-8 Domino requires authentication but DAP is not yet configured to supply credentials
To solve the situation we must set the corresponding authentication method for DAP, so navigate to the Authentication tab in the portlets configuration and select the basic Authentication model (see Figure 5-9).
Figure 5-9 Setting up DAP to use basic authentication
Now we only need to specify the credentials. Click the pencil icon and enter the username and password of a user in the databases ACL, once these are saved you should see the sample application as previously. Please refer to the chapter on authentication for a more in-depth description of the basic authentication scheme. It is not advised to use this authentication model if the communication channel between the Portal and the Domino server is not secured because the credentials are transferred unencrypted with each request, making it trivial for an eavesdropper to intercept them. The session authentication model is slightly more secure in that the credentials are transmitted to the host only once, so browse to DAPs configuration page and switch the authentication model to Session. You will see an error message similar to the one you saw earlier (see Figure 5-8, this is because the Domino server is not configured to accept session authentication yet). To enable this, open your Server Document in Domino Administrator or WebAdmin and under Internet Protocols Domino Web Engine set Session authentication to Single Server (see Figure 5-10 on page 44).
Chapter 5. Samples
43
Figure 5-10 Enabling Domino Session authentication
Save the document and restart the HTTP task to make the change effective (either restart the Domino server or type tell http restart in the console). DAP will now use the credentials that you used previously but instead of re-transmitting them with every request it will re-transmit only the authentication token it received from Domino. Enabling SSO is somewhat more involved we refer you back to the chapter on Authentication where you can find instructions on how to set up SSO between WebSphere and Domino.
5.9 Another sample

In this second example we are going to work with a mail database (instantiated from a mail6.ntf template) on the same Domino server that we used previously. We will assume that you created the database under mail/username.nsf; set up a new page with the Domino Application Portlet and point it to mail database. For this example you will need to import a custom ruleset, called Sample2Rules.xml, supplied with this document. You should also first save a copy of the original ruleset just in case you need to restore the portlet to its original state. To export a ruleset open the configuration view by clicking on the wrench icon and click the Rules tab. When you click the Export button you will be asked to specify a file name and location, for example you may enter OriginalRules.xml and note where the file will be saved. To import the ruleset for this sample, simply click the Import button and then browse to the file you downloaded earlier. Once you have completed all these steps view the page you just created and notice that the HTML has loaded, but the applet lotus.notes.apps.actionbar.ActionBar has failed to load. (Figure 5.11)
44
Figure 5-11 The action bar applet failed to load
Like in the previous example, the principal tool that we will utilize to debug the application will be tracing, so you will need a setup as described in the previous section to be able to inspect the requests and responses. So here is what we found in our test setup: Request:
GET http://portal.domain.com:9081/domjava/actionbar.jar HTTP/1.0 Accept-Language: en-IR Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Win32) Host: portal.domain.com:9081 Proxy-Connection: Keep-Alive Cookie: JSESSIONID=0000XGb_2MNQTpdvV_IhKLZd4WK:-1; wcp-context=wpsadmin@1@base
Response:
HTTP/1.1 404 Not Found Server: WebSphere Application Server/5.0 Content-Type: text/html Content-Length: 192 Connection: close <H1>Virtual Host or Web Application Not Found</H1><BR> <H3>The web group /domjava/actionbar.jar has not been defined</H3><BR><I>IBM WebSphere Application Server</I>
By examining this trace of the request/response interaction between the browser and the Domino Application Portlet, we can see that the request for actionbar.jar has generated a FileNotFound Error. The offending request was for the URL: http://portal.domain.com/domjava/actionbar.jar.
Chapter 5. Samples
45
However, the applet is located on the Domino Server not the Portal server, so it cant be found. Looking at the source code for this page shown in Figure 5-12, we can see that the location of the applet is /domjava. Since we are redirecting through the Portal Server, we need to transform this URL to reflect this.
Figure 5-12 The original source, which resulted in a request for /dom-java/actionbar.jar to the Portal server
We need a rule which takes the value of the codebase attribute and changes it to redirect it to the portal server. The output function @transform_uri_abs can perform this redirection. So our new rule is:
codebase="(.*?)" => codebase="@transform_uri_abs(@param(1))"
Figure 5-13 The HTML markup of the reverse-proxied page
As shown in Figure 5-13, this rule transforms /domjava into something like:
"/wps/PA_1_0_55L/rproxy/__PC_7_0_5BT_PI_891457__/$$ZG9tamF2YQ==$$".
This rule seeks out all text matching:

codebase="<anything>"
And transforms <anything> to point to the portal server. So:

<applet name="dominoActionBar" code="lotus.notes.apps.actionbar.ActionBar.class" codebase="/domjava" archive="actionbar.jar" mayscript>
Becomes:
<applet name="dominoActionBar"
46
code="lotus.notes.apps.actionbar.ActionBar.class" codebase="/wps/PA_1_0_55L/rproxy/__PC_7_0_5BT_PI_891457__/$$ZG9tamF2YQ==$$" archive="actionbar.jar" mayscript>
With this new rule, the applet can be found and loads properly (Figure 5-14).
Figure 5-14 Now the action bar displays correctly
Chapter 5. Samples
47
48
Chapter 6.
Updates to Domino Application Portlet 1.1

This chapter describes the modifications and new features present in the release of the Domino Application Portlet Version 1.1, which was released in September of 2004.
49
6.1 Debug tab

In the configuration section there is now a debug tab, which allows you to see the HTML returned by Domino, both before and after transformation. Here you can quickly locate the transformed text and identify the rule responsible for the transformation.
Figure 6-1 Debug Preview
Clicking on the Requests button returns a page which gives details of all the recent requests.(Figure 6-2) For each request you are given the following information: Time of each request Request URL shows the request itself Response code shows whether the request to Domino succeeded (green), was redirected (orange), or failed (red), and gives the relevant response code Content type is the mime type and character set of the content Additionally, you can see the Domino source HTML. You will see a link to the source HTML returned by the Domino server (Figure 6-3 on page 51) Transformed HTML a link to the source HTML after transformation (Figure 6-4 on page 51)
Figure 6-2 Debug Requests
50
Figure 6-3 shows the result of clicking on the Domino Source HTML link. Text that will be transformed by the parsers is colored blue. Hovering over the blue text displays a message that tells you which rule will be applied.
Figure 6-3 Debug Source
Figure 6-4 is the Transformed HTML. This time you see the results of applying rules to the text. Again, text that has been transformed by the parsers is colored blue. Hovering over the blue text displays a message that tells you which rule was applied.
Figure 6-4 Debug Transformed
6.2 Error reporting

Improvements have been made to the error reporting mechanism. DAP now provides the user with possible reasons for the errors and suggested fixes. For example Figure 6-5 shows how DAP deals with an error code returned as part of a response from the Domino server. This error arose from an incorrect name in the path variable in the edit settings. Here DAP has correctly suggested that the user check that the path and filename are correct in the Edit or Config settings.
Figure 6-5 Improved Error Reporting
Chapter 6. Updates to Domino Application Portlet 1.1
51
6.3 Customized rule sets

In DAP 1.1 each supported Web application now has its own ruleset e.g. MailD5.xml. This will improve performance if a user is only using one application. The default ruleset is also available (default_rules.xml) containing the rules for all the supported applications (except iNotes). New customized rulesets can be imported in the rules section in the configuration by clicking the Import button. The following rule set files are shipped with Domino Application portlet. Each rule set is designed for a particular Domino template. The name of the appropriate templates are shown in parentheses. default rules.xml (suitable for all templates except iNotes) mailD6.xml (mail6.ntf) and mailD5.xml (mail50.ntf) discussionD6.xml (discsw6.ntf) and discussionD5.xml (discsw50.ntf) reservationsD6.xml (resrc60.ntf) and reservationsD5.xml (resrc50.ntf) teamroomD6.xml (teamrm6.ntf) and teamroomD5.xml (teamrm50.ntf) iNotesD6.xml (iNotes6.ntf) and iNotesD5.xml (iNotes5.ntf)
6.4 Support for Domino Web Access (iNotes)

As explained above there are now rulesets for individual applications. Included among these are two rulesets that supports Domino Web Access application (iNotes). To provide DAP support for iNotes 5 or 6 replace your existing ruleset with the relevant ruleset as outlined above.
6.5 Selective MIME types for Rules tab

On the Rules tab the user can select/deselect mime types (Figure 6-6). Only files of the selected mime types will be parsed, resulting in improved performance as only relevant files will be processed.
Figure 6-6 Selecting Mime Types
6.6 Output functions

For those users interested in writing their own rules there are a number of new output functions available:
52
@path() or @path(HTML parser) This returns the name of the Domino database, for example user1.nsf @transform parent uri abs() or @transform parent uri abs(HTML parser) This returns the proxy portlet ID with the input added to the end. It is used to allow pages to target the iframe. Whereas in previous releases, the JavaScript attribute top was replaced with ifa, it is now replaced with @transform parent uri abs( ifa). For the HTML parser, this function always returns the iframe name. @transform server soft path() This is available only for the regular expression parser. It returns the path to the proxy servlet prefix, however the path does not include the server URL at the beginning.
6.7 Performance improvements

There have been changes made to improve the performance of the regular expression parser. Its throughput has been substantially increased and the performance is now roughly independent from the number of rules that the parser has to match against. The management of network connections has also been improved, this has resulted in Web applications that feel noticeably faster. Changes in the UI have improved the speed when switching between tabs on the Configuration page.
6.8 Default to users mail file

Often users do not know the path to their mail file and it is generally inferable from their username. DAP can now look up a user's mail file by using Portal's Collaborative Services. This feature is only available under WebSphere Portal 5.X. To enable the automatic mail file lookup the administrator must tick the "Default to user's mail file" check box in the Portlet Configuration view (Figure 6.7). It is important to leave the "Path and filename" empty as any value specified for it in either Configuration or Edit mode will override whatever path has been looked up in the directory. If "Default to user's mail file" is enabled and a user has not yet specified their credentials then the View mode will consist of a login form. Once some credentials have been supplied the view will display the Inbox. Note that a host must be specified. In a typical scenario the administrator would specify the host in Config Mode and hide the Domino Source Server settings from the Edit mode. When users log into the portal for the first time they will have to enter their mail file credential; later logons will bring them straight to their Inbox.
Figure 6-7 Default to Users mail file
For the lookup to work the right Collaborative Service must be enabled. These services are disabled by default, refer to the Portal Infocenter for details on configuring them. DAP needs
Chapter 6. Updates to Domino Application Portlet 1.1
53
the "Domino Directory Server" service enabled, to do this edit the Collaborative Services configuration file - CSEnvironment.properties - which typically can be found under the following directory: <WEBSPHERE DIR>/PortalServer/shared/app/config. The values that need to be set are:
# this is false by default CS_SERVER_DOMINO_DIRECTORY.enabled=true # change this to your Domino server CS_SERVER_DOMINO_DIRECTORY_1.hostname=my.server.com # for most set-ups these do not need to be changed CS_SERVER_DOMINO_DIRECTORY_1.port=389 CS_SERVER_DOMINO_DIRECTORY_1.ssl=false CS_SERVER_DOMINO_DIRECTORY_1.anonymous=true
To make any changes to CSEnvironment.properties effective the Portal server needs to be restarted.
6.9 New URL re-writing

This feature was introduced to improve the behavior of links to other documents. In DAP 1.0 links in documents are generally not rewritten as they are typically entered as complete URLs. Although it is possible to enter relative links in Domino Web Applications it may be considered a bit awkward. Given that the links are not rewritten, upon being clicked the target resource would typically be referenced directly and for most complete URLs this is the desired behavior. Consider for example the case in which a friend sends you a mail with a link to http://www.ibm.com, as you read the mail through DAP and click on the link, you expect the browser to move to that location and you would thus leave the portal. If your friend wants to send you a link to a document in a TeamRoom on another server the same happened in DAP 1.0, but in many situations the link would fail to work for example if the target server was protected by a firewall that interdicted connections from external sources. DAP 1.1 looks at links and if they appear to be links to Domino databases then it will rewrite them. Clicking on those links will keep the target application reverse proxied through DAP. As this modus operandi may not always be desirable, it is possible to turn this feature off and revert to the old 1.0 link rewriting behavior. This can be done by setting the portlet parameter "disable_cross_server_urls" to "yes" via the Portal Administration console in the Manage Portlets section.
54
Appendix A.
Known issues
Through feedback with customers and other developers, a number of issues have been brought to our attention. This section may assist you in identifying the source of any problems using the Domino Application Portlet.
55
A.1 Anonymous access issue

An issue occurs when the portlet authentication is turned off (anonymous portal user), but the database application still requires the user to authenticate. The user is presented with the Domino login screen, but authentication fails. This problem has been resolved in a hotfix and will be integrated into the next full release of DAP (Release 1.1).
A.2 Maximize portlet issue

In the current release of DAP, the width and height of the portlet are set in the Edit page and are not updated by the maximize action. This means that when the DAP portlet is maximized it remains at the defined size rather than taking up the full page.
A.3 Refresh
Currently performing a refresh of the browser window will result in the user being returned to the default page, based on the settings defined in Edit. This means that if a user is writing an email when the refresh is initiated, then the email is lost as the portlet returns to the default view for the mail database, the Inbox. A fix for this issue is proposed for Release 1.1 of DAP.
A.4 Language version issue

In the WebSphere Application Servers implementation of the HttpServletRequest.getRequestURI() method, HTTP requests are decoded if the requests URI contains percentage-encoded hexidecimal. This is a problem for some language versions of the Domino 6.5 databases where the translated view name is used in the URL instead of the alias. For example:
http://dominoserver.com/reserve.nsf/%E6%8C%89%E6%97%A5%E6%9C%9F %E9%A1%AF%E7%A4%BA%E9%A0%90%E7%B4%84?OpenView
Becomes:
http://dominoserver.com/reserve.nsf/ae??ae??eiAa~>>?OpenView
A.5 New window opening in Linux

If problems are encountered with actions that result in new windows opening (for example opening a document), the rules redirecting the target frame to ifa need to be changed to _self. For example, for Linux (only), you should change:
Input expression: target="_top" Output model: target="ifa"
To:
Input expression: target="_top" Output model: target="_self"
56
A.6 Alignment in BIDI language configuration and edit modes

When viewing configuration mode (wrench icon) in a BIDI language, the input and output fields will be LTR while the comment fields will display RTL. In order to display the rules correctly, with respect to soft characters like ( , ) and &, you must force fields containing these characters to display LTR.
A.7 Richtext applet icons

The icons to accept or reject a link do not display. This is because the icon path is specified in the applet itself, which cannot be modified.
Figure A-1 Richtext Applet Showing Missing Icons
A.8 Configuration performance (WPS 5.0)

The general portal server configuration (in Manage Portlets) is slow for Domino Application Portlet because of the relatively large quantity of configuration information. To overcome this, it is recommended that you use the Domino Web Application Portlet configuration mode (wrench icon) instead, which has improved performance times. Note - If you want to change the concrete portlet name (for example if you copy the concrete portlet) then you must use the configuration in Manage Portlets.
A.9 Configuration performance (WPS 4.1.2)

There is a known performance issue with the Domino Application Portlet configuration in WebSphere Portal Server 4.1.2, where switching tabs and saving the configuration is noticeably slower than in Version 5.0.
A.10 Load issue

On WPS 4.x, with heavy traffic accessing Domino Application Portlet, some users may receive a 500 error response code signalling a failed POST request to Domino.
A.11 Table properties

There is an issue with table properties (for example cell padding) in Domino Web Application Portlet, using the HTML parser. Domino is generating HTML with duplicate attribute names. The HTML parser overwrites the values because the attributes have the same name. This can result in the new property values not being used. Note - This is not an issue with the Regular Expression Parser.
Appendix A. Known issues
57
A.12 Domino Web Access

Domino Web Access (iNotes) is not supported with release 1.0 of the Domino Application Portlet. Note that in release 1.1 of the Domino Application Portlet, support has been provided for Domino Web Access through two application specific rulesets. See 6.4, Support for Domino Web Access (iNotes) on page 52.
58
Appendix B.
Additional material
This Redpaper refers to additional material that can be downloaded from the Internet as described below.
Locating the Web material

The Web material associated with this Redpaper is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/redp3917
Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with the Redpaper form number, REDP-3917-00.
Using the Web material

The additional Web material that accompanies this Redpaper includes the following files: File name DefaultRules.xml Sample.nsf Sample1Rules.xml Sample2Rules.xml Description Default Ruleset Sample Notes Database used for examples in this paper. Sample Ruleset Sample Ruleset
59
60
Related publications
The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this Redpaper.
IBM Redbooks
For information on ordering these publications, see How to get IBM Redbooks on page 61. Note that some of the documents referenced here may be available in softcopy only. Domino 6.5.1 and Extended Products: Integration Guide, SG24-6357 Portalizing Domino Applications: Integration with Portal 5.02 and Lotus Workplace 2.01, SG24-6466
Online resources
These Web sites and URLs are also relevant as further information sources: WebSphere Portal Development Zone - Info Center for WebSphere Portal 5.x
http://www-106.ibm.com/developerworks/websphere/zones/portal/proddoc.html#ic5
WebSphere Portal and Lotus Workplace Catalog

http://catalog.lotus.com/wps/portal/portalworkplace
How to get IBM Redbooks

You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site:
ibm.com/redbooks
Help from IBM

IBM Support and downloads
ibm.com/support
IBM Global Services

ibm.com/services
61
62
Back cover
IBM Lotus Domino Application Portlet

Configuration and Tips
Configuration and authentication Parsers and rulesets Examples and sample code
WebSphere Portal is a complete portal solution. It provides customers with integrated content and applications in addition to a unified, collaborative workplace. Domino is a comprehensive application platform. Customers have invested heavily to exploit the power of Domino in developing proprietary applications. As a result they are understandably reluctant to start again and move towards the benefits of a portal environment. The main question asked by such customers is how do we move our Domino Applications into a portal. Domino Application Portlet (DAP) provides the solution. It facilitates the easy integration of Domino Web Applications into a portal server. This IBM Redpaper describes the Domino Application Portlet (DAP) in detail and gives practical examples for configuring and customizing this portlet.
Redpaper
INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION
BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.
For more information: ibm.com/redbooks

REDP-3917-00

Lotus Domino App Portlet Configuration-Redp3917

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Lotus Domino App Portlet Configuration-Redp3917

Caricato da

Copyright:

Formati disponibili

Front cover

IBM Lotus Domino no Application Portlet

Examples and sample code

Thomas Delahunty Kornelius Elstner James Ryan Katherine Sewell

Copyright IBM Corp. 2004. All rights reserved.

IBM Lotus Domino Application Portlet: Configuration and Tips

Copyright IBM Corp. 2004. All rights reserved.

IBM Lotus Domino Application Portlet: Configuration and Tips

Become a published author

Send your comments in an email to:

Copyright IBM Corp. 2004. All rights reserved.

IBM Lotus Domino Application Portlet: Configuration and Tips

Copyright IBM Corp. 2004. All rights reserved.

Figure 1-1 Initial DAP window

1.1.1 Setup if you have installed Domino Extended Product portlets

IBM Lotus Domino Application Portlet: Configuration and Tips

Figure 1-2 Domino Application Portlet included as an Extended Product Portlet

1.2 Configuration options

1.2.1 Source and Display tab

Figure 1-3 Source and Display UI

IBM Lotus Domino Application Portlet: Configuration and Tips

Figure 1-4 Authentication UI

Figure 1-5 Caching UI

Figure 1-6 Rules UI

1.3 Edit options

Figure 1-7 Edit UI

IBM Lotus Domino Application Portlet: Configuration and Tips

Figure 1-8 Edit UI

IBM Lotus Domino Application Portlet: Configuration and Tips

Copyright IBM Corp. 2004. All rights reserved.

Figure 2-1 Authentication UI

2.3 Basic authentication

IBM Lotus Domino Application Portlet: Configuration and Tips

2.4 Session based authentication

2.5 Single sign on

2.5.1 Single sign on setup

Figure 2-2 WebSphere LTPA Configuration

Figure 2-3 Domino SSO Configuration

IBM Lotus Domino Application Portlet: Configuration and Tips

Figure 2-4 Domino Server Configuration

2.6 Credential vault

2.6.1 System slot

Figure 2-5 Credential Vault Settings

Figure 2-6 System slot

2.6.2 Shared slot

2.6.3 Private slot

IBM Lotus Domino Application Portlet: Configuration and Tips

Copyright IBM Corp. 2004. All rights reserved.

3.1 Types of caching

IBM Lotus Domino Application Portlet: Configuration and Tips

Figure 3-1 Caching

3.3 Cacheable objects

Figure 3-2 Caching

IBM Lotus Domino Application Portlet: Configuration and Tips

The order is: 1. 2. 3. 4. User and Application User Application Shared

3.4 Cache size

Figure 3-3 Clear Cache button

3.5 Using caching to improve DAP performance

IBM Lotus Domino Application Portlet: Configuration and Tips

Copyright IBM Corp. 2004. All rights reserved.

4.1 Regular expression parser

4.1.1 Input expressions

IBM Lotus Domino Application Portlet: Configuration and Tips