8/3/2019 Lotus Domino App Portlet Configuration-redp3917
1/74ibm.com/redbooks
Redpaper
Front cover
IBM Lotus DominonoApplication PortletConfiguration and Tips
Thomas Delahunt
Kornelius Elstne
James Rya
Katherine Sewe
Configuration and authentication
Parsers and rulesets
Examples and sample code
http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/8/3/2019 Lotus Domino App Portlet Configuration-redp3917
2/74
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
3/74
International Technical Support Organization
IBM Lotus Domino Application PortletConfiguration and Tips
December 2004
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
4/74
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.
First Edition (December 2004)
This edition applies to Version 1.0 and Version 1.1 of the Domino Application Portlet
Note: Before using this information and the product it supports, read the information in Notices on page v.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
5/74
Copyright IBM Corp. 2004. All rights reserved.iii
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Chapter 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Setup if you have installed Domino Extended Product portlets . . . . . . . . . . . . . . . 2
1.2 Configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 Source and Display tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.3 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.4 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3 Edit options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.6.3 Private slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.1 Types of caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2 Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.3 Cacheable objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.4 Cache size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.5 Using caching to improve DAP performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Chapter 4. Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1 Regular expression parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.1.1 Input expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.1.2 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234.1.3 Output expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.1.4 Blocks within the expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.1.5 Process for applying regular expression rules . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.2 HTML parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2.1 Input expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.2 Output expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.3 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.4 Process for applying HTML rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.3 Correlation between the rulesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
6/74
iv IBM Lotus Domino Application Portlet: Configuration and Tips
Chapter 5. Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335.1 Setting up Domino. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2 Setting up DAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2.1 Install portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2.2 Create page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2.3 Add portlet to page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2.4 Initialize portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355.3 Exploring the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.4 Fixing the icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.5 TCP/IP trace proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.6 Fixing the greedy information page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.7 Switching to the HTML parser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.8 Escalating security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.9 Another sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 6. Updates to Domino Application Portlet 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . 496.1 Debug tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.2 Error reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6.3 Customized rule sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.4 Support for Domino Web Access (iNotes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.5 Selective MIME types for Rules tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.6 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.7 Performance improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.8 Default to users mail file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.9 New URL re-writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Appendix A. Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55A.1 Anonymous access issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
A.2 Maximize portlet issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
A.3 Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
A.4 Language version issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
A.5 New window opening in Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56A.6 Alignment in BIDI language configuration and edit modes . . . . . . . . . . . . . . . . . . . . . . 57
A.7 Richtext applet icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
A.8 Configuration performance (WPS 5.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
A.9 Configuration performance (WPS 4.1.2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
A.10 Load issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
A.11 Table properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
A.12 Domino Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
7/74
Copyright IBM Corp. 2004. All rights reserved.v
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. Consultyour local IBM representative for information on the products and services currently available in your area. Anyreference 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 notinfringe any IBM intellectual property right may be used instead. However, it is the user's responsibility toevaluate 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. Thefurnishing of this document does not give you any license to these patents. You can send license inquiries, inwriting, 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 areinconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "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 ofexpress 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 madeto the information herein; these changes will be incorporated in new editions of the publication. IBM may makeimprovements and/or changes in the product(s) and/or the program(s) described in this publication at any timewithout notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in anymanner serve as an endorsement of those Web sites. The materials at those Web sites are not part of thematerials 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 incurringany obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their publishedannouncements or other publicly available sources. IBM has not tested those products and cannot confirm theaccuracy of performance, compatibility or any other claims related to non-IBM products. Questions on thecapabilities 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 themas 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 businessenterprise is entirely coincidental.
COPYRIGHT LICENSE:This information contains sample application programs in source language, which illustrates programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programs inany 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 sampleprograms 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, anddistribute 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.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
8/74
vi IBM Lotus Domino Application Portlet: Configuration and Tips
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.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
9/74
Copyright IBM Corp. 2004. All rights reserved.vii
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 acomprehensive application platform. Customers have invested heavily to exploit the power of
Domino in developing proprietary applications. As a result they are understandably reluctantto 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. DominoApplication Portlet (DAP) provides the solution. It facilitates the easy integration of DominoWeb 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 withspecific products or solutions, while getting hands-on experience with leading-edge
technologies. You'll team with IBM technical professionals, Business Partners and/orcustomers.
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 productivityand 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 thisRedpaper 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:
Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. JLU Mail Station P0992455 South Road
Poughkeepsie, New York 12601-5400
http://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/contacts.htmlhttp://www.redbooks.ibm.com/contacts.htmlhttp://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/residencies.html8/3/2019 Lotus Domino App Portlet Configuration-redp3917
10/74
viii IBM Lotus Domino Application Portlet: Configuration and Tips
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
11/74
Copyright IBM Corp. 2004. All rights reserved.1
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 theseexisting applications into portlets and display them on a portal server with minimaldevelopment 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 navigationalscheme of the portal.
The Domino Application Portlet acts like a reverse proxy, proxying the content from the backend 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 ofthe 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 isfollowed 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 setupDAP 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 havebeen 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
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
12/74
2 IBM Lotus Domino Application Portlet: Configuration and Tips
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 por tal server you must be logged in with administrator rights onthe 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 existingWebSphere Portal Collaboration Center portlets and therefore offer the ability to integrate the
application functionality of the Domino 6.5.1 platform into a intell igent common user interfaceserved 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 thetabs where you would see the Domino Application portlet and shows a sample Domino Web
application being rendered through DAP.
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.
Attention: If you want to learn more about installing and configuring the Domino ExtendedProducts 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
http://www.redbooks.ibm.com/abstracts/sg246357.htmlhttp://www.redbooks.ibm.com/abstracts/sg246357.html8/3/2019 Lotus Domino App Portlet Configuration-redp3917
13/74
Chapter 1. Introduction3
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 handcorner 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 userto 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. Finallythis tab also lets the user configure the iframe in which the DAP portlet displays the Dominocontent. The show in edit mode check box permits some of these options to be made
Domino Application Portlet
My Workplace Tab - access to fully integrated collaborative portlets
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
14/74
4 IBM Lotus Domino Application Portlet: Configuration and Tips
available to a normal portlet user in edit mode. So for example, a normal user could configurea DAP portlet to point to his/her mail database without having to have administrator rights forthe 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 serverand 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. Noteif 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 inChapter 2, Authentication on page 9.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
15/74
Chapter 1. Introduction5
Figure 1-4 Authentication UI
1.2.3 Caching
Within the Caching tab settings that affect the storage of cached objects from DAP may beset. 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 howobjects that are passed between Domino and DAP are stored. This caching takes place onthe 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
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
16/74
6 IBM Lotus Domino Application Portlet: Configuration and Tips
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 twoforms 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 onpage 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 thatthe Administrator decided to allow a normal user to configure. These may include the Domino
Database settings and the display settings.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
17/74
Chapter 1. Introduction7
Figure 1-8 Edit UI
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
18/74
8 IBM Lotus Domino Application Portlet: Configuration and Tips
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
19/74
Copyright IBM Corp. 2004. All rights reserved.9
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 indetail:
No authentication Basic authentication Session based authentication Single sign on Credential vault
2
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
20/74
10 IBM Lotus Domino Application Portlet: Configuration and Tips
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) canuse 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 toauthenticate by configuring the Domino Application Portlet with a lower model than theDomino server requires. For example, you can authenticate against a Domino server
configured for single-session authentication by specifying Basic authentication in the DominoApplication Portlet. However, you should generally match the portlet authentication modelwith the Domino server it is accessing.
2.2 No authentication
If the target server and database application does not require any authentication then thenone 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, usesbasic 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 thepassword 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 theserver.
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 thistype of slot is selected. Refer to 2.6.1, System slot on page 14 for further informationregarding this.
It then creates a header in the following format:
Header name: AuthenticationHeader value: Basic: Ghy753Jk03==??}
The header value contains the authentication model being used together with thebase64-encoding of the string username:password.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
21/74
Chapter 2. Authentication11
Upon receiving the request, Domino base64-decodes the string to reveal the username andpassword, which it then validates.
2.4 Session based authentication
DAP also provides for session authentication. Session-based authentication differs from basicpassword authentication in that the user name and password is replaced by a cookie. Theuser 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 Port Path and filenamehttp:// dominoserver.lan :80 /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\&redirectto=/mail/userA.nsf
When Domino receives this request, it validates the username and password and sends backa 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 toa 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 isgenerated by the server is sent to the browser in a cookie. You can set this up by creating adomain-wide configuration document -the Web SSO Configuration document - in the DominoDirectory. You initialize the configuration document by importing LTPA keys from WebSphere
(you will need the password specified when generating the keys in WebSphere). When SSOis 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 IBMWebSphereApplication Serverv5.0 Administrative Console)
2. Go to Security Authentication Mechanisms and click LTPA, as shown in Figure 2-2on page 12.
3. Enter the password to be used, and a file name that will contain the exported key.
4. Press Export keys button.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
22/74
12 IBM Lotus Domino Application Portlet: Configuration and Tips
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 SSOConfiguration as shown in
Figure 2-3.
Figure 2-3 Domino SSO Configuration
4. Press the Keys... button, then select ImportWebSphere 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 DominoWeb Engine tab, as shown in Figure 2-4 on page 13.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
23/74
Chapter 2. Authentication13
Figure 2-4 Domino Server Configuration
11.For Session Authentication select Multiple Servers (SSO). For Web SSOConfiguration, 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 vaultThe 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 alsoprovide 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 nocredential 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 whereportlets, such as Domino Application Portlet, store and retrieve a user's credentials (forexample, login details). Each slot holds one credential.Domino Application Portlet uses thedefault segment only. There are three different types of slots where credentials can be stored
and retrieved by DAP.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
24/74
14 IBM Lotus Domino Application Portlet: Configuration and Tips
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 portletsettings, 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 AdministrationAccessCredential 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 Portletinstances 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 thatuser.
2.6.3 Private slot
Credentials that are stored in a private slot are not accessible by all Domino ApplicationPortlet instances for a given user. They are only accessible by the user whilst accessing the
portlet instance that stored the credentials.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
25/74
Copyright IBM Corp. 2004. All rights reserved.15
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
3
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
26/74
16 IBM Lotus Domino Application Portlet: Configuration and Tips
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 onlywhile 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 putthem into the cache.
Shared (least secure)
Cached objects can be accessed by any user or application, regardless of whichapplication 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 aparticular server, D1, D2 and D3. On each instance of DAP there are various users accessingthem. 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 DAPinstance D1.
D1 - UA and D2 - UA The object is accessible by user A whilst accessing either DAP
instance D1 or D2.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
27/74
Chapter 3. Caching17
Figure 3-1 Caching
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
28/74
18 IBM Lotus Domino Application Portlet: Configuration and Tips
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 limitshared 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 listprovided 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) arecached 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 allparts 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 sharedand application caching. If an object qualifies to be cached into more than one part, order will
be used to decide.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
29/74
Chapter 3. Caching19
The order is:
1. User and Application
2. User3. Application4. Shared
For example, if both "User and Application" and "Application" caching are selected, and anobject qualifies to be cached in both, "User and Application" will be chosen. This is because itis 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 reachedits 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 tobe 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 portletinstances. For example, once a frequently requested image from Domino is stored in DAPsShared 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. Ifwe 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 fromDomino and keep a copy of it in memory.
Another way to improve performance using caching is to carefully configure the maximumsize 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 carefullyassigned if space is an issue.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
30/74
20 IBM Lotus Domino Application Portlet: Configuration and Tips
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
31/74
Copyright IBM Corp. 2004. All rights reserved.21
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 thesame way as directly accessing it through an Internet browser. References to resources, suchas 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 andlinks 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 toredirect 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 portletadministrator, in order to tailor the por tlet to support a new database application.
In this chapter, these topics are discussed in detail:
Regular expression parser HTML parser Correlation between the rulesets
4
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
32/74
22 IBM Lotus Domino Application Portlet: Configuration and Tips
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 eachposition to one of the defined rules.
The regular expressions are composed of an input expression and an output expression. Theinput 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 beplain 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 exacttext 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="", which gives us much moreflexibility and power when writing rules.
Regular expressionsThe 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 expressioncharacters 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
http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.htmlhttp://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html8/3/2019 Lotus Domino App Portlet Configuration-redp3917
33/74
Chapter 4. Rules23
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 proxyingcapabilities.
@transform_uri_absThis 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 andencoded 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 thecorresponding path of the required resource.
@transform_uri_allThis function operates in a similar manner to transform_uri_abs, but it transforms the URLwhether it is absolute (beginning with a forwardslash / ) or relative to the current path. Forexample, if the current path is http://dominoserver.ibm.com/mydb.nsf/myfolder then a URLof "mail.gif" would be appended to this path, resulting in a URL ofhttp://dominoserver.ibm.com/mydb.nsf/myfolder/mail.gif. This functionality is maintainedby the transform_uri_all function, which generates URLs of the typehttp://portalserver/wps/PA 11 0/rproxy/$$cGDdv$$.nsf/myfolder/mail.gif.
@proxypathReturns the servlet path that is used to replace the link to the Domino server. An exampleresult of applying this function is /wps/PA 1 0 69/rproxy. This path would then be used toconstruct a transformed URL.
@hostReturns the name of the Domino Server machine on which the current application is located[e.g.dominoserver.ibm.com.].
@protocolThis function returns the protocol used by the Domino Server (e.g., http or https).
@portThis 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, Blockswithin the expressions on page 24.
@parencountReturns the number of blocks (parenthesized expressions) within the input.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
34/74
24 IBM Lotus Domino Application Portlet: Configuration and Tips
@baseurlThis 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 onthe 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=""
This will replace all occurrences of with/mail/user3.nsf/83997d314a7?ReadForm. In order to deal with the more general case wherewe want to transform the string based on the input string, an output function (as described in4.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="" is:
action="wps/PA_1_0_V9/rproxy/__PC_7_0_18L_PI_432667__/"
4.1.4 Blocks within the expressions
The input expression is divided up according to the groups of parentheses it contains. Stayingwith 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 onlyone 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 outputexpressions 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:
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
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
35/74
Chapter 4. Rules25
In order to refer to the URL within the output expression, we would use the following functioncall:
@param(1)
Using a more complicated example, the input expression:
This will match all instances of applets called myApplet. For one such instance:
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.
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 onlyonce, 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 tothe 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 characterin the input text that is immediately after the found text. Return to Step 2.
Ordering of rulesDue 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 ruleappears 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="iconprint.gif". Since the first rule that matches is applied, the most specific rule should beplaced 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 giventext.
@param(1) width=250 height=100@param(2) /code@param(3) archive=Sample.jar
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
36/74
26 IBM Lotus Domino Application Portlet: Configuration and Tips
Figure 4-2 Configuration Page Showing Regular Expression Rules
Rules to skip over textAnother 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 notmodify 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 withthis 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 assrc="(.*?)", further down the list.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
37/74
Chapter 4. Rules27
Figure 4-3 Configuration Page Showing Case-Sensitive Box
Case-sensitivityRegular 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 wedo 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 lowercaseoutput. However if the case-sensitive box is selected beside the rule in the portletconfiguration then only the case given in the input expression will match.
Table 4-1 Regular Expression Rule Showing Input & Output Expressions
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 datatransformation. However due to the complexity of the rules required for the RegularExpression parser, the rules used by the HTML parser are designed to be a more
user-friendly alternative.
Since most HTML pages also contain por tions of JavaScript, the HTML parser must also deal
with them. However, since JavaScript is not structured in the way that HTML is, the HTMLparser 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 RegularExpression 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 par ts.
Input Output
href=(.*?) href=@param(1)
Note: The input text must match the input expression exactly, including spaces.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
38/74
28 IBM Lotus Domino Application Portlet: Configuration and Tips
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. Byspecifying the Tag name, rules are only applied if that tag is found within the input HTMLpage. 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. Asa final level of detail, we can specify the value of the given attribute using the Input Valuecomponent. 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, inconjunction 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 outputexpression 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 ofdifferent tags so there is no need to have a Tag component in the output expression. If suchrule 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 inputattribute 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 valueattribute 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 asingle output function.
Table 4-2 Sample HTML Rules
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 describedin 4.1.2, Output functions on page 23.
@transform_uri_abs
Tag Input Output
param
attr value attr value
name data value @transform uri all
a href * href @transform uri abs
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
39/74
Chapter 4. Rules29
@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 whichis specific to the HTML parser, the @script function. This function is used to call out to theRegular Expression Parser when JavaScript is located within the HTML page. An example ofusing this function is shown in Table 4-3, where for any tag if an attribute called onclickisfound, then the value of that attribute is transformed using the @script function. This rule isused to transform the JavaScript value of the onclickattribute.
Table 4-3 Sample HTML rule using the @script function
4.2.4 Process for applying HTML rules
For a given Tag, Input Attribute and Input Value combination, only one rule can beapplied. This mirrors the functionality of the Regular Expression parser, where only one rulecan be applied to a given portion of input text. In the case that more than one rule matches agiven 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 verygeneral. 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
If four rules are identical except for the Input attribute values shown in Example 4-4, then RuleA 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 matchall 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 thewildcard 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 30illustrates 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 inthe configuration is used, see Figure 4-4 on page 30.
Tag Input Output
*
attr value attr value
onclick * onclick @script
Rule Value
Rule A Input value: Database
Rule B Input value: Database*
Rule C Input value: Data*
Rule D Input value: *
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
40/74
30 IBM Lotus Domino Application Portlet: Configuration and Tips
Table 4-5 Example text matches for rules inTable 4-4 on page 29
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 therulesets 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 parsersare basically performing the same function.
For example, the Regular Expression rule shown in Table 4-6 is equivalent to the HTML ruleshown 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
Text Matched Rule
Database A
Database list B
Data form C
MyString D
Input Output
src=(|)(.*?)\1 src=@param(1)@transform uri abs(
@param(2))@param(1)
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
41/74
Chapter 4. Rules31
When the rules are compared in this way, it is easy to see the relative simplicity of the HTMLrules versus their Regular Expression counterparts. However, this simplicity also means alack 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 Output
*
attr value attr value
src * src @transform uri abs
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
42/74
32 IBM Lotus Domino Application Portlet: Configuration and Tips
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
43/74
Copyright IBM Corp. 2004. All rights reserved.33
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 thefollowing tutorial you will need the following:
1. A Domino 6.X server (in this document well give it the fictitious namedomino.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 theportal. We aim to cover as many features of DAP as possible, so we will gradually increase
the complexity of the setup.
5
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
44/74
34 IBM Lotus Domino Application Portlet: Configuration and Tips
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 throughhttp://domino.domain.com/Sample.nsf. Initially, we will keep all authentication off. We willthen 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 throughhttp://portal.domain.com:9081/wps/myportal. Note that we are connecting to the portaldirectly, 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 theInstall button. You should see a message that confirms the installation of the por tlet.
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 underthe MyPortal label. Most out-of-the-box portal installations will have this section set up bydefault. 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 arethat there are a lot of portlets installed on your system, so the easiest way to find DAP is toreduce 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 toDomino 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 cannow 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.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
45/74
Chapter 5. Samples35
Figure 5-1 Working DAP setup, portlet not yet configured
5.2.4 Initialize portletAll that remains to do is to point DAP to the sample application on the Domino server, click thepencil 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 filenamebox. 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 selectthe 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 stepsoutlined above.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
46/74
36 IBM Lotus Domino Application Portlet: Configuration and Tips
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 rulesthat 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 tohttp://domino.domain.com/Sample.nsf and notice how there are some icons in the appletsview 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 tointroduce 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 sometranslation to be viewed through DAP.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
47/74
Chapter 5. Samples37
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 appletthe 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 andselect 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
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
48/74
38 IBM Lotus Domino Application Portlet: Configuration and Tips
Through DAP: (Example 5-2)
Example 5-2 Example of code shown through DAP
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 thistranslation. You should also note that the URL1 parameter that is passed to the appletobviously 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 imagefrom 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 createdboxes:
Figure 5-4 Insert Rule Icon
Regular expression:
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
49/74
Chapter 5. Samples39
...
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 theruleset: 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 wefound 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 browserand 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 asa 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 setupwould look like the one shown in Figure 5.6, assuming that the workstation that you areworking on is computer.domain.com.
Figure 5-6 Set-up to capture HTTP traces with the use of proxy trace utilities
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
50/74
40 IBM Lotus Domino Application Portlet: Configuration and Tips
You will need to configure your browser to route its requests to a proxy. Typically you wouldrun the trace utility on your local machine, thus you would point your browser to localhostand 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. Somake 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 inthe 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 theSource and Display tab where you can specify the Proxy Source Server.
For the above example setup we would set the proxy source server host tocomputer.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 inplace we would see something like:
GET http://portal.domain.com:9081/icons/actn001.gif HTTP/1.1cookie: JSESSIONID=000026kWPj0CPiVpb9-ZtxEeZgU:-1
User-Agent: Mozilla/4.0 (Windows 2000 5.0) Java/1.4.2 02Host: portal.domain.com:9081Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2Proxy-Connection: keep-alive
Failing with:
HTTP/1.1 404 Not FoundServer: WebSphere Application
Server/5.0Content-Type: text/htmlContent-Length: 159Virtual Host or
Web Application NotFound
The web group /icons/actn001.gif has not beendefined
IBM WebSphere Application Server
The mere presence of a 404 indicates that something is amiss. There is also a whole group ofother 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 itmay happen that the wrong output model function is used to transform a particular URI whichin 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 applicationthrough 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 lookedon our test setup:
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
51/74
Chapter 5. Samples41
Obviously a series of JavaScript instructions are executed upon a click which assemble aURL from the current location and then the browser is then sent to it. Notice how the targetframe 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 themarkup 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 inall 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 haveto 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 regularexpression and output model with a higher priority than the top-only rule to prevent it frombeing garbled.
5.7 Switching to the HTML parser
The three rules above have of course corresponding rules in the HTML parser. To try theseout switch to the HTML parser and add the following rule:
Input match:
Tag paramInput attribute nameValue URL1
Output:
Output attribute valueOutput value @transform_uri_all
This is the dual of the first rule we added for the regular expression parser. The other tworules 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.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
52/74
42 IBM Lotus Domino Application Portlet: Configuration and Tips
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 areauthenticated when they access a database through DAP. Using the Domino Administrativeconsole 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 sessionauthentication is disabled in the server document under Internet ProtocolsDomino 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
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
53/74
Chapter 5. Samples43
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, sonavigate to the Authentication tab in the portlets configuration and select the basicAuthentication 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 usernameand 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 morein-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 Dominoserver 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 isslightly more secure in that the credentials are transmitted to the host only once, so browse toDAPs 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 Dominoserver is not configured to accept session authentication yet). To enable this, open your
Server Document in Domino Administrator or WebAdmin and under Internet ProtocolsDomino Web Engine set Session authentication to Single Server (see Figure 5-10 on
page 44).
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
54/74
44 IBM Lotus Domino Application Portlet: Configuration and Tips
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 thatyou 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 moreinvolved 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 amail6.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 DominoApplication 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 firstsave a copy of the original ruleset just in case you need to restore the portlet to its originalstate. 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 andlocation, 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 fileyou downloaded earlier. Once you have completed all these steps view the page you just
created and notice that the HTML has loaded, but the appletlotus.notes.apps.actionbar.ActionBar has failed to load. (Figure 5.11)
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
55/74
Chapter 5. Samples45
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 willbe 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.0Accept-Language: en-IR
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Win32)Host: portal.domain.com:9081Proxy-Connection: Keep-AliveCookie: JSESSIONID=0000XGb_2MNQTpdvV_IhKLZd4WK:-1;
wcp-context=wpsadmin@1@base
Response:
HTTP/1.1 404 Not FoundServer: WebSphere Application Server/5.0Content-Type: text/htmlContent-Length: 192Connection: close
Virtual Host or Web Application Not Found
The web group /domjava/actionbar.jar has not beendefined
IBM WebSphere Application Server
By examining this trace of the request/response interaction between the browser and theDomino Application Portlet, we can see that the request for actionbar.jar has generated aFileNotFound Error. The offending request was for the URL:http://portal.domain.com/domjava/actionbar.jar.
8/3/2019 Lotus Domino App Portlet Configuration-redp3917
56/74
46 IBM Lotus Domino Application Portlet: Configuration and Tips
However, the applet is located on the Domino Server not the Portal server, so it cant befound.
Looking at the source code for this page shown in Figure 5-12, we can see that the location ofthe 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 tothe portal server. The output function @transform_uri_abs can perform this redirection. Soour new rule is:
codebase="(.*?)" => codebase="@transform_uri_abs(@param(1))"
Figure 5-13 The HTML markup of the reverse-proxied page
As shown
Top Related