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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
16
16
18
19
19
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
34
34
34
34
34
35
36
37
39
40
41
42
44
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 user’s mail file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.9 New URL re-writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
50
51
52
52
52
52
53
53
54
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
IBM Lotus Domino Application Portlet: Configuration and Tips
61
61
61
61
61
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.
© Copyright IBM Corp. 2004. All rights reserved.
v
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
© Copyright IBM Corp. 2004. All rights reserved.
vii
viii
IBM Lotus Domino Application Portlet: Configuration and Tips
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 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.
© Copyright IBM Corp. 2004. All rights reserved.
1
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.
2
IBM Lotus Domino Application Portlet: Configuration and Tips
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
3
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.
4
IBM Lotus Domino Application Portlet: Configuration and Tips
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 it’s 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
Chapter 1. Introduction
5
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.
6
IBM Lotus Domino Application Portlet: Configuration and Tips
Figure 1-8 Edit UI
Chapter 1. Introduction
7
8
IBM Lotus Domino Application Portlet: Configuration and Tips
2
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
© Copyright IBM Corp. 2004. All rights reserved.
9
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
3
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
© Copyright IBM Corp. 2004. All rights reserved.
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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 DAP’s
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
IBM Lotus Domino Application Portlet: Configuration and Tips
4
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
© Copyright IBM Corp. 2004. All rights reserved.
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
Output
href=”(.*?)”
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
Output
attr
value
attr
value
param
name
data
value
@transform uri all
a
href
*
href
@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
IBM Lotus Domino Application Portlet: Configuration and Tips
@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
Output
attr
value
attr
value
onclick
*
onclick
@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
Value
Rule A Input value:
Database
Rule B Input value:
Database*
Rule C Input value:
Data*
Rule D Input value:
*
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
Matched Rule
Database
A
Database list
B
Data form
C
MyString
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
30
Input
Output
src=(”|’)(.*?)\1
src=@param(1)@transform uri abs(
@param(2))@param(1)
IBM Lotus Domino Application Portlet: Configuration and Tips
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
Output
attr
value
attr
value
src
*
src
@transform uri abs
Chapter 4. Rules
31
32
IBM Lotus Domino Application Portlet: Configuration and Tips
5
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 we’ll 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.
© Copyright IBM Corp. 2004. All rights reserved.
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 we’ve 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
IBM Lotus Domino Application Portlet: Configuration and Tips
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 isn’t 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 DAP’s modus operandi. So point your favorite browser to
http://domino.domain.com/Sample.nsf and notice how there are some icons in the applet’s
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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 applet’s 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 applet’s box.
If you look at the frame’s 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 frame’s
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
IBM Lotus Domino Application Portlet: Configuration and Tips
...
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 applet’s box, as shown in Figure 5-5.
Figure 5-5 Display of both icons in applet’s 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 Explorer’s
JVM does not support this but Sun’s 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 can’t 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 button’s 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+&quot;/Info&quot;;
window.open(myurl3,&quot;_top&quot;);"
value="Info">
40
IBM Lotus Domino Application Portlet: Configuration and Tips
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 shouldn’t.
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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 portlet’s 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 database’s 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
DAP’s 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
IBM Lotus Domino Application Portlet: Configuration and Tips
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 can’t 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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
6
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.
© Copyright IBM Corp. 2004. All rights reserved.
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
򐂰 @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 user’s 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
IBM Lotus Domino Application Portlet: Configuration and Tips
A
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.
© Copyright IBM Corp. 2004. All rights reserved.
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 Server’s implementation of the
HttpServletRequest.getRequestURI() method, HTTP requests are decoded if the request’s
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
IBM Lotus Domino Application Portlet: Configuration and Tips
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
IBM Lotus Domino Application Portlet: Configuration and Tips
B
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
© Copyright IBM Corp. 2004. All rights reserved.
59
60
IBM Lotus Domino Application Portlet: Configuration and Tips
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
© Copyright IBM Corp. 2004. All rights reserved.
61
62
IBM Lotus Domino Application Portlet: Configuration and Tips
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