lotus domino app portlet configuration-redp3917

8/3/2019 Lotus Domino App Portlet Configuration-redp3917

1/74ibm.com/redbooks

Redpaper

Front cover

IBM Lotus DominonoApplication PortletConfiguration and Tips

Thomas Delahunt

Kornelius Elstne

James Rya

Katherine Sewe

Configuration and authentication

Parsers and rulesets

Examples and sample code
http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/


2/74


3/74

International Technical Support Organization

IBM Lotus Domino Application PortletConfiguration and Tips

December 2004


4/74

Copyright International Business Machines Corporation 2004. All rights reserved.

Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule

Contract with IBM Corp.

First Edition (December 2004)

This edition applies to Version 1.0 and Version 1.1 of the Domino Application Portlet

Note: Before using this information and the product it supports, read the information in Notices on page v.


5/74

Copyright IBM Corp. 2004. All rights reserved.iii

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii

Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Chapter 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.1.1 Setup if you have installed Domino Extended Product portlets . . . . . . . . . . . . . . . 2

1.2 Configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2.1 Source and Display tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2.3 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2.4 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3 Edit options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2. Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.1 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.2 No authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.3 Basic authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.4 Session based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.5 Single sign on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.5.1 Single sign on setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.6 Credential vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.6.1 System slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.6.2 Shared slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.6.3 Private slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.1 Types of caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.2 Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.3 Cacheable objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.4 Cache size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3.5 Using caching to improve DAP performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 4. Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4.1 Regular expression parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.1.1 Input expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.1.2 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234.1.3 Output expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4.1.4 Blocks within the expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4.1.5 Process for applying regular expression rules . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.2 HTML parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

4.2.1 Input expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.2.2 Output expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.2.3 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.2.4 Process for applying HTML rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.3 Correlation between the rulesets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30


6/74

iv IBM Lotus Domino Application Portlet: Configuration and Tips

Chapter 5. Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335.1 Setting up Domino. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5.2 Setting up DAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5.2.1 Install portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5.2.2 Create page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5.2.3 Add portlet to page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

5.2.4 Initialize portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355.3 Exploring the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

5.4 Fixing the icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

5.5 TCP/IP trace proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

5.6 Fixing the greedy information page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5.7 Switching to the HTML parser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

5.8 Escalating security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

5.9 Another sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 6. Updates to Domino Application Portlet 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . 496.1 Debug tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

6.2 Error reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

6.3 Customized rule sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

6.4 Support for Domino Web Access (iNotes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

6.5 Selective MIME types for Rules tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

6.6 Output functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

6.7 Performance improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

6.8 Default to users mail file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

6.9 New URL re-writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Appendix A. Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55A.1 Anonymous access issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

A.2 Maximize portlet issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

A.3 Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

A.4 Language version issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

A.5 New window opening in Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56A.6 Alignment in BIDI language configuration and edit modes . . . . . . . . . . . . . . . . . . . . . . 57

A.7 Richtext applet icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

A.8 Configuration performance (WPS 5.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

A.9 Configuration performance (WPS 4.1.2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

A.10 Load issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

A.11 Table properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

A.12 Domino Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61


7/74

Copyright IBM Corp. 2004. All rights reserved.v

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consultyour local IBM representative for information on the products and services currently available in your area. Anyreference to an IBM product, program, or service is not intended to state or imply that only that IBM product,program, or service may be used. Any functionally equivalent product, program, or service that does notinfringe any IBM intellectual property right may be used instead. However, it is the user's responsibility toevaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. Thefurnishing of this document does not give you any license to these patents. You can send license inquiries, inwriting, to:IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions areinconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically madeto the information herein; these changes will be incorporated in new editions of the publication. IBM may makeimprovements and/or changes in the product(s) and/or the program(s) described in this publication at any timewithout notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in anymanner serve as an endorsement of those Web sites. The materials at those Web sites are not part of thematerials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurringany obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their publishedannouncements or other publicly available sources. IBM has not tested those products and cannot confirm theaccuracy of performance, compatibility or any other claims related to non-IBM products. Questions on thecapabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate themas completely as possible, the examples include the names of individuals, companies, brands, and products.All of these names are fictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:This information contains sample application programs in source language, which illustrates programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programs inany form without payment to IBM, for the purposes of developing, using, marketing or distributing application

programs conforming to the application programming interface for the operating platform for which the sampleprograms are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, anddistribute these sample programs in any form without payment to IBM for the purposes of developing, using,marketing, or distributing application programs conforming to IBM's application programming interfaces.


8/74

vi IBM Lotus Domino Application Portlet: Configuration and Tips

Trademarks

The following terms are trademarks of the International Business Machines Corporation in the United States,other countries, or both:

ibm.com

iNotes

Domino

IBM

Lotus

Redbooks

Redbooks (logo)

WebSphere

Workplace

The following terms are trademarks of other companies:

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems,Inc. in the United States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.


9/74

Copyright IBM Corp. 2004. All rights reserved.vii

Preface

This IBM Redpaper discusses the Domino Access Portlet.

WebSphere Portal is a complete portal solution. It provides customers with integrated

content and applications in addition to a unified, collaborative workplace. Domino is acomprehensive application platform. Customers have invested heavily to exploit the power of

Domino in developing proprietary applications. As a result they are understandably reluctantto start again and move towards the benefits of a portal environment. The main question

asked by such customers is how do we move our Domino applications into a portal. DominoApplication Portlet (DAP) provides the solution. It facilitates the easy integration of DominoWeb Applications into a portal server. This paper will describe DAP in detail and will give

practical examples on configuring and customizing this portlet.

Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook dealing withspecific products or solutions, while getting hands-on experience with leading-edge

technologies. You'll team with IBM technical professionals, Business Partners and/orcustomers.

Your efforts will help increase product acceptance and customer satisfaction. As a bonus,

you'll develop a network of contacts in IBM development labs, and increase your productivityand marketability.

Find out more about the residency program, browse the residency index, and apply online at:

ibm.com/redbooks/residencies.html

Comments welcome

Your comments are important to us!

We want our papers to be as helpful as possible. Send us your comments about thisRedpaper or other Redbooks in one of the following ways:

Use the online Contact us review redbook form found at:

ibm.com/redbooks

Send your comments in an email to:

[email protected]

Mail your comments to:

IBM Corporation, International Technical Support Organization

Dept. JLU Mail Station P0992455 South Road

Poughkeepsie, New York 12601-5400
http://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/contacts.htmlhttp://www.redbooks.ibm.com/contacts.htmlhttp://www.redbooks.ibm.com/http://www.redbooks.ibm.com/http://www.redbooks.ibm.com/residencies.htmlhttp://www.redbooks.ibm.com/residencies.html


10/74

viii IBM Lotus Domino Application Portlet: Configuration and Tips


11/74

Copyright IBM Corp. 2004. All rights reserved.1

Chapter 1. Introduction

The Domino Application Portlet (DAP) integrates the content and technology of existing

Domino Web Applications into the Portal environment. It allows customers to insert theseexisting applications into portlets and display them on a portal server with minimaldevelopment effort. Most importantly, it renders the portlets of the Domino Web application

within the context of the portal, thereby keeping the user within the context and navigationalscheme of the portal.

The Domino Application Portlet acts like a reverse proxy, proxying the content from the backend servers through to the browser. It appears to the browser to be the real content server.

The Domino Application Portlet (DAP) channels all requests from the user client (browser)through the portal and on to the Domino HTTP server in the back end. The portlet contains an

iframe with an embedded servlet that is responsible for the actual connection and display ofthe Domino content. It manages cookies, caching, user authentication, and framing.

Rules-based parsers rewrite the content produced by the Domino HTTP server.

This document explores the setup and configuration of DAP. The rest of this chapter

examines the basic setup and gives an overview of the configuration options available. This isfollowed by a number of sections that provide a detailed examination of these options.

Chapter 5, Samples on page 33 contains two concrete examples that show how to setupDAP and write rules that tailor it for your own application. Chapter 6, Updates to Domino

Application Portlet 1.1 on page 49 discusses specific improvements and updates which havebeen made in Version 1.1 of DAP, released in September of 2004. Finally there is a

description of some known problems we have discovered.

1


12/74

2 IBM Lotus Domino Application Portlet: Configuration and Tips

1.1 Setup

DAP is setup like any other portlet, the WAR file is installed and then the portlet is added to a

page1. To install DAP onto the por tal server you must be logged in with administrator rights onthe Portal. An example of installing and setting up DAP is given in 5.2, Setting up DAP on

page 34.

Figure 1-1 Initial DAP window

1.1.1 Setup if you have installed Domino Extended Product portlets

The Domino 6.5.1 Extended Products portlets are an enhancement to the existingWebSphere Portal Collaboration Center portlets and therefore offer the ability to integrate the

application functionality of the Domino 6.5.1 platform into a intell igent common user interfaceserved up by WebSphere Portal Server. One of the key portlets included with the Extended

Products Portlets included the Domino Application Portlet. Figure 1-2 on page 3 illustrates thetabs where you would see the Domino Application portlet and shows a sample Domino Web

application being rendered through DAP.

1 This is true for the standalone version available from the portlet catalog. However in Lotus Workplace DAP is

installed with all the other portlets.

Attention: If you want to learn more about installing and configuring the Domino ExtendedProducts portlets, refer to Chapter 8 within the redbook Domino 6.5.1 and Extended

Products: Integration Guide, SG24-6357.

http://www.redbooks.ibm.com/abstracts/sg246357.html
http://www.redbooks.ibm.com/abstracts/sg246357.htmlhttp://www.redbooks.ibm.com/abstracts/sg246357.html


13/74

Chapter 1. Introduction3

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

1.2 Configuration options

To configure the Domino Application Portlet you must have administrator access rights. The

configuration menu may be accessed by clicking the wrench icon in the upper right handcorner of the portlet.

To configure the Domino Application portlet, complete the following steps:

1. Click the Configure portlet properties icon in the top-right area of the portlet window. This

icon looks like a wrench.

It contains four main tabs, which are:

Source and Display Authentication

Caching Rules

1.2.1 Source and Display tab

The source and display tab allows the user to define which Domino server and database the

portlet is to display (Domino Source Server options). In addition to this it also allows the userto direct DAP to look for the Domino content via a proxy server. This is a useful feature if the

user wants to see what requests are being made by the portlet to the Domino server. Finallythis tab also lets the user configure the iframe in which the DAP portlet displays the Dominocontent. The show in edit mode check box permits some of these options to be made

Domino Application Portlet

My Workplace Tab - access to fully integrated collaborative portlets


14/74


available to a normal portlet user in edit mode. So for example, a normal user could configurea DAP portlet to point to his/her mail database without having to have administrator rights forthe portlet.

Figure 1-3 Source and Display UI

1.2.2 Authentication

The authentication settings may be modified on the authentication tab of the configuration

menu. These settings define the model DAP will use to authenticate with the Domino serverand also where in the Credential Vault the username and password may be found. A number

of options may be set including storage in the Credential Vault or use of Single Sign On. Noteif a user is required to enter a password (for example in Basic Authentication) this will need to

be done in the Edit settings. A more in-depth description of Authentication may be found inChapter 2, Authentication on page 9.


15/74


Figure 1-4 Authentication UI

1.2.3 Caching

Within the Caching tab settings that affect the storage of cached objects from DAP may beset. While the browser has its own caching a user may also define a number of caching

mechanisms for the DAP portlet. Essentially these mechanisms define where and howobjects that are passed between Domino and DAP are stored. This caching takes place onthe Portal server and use of caching here prevents unnecessary calls to the Domino server. A

detailed description of the options here may be found in Chapter 3, Caching on page 15.

Figure 1-5 Caching UI


16/74


1.2.4 Rules

The rules tab defines the rules that are used to transform URLs and links in the Domino

content so that they point to DAP instead of to the Domino server. These rules come in twoforms that are mutually exclusive, Regular Expression Rules or HTML Rules. While there is

too much detail to go into here and a detailed explanation is given in Chapter 4, Rules onpage 21, the essential difference between the two is that Regular Expression Rules are very

flexible, but complicated. while HTML rules are simpler and faster, but less flexible.

Figure 1-6 Rules UI

1.3 Edit options

The edit options may be accessed by selecting the pencil icon in the top right hand corner on

the DAP portlet page.

Figure 1-7 Edit UI

The edit page is where a user must enter their Domino username and password if they are

using Basic or Session based authentication. This page also contains any of the options thatthe Administrator decided to allow a normal user to configure. These may include the Domino

Database settings and the display settings.


17/74


Figure 1-8 Edit UI


18/74



19/74


Chapter 2. Authentication

This chapter describes authentication models that the Domino Application Portlet (DAP) can

use to authenticate with the target Domino server. The following topics are addressed indetail:

No authentication Basic authentication Session based authentication Single sign on Credential vault

2


20/74


2.1 Authentication

To modify the authentication settings click the wrench icon and then the authentication tab.

There are four different authentication models that the Domino Application Portlet (DAP) canuse to authenticate with the target Domino server. They are none, basic, session, and Single

Sign On (SSO).

Figure 2-1 Authentication UI

Domino may require either basic, session-based, or SSO authentication. It is possible toauthenticate by configuring the Domino Application Portlet with a lower model than theDomino server requires. For example, you can authenticate against a Domino server

configured for single-session authentication by specifying Basic authentication in the DominoApplication Portlet. However, you should generally match the portlet authentication modelwith the Domino server it is accessing.

2.2 No authentication

If the target server and database application does not require any authentication then thenone radio button should be selected. When selected, a DAP user will not be required to enter

their username and password in the portlet edit mode.

2.3 Basic authentication

Basic password authentication, also known as name-and-password authentication, usesbasic HTTP authentication schema to ask users for their names and passwords and then

verifies the accuracy of the passwords by checking them against a secure hash of thepassword stored in Person documents in the Domino Directory. When set up for this, Domino

asks for a name and password only when a client tries to access a protected resource on theserver.

When connecting to Domino, DAP retrieves the username and password specified in the edit

mode of the portlet. It may also retrieve these values from a credential vault system slot, if thistype of slot is selected. Refer to 2.6.1, System slot on page 14 for further informationregarding this.

It then creates a header in the following format:

Header name: AuthenticationHeader value: Basic: Ghy753Jk03==??}

The header value contains the authentication model being used together with thebase64-encoding of the string username:password.


21/74

Chapter 2. Authentication11

Upon receiving the request, Domino base64-decodes the string to reveal the username andpassword, which it then validates.

2.4 Session based authentication

DAP also provides for session authentication. Session-based authentication differs from basicpassword authentication in that the user name and password is replaced by a cookie. Theuser name and password is sent over the network only the first time the user logs in to a

server. Thereafter the cookie is used for authentication.

When connecting to Domino, DAP constructs a URL using the connection settings specified

in the edit or config mode of the portlet.

Protocol Host Port Path and filenamehttp:// dominoserver.lan :80 /mail/userA.nsf

If session based authentication is enabled, then the initial request to Domino is modified to

append the username and password in the URL. The URL then becomes:

http://dominoserver.lan:80/mail/userA.nsf?Login\&use\\rname=userA\&password=password\&redirectto=/mail/userA.nsf

When Domino receives this request, it validates the username and password and sends backa cookie called DomSessAuthId. This cookie is then used to authenticate the user on further

requests from DAP.

2.5 Single sign on

Single sign on (multi-server session-based authentication) allows Web users to log in once toa Domino or WebSphere server, and then access any other Domino or WebSphere servers in

the same DNS domain that are enabled for single sign on (SSO) without having to log in

again. User Web browsers must have cookies enabled since the authentication token that isgenerated by the server is sent to the browser in a cookie. You can set this up by creating adomain-wide configuration document -the Web SSO Configuration document - in the DominoDirectory. You initialize the configuration document by importing LTPA keys from WebSphere

(you will need the password specified when generating the keys in WebSphere). When SSOis enabled, the user will not be required to specify their credentials in edit mode of the portlet.

2.5.1 Single sign on setup

To configure SSO for WebSphere follow these steps:

1. Log on to the WebSphere Application Server Console.(Start IBMWebSphereApplication Serverv5.0 Administrative Console)

2. Go to Security Authentication Mechanisms and click LTPA, as shown in Figure 2-2on page 12.

3. Enter the password to be used, and a file name that will contain the exported key.

4. Press Export keys button.


22/74


Figure 2-2 WebSphere LTPA Configuration

To configure Domino follow these steps:

1. Launch the Domino Administrator application.

2. Open the current server document.

3. Press the Create Web (R5)... button then select SSOConfiguration as shown in

Figure 2-3.

Figure 2-3 Domino SSO Configuration

4. Press the Keys... button, then select ImportWebSphere LTPA Keys.

5. Specify the location of the key file that you exported the WebSphere LTPA key in the

previous step. (You may need to correct the LDAP realm, by adding a \ (backslash)

before :389. See technotes Setting up SSO -- 1098010 Troubleshooting SSO -- 1158269).

6. Enter in a value for the DNS Domain value, (e.g., .domain.com").

7. Enter in the value for the Domino Server Names. This should contain the name of the

current Domino server.

8. Give the SSO configuration a name (e.g., LtpaToken").

9. Press the Save & Close button.

10.In the Current Server Document select the Internet Protocols tab, and then the DominoWeb Engine tab, as shown in Figure 2-4 on page 13.


23/74

Chapter 2. Authentication13

Figure 2-4 Domino Server Configuration

11.For Session Authentication select Multiple Servers (SSO). For Web SSOConfiguration, select the name you entered in Step 8.

12.Save the document.

Finally, restart the Domino server, Application server, and Portal server. SSO is now enabled

between the WebSphere and Domino servers.

2.6 Credential vaultThe Domino Application Portlet uses the WebSphere Portal credential vault to handle

authentication if the authentication model in Domino is basic or session-based. In such cases,you will need to enter the slot type to be used. In addition, for system slots you must alsoprovide the slot name (identifier). If no authentication is used in Domino (anonymous access)

no credential vault settings are required.

If single sign on (SSO) is used in Domino, access is inherent in the SSO framework and nocredential vault settings are needed.The credential vault is organized as follows:

The portal administrator partitions the vault into several vault segments.

Vault segments can be created and configured only by portal administrators.

Each vault segment contains one or more vault slots. Vault slots are the drawers whereportlets, such as Domino Application Portlet, store and retrieve a user's credentials (forexample, login details). Each slot holds one credential.Domino Application Portlet uses thedefault segment only. There are three different types of slots where credentials can be stored

and retrieved by DAP.


24/74


2.6.1 System slot

The credentials that are stored in a system slot can be accessed by all users and by all

portlets. The administrator sets the username and password in a new slot via the portletsettings, as shown in Figure 2-5. (Note - this is from WebSphere Portal 5.0.)

Figure 2-5 Credential Vault Settings

To edit the Credential Vault settings:

Go to AdministrationAccessCredential Vault

Select the option Add a vault slot. Please ensure that Vault slot is shared is checked.

Whatever slot name is used to create the slot must be entered as Slot identifier in the

Domino Application Portlet configuration display as shown in Figure 2-6.

Figure 2-6 System slot

2.6.2 Shared slot

Credentials that are stored in a shared slot are accessible by all Domino Application Portletinstances for a given user. Users enter login information using the portlet's Edit mode.

Credential changes in one portlet instance are reflected in all other portlet instances for thatuser.

2.6.3 Private slot

Credentials that are stored in a private slot are not accessible by all Domino ApplicationPortlet instances for a given user. They are only accessible by the user whilst accessing the

portlet instance that stored the credentials.


25/74


Chapter 3. Caching

This chapter discusses caching options for the Domino Access Portlet. It discusses the

following topics in detail:

Access Cacheable objects Cache size Using caching to improve DAP performance

3


26/74


3.1 Types of caching

To modify the caching settings click the wrench icon and then click the caching tab. The

manner in which cached objects are accessed in DAP depends on the caching type selected.The different caching types include:

User and application (most secure)

Cached objects can be accessed only by the user who put them into the cache, and onlywhile accessing the current application.

User

Cached objects are shared by all applications, but can be accessed only by the user who

put them into the cache.

Application

Cached objects can be accessed by any user, but only while using the application that putthem into the cache.

Shared (least secure)

Cached objects can be accessed by any user or application, regardless of whichapplication or user put them into the cache.

3.2 Access

Figure 3-1 on page 17 shows how objects are accessible by different applications and users

depending on how they were cached. In this diagram there are three instances of DAP on aparticular server, D1, D2 and D3. On each instance of DAP there are various users accessingthem. For example, there are two users UserA (UA) and UserB (UB) accessing DAP

instance D1.

D1 - UA - The object is only accessible by user A whilst accessing DAP instance D1.

D1 - UA and D1 - UB - The object is accessible by user A or user B whilst accessing DAPinstance D1.

D1 - UA and D2 - UA The object is accessible by user A whilst accessing either DAP

instance D1 or D2.


27/74

Chapter 3. Caching17

Figure 3-1 Caching


28/74


3.3 Cacheable objects

Here we choose what type of objects can be stored, and the part of the cache to store them.

The part of the cache to store the object is determined using the mime-type of the object, and

in the case of shared caching, the string defining the URL of the object. This helps you to limitshared caching to objects that are common to all users. For example, you might enter

/icons

to ensure that only objects whose URLs contain "/icons" will be stored in the shared cache.The user also has an option to specify user-defined mime-types, in the situation that the listprovided is insufficient. The default caching configuration for DAP is shown in Figure 3-2.

Figure 3-2 Caching

Shared caching is selected.

All objects that have an image mime-type, and have an applet mime-type (not shown) arecached in this part of the DAP cache.

There is a maximum of 100 objects in the cache. This is the maximum for all objects in allparts of the DAP cache inclusive.

The maximum size of each object in the cache is set to 250 kb.

It is possible to select more than one part of the cache to be used, e.g., by selecting sharedand application caching. If an object qualifies to be cached into more than one part, order will

be used to decide.


29/74

Chapter 3. Caching19

The order is:

1. User and Application

2. User3. Application4. Shared

For example, if both "User and Application" and "Application" caching are selected, and anobject qualifies to be cached in both, "User and Application" will be chosen. This is because itis more secure than "Application" caching.

3.4 Cache size

The maximum size of both the cache and the cached objects are configurable. The cache

operates in a Most Recently Used basis, whereby when the size of the cache has reachedits maximum, the object with the oldest accessed date is removed before adding a new

object. DAP also provides a Clear Cache button, which allows for the contents of the cache tobe deleted.

Figure 3-3 Clear Cache button

3.5 Using caching to improve DAP performance

The primary way to improve DAP performance using caching is to make use of the Shared

cache. The Shared cache will store objects that are accessible to all users on all DAP portletinstances. For example, once a frequently requested image from Domino is stored in DAPsShared cache by a particular user on a DAP instance, this image will be accessible by all

subsequent users on any DAP instance without the need to retrieve it from Domino again. Ifwe compare this with deciding to store objects in the user and application cache, a lot more

overhead is required. For each user accessing the same resource we must request it fromDomino and keep a copy of it in memory.

Another way to improve performance using caching is to carefully configure the maximumsize of the contents of the cache, and the maximum size of each object in the cache. Since

the objects are effectively cached in the Portal server's memory, allocation should be carefullyassigned if space is an issue.


30/74



31/74


Chapter 4. Rules

The Domino server provides the ability to allow users to browse Domino databases over the

Internet. Unfortunately, accessing Domino data through a Portal server does not work in thesame way as directly accessing it through an Internet browser. References to resources, suchas graphics and applets, and links to other pages are generally relative to the Domino

database. In order to access this data correctly through a Portal server these resources andlinks need to be redirected through the portlet.

The Domino Application Portlet uses a parser to configure the content returned by Domino.There are currently two available parsers: a Regular Expression parser and a HTML parser.

Each parser uses a set of rules to define the appropriate data transformations necessary toredirect the application through the Portal.

The supplied rules are designed to cater to the four supported applications: mail, discussion,teamroom and reservations. However, these rules can be configured, by the portletadministrator, in order to tailor the por tlet to support a new database application.

In this chapter, these topics are discussed in detail:

Regular expression parser HTML parser Correlation between the rulesets

4


32/74


4.1 Regular expression parser

The Regular Expression Parser makes use of the Jakarta regular expression parsing engine.

It treats the entire input (from Domino) HTML page as plain text and tries to match eachposition to one of the defined rules.

The regular expressions are composed of an input expression and an output expression. Theinput expression defines the content each rule is to search the text for.

4.1.1 Input expressions

The first component of a Regular Expression rule is the input expression. This expression

defines what the rule is to search for within the given input. Input expressions can either beplain text, which will look for an exact match, or a regular expression to match when the

content you are trying to match can change. For example, an input expression of:

parent.window.location

This will only match that exact text. However, in most cases we are less sure of what the exacttext will be and need to use regular expression to deal with:

action="/mail/user1.nsf/83997d314a7eae6?ReadForm"action="/mail/user2.nsf/83997d314a7eae6?ReadForm"

A separate rule is required for each case. However, this input expression:

action="(.*?)"

This will match all strings of the type action="", which gives us much moreflexibility and power when writing rules.

Regular expressionsThe main matching operators used in the current ruleset are:

( Start a grouping of operators. Match any character

* Zero or more times

? Use minimum (reluctant) matching

) End the grouping of operators

| Logical OR

[] Character class

^ Beginning of a string. If within character class, then

signifies logical NOT

Actually, the exact input expression parent.window.location,will not match instances of"parent.window.location" within the input text. This is because the input expression contains

reserved regular expression characters - the dots. To include any of the regular expressioncharacters in the text part of an input expression you must precede them with a backslash1.

So the actual input expression to match cases of "parent.window.location" is:

parent\.window\.location

1 For more details on regular expression composition see the Jakarta Regular Expression API

http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html
http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.htmlhttp://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html


33/74

Chapter 4. Rules23

4.1.2 Output functions

In situations where outputting a static string is insufficient to properly deal with the proxying, a

function is required. Output functions are used to perform complicated rule transformations,usually taking the matched text as input. The most commonly used functions are the pair of@transform functions. These functions transform URLs found within the Domino input,redirecting them from the Domino server through the Domino Application Portlet. These

methods therefore form the basis of the Domino Application Portlet's reverse proxyingcapabilities.

@transform_uri_absThis function only transforms URLs whose path is absolute (beginning with a forwardslash

/).It transforms URLs so that they begin with the servlet path and end with an encrypted andencoded string that references the original URL. In this way the servlet used within the

Domino Application Portlet can identify the Domino database to access and thecorresponding path of the required resource.

@transform_uri_allThis function operates in a similar manner to transform_uri_abs, but it transforms the URLwhether it is absolute (beginning with a forwardslash / ) or relative to the current path. Forexample, if the current path is http://dominoserver.ibm.com/mydb.nsf/myfolder then a URLof "mail.gif" would be appended to this path, resulting in a URL ofhttp://dominoserver.ibm.com/mydb.nsf/myfolder/mail.gif. This functionality is maintainedby the transform_uri_all function, which generates URLs of the typehttp://portalserver/wps/PA 11 0/rproxy/$$cGDdv$$.nsf/myfolder/mail.gif.

@proxypathReturns the servlet path that is used to replace the link to the Domino server. An exampleresult of applying this function is /wps/PA 1 0 69/rproxy. This path would then be used toconstruct a transformed URL.

@hostReturns the name of the Domino Server machine on which the current application is located[e.g.dominoserver.ibm.com.].

@protocolThis function returns the protocol used by the Domino Server (e.g., http or https).

@portThis function returns the port number used by the Domino Server (e.g., 80).

@param(n)

[where n is an integer] This function returns a string corresponding to the nth block(parenthesized expression) in the input expression. The first block is 1, the second 2 and so

on. The whole of the matched text is 0. This is described in greater detail in 4.1.4, Blockswithin the expressions on page 24.

@parencountReturns the number of blocks (parenthesized expressions) within the input.


34/74


@baseurlThis is a function dealing with occurrences of URLs within the base tag and is not generally

required.

These functions are used in the Output Expressions described in 4.1.3, Output expressions

on page 24.

4.1.3 Output expressions

For each input expression for example:

action="(.*?)"

There is a corresponding output expression, which defines the transformations to perform onthe text matched by the input expression. The output expression may be plain text, such as:

action="/mail/user3.nsf/83997d314a7?ReadForm"

Which will, given the input string:

action=""

This will replace all occurrences of with/mail/user3.nsf/83997d314a7?ReadForm. In order to deal with the more general case wherewe want to transform the string based on the input string, an output function (as described in4.1.2, Output functions on page 23) is required. This rule uses two output functions@param(1)and @transform uri all().

action="@transform_uri_all(@param(1))"

The result of applying this rule to action="" is:

action="wps/PA_1_0_V9/rproxy/__PC_7_0_18L_PI_432667__/"

4.1.4 Blocks within the expressions

The input expression is divided up according to the groups of parentheses it contains. Stayingwith the input expression defined in 4.1.1, Input expressions on page 22:

action="(.*?)"

We see that this expression has one set of parenthesis. Since there may be more than one

set per input expression, the blocks are identified by number. In this example, there is onlyone set so it is referred to as block 1. Subsequent parentheses blocks would be identified by

in a similar fashion by the number 2, 3 etc. These block numbers are used in the outputexpressions to identify the parts of the string to transform. A specific output function:

@param(block_number)

This is used to reference the individual blocks. So given an input string of:

This will match our rule, action="(.*?)", as follows:

action="/mail/user1.nsf/83997d316273?ReadForm"

The regular expression within the parentheses of the input expression matches the URL:

/mail/user1.nsf/83997d316273?ReadForm


35/74

Chapter 4. Rules25

In order to refer to the URL within the output expression, we would use the following functioncall:

@param(1)

Using a more complicated example, the input expression:

This will match all instances of applets called myApplet. For one such instance:

The resulting blocks, returned using the @param() function are shown in Figure 4-1. There is

also a default block, 0, which refers to the whole matched string.

Figure 4-1 Constituent Blocks

4.1.5 Process for applying regular expression rules

The Regular Expression rules are processed according to the order which they appear in the

Domino Application Portlet Configuration page. A given piece of text can be transformed onlyonce, by the first rule that matches it. This process means that text is only processed by one

rule since once the parser matches a rule, the text is transformed and the parser skips on tothe text after the matched input. The process for applying regular expression rules is as

follows:

1. Begin at the first character of the input text.

2. Beginning with 1st rule, apply each rule in turn looking for a match.

a. If a match is found, do not process further rules. Go to Step 3.

b. If no match is found move to the next character in the input text. Return to Step 2.

3. Transform the found text according to the output model for the rule. Move to the characterin the input text that is immediately after the found text. Return to Step 2.

Ordering of rulesDue to the method in which the rules are processed, the most specific rule must appear first

in the ruleset. Since only one rule can match a given portion of text, if the specific ruleappears after a more general one then it will never be hit. This is only an issue for similar

rules, which may match a subset of the text matched by other rules.

Both of the rules src="(.*?)_gif" and src="icon (.*?)_gif" would match the text src="iconprint.gif". Since the first rule that matches is applied, the most specific rule should beplaced highest in the list of rules. If a different transformation is required for images starting

with the text icon, then this rule needs to be before the more general src="(.*?)_gif",otherwise it will never be applied.In this manner there may be several specific rules to deal

with specialized cases and then one general rule to catch all other occurrences of the giventext.

@param(1) width=250 height=100@param(2) /code@param(3) archive=Sample.jar


36/74


Figure 4-2 Configuration Page Showing Regular Expression Rules

Rules to skip over textAnother feature of the rule processing is that rules can be designed to make the parser skip

over portions of the text. A rule may be written which matches the text but that does notmodify it. Since only one rule can match a given portion of text, no subsequent rules can be

applied and the text remains unchanged.

As described in 4.1.4, Blocks within the expressions on page 24, there is a default block (0),which refers to the entire matched string. Using the output function @param in conjunction withthis block reference allows us to obtain the matched text. By outputting the matched input

text, there is no change to the text. For example, if an input expression is:

src="special_icon(.*?)gif"

And the output model is:

@param(0)

Then the matched input text, e.g.,

src="special_icon65.gif"

This will remain unchanged in the output, even if there is a more general rule, such assrc="(.*?)", further down the list.


37/74

Chapter 4. Rules27

Figure 4-3 Configuration Page Showing Case-Sensitive Box

Case-sensitivityRegular expressions in the Domino Application Portlet are not case-sensitive by default, but

you can select case-sensitivity for the input expression of any rule. In some circumstances wedo not want to apply rules to specific pieces of text. The rule shown in Table 4-1 will match

any possible capitalization of href (e.g Href, HREF,..) but will always produces a lowercaseoutput. However if the case-sensitive box is selected beside the rule in the portletconfiguration then only the case given in the input expression will match.

Table 4-1 Regular Expression Rule Showing Input & Output Expressions

4.2 HTML parser

In addition to the Regular Expression parser, a HTML parser has been provided which parses

the input text based on its HTML structure. This parser also uses a set of rules for datatransformation. However due to the complexity of the rules required for the RegularExpression parser, the rules used by the HTML parser are designed to be a more

user-friendly alternative.

Since most HTML pages also contain por tions of JavaScript, the HTML parser must also deal

with them. However, since JavaScript is not structured in the way that HTML is, the HTMLparser cannot deal with the scripts itself. A dedicated JavaScript parser is planned for a future

release, but currently when the HTML parser encounters JavaScript it calls out to the RegularExpression parser to parse the script.

As with the Regular Expression rule structure discussed in 4.1, Regular expression parser

on page 22, the HTML rules are divided into an input expression and an output expression.However these two expressions have been split into smaller constituent par ts.

Input Output

href=(.*?) href=@param(1)

Note: The input text must match the input expression exactly, including spaces.


38/74


4.2.1 Input expression

The input expression has been subdivided into three components:

Tag Input Attribute Input Value

The Tag component specifies the particular HTML tag that this rule is applied to. Byspecifying the Tag name, rules are only applied if that tag is found within the input HTMLpage. The input expression requires two additional components which identify the particular

tag attribute/value pairs to search for.

The Input Attribute specifies the attribute, of the given tag, that the rule is to be applied to. Asa final level of detail, we can specify the value of the given attribute using the Input Valuecomponent. Since the HTML rules were designed to be easier to read, negating the need to

understand regular expressions, we tried to keep each component as simple as possible.However, to allow some flexibility one wildcard character is allowed - the *. This is either used

to signify any within one of the input components, or, in the case of Input Value, inconjunction with some text to signify any text beginning with. If all three components of the

input expression match the input string then the rule is applied.

4.2.2 Output expression

Due to the structure of the HTML rules, a rule may transform the value of a particular attribute

of a particular tag. Once a match has been found the attention switches to the outputexpression to decide what transformations to invoke. The output expression for the HTML

rules is in two parts:

Output Attribute Output Value

HTML Rules are not allowed to search for attributes of one tag and then modify the values ofdifferent tags so there is no need to have a Tag component in the output expression. If suchrule functionality is required then the Regular Expression parser must be used. The Output

Attribute specifies the attribute name for the output. Often this is the same as the inputattribute name, but this is not a requirement. For example, a rule specified on the param tag

may use the name attribute to locate the appropriate portion of HTML, but it is the valueattribute that will require modification. An illustration of this is shown in Table 4-2. The Output

Value specifies the value for the output attribute. It comprises text optionally combined with asingle output function.

Table 4-2 Sample HTML Rules

4.2.3 Output functions

The output functions provided for use with the HTML parser are mostly consistent with those

available for the Regular Expression Parser.The functions listed below have been describedin 4.1.2, Output functions on page 23.

@transform_uri_abs

Tag Input Output

param

attr value attr value

name data value @transform uri all

a href * href @transform uri abs


39/74

Chapter 4. Rules29

@transform_uri_all @host @proxypath @protocol @port @baseurl

The @param(n) and @parencount output functions are specific to the Regular Expression

parser and are not available for use with the HTML parser. There is one output function whichis specific to the HTML parser, the @script function. This function is used to call out to theRegular Expression Parser when JavaScript is located within the HTML page. An example ofusing this function is shown in Table 4-3, where for any tag if an attribute called onclickisfound, then the value of that attribute is transformed using the @script function. This rule isused to transform the JavaScript value of the onclickattribute.

Table 4-3 Sample HTML rule using the @script function

4.2.4 Process for applying HTML rules

For a given Tag, Input Attribute and Input Value combination, only one rule can beapplied. This mirrors the functionality of the Regular Expression parser, where only one rulecan be applied to a given portion of input text. In the case that more than one rule matches agiven combination, the most specific rule available is applied. The more detail a rule gives, the

more specific it is. For example, a rule which uses the wildcard * to signify any tag is verygeneral. In contrast, a rule which specifies the tagname is more specific. This applies to the

attribute and value components as well.

Table 4-4 Example rules

If four rules are identical except for the Input attribute values shown in Example 4-4, then RuleA is the most specific, while Rule D is the least specific. Rule A will only match the exact text

Database, all variants of this text will be ignored. Rule B is slightly more flexible, it will matchall text beginning with Database. This means that Database2 and Database list will also

match. Rule C is similar to Rule B, but since more of the text has been replaced by thewildcard it is more general. It will match Database, Database list and Data form. Finally,Rule D is the most general since any value will match. This is usually used in cases where the

value will have to be modified, such as the value of a href attribute. Table 4-5 on page 30illustrates some possible text matches based on the rules described in Table 4-4 If rules are

identical, except for their Output Attribute and/or Output Value, the rule that appears first inthe configuration is used, see Figure 4-4 on page 30.

Tag Input Output

*


onclick * onclick @script

Rule Value

Rule A Input value: Database

Rule B Input value: Database*

Rule C Input value: Data*

Rule D Input value: *


40/74


Table 4-5 Example text matches for rules inTable 4-4 on page 29

Figure 4-4 Configuration Page Showing HTML Rules

4.3 Correlation between the rulesets

As described in 4.1, Regular expression parser on page 22 and 4.2, HTML parser on

page 27, the Regular Expression and HTML parsers function in different ways and so therulesets for each one are structured differently. This has led to some differences in the

rulesets. However, as a whole there is a general correlation between the rules as the parsersare basically performing the same function.

For example, the Regular Expression rule shown in Table 4-6 is equivalent to the HTML ruleshown in Table 4-7 on page 31. Both of these rules search for the HTML attribute src with any

value and output the result of applying the transform uri abs function.

Table 4-6 Regular Expression rule

Text Matched Rule

Database A

Database list B

Data form C

MyString D

Input Output

src=(|)(.*?)\1 src=@param(1)@transform uri abs(

@param(2))@param(1)


41/74

Chapter 4. Rules31

When the rules are compared in this way, it is easy to see the relative simplicity of the HTMLrules versus their Regular Expression counterparts. However, this simplicity also means alack of flexibility when defining a new rule. For this reason, the decision over which parser

best suits your needs may depend on the complexity level of the rules you will need.

Table 4-7 Equivalent HTML rule

Tag Input Output

*


src * src @transform uri abs


42/74



43/74


Chapter 5. Samples

Now that you have acquainted yourselves with the theoretical aspects that underlie the

workings of DAP, you are ready to delve into a practical application. In order to complete thefollowing tutorial you will need the following:

1. A Domino 6.X server (in this document well give it the fictitious namedomino.domain.com)

2. A portal server (this one we call portal.domino.com)

We will host a sample application, called Sample.nsf (supplied with this document), on the

Domino server and configure DAP so that the same application will be visible through theportal. We aim to cover as many features of DAP as possible, so we will gradually increase

the complexity of the setup.

5


44/74


5.1 Setting up Domino

The sample database (Sample.nsf) needs to be copied into the Data folder of the Domino

server. This should be enough to expose the application throughhttp://domino.domain.com/Sample.nsf. Initially, we will keep all authentication off. We willthen enable this later, once weve verified that all other parts work as intended.

5.2 Setting up DAP

The portal server needs to have DAP installed, verify that this is the case through the

administrative console. To check this, log into the portal as an administrative user throughhttp://portal.domain.com:9081/wps/myportal. Note that we are connecting to the portaldirectly, depending on your setup you may omit the port and connect to the portal via the

HTTP server. Navigate to the Administration section, then select Portlets -> Manage Portlets;

the list should include an entry for a Domino Application Portlet. If that is the case you can

go ahead and create a page to host the portlet, otherwise you have to install the portlet first.

5.2.1 Install portlet

To do that you will need a copy of the standalone portlet archive (dap.war); under Portlets

click Install, browse to the archive, click Next, and finally confirm the action by clicking theInstall button. You should see a message that confirms the installation of the por tlet.

5.2.2 Create page

Now we need a page to host the portlet, to do this click Portal User Interface and then

Manage Pages on the navigation bar on the left. We suggest you create the new page underthe MyPortal label. Most out-of-the-box portal installations will have this section set up bydefault. So click the MyPortal link followed by the New Page button, give it a nice name, for

example Sample Domino Application and confirm with OK.

5.2.3 Add portlet to page

To add the portlet to the page you click the pencil icon in the page list of the MyPortal section,this will lead you to the portal layout editor, keep the default layout for the page and click the

Add Portlet button, you will be presented with a list of all the available portlets. Chances arethat there are a lot of portlets installed on your system, so the easiest way to find DAP is toreduce the list by entering some search criteria. By searching for the word domino in the

portlet titles, the list should reduce to a handful of portlets, tick the selection box next toDomino Application Portlet and click OK. The system should confirm the success of the last

operation and to complete the addition of DAP to the page click the Done button. You cannow look at a running instance of DAP by navigating to the MyPortal section and then to

Sample Domino Application Page; you should see a window similar to Figure 5-1 on page 35.


45/74

Chapter 5. Samples35

Figure 5-1 Working DAP setup, portlet not yet configured

5.2.4 Initialize portletAll that remains to do is to point DAP to the sample application on the Domino server, click thepencil icon and on the following page enter domino.domain.com (or rather, the actual name of

the Domino server that you are using) as the host and Sample.nsf in the path and filenamebox. Click first on Save, then on the Close button. You must also check that authentication is

set to None, to do that click the wrench icon to enter the portlet configuration mode and selectthe Authentication tab. DAP defaults to Basic authentication so you will probably have to

select the None option.

If you made any changes here click Save and then Close. Now you should see a window

similar to Figure 5-2 on page 36. If that isnt the case, ensure you followed all the stepsoutlined above.


46/74


Figure 5-2 Sample application as seen through DAP - note how the applet images failed to load

5.3 Exploring the application

You should also make yourself familiar with the application as seen directly from the Domino

server, as there are a couple of issues with the one seen through the portal. The base rulesthat the portlet ships with will ensure that most of the application will work, yet we will focus on

the bits that do not to illustrate DAPs modus operandi. So point your favorite browser tohttp://domino.domain.com/Sample.nsf and notice how there are some icons in the appletsview area (Figure 5-3 on page 37), compare this with the portalized application (Figure 5-2).

Also observe the behavior of the Info button of the sample application both when seen

through DAP and when seen directly from Domino. In the following paragraphs we hope tointroduce you to the art of rule-making, as you will see it will require a good dose of instinct

and plenty of experience to successfully identify the fragments of a page that require sometranslation to be viewed through DAP.


47/74


Figure 5-3 The sample application as seen directly from Domino

5.4 Fixing the icons

As we mentioned the application viewed through DAP is missing two icons, being an appletthe initial strategy is to inspect the applets tags both when viewed directly on Domino and

when viewed through DAP. To view the markup of the two pages, right-click the frame andselect View Source.

This is what we saw on our test servers:

From Domino: (Example 5-1)

Example 5-1 Example of code shown through Domino


48/74


Through DAP: (Example 5-2)

Example 5-2 Example of code shown through DAP

As you can see the codebase attribute of the applet tag is successfully reverse-proxied, and

we urge you to find the corresponding rule in the standard ruleset that is responsible for thistranslation. You should also note that the URL1 parameter that is passed to the appletobviously refers to a resource on the Domino server, namely the abook.gif icon in the /icons

folder. When the page is viewed through the portlet it will request the /icons/abook.gif imagefrom the Portal server which will of course fail. What we need is a rule that will reverse-proxy

the value of the URL parameter; click the spanner icon of the portlet and select the Rules tab.Ensure that the rule type is set to Regular Expression. Scroll to the bottom of the page and

click the insert rule icon (Figure 5.4) of the last rule. Enter the following in the newly createdboxes:

Figure 5-4 Insert Rule Icon

Regular expression:


49/74


...

Clearly the applet is being modified programmatically and we need to reverse-proxy the string

that is being passed to it through the setImage2 method. Append the following rule to theruleset: Regular expression:

\.setImage2$"(.*?)"$

Output model:

.setImage2("@transform_uri_all(@param(1))")

After saving you should see both icons in the applets box, as shown in Figure 5-5.

Figure 5-5 Display of both icons in applets box

5.5 TCP/IP trace proxies

Admittedly this example is quite simple, you will find that generally it is considerably trickier to

identify the text that requires processing by the parser. During development of the portlet wefound that TCP tracing utilities are exceedingly useful for debugging purposes. These utilities

act as a proxy and let you view a trace of all the request and responses between the browserand the portal and also between portal and the Domino server. WebSphere Studio

Application Developer includes a special type of server a TCP Monitor which you can use asa tracer but you can also find freeware utilities on the Internet that offer the same functionality.

Refer to the WebSphere Studio documentation to set up a TCP Monitor. A typical test setupwould look like the one shown in Figure 5.6, assuming that the workstation that you areworking on is computer.domain.com.

Figure 5-6 Set-up to capture HTTP traces with the use of proxy trace utilities


50/74


You will need to configure your browser to route its requests to a proxy. Typically you wouldrun the trace utility on your local machine, thus you would point your browser to localhostand whatever port you have configured your proxy trace utility to listen at. Note also that most

Domino applications make use of applets which may make their own network requests. Somake sure your plugin is configured to route HTTP requests to the proxy. Internet Explorers

JVM does not support this but Suns Java plugin does, you can find the relevant options inthe Java plug-in control panel under the Proxies tab. DAP, like a browser, can be configured

to route all its requests to a proxy, this option is available in the configuration view under theSource and Display tab where you can specify the Proxy Source Server.

For the above example setup we would set the proxy source server host tocomputer.domain.com and the port to 8081. We cant stress enough how useful a HTTP

trace can be when debugging a DAP-ed application.

For example if the applet of the sample application used a default location to find its icons it

would not be immediately obvious that the icon is even being requested. If a proxy trace is inplace we would see something like:

GET http://portal.domain.com:9081/icons/actn001.gif HTTP/1.1cookie: JSESSIONID=000026kWPj0CPiVpb9-ZtxEeZgU:-1

User-Agent: Mozilla/4.0 (Windows 2000 5.0) Java/1.4.2 02Host: portal.domain.com:9081Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2Proxy-Connection: keep-alive

Failing with:

HTTP/1.1 404 Not FoundServer: WebSphere Application Server/5.0Content-Type: text/htmlContent-Length: 159Virtual Host or Web Application NotFound
The web group /icons/actn001.gif has not beendefined
IBM WebSphere Application Server

The mere presence of a 404 indicates that something is amiss. There is also a whole group ofother problems that would be very hard to diagnose without the help of a trace, for instance it

is often necessary to inspect data that is posted as a consequence of a form submission or itmay happen that the wrong output model function is used to transform a particular URI whichin turn results in some funny requests that without a trace would remain undetected.

5.6 Fixing the greedy information page

One thing you might not have noticed is that when you click the Info page of the applicationthrough DAP it will grab the entire page and seemingly leave the portal. We will have to look

at what exactly happens when the Info button is clicked, here is what the buttons tag lookedon our test setup:


51/74


Obviously a series of JavaScript instructions are executed upon a click which assemble aURL from the current location and then the browser is then sent to it. Notice how the targetframe for this operation is top.

This is not quite what we want; instead we want the target to be ifa which is the IFRAME

containing the reverse proxied page. Thus by adding the rule:

Regular expression:

_top

Output model:

ifa

We will obtain the desired behavior. The above example is somewhat contrived, and the rules

used to fix far from ideal. The problem is that the rule top is very general and it may well

match some text that we do not want to translate. If the text top appears anywhere in themarkup it will be translated, for example if elsewhere on the page we had a script with a

variable named about to topple that would be transformed into about to ifaple which will inall likelihood prevent the page from working correctly. Sometimes it will prove too difficult to

come up with regular expressions that are sufficiently discriminating, in this case you will haveto provide pass-through rules for all the instances in which it matches something it shouldnt.

In the example above, we would have to add a rule with about to topple as both regularexpression and output model with a higher priority than the top-only rule to prevent it frombeing garbled.

5.7 Switching to the HTML parser

The three rules above have of course corresponding rules in the HTML parser. To try theseout switch to the HTML parser and add the following rule:

Input match:

Tag paramInput attribute nameValue URL1

Output:

Output attribute valueOutput value @transform_uri_all

This is the dual of the first rule we added for the regular expression parser. The other tworules are identical as they are processed by the javascript parser, so you can append them

verbatim into the Java Script Rules section of the HTML parser configuration.


52/74


Figure 5-7 Requiring authentication, Anonymous access is set to No Access

5.8 Escalating security

To start off with we had no security enabled. We will now proceed and ensure users areauthenticated when they access a database through DAP. Using the Domino Administrativeconsole modify the ACL so that Anonymous access is disabled for the Sample.nsf database

(see Figure 5-7) and add one of your Domino users to the ACL1. Also ensure that sessionauthentication is disabled in the server document under Internet ProtocolsDomino Web

Engine. You should now see an error message when viewing the database through DAP(Figure 5.8).

1 If you get insufficient rights when modifying the ACL you may need to modify it locally before starting the Domino

server


53/74


Figure 5-8 Domino requires authentication but DAP is not yet configured to supply credentials

To solve the situation we must set the corresponding authentication method for DAP, sonavigate to the Authentication tab in the portlets configuration and select the basicAuthentication model (see Figure 5-9).

Figure 5-9 Setting up DAP to use basic authentication

Now we only need to specify the credentials. Click the pencil icon and enter the usernameand password of a user in the databases ACL, once these are saved you should see the

sample application as previously. Please refer to the chapter on authentication for a morein-depth description of the basic authentication scheme. It is not advised to use this

authentication model if the communication channel between the Portal and the Dominoserver is not secured because the credentials are transferred unencrypted with each request,

making it trivial for an eavesdropper to intercept them. The session authentication model isslightly more secure in that the credentials are transmitted to the host only once, so browse toDAPs configuration page and switch the authentication model to Session. You will see an

error message similar to the one you saw earlier (see Figure 5-8, this is because the Dominoserver is not configured to accept session authentication yet). To enable this, open your

Server Document in Domino Administrator or WebAdmin and under Internet ProtocolsDomino Web Engine set Session authentication to Single Server (see Figure 5-10 on

page 44).


54/74


Figure 5-10 Enabling Domino Session authentication

Save the document and restart the HTTP task to make the change effective (either restart the

Domino server or type tell http restart in the console). DAP will now use the credentials thatyou used previously but instead of re-transmitting them with every request it will re-transmit

only the authentication token it received from Domino. Enabling SSO is somewhat moreinvolved we refer you back to the chapter on Authentication where you can find instructions on

how to set up SSO between WebSphere and Domino.

5.9 Another sample

In this second example we are going to work with a mail database (instantiated from amail6.ntf template) on the same Domino server that we used previously. We will assume that

you created the database under mail/username.nsf; set up a new page with the DominoApplication Portlet and point it to mail database. For this example you will need to import a

custom ruleset, called Sample2Rules.xml, supplied with this document. You should also firstsave a copy of the original ruleset just in case you need to restore the portlet to its originalstate. To export a ruleset open the configuration view by clicking on the wrench icon and click

the Rules tab. When you click the Export button you will be asked to specify a file name andlocation, for example you may enter OriginalRules.xml and note where the file will be saved.

To import the ruleset for this sample, simply click the Import button and then browse to the fileyou downloaded earlier. Once you have completed all these steps view the page you just

created and notice that the HTML has loaded, but the appletlotus.notes.apps.actionbar.ActionBar has failed to load. (Figure 5.11)


55/74


Figure 5-11 The action bar applet failed to load

Like in the previous example, the principal tool that we will utilize to debug the application willbe tracing, so you will need a setup as described in the previous section to be able to inspect

the requests and responses. So here is what we found in our test setup:

Request:

GET http://portal.domain.com:9081/domjava/actionbar.jar HTTP/1.0Accept-Language: en-IR

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Win32)Host: portal.domain.com:9081Proxy-Connection: Keep-AliveCookie: JSESSIONID=0000XGb_2MNQTpdvV_IhKLZd4WK:-1;

wcp-context=wpsadmin@1@base

Response:

HTTP/1.1 404 Not FoundServer: WebSphere Application Server/5.0Content-Type: text/htmlContent-Length: 192Connection: close

Virtual Host or Web Application Not Found
The web group /domjava/actionbar.jar has not beendefined
IBM WebSphere Application Server

By examining this trace of the request/response interaction between the browser and theDomino Application Portlet, we can see that the request for actionbar.jar has generated aFileNotFound Error. The offending request was for the URL:http://portal.domain.com/domjava/actionbar.jar.


56/74


However, the applet is located on the Domino Server not the Portal server, so it cant befound.

Looking at the source code for this page shown in Figure 5-12, we can see that the location ofthe applet is /domjava. Since we are redirecting through the Portal Server, we need to

transform this URL to reflect this.

Figure 5-12 The original source, which resulted in a request for /dom-java/actionbar.jar to the Portal

server

We need a rule which takes the value of the codebase attribute and changes it to redirect it tothe portal server. The output function @transform_uri_abs can perform this redirection. Soour new rule is:

codebase="(.*?)" => codebase="@transform_uri_abs(@param(1))"

Figure 5-13 The HTML markup of the reverse-proxied page

As shown

lotus domino app portlet configuration-redp3917

Documents