Front cover
WebSphere Portal 4.12
Collaboration Services
Hints and Tips for performing a
successful installation
Use of the Collaborative
Components API and tags
Sample collaborative
portlets
William Tworek
Vince Fertig
Daniel de la Fuente Martinez
Margaret O’Connell
Michael Renner
ibm.com/redbooks
Redpaper
International Technical Support Organization
WebSphere Portal 4.12 Collaboration Services
August 2002
Note: Before using this information and the product it supports, read the information in
“Notices” on page vii.
First Edition (August 2002)
This edition applies to WebSphere Portal Extend, v4.12
© Copyright International Business Machines Corporation 2002. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The team that wrote this Redpaper . . . . . . . . . . . . . . . . . .
Become a published author . . . . . . . . . . . . . . . . . . . . . . . .
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.......
.......
.......
.......
......
......
......
......
. . . ix
. . . ix
. . . xi
. . . xi
Chapter 1. Introduction to WebSphere Portal. . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Introduction to WebSphere Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 What is the WebSphere Portal family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.1 WebSphere Portal Enable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.2 WebSphere Portal Extend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.3 WebSphere Portal Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 The WebSphere Portal infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.1 WebSphere Portal runtime process flow . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 2. Installation, configuration, and deployment planning . . . . . . 11
2.1 The installation process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1.1 The Setup Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1.2 Install approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1.3 Hints/tips for using the Setup Manager . . . . . . . . . . . . . . . . . . . . . . . 14
2.2 Installing manually. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3 Integration with Lotus collaboration technologies . . . . . . . . . . . . . . . . . . . 22
2.3.1 Lotus Domino integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.2 Lotus Sametime integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.3.3 Lotus QuickPlace (2.08) integration . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.3.4 Lotus Discovery Server integration . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.4 Testing your WebSphere Portal Extend install . . . . . . . . . . . . . . . . . . . . . 30
2.4.1 Verifying Domino integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.4.2 Verifying people awareness and menu services . . . . . . . . . . . . . . . . 32
2.5 Deploying the collaborative portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.6 Deploying the Collaborative Components (API) . . . . . . . . . . . . . . . . . . . . 34
2.7 Installed components of WebSphere Portal Extend . . . . . . . . . . . . . . . . . 36
2.7.1 Key files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.7.2 Log files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.7.3 Registry entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.7.4 Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.8 Collaborative portal deployment planning . . . . . . . . . . . . . . . . . . . . . . . . . 40
© Copyright IBM Corp. 2002. All rights reserved.
iii
2.8.1
2.8.2
2.8.3
2.8.4
General WebSphere Application Server considerations . . . . . . . .
A test and proof-of-concept environment . . . . . . . . . . . . . . . . . . .
A more typical production environment. . . . . . . . . . . . . . . . . . . . .
Collaboration technology considerations (LDAP and SSO) . . . . .
..
..
..
..
40
40
41
43
Chapter 3. Collaborative portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.1 An introduction to key portlet concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.1.1 What a portlet is . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.1.2 Portlet modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.2 Introduction to the collaborative portlets . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.2.1 Included collaborative portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.2.2 Other collaborative portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.2.3 Downloading collaboration portlet updates (portlet catalog) . . . . . . . 53
3.2.4 A sample use of the collaboration portlets . . . . . . . . . . . . . . . . . . . . 54
3.3 The Notes portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.3.1 NotesView portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3.3.2 NotesMail portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
3.3.3 MyNotes portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.3.4 Notes Discussion and Teamroom portlets . . . . . . . . . . . . . . . . . . . . 69
3.3.5 Common features of the Notes portlets . . . . . . . . . . . . . . . . . . . . . . 70
3.4 iNotes portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
3.5 Sametime portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
3.6 Quickplace portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.7 Bookmark and Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.7.1 Bookmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.7.2 Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.8 Collaborative portlet deployment considerations. . . . . . . . . . . . . . . . . . . . 79
3.8.1 Do not forget browser limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.8.2 Consider enabling caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.8.3 Notes on Domino compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
3.8.4 Setting myportal addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Chapter 4. Collaborative Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4.2 Overview of the Collaborative Components . . . . . . . . . . . . . . . . . . . . . . . 85
4.2.1 Infrastructure objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.2.2 Java service objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.2.3 Subordinate objects for DominoService . . . . . . . . . . . . . . . . . . . . . . 86
4.2.4 Tag language descriptors for custom tags . . . . . . . . . . . . . . . . . . . . 86
4.3 Developing a basic collaborative portlet . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.3.1 Software prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.3.2 Setting up WebSphere Studio Application Developer . . . . . . . . . . . . 88
4.3.3 Writing a basic collaborative Hello portlet . . . . . . . . . . . . . . . . . . . . . 90
iv
WebSphere Portal 4.12 Collaboration Services
4.3.4 Deploying the Collaborative Hello portlet . . . . . . . . . . . . . . . . . . . . . 95
4.4 Advanced collaborative portlet samples . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4.4.1 PeopleSample portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4.4.2 MenuSample portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.4.3 An advanced collaboration sample . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.4.4 Deploying Advanced Collaboration portlets . . . . . . . . . . . . . . . . . . 115
4.5 Best practices for collaborative portlet development. . . . . . . . . . . . . . . . 119
4.5.1 Debugging recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.5.2 Portlet deployment considerations . . . . . . . . . . . . . . . . . . . . . . . . . 120
4.5.3 Portlet performance considerations . . . . . . . . . . . . . . . . . . . . . . . . 121
Appendix A. Collaborative Components: classes/methods . . . . . . . . . . 125
CalendarDayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
ColumnInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
CSCredentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
CSEnvironment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
CSFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
DiscoveryServerService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
DominoService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
EntryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
PeopleService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
QPService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
RowInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ViewInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Appendix B. Collaborative Components: tag libraries . . . . . . . . . . . . . . 153
People Service tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Menu Library tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Appendix C. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Related IBM Redbooks/Redpapers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Product documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Contents
v
vi
WebSphere Portal 4.12 Collaboration Services
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. 2002. All rights reserved.
vii
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
AIX®
DB2®
IBM®
Perform™
Redbooks™
Redbooks(logo)™
SP™
Tivoli®
TME®
WebSphere®
xSeries™
The following terms are trademarks of International Business Machines Corporation and Lotus Development
Corporation in the United States, other countries, or both:
Domino Designer®
Domino.Doc®
Domino™
iNotes™
K-station™
Lotus Discovery Server™
Lotus Notes®
Lotus®
Notes®
QuickPlace™
Sametime®
SmartSuite®
Word Pro®
The following terms are trademarks of other companies:
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United
States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
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.
C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure
Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service marks of others.
viii
WebSphere Portal 4.12 Collaboration Services
Preface
The WebSphere Portal Family consists of three packaged offerings: the Portal
Enable offering is the base offering; Portal Extend and Portal Experience add
more functionality. WebSphere Portal Extend allows your portal users to act on
information and applications accessed by collaborating with other portal users.
This Redpaper discusses the collaborative capabilities included in the
WebSphere Portal Extend offering. It covers:
򐂰 An introduction to the WebSphere Portal Family and the concept of
collaborative portlets
򐂰 Installation and deployment-oriented topics for getting a collaborative Portal
Extend environment up and running
򐂰 Details about the Collaborative Portlets available out-of-the-box with Portal
Extend
򐂰 Details and best practices for the use of the Collaborative Components API
and Tags available with Portal Extend, including several sample Collaborative
Portlets that leverage this API.
This Redpaper is primarily intended for technologists involved with collaborative
WebSphere Portal projects. However, the introductory content in each chapter
may be useful to managers who are responsible for such projects.
The team that wrote this Redpaper
This Redpaper was produced by a team of specialists from around the world
working at the International Technical Support Organization, Cambridge Center.
William Tworek is a Project Leader with the International Technical Support
Organization, working out of Westford, Massachusetts. He manages projects that
produce Redbooks on various topics involving IBM and Lotus Software
technologies. Prior to joining the ITSO, he was an IT Architect in the consulting
industry working for Andersen Consulting/Accenture, followed by IBM Software
Services for Lotus. His areas of expertise include system integration and
systems infrastructure design.
Vince Fertig is an IT Architect with IBM Software Services For Lotus in
Cambridge MA. He has over 13 years of experience in the IT industry. His areas
of expertise include object-oriented analysis and design, multi-threaded
© Copyright IBM Corp. 2002. All rights reserved.
ix
client/server applications, and systems programming. His recent areas of focus
have been in designing and developing solutions involving Domino, Sametime,
and WebSphere.
Daniel de la Fuente Martinez is an IT Architect with IBM Software Service for
Lotus, based in Spain. He holds a degree in information technology from
Polytechnician University of Madrid, and recently received his MBA from IESE
business school in Madrid. He leads the development group in ISSL Spain,
supporting the sales and delivery process in the Banking and Public
Administration sectors. He has published several technical articles about
Domino and related technologies.
Margaret O’Connell is an Advisory Software Engineer currently working on the
Lotus NextGen efforts to develop collaborative components for J2EE. Margaret
has been with the IBM Software Group for more than six years. She was the
team lead for the architecture and development of the Lotus Collaborative
Components (LCC) deliverable for WebSphere Portal Server, version 4.1. Before
working on LCC, Margaret worked on the Lotus SmartSuite, eSuite, and
K-station products. Margaret holds a Masters degree in Mathematics from
Boston College.
Michael Renner is an IT Specialist with IBM Switzerland. He joined Lotus as a
systems engineer responsible for global accounts in EMEA. He current ly
supports the sales team with technical know-how, and provides product
presentations and demonstrations on the current Lotus products for customers.
Along with two colleagues, he runs the Swiss Lotus Technology Center,
specializing in portals and LDS, software engineering (software development on
Domino and Java), and system integration (LEI) in Switzerland. Michael worked
with Domino for four years before joining Lotus.
We would also like to thank the following people for their contributions to this
project:
򐂰 Chris Reckling, Senior Product Manager, Dynamic Workplace Solutions Lotus Software, IBM Software Group
򐂰 Gregg Cherbonneau, Marketing Manager, Advanced Collaboration, Lotus
Software, IBM Software Group
򐂰 Andrew Gawin, Product Specialist - Lotus Software, IBM Software Group
򐂰 Dan Collins, Product Specialist - Lotus Software, IBM Software Group
򐂰 Doug McDonald, Staff Software Engineer, Portal Solutions - Lotus Software,
IBM Software Group
򐂰 Mary Shaheen, Staff Software Engineer, Portal Solutions - Lotus Software,
IBM Software Group
x
WebSphere Portal 4.12 Collaboration Services
򐂰 Thangaraj Veerappan, Advisory Software Engineer, Portal Solutions - - Lotus
Software, IBM Software Group
򐂰 Eric Portner, SeniorSoftware Engineer, Portal Solutions - Lotus Software, IBM
Software Group
򐂰 Zhouwen Lu, Staff Software Engineer, Portal Solutions - Lotus Software, IBM
Software Group
򐂰 Mary Carbonara, Information Developer, KM Applications - Lotus Software,
IBM Software Group
򐂰 William Drake, Consulting IT Architect - IBM Software Services for Lotus
򐂰 The authors of the Portlet Development Guide Working with the Portlet API,
Stephan Hesmer, Peter Fischer, Ted Buckner, Ingo Schuster. Material from
this guide was used in producing this Redpaper.
򐂰 The authors of the WebSphere Portal Extend InfoCenter. Material from the
InfoCenter was used in producing this Redpaper.
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 Internet note to:
Preface
xi
redbook@us.ibm.com
xii
WebSphere Portal 4.12 Collaboration Services
1
Chapter 1.
Introduction to WebSphere
Portal
IBM WebSphere Portal provides a single point of access to applications,
application content, processes, and people in your network. In order to provide
this unified access, WebSphere Portal implements rich and valuable functions.
This chapter presents an overview of the IBM WebSphere Portal offerings, and
briefly introduces the architecture and wide variety of functionalities of the
WebSphere Portal components.
The rest of this paper then specifically discusses the Lotus Software
Collaborative Components and Collaborative Portlets that are part of the
WebSphere Portal Extend - as introduced in 1.2.2, “WebSphere Portal Extend”
on page 5.
© Copyright IBM Corp. 2002. All rights reserved.
1
1.1 Introduction to WebSphere Portal
IBM WebSphere Portal allows you to establish customized portals for your
employees, Business Partners, and customers. As illustrated in Figure 1-1, the
framework architecture implemented in this product provides a unified access
point to internal and external Web applications as well as portal access to other
legacy applications. In this way, users sign on to the portal and receive
personalized Web pages.
Figure 1-1 Horizontal and vertical portals
The personalized single point of access to all necessary resources reduces
information overload, accelerates productivity, and increases Web site usage. In
addition, portals do much more; for example, they provide additional valuable
functions such as security, search, collaboration and workflow.
A portal delivers integrated content and applications, plus a unified, collaborative
workplace. Indeed, portals are the next-generation desktop, delivering
e-business applications over the Web to all kinds of client devices.
IBM WebSphere Portal Version 4.1 has been designed in response to the
following set of fundamental business objectives:
򐂰 A single point of access to all resources associated with the portal domain
򐂰 Personalized interaction with the portal services
򐂰 Federated access to hundreds of data types and repositories, aggregated and
categorized
򐂰 Collaboration technologies that bring people together
򐂰 Integration with applications and workflow systems
IBM as well as some industry analysts have coalesced around the concept of
horizontal and vertical portals. Horizontal portals are the primary infrastructure
upon which a portal is built. Vertical portals are built upon the horizontal layer and
represent a specific portal instance, usually defined by a major topic or domain.
2
WebSphere Portal 4.12 Collaboration Services
As illustrated in Figure 1-2, the horizontal portal infrastructure consists of several
modular subsystems including the following:
򐂰 Presentation layer - a Web user interface plus pervasive device support
򐂰 Personalization - the ability to serve dynamic response to the user based on
personal profiles
򐂰 Collaboration - tools that allow e-mail, team rooms, shared places, etc. to be
exchanged
򐂰 Portlets - a framework for easily attaching software modules (portlets) and
services
򐂰 Applications and workflow - integration of legacy and new applications
򐂰 Search and navigation - categorizing repositories of content and searching
them for relevant information
򐂰 Publish and subscribe - the ability to author new content and publish it to
subscribers
򐂰 Administration and security - basic Web site services such as page designers,
performance monitors, cluster services, and metadata management
Integration - metadata sharing, XML, connectors, standards, EAI
Figure 1-2 WebSphere Portal architecture
Chapter 1. Introduction to WebSphere Portal
3
WebSphere Portal provides additional services such as single sign-on, security,
Web content publishing, search and, personalization, collaboration services,
enterprise application integration, support for mobile devices, and site analysis.
Note: WebSphere Portal provides an extensible framework for interacting with
enterprise applications, content, people, and processes. Self-service features
allow end users to personalize and organize their own view of the portal, to
manage their own profiles, and to publish and share documents with their
colleagues.
1.2 What is the WebSphere Portal family
IBM WebSphere Portal provides three offerings: Enable, Extend, and
Experience, each designed to provide the infrastructure you need to build and
deploy highly scalable portals. These three offerings share a common framework
(the portal server) plus additional products and services. The Enable offering is
the base offering for the Portal offerings; Extend and Experience add more
functionality.
1.2.1 WebSphere Portal Enable
The IBM WebSphere Portal Enable offering lets you quickly build highly scalable
portals that simplify and speed your access to personalized information and
applications. Portal Enable provides common services including:
򐂰 Connectivity and integration to allow access to enterprise data, external data,
or even your trading partners’ applications
򐂰 Presentation and administration to enable computing desktop customization
to match your own work patterns and needs
WebSphere Portal
WebSphere Portal provides personalization, user management, security, and
other services for constructing the portal site.
WebSphere Personalization
The WebSphere Personalization offering provides personalization technologies
for targeting Web content to meet user needs and preferences:
򐂰 Rules-based personalization, where the business manager defines a set of
business rules that determine which Web content is displayed for a particular
user.
4
WebSphere Portal 4.12 Collaboration Services
򐂰 Recommendations, using advanced statistical models and other matching
techniques to extract trends from the behavior of Web site visitors. This
approach adapts to changing trends in visitor interests without creating new
business rules.
򐂰 Campaign management, for e-mail and Web-based promotions, such as
enrollment offers or product introductions.
Web Content Publisher
Provides a browser-based interface that enables nontechnical users to create,
contribute and manage content on portals and Web sites in a simple and
controlled manner. Features such as template management, workflow
management, versioning, and access control allow you to publish content quickly
and efficiently, providing end users access to the most up-to-date information
when they need it.
WebSphere Studio Application Developer
These are professional developer tools for creating, testing, debugging, and
deploying portlets, servlets, and other assets related to portals and Web
applications.
1.2.2 WebSphere Portal Extend
The WebSphere Portal Extend offering allows portal users to act on information
and applications accessed by collaborating with other portal users. This offering
includes all capabilities of the Enable offering, plus integrated team room, instant
messaging, extended search, community and Web site analysis capabilities.
Lotus Collaborative Components
Lotus Collaborative Components are building blocks (APIs and JSP tag libraries)
for integrating the functionality of Lotus Domino, Lotus Sametime, Lotus
QuickPlace, and Lotus Discovery Server into the portal. Developers can leverage
the features of Lotus Domino, Lotus QuickPlace, Lotus Sametime, and Lotus
Discovery Server by using these components to add user interface extensions to
their portlets and portal pages.
Lotus collaborative portlets
The collaborative portlets for Lotus advanced collaboration software included the
WebSphere Portal Extend and WebSphere Portal Experience offerings have
advanced built-in features that allow portal users to take actions on documents or
user names that appear in a portlet.
A portal user can see, directly from the portlet, if other users are online and then
select from a menu of options to interact with those users. Based on the context
Chapter 1. Introduction to WebSphere Portal
5
of the portlet, document actions allow users to take actions directly from the
portlet with or without launching the entire application. For example, Lotus Notes
e-mail portlets make any e-mail author's name live with online awareness and
menu options without altering the underlying e-mail application.
Collaborative portlets are available for all Lotus advanced collaboration
technologies, including: Lotus Notes/Domino, iNotes, Sametime, QuickPlace,
Discovery Server, and Extended Search.
Bookmarks
Bookmark capabilities are also included with the Extend offering. In the portal
environment, bookmarks are links to any Web address. Portal users can store
personal bookmarks, or bookmarks for the entire team. They are stored on the
server instead of on the browser, allowing them to be seen by all members of a
shared portal page. Bookmarks can be used to point to important news articles
or important information relevant to the team.
IBM Lotus Extended Search
IBM Lotus Extended Search provides parallel, distributed, heterogeneous search
capability across Notes domains, legacy data stores, and the Internet—from
within the Notes environment or via a Web browser. The result is single-point
access to a variety of data stores including Domino 4.5 and higher, relational
databases (IBM DB2, Oracle, Sybase, MS SQL Server, MS Access),
Domino.Doc, MS Index Server, MS Site Server, MS Exchange and over 18 Web
search sites.
Previously released as Domino Extended Search, IBM Lotus Extended Search
3.7 works across a number of Web application servers including Domino,
WebSphere, Microsoft IIS and IBM HTTP Server.
IBM Tivoli Web Site Analyzer
IBM Tivoli Web Site Analyzer is an enterprise-level Web analytics tool that
transforms random Web data into valuable e-business intelligence. It provides a
clear picture of the overall health and integrity of the e-business infrastructure
supporting business outcome management.
By capturing, analyzing, storing and reporting on Web site usage, health,
integrity, and site content, IBM Tivoli Web Site Analyzer can shed light on visitor
site interactions and the site's overall performance. You can leverage this insight
to optimize the site for increased customer loyalty and e-business effectiveness.
6
WebSphere Portal 4.12 Collaboration Services
Lotus Discovery Server Integration
Another concept that is key to WebSphere Portal Extend offering is the Lotus
Discovery Server integration. It is this integration, not the Discovery Server
product itself, that is packaged with WebSphere Portal.
When using Lotus Discovery Server with WebSphere Portal Extend or
WebSphere Portal Experience, certain features are automatically enabled inside
the portal. Examples of integration include additional menu options that appear
when you click on a user name in a portlet, allowing you to perform actions such
as searching for all documents by the user selected, or launching a profile of the
user that is maintained and stored with the Discovery Server.
1.2.3 WebSphere Portal Experience
The Portal Experience offering includes all products in the Extend offering and
adds additional tools and functionality including advanced collaboration, content
management, and security policy management, creating the most
comprehensive portal offering on the market.
Features include:
򐂰 Advanced collaboration features for e-meetings, application sharing, and
whiteboarding (whiteboards are used in teleconferencing applications) enable
effective online collaboration, as well as the ability to take team rooms offline.
򐂰 Data storage for a broad spectrum of digital information including facsimiles,
images, PC files, XML files, and multimedia.
򐂰 Content infrastructure for applications including call center, high-volume
claims processing, and accounts payable.
򐂰 Folder management and document workflow.
򐂰 Sample Java applications, as well as advanced application development
tools.
򐂰 Security policy management tools for e-business and distributed applications.
IBM Content Manager
This offering provides data store capabilities for a broad spectrum of digital
business information, for example scanned images, facsimiles, PC files, XML
files, and rich multimedia and Web content. Content Manager also provides
folder management and document workflow. It provides the content infrastructure
for applications from call centers, high-volume claims processing, and accounts
payable, to e-commerce catalogues and e-learning.
Chapter 1. Introduction to WebSphere Portal
7
IBM Tivoli Access Manager
Tivoli Access Manager provides security policy management tools for e-business
and distributed applications. It is a policy-based access control solution for
e-business and enterprise applications.
1.3 The WebSphere Portal infrastructure
IBM WebSphere Portal provides a framework that breaks the different portal
components into portlets to accommodate the aggregation and display of diverse
content. Each portlet is responsible for accessing content from its source (for
example, a Web site, database, or e-mail server) and transforming the content so
that it can be rendered to the client.
From a user’s perspective, a portlet is a small window in the portal that provides a
specific service or information. From an application development perspective,
portlets are pluggable modules that are designed to run inside a portlet container
of a portal server. The portlet container provides a runtime environment in which
portlets are installed and used.
Portlets rely on the portal infrastructure to access user profile information,
participate in window and action events, communicate with other portlets, access
remote content, look up credentials, and store persistent data. The Portlet API
provides standard interfaces for these functions.
The portlet container is not a stand-alone container like the servlet container.
Instead, it is implemented as a thin layer on top of the servlet container and
reuses the functionality provided by the servlet container.
For more information about portlet API, refer to the Portlet Development Guide
at:
ftp://ftp.software.ibm.com/software/webserver/portal/V41PortletDevelopmentG
uide.pdf
1.3.1 WebSphere Portal runtime process flow
After installation, the portal developer develops and deploys the portal to users.
The developer alters the layout and appearance of the default portal page by
selecting a theme and skins that WebSphere Portal provides, or by creating a
page layout that matches a corporate standard. A portlet programmer writes and
registers additional portlets by using the portlet API.
After the portal recognizes user data, a user can log on to the portal. If a user
attempts a logon, the incoming request passes through an authentication layer
8
WebSphere Portal 4.12 Collaboration Services
that provides controlled access to the portal. If the logon is authenticated, a
single sign-on component stores user information for later use by other programs
that require authentication, and user information is placed in a data store, such
as an LDAP directory or a relational database. Based on the user information,
the portal framework retrieves the portal page layout and customization data
from storage. WebSphere Portal processes the layout by generating markup for
the portal page and rendering the portlets that are accessible to the user.
Figure 1-3 illustrates the runtime process flow in WebSphere Portal.
Figure 1-3 WebSphere Portal process flow (runtime)
Chapter 1. Introduction to WebSphere Portal
9
10
WebSphere Portal 4.12 Collaboration Services
2
Chapter 2.
Installation, configuration,
and deployment planning
This chapter describes the installation and setup process for WebSphere Portal
Extend. The goal of the chapter is not to provide step-by-step procedures and
screen shots, but rather to highlight the key points and crucial considerations
required for a successful installation and deployment.
In general, this chapter discusses:
򐂰 Hints and tips for installation and configuration of a single WebSphere Portal
Extend server
򐂰 Considerations for a real world/multi-server deployment
򐂰 Crucial steps for successful integration with required Lotus collaboration
technologies (that is, Domino, Sametime, and QuickPlace).
All of the suggestions, hints/tips, and considerations discussed in this chapter are
based on a Microsoft Windows 2000-based server infrastructure. While we have
made every effort to discuss many of the concepts in a platform-independent
fashion, some Windows 32-specific aspects may exist. Therefore, should you be
performing your installations on AIX, Linux, or any of the other portal server
platforms, you should leverage other documentation sources specific to those
platforms in addition to this chapter.
© Copyright IBM Corp. 2002. All rights reserved.
11
2.1 The installation process
This section focuses on installing the WebSphere Portal Server software itself.
The following sections in this chapter will then discuss the deployment and
integration concerns required to successfully leverage this installation for a full
collaboration environment.
2.1.1 The Setup Manager
The WebSphere Portal software now comes with a fully automated installation
tool called the Setup Manager.
Tip: The setup manager can be found on CD1 of WebSphere Portal CDs, and
is launched by running install.bat on a Windows 2000 platform.
This tool is a Java application, and thus when starting the installation process the
tool must first check to see if you have a resident Java Virtual Machine under
which it can run. If none is located, it first installs the latest IBM JVM prior to
starting the Setup Manager (Java) GUI.
Once started, the Setup Manager GUI then allows you to select the software to
install, and prompts you to enter any needed configuration parameters and
settings based on the installation choices you have selected. See Figure 2-1 on
page 13.
12
WebSphere Portal 4.12 Collaboration Services
Figure 2-1 Setup Manager install component choices
As the Setup Manager installs the various packages you have selected, it will
occasionally prompt you for additional WebSphere Portal CDs. It does not
require the CDs themselves. You can copy the CDs to the local drive or a network
share giving a separate subdirectory for each CD—and simply provide the full
path to the CD contents when prompted.
2.1.2 Install approaches
There are actually several approaches to leveraging the automated capabilities
of the Setup Manager to assist in your installation:
򐂰 You can actually use the Setup Manager to install all needed products for the
portal to run in one step. Thus, it can install DB2, WebSphere Application
Server, the Portal Server code itself, etc.—all with minimal human
involvement. The setup manager will prompt you to reboot as needed and
required throughout the process.
򐂰 Setup Manager can also be used to install all software, but in multiple steps.
That is, you can first install DB2 utilizing the Setup Manager. Then, once this
is complete, perform full reboots and testing of the DB2 installation to verify
Chapter 2. Installation, configuration, and deployment planning
13
that it is functioning properly. After you are confident that DB2 is successfully
installed, you can run Setup Manager again to install WebSphere Application
Server (WAS). Again, after full rebooting and testing, run the Setup Manager
again to continue installing other components. Setup Manager will always
detect which software and versions you have already installed in your server,
and will take this into account when presenting you with installation options.
򐂰 You can also perform a basic install of a WebSphere Application Server on
your own, should your organization already have a ghost image or other easy
method for building such a base server. You would then use the Setup
Manager to update the DB2 and WebSphere fixpacks, and then install the
Portal Server code itself.
In our testing we performed installations with all three approaches. The approach
you choose should probably be based on your familiarity with the WebSphere
Portal Server software.
The first approach, allowing Setup Manager to install everything in one step, is
the most automated and requires the least amount of involvement. However, it
does take several hours to complete, even on the dual processor IBM xSeries we
utilized in our testing. Therefore, if you made any mistakes entering parameters,
you will not really know of the mistakes until several hours later. Thus, if you are
newer to the WebSphere Portal Server, you may want to take the second
approach of using Setup Manager in little steps. This allows you to become
familiar with the tool, while also testing after each step to verify that things are
working as expected.
Finally, if you are an experienced WebSphere Application Server administrator
and have lots of experience with that platform, you may wish to utilize your
existing procedures and processes to more quickly get the base WAS up and
running. In this case we would still recommend that you let the Setup Manager
verify that you have the correct DB@ and WAS fixpacks installed, as these are
crucial to the successful operation of the portal.
2.1.3 Hints/tips for using the Setup Manager
In general, the Setup Manager is pretty straightforward to use. However, at times
we did run into strange issues and failed installs. The following hints/tips will
hopefully help you to skip past some of the issues we initially encountered.
Be sure you have the correct key
The first item that you need to provide during the installation is the install key,
which is a long alphanumeric number similar to a serial number. You are
prompted for this key every time you run the Setup Manager, and it uses this key
to determine what capabilities of WebSphere Portal you are licensed for, and
14
WebSphere Portal 4.12 Collaboration Services
thus what installation choices you should have. It is important that you are sure
the key that you give the install process is an Extend or Experience install key, or
you will not be given the choice to install the Lotus Collaborative Components.
Be sure to select Lotus Collaborative Places & Components
If you want to install the Portal Collaboration Places and Components, you need
to install them at the same time you choose to install the Portal Server. You
cannot install them during separate runs of the Setup Manager, as the portal
“extend” components/install cannot be run on an existing install of a portal
“enable”. The Collaboration Places and Components choice is what installs all
Portal “extend” hooks for your portal server.
Thus, if you enter an Extend key, but then choose to install only the Portal Server,
the Enable version of Portal Server will be installed. If you enter the Extend key
and choose to install Portal Server and the Collabortive Places and Components,
the Extend version of Portal Server will be installed.
Use the standard install process
We highly suggest that you utilize the “standard install” choice in Setup Manager.
The quick install will not allow you to make all of the choices required for an
enterprise install with collaboration, and the advanced install leaves all the
individual product settings up to you. The standard install is a nice interim step
between the two, which automates most install steps, but still allows you to
choose key configuration settings.
Keep an eye on the processor utilization
On the Windows platform, it is important to use the Task Manager/Performance
Monitor and watch the CPU loads during the installation process of the various
processes.
Several times during the installation process you are prompted to enter a value,
insert a new CD, verify that WebSphere has restarted/etc. We found it crucial to a
successful install using the Setup Manager to verify that the CPU utilization of
any Java processes has leveled off prior to continuing with the installation. In
most installs, depending on your installation point, there will actually be up to four
or five Java processes shown in the task manager at various points.
Chapter 2. Installation, configuration, and deployment planning
15
Figure 2-2 Multiple Java processes during portal setup
Continuing before CPU utilization has leveled off could mean that a required
process is still loading, and the installation process will fail.
Keep an eye on the available memory
The installation process consumes a lot of resources, and memory is one of the
resources you should ensure is abundant. We increased the virtual memory in
our test servers to be sure that the system would have enough memory for all of
the Java processes started during the installation process.
In our tests, the Setup Manager itself would utilize over 150 MB for its Java
process at some points, and this is in addition to the memory requirements of the
various WebSphere Application Server processes that are started during the
installation process. As an example, Figure 2-2, taken during one of our
installations, shows the Setup Manager utilizing over 80 MB, while the Portal
Server is utilizing 200+ MB.
We recommend a minimum of 512 MB of physical memory installed on your
server to simply run the installation process, and greater than 512 MB if you are
going to utilize the Setup Manager to install all software in one automated step.
These memory recommendations are just for the installation process—additional
16
WebSphere Portal 4.12 Collaboration Services
memory would be highly recommended for actually running the server after
install.
Testing LDAP access and syntax
LDAP syntax and access errors will account for the majority of your failed
installations. Therefore, before you fill in the LDAP setup specifics when
prompted by Setup Manager, it is good to test if you have LDAP access to your
LDAP directory via an LDAP request from the browser on this server.
You should write in your browser in the URL address field:
ldap://myldapserver.myco.com/cn=myuser,o=myorg
You should then receive a results window with the data retrieved from the LDAP
server about that user.
If you have an error, you should first verify your IP setup (DNS, hosts files, etc.)
as well as verify that you are using the correct LDAP port (that is, 389), in case
your organization utilizes a different port for your LDAP server.
Additionally, you should check the syntax of the users you are entering. The fully
distinguished syntax for a given user may vary based on your LDAP setup. For
example, the syntax for wpsadmin in a Domino LDAP server might be
“cn=wpsadmin,o=ibm”, while the syntax for the same user in a Secureway LDAP
directory might be “uid=wpsadmin,u=ibm,c=com”. You should use the above
process to verify that you are using the correct syntax prior to giving that syntax
to the Setup Manager.
We recommend that you test all three entries that WebSphere uses during the
installation (wpsadmin, wpsbind, and wpsadmins), to be sure that you can reach
them with the right format.
Tip: Do not leave a blank “suffix” for your organization when prompted by
Setup Manager, because WebSphere Portal needs this information to properly
set up groups and memberships.
Be careful when rebooting your machine
During the installation process you have to reboot your machines several times,
one after the DB2 installation, another after the DB2 fixpack installation, after the
WAS and Fixpack2 installation, and finally when you finish the Portal installation.
We recommend that you manually stop the WebSphere and DB2 services prior
to rebooting each time as appropriate. We always stopped first WebSphere
Admin services, then the IBM HTTP Server and Admin services, each time
looking at the processes monitor to verify that all theJjava processes for
WebSphere, and apache processes for IHS, had finished.
Chapter 2. Installation, configuration, and deployment planning
17
We experienced some corruption problems with the WebSphere environment
when we just rebooted the machine without ensuring that the Java processes
had enough time to shut down successfully.
Testing your environment during installation
There are several points when you can test your environment during the
installation. We found it very important to perform these interim tests to verify the
success of the installation processes, and identify any issues early on.
One such point is just after you have finished the installation of the WebSphere
Application Server. Prior to continuing the installation, you can launch the
WebSphere administrative console, start the “default server”, and try to access
one of the examples of the default server from your browser. We always used a
snoop servlet to see if WebSphere was functioning properly:
http://myserver.myco.com/servlet/snoop
Tip: Be sure to stop the default server within the WebSphere Administration
Console after performing this test, because this saves several MB of crucial
system memory for the next portion of the install.
The other important point to test your environment is when you are near the end
of installation and the window shown in Figure 2-3 on page 19 appears.
18
WebSphere Portal 4.12 Collaboration Services
Figure 2-3 An important point at which to test your rinstall
At this point, you should be able to test whether you have already successfully
installed the Portal Server engine. To do that, you should start Admin Console
and check if the security is enabled. Usually if you are using the Setup Manager
to install all the products, it should set up the security for you and you just have to
add to the Admin Role the wpsadmin and wpsbind users and the wpsadmins
group, as you can see in the window message.
We had some scenarios where Setup Manager could not properly set up the
security, and we were forced to set up the WebSphere global security settings
manually. If this is the case you must reboot Admin Server and HTTP Server
after making the security changes, and then start the Portal Server Application
Server from the WebSphere Admin Console—before pressing OK to continue
the install.
Chapter 2. Installation, configuration, and deployment planning
19
The URL you can test is the homepage of your WebSphere Portal installation:
http://myserver.myco.com/wps/portal
Then you should have the following window (Figure 2-4) with no portlets inside
because the installation of the portlets will be the next step in your installation
process. This will happen when you press OK in Figure 2-3 on page 19.
Figure 2-4 Successful portal test, prior to portlet deployment
Finally, when you have finished your installation, you will have the following
window (Figure 2-5) telling you that you have successfully finished your
installation.
Figure 2-5 Installation complete message
That is the moment to test your environment again with the same Web address
you used before:
http://myserver.myco.com/wps/portal
Then try to log in with the key icon you have in the top right corner of your page
as wpsadmin (Figure 2-6 on page 21). Then you will be able to access
Administration Portal, and Work With Pages PageGroups.
20
WebSphere Portal 4.12 Collaboration Services
Figure 2-6 Default portal home page
2.2 Installing manually
It is possible to install all the components of your WebSphere Portal environment
via a more manual process, not leveraging the Setup Manager. Instead, you
install each component via its own install process, install all fixpacks/patches,
and then run the more basic Portal Installer found on CD7 of your WebSphere
Portal CDs.
We chose to desribe only the use of Setup Manager in this paper, because we
found this install process to be less problematic.
For assistance with performing a full manual install, reference the IBM Redpaper
WebSphere Portal V4.1 Windows 2000 Installation, REDP3593 at:
http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb6
5f/fedd3307ed1bb86485256c300054252d?OpenDocument
Chapter 2. Installation, configuration, and deployment planning
21
2.3 Integration with Lotus collaboration technologies
After you have successfully set up your WebSphere Portal Extend Server, you
then need to verify that all required integration with the Lotus Collaborative
technologies is enabled to enable you to take advantage of the full collaborative
capabilities in the Portal Extend family.
2.3.1 Lotus Domino integration
Portal administrators must enable a Domino server to make all the features of the
Collaborative Portlets and Collaborative Components available to Portal users.
From the Portal perspective, there are two types of Domino servers: the Domino
Directory server itself, and any Domino Server that will act as a Domino data
source.
򐂰 The Domino Directory server must be LDAP-enabled. Domino LDAP is
required to look up various user values and attributes, such as mailfile,
mailserver, etc. Some of the Collaborative portlets use these values to locate
the appropriate Domino data source server to use.
򐂰 Any Domino data source servers must have HTTP, LDAP, and Domino IIOP
enabled.
– The Domino HTTP is used to access Domino data via Domino XML (i.e.
DXL)
– Domino IIOP is used to prepopulate some of the lists shown in the edit
mode of the Collaborative portlets.
If you do not install, configure, and enable these Domino capabilities, then
Collaborative capabilities will still work in some cases. For example, the Domino
server names will not appear in the server selection lists in the Notes View portlet
or the QuickPlace portlet, and the My Lotus Notes portlets will not be able to find
the Notes mail server for authenticated Portal users. However, you can type the
server name, database name, and view name in the text fields for these
configuration parameters.
Additionally, it is important to note that the Collaborative Components person and
menu tags also do not require Domino.
Portal settings to support Domino
You must enable the Domino Directory server either during Portal Server
installation, or later using the portal collaborative environment properties file:
<WASROOT>\lib\app\config\CSEnvironment.properties
The following entries in this file are specific to Domino integration:
22
WebSphere Portal 4.12 Collaboration Services
CS_SERVER_DOMINO_DIRECTORY.enabled=true
CS_SERVER_DOMINO_DIRECTORY_1.hostname=issl2.lotus.com
These variables enable the Domino Directory, which is needed to work with
Collaboration services. You must have the enable variable set to true and your
hostname must be the same that you have in the Fully Qualified Internet host
name in the Server document of your LDAP-enabled Domino Server.
Domino server settings to support the portal
You should verify the followings settings in your general Domino server
configuration. All of these settings/values can be found on your Domino server
document.
򐂰 On the Basics Tab of the Server document, check that the Fully Qualified host
name is filled in.
򐂰 On the Ports Tab, check that the Net Address of the TCP/IP port is set to
either the numerical IP address of the server, or its fully qualified host name
(preferred).
򐂰 On the Internet Protocols Tab, HTTP sub-tab, check that the Host Name field
contains the fully qualified host name for the server.
򐂰 The “Allow HTTP Clients to Browse Databases” field should be set to “yes” to
allow the selection of databases from within the properties tab of the Notes
portlets.
Domino LDAP-specific settings
As described earlier, even if you have Portal server setup to utilize an external
LDAP server for authentication and authorization purposes, you must have
Domino LDAP enabled to take full advantage of all of the Portal Extend
collaboration capabilities.
Here we briefly describe the steps you should perform to check if you have the
LDAP configuration right:
򐂰 Check the Domino Directory ACL
In the names.nsf file for the users wpsadmin and wpsbind and the wpsadmins
group: they must be managers and have the Group Creator, Group Modifier,
User Creator and User Modifier roles. And they also may delete documents.
You have to remember that this is only for the installation process. After that
you have to plan which groups you are going to use for Portal Users. You can
manage these groups from the Portal Administration portlet but you have to
modify the ACL manually to be sure those groups have reader access.
򐂰 LDAP field list settings
Chapter 2. Installation, configuration, and deployment planning
23
Within the names.nsf file you must ensure that the MailFile and MailServer
“person” fields, and the http_HostName “server” fields are selected as
available (i.e. shown) via LDAP. The LDAP fields list and LDAP write access
settings are maintained in a Global Configuration document in the
Servers\Configurations view.
Tip: You must select “yes” for “Use settings as the default settings for all
servers” within a Global Configuration document in order for the LDAP tab
and field list to show.
SingleSignOn settings
To allow SingleSignOn (SSO) access—so that users that sign onto the
WebSphere portal can utilize Domino-based collaboration portlets without being
prompted for authentication—you must enable the IBM LTPA capabilities
included in both WebSphere and Domino.
Domino imports the LTPA token generated by WebSphere, and this token would
be used for all Domino servers within the Domino domain.
The following list can be used to enable and test an SSO configuration in your
Domino or WebSphere environment:
򐂰 With Domino Release 5 you can only import an LTPA token from WebSphere,
so the first thing to do is to generate the LTPA in the WebSphere
Administration console.
򐂰 Once you have your LTPA file, create a Web Configuration document for the
servers you want to enable SSO, click Web in the action bar, and select
Create Web SSO Configuration.
򐂰 Enter the IP domain name in the TokenDomain field, which must be the same
that you wrote in the WebSphere Administration console when you generated
the LTPA token.
򐂰 Add the names of the Domino servers that will participate in the SSO domain
in the Domino Server Names field. You do not need to enter the names of the
WebSphere servers.
򐂰 You should receive a success message. If you do not, repeat the earlier steps
for importing the key. Pay attention to the path, filename, and password.
򐂰 Manually change the value in the LDAP Realm field to hostname\:389 once
you have imported the LTPA token. This was the standard port that
WebSphere added to your domain name. The backslash is important to have
SSO working between WebSphere and the collaboration servers.
򐂰 Save the configuration document.
24
WebSphere Portal 4.12 Collaboration Services
򐂰 Open the server document of the Domino server. Change to the Internet
Protocols tab and go to the Domino Web Engine sub-tab. Then change the
Session Authentication setting to Multi-Server.
򐂰 Restart your Domino server. You will see in the Domino console a message
stating that the LPTA settings have been successfully started.
For more details on the LPTA token setup, see the redbook Domino and
WebSphere Together . This book discusses the various domain/hostname,
realm, and token expiration issues that can often plague LPTA setups.
Domino IIOP settings
Some of the Collaborative portlets and Collaboration Services use IIOP to
access the Domino server and get information from databases.
To set up Domino IIOP settings, do the following:
򐂰 Load the IIOP task to your Domino console or add it to the notes.ini file of your
Domino server and restart the server.
򐂰 If you are using the IBM HTTP server as Web server in your WebSphere
Portal environment, the collaborative portlets and components go to this
server to get the diiop_ior.txt file to open IIOP sessions with the Collaboration
servers. You have to copy this file from your Domino server to the IBM HTTP
server directory. The file is located under:
C:\Lotus\Domino\Data\domino\html
It should be copied into:
C:\IBM HTTP Server\htdocs
Tip: If you are using different collaboration servers in your environment using
SSO between them, you can check that all the diiop_ior.txt files have the same
content. This is because when you set up the Web SSO Configuration and run
the DIIOP tasks, the IOR is common for all the servers in the environment.
2.3.2 Lotus Sametime integration
Sametime provides real-time collaboration to the Portal environment. You can set
up the Sametime server on top of a Domino server or use an external LDAP
directory. The following guidelines are provided to assist you in enabling this
Sametime integration.
Portal settings to support Sametime
You must enable the Sametime hook either during Portal server installation, or
later using the portal collaborative environment properties file:
Chapter 2. Installation, configuration, and deployment planning
25
<WASROOT>\lib\app\config\CSEnvironment.properties
The following entry in this file is specific to Sametime integration:
CS_SERVER_SAMETIME.enabled=true
The Sametime variable must be set to “true” if you have a Sametime server in
your Portal environment and you expect to use people awareness in your
portlets.
The HostAddress.xml file then contains the values that actually point to the
Sametime server, as follows:
<WASROOT>\PortalServer\app\wps.ear\wps.war\peopleawareness\hostAddress.xml
<?xml version="1.0" encoding="UTF-8" ?>
<sametime>
<hostaddress>itso-sametime3.ibm.com</hostaddress>
<httpPort>80</httpPort>
</sametime>
Sametime settings to support WebSphere Portal
򐂰 Sametime Installation: If you tried to install Sametime Server 2.5 on top of
Domino 5.0.10, the window error shown in Figure 2-7 appears:
Figure 2-7 Sametime 2.5 on Domino 5.0.10 error message
You can avoid this error if you get the nstring.dll file from a previous Domino
server release and replace it. The file is located in the Domino directory. After
the process installation, remember to replace the file again before starting the
server, or the server will crash.
Additionally, you should install Sametime fixpack1 on top of your Sametime
2.5 installation. Your Domino directory will now show two new directories,
2.5PF1 and 2.5PF1-Data.
򐂰 STLinks installation: This step is only required for integration with Sametime
2.5 or earlier servers, and is not required for Sametime 3.0. To allow for
Sametime 2.5 integration, install Sametime Links in the same directory as you
26
WebSphere Portal 4.12 Collaboration Services
have Sametime 2.5 installed. To test if stlinks is running, you can check the
following Web address, where you can find examples that show how to use
Sametime links in your applications, plus good developer documentation for
the toolkit.
http://yourserver/sametime/toolkits/st30linkstk/index.html
Restart the Sametime server. We recommend that you reboot the entire
machine.
򐂰 Sametime.ini: You need to modify Sametime.ini in order to allow portlets that
reside in the Portal Server Machine to access Sametime functions. Then you
must add one of the two following variables to the Sametime.ini file, which is
located in the Domino directory:
VPS_BYPASS_TRUSTED_IPS=1
or
VPS_TRUSTED_IPS= IPAddress,IPAddress,...
The first one is used to allow all the machines to ask for the Sametime
services.
The second one is to restrict access to Sametime services to only the listed
IPs.
2.3.3 Lotus QuickPlace (2.08) integration
After you install QuickPlace you have to do some setup in your QuickPlace
server in order to integrate with your WebSphere Portal installation.
Portal settings to support QuickPlace
You must enable the QuickPlace connection either during the WebSphere Portal
server installation, or later using the portal collaborative environment properties
file:
<WASROOT>\lib\app\config\CSEnvironment.properties
The following entries in this file are specific to QuickPlace integration:
CS_SERVER_QuickPlace.enabled=true
CS_SERVER_QuickPlace_1.hostname=YourQuickPlace.yourco.com
You must have the Enable variable set to true and your hostname must be the
same as in the Fully Qualified Internet hostname of your QuickPlace server.
The QuickPlace server entered here is used by the portlets, and by the
Collaborative Components API during its initialization, as the default QuickPlace
server. Thus if no QuickPlace server is defined during the API call or in the
portlet edit menu, it falls back to this QuickPlace server as the default.
Chapter 2. Installation, configuration, and deployment planning
27
QuickPlace settings to support WebSphere Portal
򐂰 Shut down the server and browser. You now need to create a domcfg.nsf file
in the Domino Data directory. You can use the domcfg.nsf file found in the
Lotus Developers domain, or on the online support site.
򐂰 You have to set up the DIIOP task for this server, because the QuickPlace
portlet uses the IIOP to get information about QuickPlace databases. You can
check 2.3.1, “Lotus Domino integration” on page 22 to do it.
򐂰 In the Server Document on the Internet Protocols tab you must check Yes in
“Allow HTTP clients to browse databases”. That is because the QuickPlace
portlets need to browse the QuickPlace databases you have in your server to
present the “picklist” of QuickPlaces to the user when configuring the portlet.
Tip: The above settings are only required on your QuickPlace server to allow
the “picker” feature in the QuickPlace portlets edit mode that enables browsing
of QuickPlaces on a given server. If these capabilties are not enabled, the
QuickPlace portlets can still be used to access QuickPlaces by manually
entering server and place names—and the QuickPlace Collaborative
Components can still be used to create QuickPlaces.
2.3.4 Lotus Discovery Server integration
There are three types of integration with Discovery Server that must be
configured:
1. The Find button
2. Discovery Server portlets
3. Discovery Server Collaborative Components API
The Find button
WebSphere Portal, in the Extend and Experience versions, includes a Find
button, which can be defined to open the Discovery Server K-map for all portal
searches. Figure 2-8 on page 29 shows the Find button as it appears on the
standard portal theme.
28
WebSphere Portal 4.12 Collaboration Services
Figure 2-8 The detault WebSphere Portal Find button
No real installation setup or configuration is required for this integration. Rather,
the Web address of the Discovery Server KMAP should be configured as the
Find URL within Portal Administration - Portal Setup of the portal, as shown in
Figure 2-9.
Figure 2-9 Setting the URL for Find
Collaborative Portlets and Collaborative Components API
To support the Discovery Server portlets and the API, you must enable the
Discovery Server connection either during the WebSphere Portal Server
installation, or later using the portal collaborative environment properties file:
<WASROOT>\lib\app\config\CSEnvironment.properties
The following entries in this file are specific to Discovery Server integration:
CS_SERVER_DISCOVERY_SERVER.enabled=false
CS_SERVER_DISCOVERY_SERVER_1.hostname=YourLDSServer.yourco.com
You must have the Enable variable set to true and your hostname must be the
same that you have in the Fully Qualified Internet host name of your Discovery
Server.
Chapter 2. Installation, configuration, and deployment planning
29
2.4 Testing your WebSphere Portal Extend install
After you have completed your WebSphere Portal install, and installed/integrated
all of the Lotus Collaborative technologies, the best way to test if you have
configured and set up your Portal environment correctly is to see how it works on
one of the supplied collaborative portlets. We recommend using the NotesView
Portlet because it utilizes many of the key components required.
You can create a new portal page from WebSphere Portal, or just reuse an
existing page. Then add the NotesView portlet to the page and click Edit.
2.4.1 Verifying Domino integration
The following window then appears, and you should see in the Servers List of the
portlet the list of the servers you have in your Domino Directory. From a technical
point of view, the portlet opens a Notes Session via LDAP and retrieves the
server’s information. Thus, if this functionality is not working properly, you know
to troubleshoot your Domino Directory configuration.
Figure 2-10 Setting up the Notes View portlet
Then select your Database and View. For our testing we used the names.nsf
database, with the people view, with a blank in the field category. If the database
listing does not show up, then you should verify that you have the “Allow HTTP
users to browse databases” choice enabled, because this is how this list is
populated (that is, via HTML/XML). If the view list does not show up, then this is a
potential Domino IIOP issue, as the view list lookup functions over IIOP.
30
WebSphere Portal 4.12 Collaboration Services
Once you have selected the Database and View, press Next and you will have
the window shown in Figure 2-11, where you can set up the following:
򐂰 The number of rows to appear per screen
򐂰 Alternate row colors
򐂰 An icon to create new documents (if you check this you have to set up which
form to use for creating new documents)
򐂰 Whether to view documents in Lotus Notes or in the browser
Restriction: The option to view documents in the Notes client only works
with Internet Explorer browsers, as it functions via a small ActiveX control
that launches the Notes client and passes the database and document
details to it. Non-IE browser users will view documents in their browser via
Domino HTTP.
򐂰 A default categorized view: All expanded/All collapsed
򐂰 Columns
Here you can define:
– Which column will use people awareness to highlight if the people are
online, and use the menu actions with them.
– Which column you want to launch the document selected.
– Which columns you want to hide from the view presented by the portlet.
Tip: You should be careful which column you set for people awareness,
and which column is used to launch the document. For example, the
people awareness should contain people names only; the portlet cannot
pull names that are included within other text. Additionally, if the same
column is identified for both people awareness and document selection,
then you will lose the ability to open documents—because the people
awareness takes precedence.
򐂰 The direction for default sorting: Ascending/Descending
Chapter 2. Installation, configuration, and deployment planning
31
Figure 2-11 Setting up the Notes View portlet
2.4.2 Verifying people awareness and menu services
Once you have completed setting up the portlet, you should open the portlet
page in a window and verify the functioning of the portlet. The column that you
identified for people awareness should be green or red, showing the online status
of document authors. This verifies that people awareness is functioning properly.
If this is not working, then you may either have a Sametime configuration issue,
or it is possible that you have a username/authentication issue. For example, the
user ID with which you log into the portal must be a valid user to the Sametime
server.
Additionally, you should click on the people names or e-mail addresses for a
menu action for a user—or click the menu icon (the first icon in the row) for menu
32
WebSphere Portal 4.12 Collaboration Services
actions for documents. This verifies the functionality of the collaboration menu
services. You will have a menu action in the column names with one action for
the not-connected people (send e-mail) and two actions for the people who are
online (chat and send e-mail).
Figure 2-12 Notes View portlet -document actions
Figure 2-13 Notes View portlet - people actions
Now that you have some idea what collaboration components and services are,
you just have to test the power of collaboration in your portal environment. The
next two sections give you the tools to develop real collaboration portlets and get
all the advantages to integrate the WebSphere and Domino applications.
2.5 Deploying the collaborative portlets
After you have finished installing WebSphere Portal Extend, you may then need
to “deploy” several of the collaborative portlets for use in your portal.
Portlets that are installed on your server, but not deployed into the Portal server,
can be found in:
<WASROOT>\portalserver\install
Chapter 2. Installation, configuration, and deployment planning
33
After the portlets have been deployed, the .war files are moved to:
<WASROOT>\portalserver\deployed
and the contents of the .war files are expanded to:
<WASROOT>\appserver\installedapps\*.war
Deployed portlets
The following portlets are deployed for you as part of the installation process,
assuming that you selected to install the Productivity Portlets in the Setup
Manager:
򐂰 QuickPlace2.war - provides QuickPlace in an iframe portlet.
򐂰 Webpage.war - provides the Web Page portlet for launching an Internet or
intranet Web page in a scrollable iframe, addressable by Web addresses.
򐂰 Notes2.war - provides portlets to Lotus Notes/Domino:
–
–
–
–
–
–
–
Notes View
Notes Mail
My Notes To Do
My Notes Mail
My Notes Calendar
Notes Discussion
Notes Teamroom
򐂰 Bookmarks.war - provides the Bookmarks popup that lists the favorite Web
site links for a page group (i.e., place).
Portlets requiring deployment
There are other collaborative portlets that are not deployed by default. You must
manually install, configure, and maintain these portlets, as described in the
Portlet Administration section in the WebSphere Portal Infocenter. Some
examples of other collaborative portlets you may consider deploying are:
򐂰 iNotes.war - portlets providing an iframe wrapper of the iNotes interface
(including the iNotes calendar, todo, and notebook capabilities)
򐂰 Sametime .war - a simple Sametime client launching portlet
򐂰 Quickplace.war - a simple QuickPlace launching portlet
2.6 Deploying the Collaborative Components (API)
The core capabilities of the Lotus Collaborative Components are built into the
WebSphere Portal Extend install; this includes:
򐂰 The six-key API jar files installed in <WASROOT>\AppServer\lib\app
34
WebSphere Portal 4.12 Collaboration Services
򐂰 The CSEnvironment.properties file installed in
<WASROOT>\AppServer\lib\app\config
򐂰 Other key files installed as part of the wps.ear enterprise application in
<WASROOT>\PortalServer\app\wps.ear
However, the Collaborative Components JSP samples are contained in the
Collaborative Components enterprise application (cs.ear), and this application
must be deployed before the JSP samples can be utilized. This enterprise
application also includes all the API and properties files, in addition to their
installed locations as described above.
During the WebSphere Portal Extend install, this enterprise application file is
copied to:
<WASROOT>\AppServer\installableApps\cs.ear
by the Setup Manager.
To use the supplied JSP-based samples, you need to install this enterprise
application into the WebSphere Application Server environment.
To install/deploy the Collaborative Components enterprise application, follow
these steps:
1. Ensure that SSO is enabled on the server where the Collaborative
Components enterprise application (cs.ear) file is located—either the
Application server or the Portal server.
2. Open the WebSphere Administrative Console.
3. Stop the default server if it is running, by right-clicking this server and saying
Stop. This server is found in the Administrative Domain topology under
Notes\Yourserver\ApplicationServer\.
4. Click Console -> Wizards -> Install Enterprise Application.
5. Click Browse and select the cs.ear file. The default location is:
<installation_drive>:\WebSphere\Appserver\InstallableApps.
򐂰 Click Next in the series of screens that follow.
򐂰 When the screen that prompts you to select a “host” appears, select Default
Server and then click Finish.
Chapter 2. Installation, configuration, and deployment planning
35
Note: If you are not installing Collaborative Components with Portal Server
and you want a standalone installation, ensure that an Alias of *:9080 has
been automatically set for the default host. (In the WebSphere Advanced
Administrative Console topology view, select Virtual Host and click
Properties on its popup menu to view the Aliases specified. If you do not
see an Alias of *:9080, add this Alias by editing the properties of the Virtual
Host.)
򐂰 The samples are then accessed/run by using the address:
http://yourserver.yourdomain.com/cs/index.jsp
2.7 Installed components of WebSphere Portal Extend
This section lists the key files, and their locations, as they are installed after you
have successfully completed your collaborative portal server installation.
2.7.1 Key files
򐂰 The Collaborative Components classes and tag libraries—installed for use by
the Portal server
The default location for the JAR files is:
<WASROOT>\AppServer\lib\app
While the default location for the TLD tag library files is:
<WASROOT>\PortalServer\app\wps.ear\wps.war\WEB-INF\tld
򐂰 The Collaborative Components API Javadoc HTML files
The default location is:
<WASROOT>\PortalServer\app\wps.ear\wps.war\doc\Javadoc\CollabServices
򐂰 A directory of files related to people awareness, including the
hostAddress.xml file required for Sametime integration.
The default location is:
<WASROOT>\PortalServer\app\wps.ear\wps.war\peopleawareness
򐂰 A people awareness tag language descriptor file, people.tld
The default location is:
<WASROOT>\PortalServer\app\wps.ear\wps.war\web-inf\tld
򐂰 A directory of files related to menus
36
WebSphere Portal 4.12 Collaboration Services
The default location is:
<WASROOT>\PortalServer\app\wps.ear\wps.war\menu
򐂰 A menu tag language descriptor file, menu.tld
The default location is:
<WASROOT>\PortalServer\app\wps.ear\wps.warwps.war\web-inf\tld
򐂰 A set of CS
򐂰 The CSEnvironment.properties file
The default location is:
<WASROOT>\AppServer\lib\app\config
򐂰 The Collaborative Components enterprise application, cs.ear
The default location prior to deploying this enterprise application via the
WebSphere Administrative Console is:
<WASROOT>\AppServer\installableApps\cs.ear
After deploying this application, the contents of cs.ear are unzipped into a
cs.ear subdirectory at:
<WASROOT>\AppServer\installedApps\cs.ear\
The cs.ear file contains the following key files:
– Collaborative Components JSP samples
<WASROOT>\AppServer\installedApps\cs.ear\cs.war\*.jsp
– The Collaborative Components Java class files: cs.jar, commres.jar,
kdsapi.jar, kdsw.jar, ncsow.jar, stcommsrvrtk.jar
<WASROOT>\AppServer\installedApps\cs.ear\cs.war\WEB-INF\lib
– The Collaborative Components tag library files: menu.tld and people.tld
<WASROOT>\AppServer\installedApps\cs.ear\cs.war\WEB-INF\tld
򐂰 The collaborative portlets, as described in 2.5, “Deploying the collaborative
portlets” on page 33
2.7.2 Log files
Errors detected during the installation of Lotus Collaborative Places and
Components on the Portal server are recorded in the log file, whose location is:
WebSphere\PortalServer\extendInstall.log
Chapter 2. Installation, configuration, and deployment planning
37
2.7.3 Registry entries
System Registry entries verifying the installed version are:
򐂰 For the Windows platform in the Windows Registry:
HKEY_LOCAL_MACHINE\Software\IBM\WebSphere Portal Server\4.1: "Extend"
"4.1.2.0"
򐂰 For AIX in the AIX ODM:
FileSet: wpsExtend
Level: 4.2.0.0
򐂰 In Solaris in the Solaris PK Registry:
Name: wpsExtend
Abbreviation: wpsExtend 4.1.2.0.DSP=4.1.2.0
Package Instance: IBMWPSExt
򐂰 In Linux the AppServer/extendVersion.txt file will show:
"wpsExtend.version=4.1.2.0".
2.7.4 Directory structure
After the install, the Portal server subdirectory on your server should have the
directory structure shown in Figure 2-14 on page 39.
38
WebSphere Portal 4.12 Collaboration Services
wp_root
|
+
_uninst
|
+-- app
|
+-- WCMPznPublish.ear
|
|
|
+-- wms.ear
application
|
|
|
+-- wps.ear
|
|
|
|
|
+-- META-INF
|
|
+-- wps.war
|
|
|
|
|
+-- doc
Untitled
Root directory for Portal Server
Files used to uninstall Portal Server
Root directory for Content Organizer enterprise application
Root directory for WebSphere Member Services enterprise
Root directory for portal enterprise application
Metadata for portal enterprise application
Root directory for portal Web module
WebSphere Portal InfoCenter and Javadoc
|
|
+-- dtd
Document Type Definitions (DTDs) for Portal Server
|
|
+-- html
HTML files for the portal
|
|
+-- images
Graphics for the portal
|
|
+-- menu
Files for MenuService
|
|
+-- META-INF
Metadata for the portal Web application
|
|
+-- peopleawareness
Files for PeopleService
|
|
+-- screens
Java Server Pages for the portal
|
|
|
+-- markup_name
Subdirectory for each markup type
|
|
|
|
|
+-- skins
Skins for portlets
|
|
|
+-- markup_name
Subdirectory for each markup type
|
|
|
|
|
+-- themes
Themes for the portal
|
|
|
+-- markup_name
Subdirectory for each markup type
|
|
|
|
|
+-- WEB-INF
Resources for the Portal Server Web application
|
|
|
|
|
+-- conf
Portal configuration directory
|
|
+-- tld
Tag Library Descriptors
|
|
|
+-- wsproxy.ear
Root directory for Web services proxy enterprise application
|
|
|
+-- META-INF
Metadata for Web services proxy enterprise application
|
|
|
+-- wsproxy.war
Root directory for Web services proxy Web module
|
|
|
+-- META-INF
Metadata for Web services proxy Web module
|
|
|
+-- WEB-INF
Resources for Web services proxy Web module
|
+-- bin
Portal configuration interface and other portal utilities
|
+-- deployed
Copies of the .ear and .war files for installed portlet
applications.
|
WebSphere Application Server uses copies of these files in the
|
was_root\installedApps directory.
|
+-- install
Scripts, logs and other files used to install Portal Server
|
+-- license
Product license agreement files (multiple languages)
|
+-- log
Portal Server log files
|
+-- migration
Tools and instructions for migrating Portal Server Version 2.1
|
to Version 4.1
|
+-- src
Source files for User, Group and related resources
|
+-- wms
Resources for WebSphere Member Services
Figure 2-14 Directory structure for the Portal server subdirectory
Chapter 2. Installation, configuration, and deployment planning
39
2.8 Collaborative portal deployment planning
At the core of WebSphere Portal is the Java-based Portal Server, which runs as
an application server on top of WebSphere Application Server. The information in
this section is provided as an introduction to the topologies that WebSphere
Application Server supports, and the ones that apply to running the portal, and
more specifically the considerations crucial for a collaborative WebSphere Portal
Extend environment.
2.8.1 General WebSphere Application Server considerations
The number of machines that WebSphere Portal requires, and where these
machines will be placed, varies depending on customer requirements. Use the
information in this section as an introduction to WebSphere topologies as related
to the portal.
Refer to the following documentation for detailed information on general planning
for any WebSphere Application Server environment:
򐂰 WebSphere Application Server Infocenter
The WebSphere Application Server InfoCenter provides details about the
topologies that WebSphere Application Server supports.
http://www-3.ibm.com/software/webservers/appserv/doc/v40/aee/index.html
򐂰 WebSphere 4.0 Advanced Scalability, SG24-6192
This redbook provides topics related to workload management, load
balancing, and overall scalability. Advantages related to using server groups
and clones, and separating the Web server and database servers, are
discussed.
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246192.html
?Open
򐂰 WebSphere 4.0 Advanced Edition Handbook, SG24-6167
This redbook provides instructions related to installing and managing
WebSphere Application Servers.
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246167.html
?Open
2.8.2 A test and proof-of-concept environment
For many test and proof-of-concept installations, the number of servers can be
kept to a minimum. In such a minimal installation DB2, IBM HTTP Server, and
the Portal Server (running on top of WebSphere Application Server) can all be
installed and run on one server, while the Lotus based collaborative technologies
40
WebSphere Portal 4.12 Collaboration Services
(that is, Lotus Domino, Sametime, and QuickPlace) can all run on a second
server. In fact, we successfully installed all needed components—DB2, WAS,
WPS, Domino, Sametime, and QuickPlace—on one server, with 1GB of memory.
However, getting Lotus QuickPlace, Domino, and Sametime to run happily on the
same server is sometimes problematic. Additionally, such a setup is not very
realistic for your production environment, and thus does not allow for a real-life
test of the integration/installation process for the collaborative technologies.
Therefore, in our environment we placed each of the main Lotus technologies on
their own servers so that we could more realistically test the collaboration
components.
Following this strategy, our four-server test environment for this Redpaper looked
as follows:
WPSServer:
WebSphere Application Server w/Webpshere Portal
Server, IBMDB2, IBM HTTP Server
DominoServer:
Lotus Domino R5
QuickPlace Server:
Lotus QuickPlace
Sametime Server:
Lotus Sametime
Should one also desire to test the clustering and scalability capabilities of the
Portal Server, we would suggest splitting the WPSServer into a separate server
for each component as well.
2.8.3 A more typical production environment
The basic single WebSphere machine configuration can be extended by
distributing WebSphere Portal over multiple machines, and by making more
efficient use of the processing power of each machine in the configuration.
WebSphere Application Server supports a wide variety of ways to deploy the
portal in multi-machine environments. Commonly used topologies fall into one of
the following broad categories.
򐂰 Multi-tiered topologies
The components (the Web server, application server, databases, and so
forth) are physically separated onto different machines.
򐂰 Vertical scaling topologies
Additional WebSphere Portal processes are created on a single physical
machine by using models and clones.
Chapter 2. Installation, configuration, and deployment planning
41
򐂰 Horizontal scaling topologies
Additional WebSphere Portal processes are created on multiple physical
machines by using models and clones. HTTP redirector products such as
Network Dispatcher can also be used to implement horizontal scaling.
򐂰 HTTP server separation topologies
The Web (HTTP) server is located on a different physical machine than
WebSphere Application Server and WebSphere Portal. Requests can be
redirected to the portal through a variety of methods.
򐂰 Demilitarized zone (DMZ) topologies
Firewalls can be used to create demilitarized zones—machines that are
isolated from both the public Internet and other machines in the configuration.
This improves portal security, especially for sensitive backend resources such
as databases.
Note: It is important to remember that, in any topology, many resources and
settings defined in WebSphere Application Server, like Global Security Settings,
Data Sources, and so on, are shared across all applications, including the portal
instance.
These examples are not intended to be an exhaustive list of WebSphere
topologies that you can create. Instead, they are intended to suggest various
ways that you can set up your portal in a multi-machine environment.
A typical “production” WebSphere Portal environment will often look like the
environment depicted in Figure 2-15 on page 43.
42
WebSphere Portal 4.12 Collaboration Services
Figure 2-15 A typical “production” WebSphere Portal Server environment
2.8.4 Collaboration technology considerations (LDAP and SSO)
There are two main considerations involved when planning for a “collaborative
portal” infrastructure: Single-sign-on/authentication aspects, and LDAP
server/directory integration. The single-sign-on aspects are essentially
dependant upon the specific LDAP directory configuration you choose.
Overall, WebSphere Portal Server supports any standard LDAP server for
authentication and authorization. This authentication/authorization LDAP server
is the server defined during a standard WebSphere Application Server
install—the LDAP server defined in the WebSphere Global Security settings. It is
the LDAP directory that is used to verify your login to the portal, etc.
Additionally, the collaborative portlets themselves also use an LDAP server to
look up various user attributes such as “mailfile” and “mailserver”. This
collaboration LDAP server is specified separately in the
CSEnvironment.properties file, as described in “Portal settings to support
Domino” on page 22.
Note: It is important to note that the menu and person tags do not require
LDAP, or Domino LDAP, to function. These two features of the Collaborative
Components can be leveraged in any environment.
Chapter 2. Installation, configuration, and deployment planning
43
These two LDAP values can be set to point to the same LDAP server, or two
different LDAP servers, depending on your environment and configuration. Thus,
there are really three LDAP server configurations to consider for a collaborative
WebSphere Portal Extend environment:
򐂰 Lotus Domino LDAP
The easiest configuration to use to ensure the full capabilities of the
collaborative portlets, is to utilize the LDAP services in Lotus Domino itself for
all WebSphere portal and collaboration capabilities. Chances are that any
organization that is choosing to utilize the Lotus Domino-based collaboration
capabilities in WebSphere Portal Server already has Lotus Domino deployed
in their environment, which can be leveraged for this purpose.
Setup guidelines:
– Enable LDAP on your Domino server, if not already enabled.
– Use Domino LDAP values during your WebSphere install for all
WebSphere global security and portal settings.
– “Show” the user attributes through Domino LDAP as described in “Domino
server settings to support the portal” on page 23 (“Domino LDAP
settings”).
– Use the Domino LDAP server hostname for the
CS_SERVER_DOMINO_DIRECTORY_1.hostname value in the
CSEnvironment.properties file.
– Enable LPTA between Domino and your WebSphere Portal Server as
described in “Domino server settings to support the portal” on page 23
(“Single-sign-on settings”).
Pros:
– Easiest setup—no LDAP schema changes are required.
– Minimal single-sign-on configuration—users are authenticated against
Domino for both their initial authentication into the portal server, and for
authentication via the collaborative portlets as they access Domino.
Domino LPTA handles the SSO aspects.
Cons:
– Scalability concerns of Lotus Domino LDAP server
– Most major organizations already have an existing enterprise LDAP
directory as an authentication standard for Web applications, and will
require you to hook into that.
򐂰 non-Domino LDAP
If an non-Domino LDAP server is used, such as the IBM Secureway
eDirectory, then there are some additional setup steps involved. However, the
44
WebSphere Portal 4.12 Collaboration Services
usage of Domino Directory Assistance should minimize any single-sign-on
concerns.
Setup guidelines:
– Enable Domino to utilize LDAP Directory Assistance for HTTP
authentication. This will ensure that portlet users’ credentials are verified
against the same LDAP server utilized when they logged into WebSphere.
– Use the third-party LDAP (Secureway, etc.) values during your WebSphere
install for all global security settings.
– Extend the schema of your third-party LDAP (Secureway, etc.) directory to
include the user attributes required for collaborative capabilities:
mailserver, mailfile, and sametimeserver.
– Use the third-party LDAP (Secureway, etc.) hostname for the
CS_SERVER_DOMINO_DIRECTORY_1.hostname value in the
CSEnvironment.properties file.
– Enable LPTA between Domino and your WebSphere Portal Server as
described in “Domino server settings to support the portal” on page 23
(“Single-sign-on settings”).
Pros:
– This option may better fit into larger organizations’ directory strategy.
– Still a minimal single-sign-on configuration—users are authenticated
against the third-party LDAP server for both their initial authentication into
the portal server, and for authentication with the collaborative portlets as
they access Domino. Domino via Domino Directory Assistance integration
to the external LDAP. LPTA still handles the SSO aspects, in conjunction
with Domino Directory Assistance.
Cons:
– Some organizations will not want to modify their LDAP schema with the
required collaboration-oriented user attributes (mailserver, mailfile,
sametimeserver, etc). If this is the case, then some of the collaborative
capabilities will not function.
– Making the required schema modifications can be tricky and require some
level of testing.
Chapter 2. Installation, configuration, and deployment planning
45
Important: As of the writing of this Redpaper, there is a known bug in the
“my” collaboration portlets that do not allow them to function when the
non-Domino directory option is used. This error occurs due to a problem
with how the “my” portlets look up some of the user attributes such as
“mailserver” and “mailfile”.
However, all other collaboration portlets continue to function in this
configuration.
򐂰 Domino LDAP plus non-Domino LDAP
If an organization is hesitant to modify their enterprise LDAP schema to
support the collaborative attributes required, and already has a non-Domino
LDAP directory populated with users for authentication alongside their
Domino directory populated with Notes users—then a two-directory approach
may make sense.
Setup guidelines:
– Enable LDAP on your Domino server, if not already enabled.
– “Show” the user attributes through Domino LDAP as described in “Domino
server settings to support the portal” on page 23 (“Domino LDAP
settings”).
– Use the Domino LDAP server hostname for the
CS_SERVER_DOMINO_DIRECTORY_1.hostname value in the
CSEnvironment.properties file.
– Use the third-party LDAP (Secureway, etc.) values during your WebSphere
install for all global security settings.
– Instruct your users to utilize the credential vault capabilities of the Notes
portlets to provide Single-sign-on type capabilities. Thus, users’
credentials will be verified against the third-party LDAP directory for
authentication to the portal. Then the collaborative portlets will use the
credentials supplied by the users in the credential vault for authentication.
Note: As of the writing of this Redpaper, the Notes portlets supporting
credential vault capabilities where not available in the installation CDs.
Rather, these updated portlets must be downloaded from the IBM
Portal Catalog as described in 3.2.3, “Downloading collaboration portlet
updates (portlet catalog)” on page 53.
– Enable LPTA between Domino and your WebSphere Portal Server as
described in “Domino server settings to support the portal” on page 23
(“Single-sign-on settings”).
46
WebSphere Portal 4.12 Collaboration Services
Pros:
– This option provides for full collaborative capabilities, with minimal to no
changes required to existing directories.
– This option may make sense for organizations that have not yet
implemented an overall directory strategy, and still have separate
directories for Web authentication, Domino authentication, etc.
Cons:
– Single-sign-on is not transparent to end users, as they must set up their
credential vault. Users’ credentials will be verified against the third-party
LDAP directory for authentication to the portal. The collaborative portlets
will use the credentials supplied by the users in the credential vault to
authenticate to Domino as they access Domino.
– Sametime integration, and people awareness, are more difficult to
maintain. It requires user IDs to be common between the Domino and
third-party LDAP directory.
– Overall, this is a more complicated and error-prone setup to maintain.
Sametime single sign-on concerns
Another directory integration/SSO aspect to consider for a collaborative portal
deployment concerns the people awareness capabilities. For this to function
properly, both your portal infrastructure and your Lotus Sametime infrastructure
must be enabled for the same authoritative LDAP directory (Domino LDAP, or
any third-party LDAP). This is required so that the user name you use to log in to
the portal is recognized as a valid user to your Sametime infrastructure.
Other LDAP and single-sign-on concerns
Single-sign-on and Directory Integration aspects are one of the most complex
parts of any enterprise-wide deployment of technology. It is not possible for us, in
this small Redpaper, to cover all the various combinations of LDAP directories,
customer authentication routines, etc., that can come into play when you are
combining all of the technologies involved in a WebSphere Portal Extent
collaborative portal. Therefore, you should always include an ample amount of
time in any deployment project plan to address these aspects.
Other potential issues to consider in your planning:
򐂰 Does your organization utilize a custom authentication routing on your HTTP
servers, or Domino servers (that is, DSAPI)? How will this affect the single
sign-on and people awareness features you desire?
򐂰 Does your organization utilize a third-party centralized security management
application such as Tivoli Access Manager for e-Business (formerly known as
Tivoli Policy Director)?
Chapter 2. Installation, configuration, and deployment planning
47
Tip: When investigating your SSO setup, it may be helpful to track the cookies
set by the servers.
The following cookies apply:
򐂰 On hitting WPS on myportal, your client gets the WASReqURL token for
your portal domain, expiring at the end of the session.
򐂰 After pressing the login button, the token LtpaToken for the single-sign-on
(SSO) domain is stored, also expiring at the end of the session.
򐂰 The third token just following is JSESSIONID, which is also valid for the
portal domain, expiring at the end of the session.
To view the tokens as they are set in Internet Explore, change the cookie
settings in Start -> Settings -> Control Panel -> Internet Options from
Enable to Prompt. The change is made on the security tab by clicking Custom
Level and scrolling down to Cookies.
48
WebSphere Portal 4.12 Collaboration Services
3
Chapter 3.
Collaborative portlets
This chapter provides an overview of the collaborative portlets provided with
WebSphere Portal Extend.
The following topics are covered:
򐂰 Key concepts behind portlets, and the portlet user interface
򐂰 Capabilities and functions
򐂰 Key technologies and files
򐂰 Suggestions and considerations for deployment
© Copyright IBM Corp. 2002. All rights reserved.
49
3.1 An introduction to key portlet concepts
There are many good sources of general information about the concept of
portlets. However, in case the reader is new to this, we include some concepts
here that will be important for reading the rest of this chapter.
3.1.1 What a portlet is
Portlets are the heart of WebSphere Portal. They are small portal applications,
usually depicted as a small box in the Web page. Portlets are developed,
deployed, managed, and displayed independent of other portlets. Administrators
and end users compose personalized portal pages by choosing and arranging
portlets, resulting in customized Web pages.
However, portlets are more than simple views of existing Web content. A portlet
is a complete application, following a standard model-view-controller design.
Portlets have multiple states and view modes, plus event and messaging
capabilities.
Portlets run inside the portlet container of the Portal Server component, similar to
the way a servlet runs on an application server. The portlet container provides a
runtime environment in which portlets are instantiated, used, and finally
destroyed. Portlets rely on the WebSphere Portal infrastructure to access user
profile information, participate in window and action events, communicate with
other portlets, access remote content, look up credentials, and store persistent
data.
3.1.2 Portlet modes
Portlet modes allow a portlet to display a different user interface, depending on
the task required of the portlet. A portlet has several modes of display that can be
invoked by icons on the portlet title bar: View, Help, and Edit.
A portlet is initially displayed in its View mode (Figure 3-1 on page 51). As the
user interacts with the portlet, the portlet may display a sequence of view states,
such as forms and responses, error messages, and other application-specific
states. Help mode provides user assistance. Edit mode provides a page for users
to change portlet settings. For example, a weather portlet might provide an Edit
page for users to specify location. Users must be logged in to WebSphere Portal
to access Edit mode.
50
WebSphere Portal 4.12 Collaboration Services
Figure 3-1 Entering Edit mode of a portlet, with other “mode” icons shown
Each portlet mode can be displayed in normal, maximized, or minimized states.
When a portlet is maximized, it is displayed in the entire body of a page,
replacing the view of other portlets. When a portlet is minimized, only the portlet
title bar is displayed on the page.
3.2 Introduction to the collaborative portlets
The collaborative portlets provided with WebSphere Portal Extend fall into two
categories:
New portlets
Several portlets are provided with WebSphere Portal Extend that allow for
interaction with newer Lotus collaborative technologies. For example, the Extend
package includes portlets for utilizing the advanced capabilities of the iNotes
interface. No such portlets are provided in the Enable package.
Enhanced portlets
In addition to new portlets in WebSphere Portal Extend, other portlets are
included that are simply enhanced versions of the portlets provided in
WebSphere Portal Enable. These enhanced portlets introduce advanced
features over the basic portlets provided in Enable.
The advanced features allow portal users to take actions on documents or user
names that appear in a portlet. A portal user can see if other users are online
directly from the portlet, and then select from a menu of options to interact with
those users.
The “interaction” can be as simple as e-mailing the user, or more advanced such
as starting an instant chat, or viewing a user’s Lotus Discovery Server “expertise”
profile to find out what else the person knows. The available contact or
interaction options that will show up in the menu vary based on the capabilities
for which you have enabled your collaborative portal. See 2.3, “Integration with
Lotus collaboration technologies” on page 22 for more details on enabling the
various capabilities.
Chapter 3. Collaborative portlets
51
Additionally, based on the context of the portlet, document actions allow users to
take actions directly from the portlet with or without launching the entire
application. They can open the document, create a new document,
etc.—depending on the current portlet context, and a given portlet’s capabilities.
3.2.1 Included collaborative portlets
Table 3-1 briefly lists and defines the collaborative portlets that are provided on
the installation CDs with WebSphere Portal Extend v4.12.
The remaining sections in this chapter then describe each of these portlets in
some additional details.
Table 3-1 Collaborative portlets provided in WebSphere Portal Extend
52
Portlet Name
Portlet Description
iNotesMailPortlet
iNotesCalendarPortlet
iNotesContactsPortlet
iNotesNotebookPortlet
iNotesToDoPortlet
Provides iframe-based access to iNotes
enabled Domino servers and mail files. It
includes access to the Welcome, Mail,
Calendar, To Do List, Contacts, and
Notebook iNotes functions.
MyNotesMailPortlet
MyNotesCalendarPortlet
MyNotesToDoPortlet
Displays users’ mail, calendar, and to-dos
from their traditional Lotus Domino mail
file.
The “my” name designates the fact that
these portlets autodetect a user’s mail file
settings—and thus do not need to be
configured individually for each user.
NotesMailPortlet
Displays any view in a traditional Notes
mail database.
NotesDiscussionPortlet
Displays a Notes database built with the
Notes Discussion database template.
NotesTeamroomPortlet
Displays a Notes database built with the
Notes Teamroom database template.
NotesViewPortlet
Displays any view in any Notes database.
In-line Quickplace Portlet
Displays a QuickPlace inside an iframe.
QuickplacePortlet
Launches a designated QuickPlace in a
separate browser window.
This portlet is also included in WebSphere
Portal Enable.
WebSphere Portal 4.12 Collaboration Services
Portlet Name
Portlet Description
SametimePortlet
Launches the Sametime Connect Java
client.
This portlet is also included in WebSphere
Portal Enable.
WebPagePortlet
Displays any Web page inside an iframe.
Not quite a “collaborative” technology, but
included with WebSphere Portal Extend,
as it is based on the same technology as
the QuickPlace and iNotes iFrame
portlets.
3.2.2 Other collaborative portlets
In addition to the collaborative portlets provided out of the box with WebSphere
Portal Extend, many other portlets to Lotus collaborative technologies are
available for download from the IBM Portlet Catalog. Some of these, as of the
writing of this paper, include:
򐂰 Lotus Discovery Mini-Search Portlet
򐂰 Lotus Discovery Search Results Portlet
򐂰 Lotus Discovery K-map Portlet
򐂰 IBM Lotus Extended Search Portlets
򐂰 MyiNotes - these portlets autodetect the users’ mail file settings—and thus do
not need to be configured individually for each user.
򐂰 Configurable iNotes - one portlet that is configurable for the various iNotes
views.
Additionally, while this chapter discusses leveraging the provided collaborative
portlets, Chapter 4, “Collaborative Components” on page 83 discusses the
usage of the Collaborative Components API to create your own collaborative
portlets. You are not limited by the portlets provided out of the box! Rather, you
are only limited by your imagination and creativity.
3.2.3 Downloading collaboration portlet updates (portlet catalog)
IBM maintains a central store for all WebSphere Portal portlets at:
http://www-3.ibm.com/software/webservers/portal/portlet/catalog
This site should be checked regularly for updates to the existing portlets, as well
as to download any new collaborative portlets that may be made available.
Chapter 3. Collaborative portlets
53
3.2.4 A sample use of the collaboration portlets
In this section, we demonstrate some of the capabilities of the Notes portlets by
using a portal place/page-group called Collaboration, as shown in Figure 3-2.
Figure 3-2 Our sample “Collaboration” portal place
The first page of our Collaboration place, starting at the top left, has the
MyNotesMail portlet showing the inbox, the MyNotesCalendar portlet, the
NotesToDo portlet, and the NotesView portlet showing the address book.
.
Note: The NotesViewPortlet is viewing a custom view that we created in the
Public directory (i.e., pubnames.ntf) to allow for people awareness—because
none of the default views in this database displayed the names in a format that
matched our Sametime user names.
To show the other portlets, there is also a “Production” teaming page in our
sample Collaboration place—with the Notes Discussion, Notes Teamroom and
Sametime Connect (Java) launcher portlets; see Figure 3-3 on page 55.
54
WebSphere Portal 4.12 Collaboration Services
Figure 3-3 Our sample Collaboration place, production/teaming page
The last page in our Collaboration place is called QuickPlace, and it shows the
two QuickPlace portlets that are available. To the left on this QuickPlace page
there is the QuickPlace In-Line portlet displaying a specific area of a defined
QuickPlace.
The other portlet is the one from the Enable offering. It displays a dialog box that
lists the QuickPlaces the user has defined. The user selects a QuickPlace from
the list and clicks Go. The selected QuickPlace is launched in a separate
window.
Figure 3-4 Collaboration place, QuickPlace page
Chapter 3. Collaborative portlets
55
In addition to the portlets highlighted above, it is also important to show the
advanced collaboration we included in our environment. Since our portal
infrastructure has a Lotus Discovery Server available, all of the people services
(i.e., the pop-up menu on people columns) become automatically expanded with
two additional commands to choose from, as shown in Figure 3-5.
Figure 3-5 LDS Enhanced People menu
The choice to Show Profile will present you with the persons profile as compiled
by Lotus Discovery Server in a separate browser window (Figure 3-6).
The Find Documents Authored By function performs a Lotus Discovery Server
search, and brings the results back in a separate browser window.
Figure 3-6 LDS Person Profile
56
WebSphere Portal 4.12 Collaboration Services
3.3 The Notes portlets
As mentioned earlier in this chapter, several Notes portlets for accessing
traditional Notes mail and other Notes databases are provided with WebSphere
Portal Extend:
򐂰 NotesMail Portlet
򐂰 MyNotesMail Portlet
򐂰 MyNotesCalendar Portlet
򐂰 MyNotesToDo Portlet
򐂰 NotesDiscussion Portlet
򐂰 NotesTeamroom Portlet
򐂰 NotesView Portlet
All of these portlets are contained in one portal application, notes2.war.
However, it should be noted that there are actually two Notes-related war files
that may be found in a WebSphere Portal environment. In general, Notes.war
contains the Enable Notes portlets, while Notes2.war contains the Extend
portlets.
򐂰 The Notes.war file contains the WebSphere Portal Enable portlets. This
includes basic versions of the five Notes portlets: NotesView, NotesMail,
MyNotesMail, MyNotesToDo, and MyNotesCalendar. These basic versions
have no advanced collaboration capabilities such as people awareness and
menu services. Additionally, these portlets do not provide the picklist
capabilities during the edit mode for looking up databases, etc. Server names,
databases, views, etc., must all be entered manually.
򐂰 The Notes2.war file contains the same five portlets as the notes.war file.
However, these five portlets are enhanced with advanced collaboration
capabilities: people awareness and menu services. The Notes.war file also
contains the Notes Discussion and Notes Teamroom portlets. There are no
versions of these portlets available with WebSphere Portal Extend.
Chapter 3. Collaborative portlets
57
3.3.1 NotesView portlet
Lotus Notes View Portlet
The name used in the documentation (e.g.
InfoCenter)
Notes View Portlet
Title in portlet selector (Edit Layout and
Content”)
NotesViewPortlet
Name in portlet selector (installation)
The NotesView portlet is designed to allow you to display any Notes database
view in a portlet window. It is the most flexible of all the Notes portlets, as it is not
limited to databases with specific templates, etc.
Configuration options
This portlet actually has two edit mode and configuration screens that must be
completed, as shown in Figure 3-7 on page 60 and Figure 3-8 on page 61. Be
sure to press Next on the bottom of the first edit screen to go on to the second
edit screen. If you press OK on the first edit screen instead, you will exit the edit
view and be left with the default settings for much of the portlets configuration.
򐂰 Edit screen 1 options (Figure 3-7 on page 60):
– The first configuration setting to make is to name the portlet. This name
will show at the top of the portlet window in the portal.
– The next few options are basic options selecting the server, database, and
the view for the portlet. After selecting a server, you select the check mark,
and the portlet populates the database list. The check box next to the
database list then populates the view list once you have chosen a
database, etc.
Note: There is some support for spelling in these configuration fields.
For example, the database name does not have to end in “.nsf” .
If you don’t see your servers in the server list, or the databases/views to
choose, then it is possible that the access rights are not properly set in
your environment; refer to 2.3.1, “Lotus Domino integration” on page 22
to verify that you have enabled all the correct Domino settings (LDAP,
HTTP, DIIOP, etc.).
– The protocol that is used for the portlet can also be selected on this
screen. If “Detect protocol automatically” is selected, the portal will first try
HTTP. If that is unavailable, it will try HTTPS.
58
WebSphere Portal 4.12 Collaboration Services
򐂰 Edit screen 2 options (Figure 3-8 on page 61):
– First choose the number of rows to appear in your portlet. The default
setting is 15.
– Choose whether or not to alternate row colors to better highlight the row
divisions. The default setting is yes.
– You can choose to display the icon to create new documents. If you check
this option, you then have to enter which Notes form is used for creating
new documents.The default setting is no.
– Choose how documents the user wishes to view are launched—either in
the Lotus Notes client, or in another Web browser window. The default
setting is to use the browser.
Restriction: The option to view documents in the Notes client only
works with Internet Explorer browsers, as it functions via a small
ActiveX control which launches the Notes client and passes the
database and document details to it. Non-IE browser users will view
documents within their browser via Domino HTTP.
– Choose whether categorized views are expanded or collapsed when
opening. The default is expanded.
– Choose several options for the view columns:
•
Which column will be enabled for people awareness—so that names
will be highlighted if the people are online, and contact option menus
will be presented.
•
Which column you want to use to launch the document selected via
document action menus.
•
Which columns (if any) you want to hide from the view as it is
presented by the portlet.
Tip: You should be careful which column you set for people awareness,
and which column is used to launch the document. For example, the
people awareness column should contain people names only; the
portlet cannot pull names that are included within other text.
Additionally, if the same column is identified for both people awareness
and document selection, you will lose the ability to open documents,
because people awareness will take precedence.
– Finally, you must choose the direction for default sorting: either Ascending
or Descending. The default is Ascending.
Chapter 3. Collaborative portlets
59
Figure 3-7 Notes View Portlet Edit Mode- Page One
60
WebSphere Portal 4.12 Collaboration Services
Figure 3-8 Notes View Portlet Edit Mode - Page Two
Key files associated with this portlet
File
Description
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesView.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesViewEditOne.jsp
…\WPSNotesViewEditTwo.jsp
JSPs used to display the portlet content in
edit/configuration modes
Chapter 3. Collaborative portlets
61
3.3.2 NotesMail portlet
Lotus Notes Mail
The name used in the documentation (e.g.
InfoCenter)
Notes Mail Portlet
Title in portlet selector (Edit Layout and
Content”)
NotesMailPortlet
Name in portlet selector (installation)
The basic mail portlet can be set up to present the main (Domino) views of the
traditional user mail database: Calendar, Inbox, or To Dos.
As this portlet must be configured to point to each user’s mail file individually, it
cannot be set up in advance for all users by a Portal administrator. Users must be
given editor access to this portlet in the WebSphere Portal configuration settings
to be able to configure it for their use.
Restriction: The NotesMail portlets are designed for use against the
StdR5Mail and StdR6Mail templates; if the iNotes template is used it will
generate errors. Any custom mail templates may also cause problems,
depending on the amount of customization performed.
Configuration options
The first screen of the edit view for this portlet looks the same as the NotesView
portlet described earlier. On this first screen users would select their mail server,
database, and the view of their mail that they would like to see (i.e., Inbox,
Calendar, and To-do).
The second edit screen also presents the same options as the second edit
screen in the NotesView portlet, unless the Calendar view was chosen on the
first edit screen. If the Calendar view was chosen, then the special edit screen
shown in Figure 3-9 on page 63 is displayed instead. On this screen users must
choose how many days to display in their portlet view of the calendar, and to
launch/view calendar entry details in the Notes client or another browser window.
62
WebSphere Portal 4.12 Collaboration Services
Figure 3-9 NotesMail portlet, calendar edit view
Key files associated with this portlet
Property
Description
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesMail.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesMailEditOne.jsp
…\WPSNotesMailEditTwo.jsp
JSPs used to display the portlet content in
edit/configuration modes
3.3.3 MyNotes portlets
The “my…” portlets exist for mail, calendar and to do. The “my” portlets get a
simplified configuration because the mail sever and the mail box of the user are
looked up by the portlet from within the directory, so they do not need to be
specified in the edit mode. Portal administrators can thus make the basic
configuration settings for users, and then the portlets will automatically function
for each user (i.e., users do not need edit rights to the portlet).
Chapter 3. Collaborative portlets
63
My Notes Mail portlet
My Lotus Notes Mail
The name used in the documentation (e.g.
InfoCenter)
My Notes Mail Portlet
Title in portlet selector
MyNotesMailPortlet
Name in portlet selector
Configuration options
As the configuration of these “my” portlets is simplified, you only see one edit
screen; see Figure 3-10 on page 65. This edit screen presents some of the same
edit options as the NotesView portlet, along with some additional options specific
to the mail database.
On this screen you enter/choose the following:
򐂰 The name to display on this portlet.
򐂰 The number of rows to appear in your portlet. The default setting is 15.
򐂰 Wether or not to alternate row colors to better highlight the row divisions. The
default setting is yes.
򐂰 Wether or not to show the file size column. The default setting is no.
򐂰 Whether or not to show an icon for messages that have file attachments. The
default setting is yes.
򐂰 Whether to show the inbox view, or the “All documents” view from the mail file.
򐂰 How documents the user wishes to view are launched, either within the Lotus
Notes client, or in another Web browser window. The default setting is to use
the browser.
򐂰 The direction for default sorting: either Ascending or Descending. The default
is Ascending.
򐂰 The protocol that is used for the portlet can also be selected on this screen. If
“Detect protocol automatically” is selected, the portal will first try HTTP. If that
is unavailable, it will try HTTPS.
64
WebSphere Portal 4.12 Collaboration Services
Figure 3-10 MyNotesMail portlet, edit options
Key files associated with this portlet
File Name
Description
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesMail.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\NotesMailEditTwo.jsp
JSP used to display the portlet content in
edit/configuration mode
Chapter 3. Collaborative portlets
65
My Notes Calendar portlet
Lotus Notes Mail
The name used in the documentation (e.g.
InfoCenter)
Notes Mail Portlet
Title in portlet selector (Edit Layout and
Content”)
NotesMailPortlet
Name in portlet selector (installation)
Configuration options
Again, as the configuration of these “my” portlets is simplified, you only see one
edit screen; see Figure 3-11 on page 67. This edit screen presents some of the
same edit options as the calendar edit view in the NotesMail portlet, along with
some additional options.
Within this screen you enter/choose:
򐂰 The name to display on this portlet.
򐂰 The number of days to show in your portlet view of the calendar. The default
setting is 7 days.
򐂰 How calendar entries the user wishes to view are launched—either within the
Lotus Notes client, or in another Web browser window. The default setting is
to use the browser.
򐂰 The protocol that is used for the portlet can also be selected on this screen. If
“Detect protocol automatically” is selected, the portal will first try HTTP. If that
is unavailable, it will try HTTPS.
66
WebSphere Portal 4.12 Collaboration Services
Figure 3-11 MyNotesCalendar portlet, edit options
Key files associated with this portlet
Property
Description
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesCalendarView.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesCalendarEditOne.
jsp
JSPs used to display the portlet content in
edit/configuration mode
Chapter 3. Collaborative portlets
67
MyNotesToDo portlet
My Notes To Do
The name used in the documentation (e.g.
InfoCenter)
My Notes Todo Portlet
Title in portlet selector
MyNotesToDoPortlet
Name in portlet selector
Configuration Options
Again, as the configuration of these “my” portlets is simplified, you only see one
edit screen, see Figure 3-12. This edit screen present some of the same edit
options as in the MyNotesMail portlet.
Figure 3-12 MyNotesToDoPortlet, edit options
68
WebSphere Portal 4.12 Collaboration Services
Key files associated with this portlet
Property
Description
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesCalendarView.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesCalendarEditOne.
jsp
JSP used to display the portlet content in
edit/configuration mode
3.3.4 Notes Discussion and Teamroom portlets
The Notes Discussion and Teamroom portlets are very similar to the NotesView
portlets. In fact, their edit/configuration screens are identical to those shown for
the NotesView portlet in Figure 3-7 on page 60 and Figure 3-8 on page 61.
NotesDiscussion portlet
Name
Description
Notes Discussion
The name used in the documentation (e.g.
InfoCenter)
Discussion Portlet
Title in portlet selector
DiscussionPortlet
Name in portlet selector
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesDiscussionView.j
sp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesDiscussionEditOn
e.jsp
…\WPSNotesDiscussionEditTwo.jsp
JSP used to display the portlet content in
edit/configuration mode
Chapter 3. Collaborative portlets
69
NotesTeamRoom portlet
Property
Description
Notes Team room
The name used in the documentation (e.g.
InfoCenter)
Notes Teamroom Portlet
Title in portlet selector
NotesTeamroomPortlet
Name in portlet selector
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesTeamroomView.j
sp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_127.ear\notes2.war\WEBINF\html\jsp\WPSNotesTeamroomEditOn
e.jsp...\WPSNotesTeamroomEditTwo.jsp
JSP used to display the portlet content in
edit/configuration mode
3.3.5 Common features of the Notes portlets
There are several “common” aspects of the Notes portlets supplied with
WebSphere Portal Extend:
򐂰 The configured server always shows up below the portlet window’s title region
(itso-domino.ibm.com in Figure 3-13).
򐂰 If the portlet allows for launching the full (Notes) client, the launch rocket icon
is present below the title region.
򐂰 If you have rights to create documents in the respective Domino db, which is
“author” at minimum, then a “Create new document” icon also shows up next
to the launch rocket icon.
All these aspects are shown in Figure 3-13.
Figure 3-13 Sample of a configured portlet (Teamroom portlet)
70
WebSphere Portal 4.12 Collaboration Services
3.4 iNotes portlets
As mentioned earlier in this chapter, several iNotes portlets are available, which
provide iframe-based access to iNotes-enabled Domino servers and mail files.
The following portlets are available:
򐂰 iNotesMailPortlet
򐂰 iNotesCalendarPortlet
򐂰 iNotesContactsPortlet
򐂰 iNotesNotebookPortlet
򐂰 iNotesToDoPortlet
All of these portlets are contained in one portal application, inotes.war.
Configuration Options
All five of the iNotes portlets are set up in the same manner. They all present the
same configuration options, as shown in Figure 3-14. The options are simply the
name of the iNotes server, plus the database name and password to use for
accessing the server. The password is only used if the login credentials supplied
to log in to the portal server are not valid for the iNotes server. The portlets then
use the password entered here, along with the same user name that you used to
log in to the portal server.
Figure 3-14 iNotesPortlet, edit options
Chapter 3. Collaborative portlets
71
Technology details
It is important to note that no options are provided for modifying the interface
presented in the iNotes portlet, such as the options provided in the Notes portlets
to select the numbers of rows, icons, etc. This difference has to do with the
underlying technologies used for the Notes portlets versus the iNotes portlets.
The Notes portlets actually access Domino via HTTP on the server, and pull the
data from Domino via Domino XML (DXL). They can then manipulate the
presentation of the data by using or transforming the XML-based data as
needed, before the results are sent to the browser.
The iNotes portlets do not utilize such an XML/DXL method, rather they utilize
inline frame elements. Inline framing works similar to server side include
capabilities, except it is the browser itself that fetches the additional Web page
and includes it inside an inline frame. This means that iNotes portlets build the
inline frame in the portlet, and build the URL to the iNotes server with an iframe
tag; the browser then reads this iframe tag and fetches the iNotes interface for
inclusion in the portlet.
Based on this, the iNotes portlets present the iNotes interface exactly as it is
displayed when utilizing iNotes directly—with the exception that the header and
sidebar are removed, as shown in Figure 3-15 and Figure 3-16.
Figure 3-15 Standard iNotes inbox
Figure 3-16 iNotes inbox via the iNotesMail Portlet
72
WebSphere Portal 4.12 Collaboration Services
Key files associated with this portlet
All five of the iNotes portlets share a common set of files.
Property
Description
WebSphere\AppServer\installedApps\inot
es_WPS_PA_xxx.ear\inotes.war\WEB-IN
F\html\jsp\WpsiNotesView.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\not
es2_WPS_PA_xxx.ear\inotes2.war\WEBINF\html\jsp\WpsiNotesEdit.jsp
JSP used to display the portlet content in
edit/configuration mode
3.5 Sametime portlets
Sametime Portlet
Sametime Chat
The names used in the documentation
(e.g. InfoCenter)
Sametime Portlet
Name in portlet selector
Sametime Connect
Title in portlet selector
The Sametime portlet is a basic launcher of the Java Sametime Connect client.
The Java client is automatically downloaded from the Sametime server if it is not
already present, and provides almost all the features of the respective full
Windows client (depending on the version of Sametime that is used).
The Sametime launcher portlet is included in the sametime.war Web application
file. This portlet is available with WebSphere Portal Enable and Extend.
Configuration options
As the Sametime portlet is simply a launcher of the Sametime Java client, the
only configuration options are: the Sametime server to launch the client from,
and the port number for which Sametime is running on that server. See
Figure 3-17 on page 74.
Chapter 3. Collaborative portlets
73
Figure 3-17 SametimePortlet, edit options
Key files associated with this portlet
Property
Description
WebSphere\AppServer\installedApps\sa
metime_WPS_PA_xxx.ear\sametime.war
\WEB-INF\html\jsp\WpsSametimeView.js
p
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\sa
metime_WPS_PA_xxx.ear\sametime.war
\WEB-INF\html\jsp\WpsSametimeEdit.jsp
JSP used to display the portlet content in
edit/configuration mode
3.6 Quickplace portlets
There are two Quickplace portlets installed with WebSphere Portal Extend:
򐂰 In-line Quickplace Portlet
򐂰 QuickplacePortlet
The portlet names can get confusing, as both portlets are named
QuickplacePortlet in the Portlet selection GUI when adding portlets to pages.
One should be sure to look at the portlet Title and Description in this GUI to be
sure which portlet is being selected.
74
WebSphere Portal 4.12 Collaboration Services
Quickplace Launcher portlet
Sametime Portlet
Sametime Chat
The name(s) used in the documentation
(e.g. InfoCenter)
QuickplacePortlet
Name in portlet selector
Quickplace Portlet
Title in portlet selector
This portlet is available with WebSphere Portlet Enable and Extend. It is a basic
launcher of the full QuickPlace interface in a separate browser window. The
portlet presents a picklist of up to six QuickPlace Web addresses from which the
user may choose to launch. This portlet is very similar to the basic Quicklinks
launcher portlet that is also provided with WebSphere Portal.
The Quickplace launcher portlet is included the quickplace.war Web application
file.
Configuration options
As the Quickplace portlet is simply a launcher of a QuickPlace URL in a separate
browser window, the only configuration options are to enter up to six QuickPlace
URLs.
Figure 3-18 Quickplace portlet, edit options
Chapter 3. Collaborative portlets
75
Key files associated with this portlet
Property
Description
WebSphere\AppServer\installedApps\qui
ckplace_WPS_PA_xxx.ear\quickplace.wa
r\WEB-INF\html\jsp\WpsQuickplacePortle
tView.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\qui
ckplace_WPS_PA_xxx.ear\quickplace.wa
r\WEB-INF\html\jsp\WpsQuickplacePortle
tEdit.jsp
JSP used to display the portlet content in
edit/configuration mode
In-line Quickplace portlet
Lotus Quickplace Portlet
Quickplace Portlet (extent)
The name(s) used in the documentation
(e.g. InfoCenter)
QuickplacePortlet
Name in portlet selector
In-line Quickplace Portlet
Title in portlet selector
This portlet presents a Quickplace, or specific component of a Quickplace, within
the portlet window itself via an iframe. Thus, the technology behind this portlet is
very similar to that of the iNotes portlets.
When a specific component is chosen, this essentially means a specific view in
the Quickplace. The specific view/component defined is then shown without the
header and footer around it.
This inline Quickplace portlet is included in the quickplace2.war Web application
file.
Configuration options
The inline QuickPlace portlet has an edit interface similar to some of the Notes
portlets. It lets you:
򐂰 Assign a title for the portlet window as it will be displayed on the portal page.
򐂰 Select a Quickplace server. It will initially present a list of all available Domino
servers from the Domino directory.
򐂰 Select a specific QuickPlace (i.e., database) from the Quickplace server.
򐂰 Select a specific component (or view) of the Quickplace.
76
WebSphere Portal 4.12 Collaboration Services
Similar to the Notes portlets, if the picklists do not automatically populate on their
own, then one should double-check the QuickPlace integration steps, as
specified in 2.3.3, “Lotus QuickPlace (2.08) integration” on page 27, to verify that
everything is set up correctly.
Figure 3-19 In-line QuickplacePortlet, edit options
Key files associated with this portlet
Property
Description
WebSphere\AppServer\installedApps\qui
ckplace2_WPS_PA_xxx.ear\quickplace2.
war\WEB-INF\html\jsp\WpsQPView.jsp
JSP used to display the portlet content in
view mode
WebSphere\AppServer\installedApps\qui
ckplace2_WPS_PA_xxx.ear\quickplace2.
war\WEB-INF\html\jsp\WpsQPEdit.jsp
JSP used to display the portlet content in
edit/configuration mode
Chapter 3. Collaborative portlets
77
3.7 Bookmark and Find
Bookmark and Find are features included with WebSphere Portal Extend that are
actually not portlets, but rather features built into the portal header or navigation
bar. They are the only collaboration-oriented features installed with Extend and
Experience that are not implemented as portlets.
Figure 3-20 Bookmark and Find UI Hotspots
3.7.1 Bookmark
The bookmark capabilities discussed here are a means for grouping links and
information which are of interest to the community using the respective place.
They allow for place-specific links. This bookmark capability is distinct from the
bookmarks portlet, which is also available. This portlet can be added to a specific
page to allow bookmarks to be configured on a page-by-page basis.
The editing of the place bookmarks is done in the Work with Pages section of the
WebSphere portal. Besides “external” links, which are links (i.e., Web addresses)
to information out of the portal, you can also link to pages in the portal by
selecting the respective place and page.
If users of a place don’t have access to internal links—for example, a page in
another place is not accessible to them but is included as a bookmark—then the
link isn’t visible to them within the list of bookmarks.
3.7.2 Find
The Find capabilities are enabled by entering a URL for your search services in
the administrative panel (Portal Administration -> Portal Settings -> Global
Settings). It is intended that this URL be a URL of the search engine/interface,
etc., you would like your users to utilize when searching content in, or also
possibly outside, the portal.
78
WebSphere Portal 4.12 Collaboration Services
Figure 3-21 Find URL in Portal Administration
In a collaborative-oriented portal environment it is recommended that this be
configured to point to a Lotus Discovery Server.
3.8 Collaborative portlet deployment considerations
This section lists some general considerations that should be taken into account
when deploying and utilizing the provided collaborative portlets in your
environment.
3.8.1 Do not forget browser limitations
The portal server lists minimal requirements for a client’s Web browser:
򐂰 Microsoft Internet Explorer Version 4.01 or later
򐂰 Netscape Communicator 4.7 or later
However, the portlets themselves sometimes depend on the services used from
other platforms. The collaborative portlets get their services via integration with
their respective sources: Domino, Sametime, QuickPlace, etc. This may imply
stricter browser requirements than those valid for the portal itself. For example, if
you intend to use the iNotes portlets, you have to adhere to the browser
requirements of iNotes, because you are not only using the data and functionality
of iNotes, but the whole user interface in the iFrame portlet.
3.8.2 Consider enabling caching
Portlets have a caching mechanism as part of their feature set in WebSphere
Portal. However, the collaborative portlets do not support caching in their current
incarnations. Caching was disabled, as the developers felt Domino users would
be used to receiving near real-time, up-to-date views of their Domino data/mail,
etc. Based on this, every refresh of a portal page in a browser results in another
connection to Domino, fetching of the data, and close of the session to Domino.
Chapter 3. Collaborative portlets
79
Should you be deploying the Domino portlets to a large user base or
environment, you may want to consider enabling caching on the portlets by
adding the caching tag to the portlet.xml file in the Notes portlets Web application
(notes.war). When doing so, you would want to determine an appropriate time for
the cache refresh limit for your environment and users. For more details on
enabling caching in a portlet, please see “Caching” in 4.5.3, “Portlet performance
considerations” on page 121.
After you have enabled caching in a copy of the notes.ware file, you need to
update this portal application in the Portal administration to have the portlet.xml
changes take effect.
3.8.3 Notes on Domino compatibility
The collaborative cortlets are compatible back to the release 4.6.x code stream
of Notes/Domino. However, the technologies utilized by the portlets to talk to
Domino can vary based on the version of Domino. Whenever possible, the
portlets try to use the lightest technology to access Domino, where there is a
choice to make. Nevertheless, you should be aware of the technologies used by
the collaborative portlets to ensure that all required ports are open in firewalls,
etc., and any potential performance impacts are carefully considered.
As a general rule of thumb regarding the collaborative portlets:
򐂰 The information gathered from Domino regarding lists of users and servers is
gotten using LDAP calls between the portal server and the Domino server.
򐂰 A list of databases is gathered via HTML (i.e., users can browse databases
via HTTP).
򐂰 Design information (i.e., views, form, columns, fields) is accessed through
DIIOP calls between the portal server and the Domino server.
򐂰 For versions of Domino starting with release 5.05, most view and document
data is accessed via HTML/XML, leveraging the Domino XML capabilities
(DXL). On older versions of Domino this type of information must be gathered
via DIIOP.
Important: For the Notes Calendar portlets in particular, there is a
significant reliance on DIIOP calls for Domino version prior to 5.05. The
Calendar portlets perform much slower on these versions of Domino,
because essentially all data must be gathered via DIIOP. The needed
calendar info was not exposed via DXL until Domino release 5.05.
80
WebSphere Portal 4.12 Collaboration Services
3.8.4 Setting myportal addresses
During the configuration of your collaborative portal you might find yourself
logging in and out to the portal continuously, going to certain portlets, places, or
to specific pages you are working on.
In order to make this easier, you may want to set bookmarks/favorites in your
browser to these specific portal pages. However, to enable this you must make
one quick change to your portal infrastructure, as follows:
1. In the directory <wasroot>\lib\app\config\services there is a file called
ConfigService.properties.
2. To enable URL addressability, set the key uri.requestid in this file to false. The
default for this key is true, which means that URL addressability is not enabled
for the portal, and that pages cannot be easily bookmarked, or linked to.
3. For the change to become active, stop and start your portal server enterprise
application with the WebSphere Administrator Control Panel.
Chapter 3. Collaborative portlets
81
82
WebSphere Portal 4.12 Collaboration Services
4
Chapter 4.
Collaborative Components
This chapter describes the Collaborative Components available with WebSphere
Portal Extend, which allow you to more easily create your own collaborative
portlets leveraging Lotus technologies.
This chapter offers the following:
򐂰 An overview of the Collaborative Components API capabilities
򐂰 Step-by-step introductions for creating a basic portlet leveraging the
Collaborative Components
򐂰 Some more advanced collaborative portlet samples
򐂰 Some best practices for developing collaborative portlets
This chapter assumes that the reader has a basic understanding of the Java
programming language and has developed basic Java applications.
© Copyright IBM Corp. 2002. All rights reserved.
83
4.1 Introduction
What the Collaborative Components are
Collaborative Components allow developers who are writing portlets for
WebSphere Portal Server to easily add Lotus collaborative functionality to their
portlets. All of the Collaborative Components except for the Person and Menu
tags are “UI Neutral”. In other words, the goal of most of the Collaborative
Components is to provide the data from collaborative systems, and to allow the
developer to execute actions on the Lotus collaborative products—while also
leaving the user interface up to the developer.
Collaborative Components hide the configuration details of the Lotus products
that are installed in the enterprise. Developers using these components can add
collaborative functionality to a portlet without regard to server configuration
specifics. For example, a developer can use the people awareness tags without
having to know the name of the Sametime or LDAP server.
Collaborative Components are implemented in Java and include no
platform-specific code. They can be used on any J2EE-compliant server.
Types of Collaborative Components
The collaborative components can be divided into two main categories:
򐂰 Java Classes and Methods (cs.jar)
This package contains all the Java implementations of the collaborative
components. There are classes and methods for leveraging Domino,
QuickPlace, Sametime, and Discovery Server.
򐂰 JavaScript tag libraries (people.tld and menu.tld)
These tag libraries provide Sametime awareness and contextual menus to
JSPs.
When to use the Collaborative Components
The goal of the Collaborative Components is to expose the most commonly used
aspects of the Lotus collaborative technologies through a simple and consistent
API. The components are not a replacement of the core product APIs, but rather
are complementary. Developers may choose to use the Collaborative
Components when they need quick and easy access to Lotus technologies, and
may also use the core product APIs in other portions of their applications when
more advanced integration with the Lotus Collaborative technologies is required.
84
WebSphere Portal 4.12 Collaboration Services
4.2 Overview of the Collaborative Components
The Collaborative Components consist of infrastructure objects, service objects
(and their subordinate objects), and tag language descriptors for custom tags.
This section provides a high-level overview of these key objects and tags.
For more details on each class, tag, and the available methods, see:
򐂰 Appendix A, “Collaborative Components: classes/methods” on page 125
򐂰 Appendix B, “Collaborative Components: tag libraries” on page 153
4.2.1 Infrastructure objects
򐂰 CSEnvironment
Initializes the server environment and retrieves credentials for the logged-in
user.
򐂰 CSCredentials
Represents the authentication information for the logged-in user. CSFactory
uses these credentials to authenticate against the worker servers (Sametime,
QuickPlace, etc.).
򐂰 CSFactory
Constructs the Java service objects and generates a connection to the
appropriate worker server.
4.2.2 Java service objects
The CSFactory object instantiates these service objects. The developer is
responsible for calling the cleanup() member function on each object before they
go out of scope. This cleanup function releases any resources a service object
holds.
򐂰 DominoService
Provides standardized access to all versions of Domino from R4.67.
򐂰 QPService
Provides the ability to create a QuickPlace.
򐂰 PeopleService
Provides Sametime awareness (users logged onto Sametime) plus the ability
to obtain information about a specified person, such as their e-mail address.
Chapter 4. Collaborative Components
85
򐂰 DiscoveryServerService
Provides the ability to discover, search for, and retrieve Categories, People,
Places, and Documents from a Discovery Server.
4.2.3 Subordinate objects for DominoService
򐂰 ViewInfo
Represents information about a view in a Domino database.
򐂰 ColumnInfo
Contains information about the columns in a Notes view.
򐂰 RowInfo
Represents data from one row in a Notes view.
򐂰 CalendarDayInfo
Encapsulates all the calendar entries for a particular day.
򐂰 EntryInfo
Contains information about a single calendar entry.
4.2.4 Tag language descriptors for custom tags
򐂰 PeopleService tags
The people service tags generate context sensitive menus and Sametime
awareness for names found in the LDAP directory.
– person
Enables collaboration on the enclosed name.
– peopleinit
Initializes the people tag functionality. Do not use this function inside a
portlet, as it is intialized by the portal server itself at startup.
– peopleend
Finalizes the people tag functionality. Do not use this function inside a
portlet, as it is intialized by the portal server itself at startup.
򐂰 Menu tags
These allow developers to add pop-up menus to their Collaborative
Components applications. The PeopleService tags make use of this service
to display the person link menu. The pop-up menus are Java applets.
– menuinit
86
WebSphere Portal 4.12 Collaboration Services
Initializes the menu tag functionality. Do not use this function inside a
portlet, as it is intialized by the portal server itself at startup.
– menucontext
Starts the definition of one or more menus under a common context name.
– menu
Defines a menu within a menu context.
– menuitem
Defines an entry in a menu.
– menudisplay
Activates and displays the specified menu.
4.3 Developing a basic collaborative portlet
This section guides you through the process of installing the required
development tools, and then coding, testing and deploying a basic “hello world”
collaborative portlet.
4.3.1 Software prerequisites
You should have the following software installed on your development machine:
򐂰 WebSphere Studio Application Developer Version (WSAD) 4.0.3 or higher
Supports end-to-end development, testing, and deployment of e-business
applications.
򐂰 Portal Toolkit 4.1 or higher
The Portal Toolkit plugs in to WebSphere Studio Application Developer 4.0.3
and provides wizards for creating portlet application projects, and for creating
portlets based on the PortletAdapter and MVCPortlet classes. It also supports
the creation of template-based portlets (ServletInvokerPortlet, JSPPortlet,
and XSLTPortlet).
Tip: Make sure that your system's PATH environment variable is set up to use
JDK 1.3.0, which is the JDK used by WebSphere Application Server. You will
need to use this JDK level to compile class files for use in your portlets.
Chapter 4. Collaborative Components
87
On your development server:
򐂰 WebSphere Portal Server 4.1 Extend
See Chapter 2, “Installation, configuration, and deployment planning” on
page 11 for more detailed instructions on setting up your environment for
WebSphere Portal Server, with the appropriate Extend version code and
Lotus technology integration.
4.3.2 Setting up WebSphere Studio Application Developer
Install the Collaborative Components jar files
At a minimum you must install the Collaborative Components jar files on your
development machine and make them available to WSAD. The required jar files
are:
򐂰 cs.jar
򐂰 commres.jar
򐂰 kdsapi.jar
򐂰 kdsw.jar
򐂰 ncsow.jar
򐂰 stcommsrvrtk.jar
The simplest way to accomplish this task is to load the cs.ear file into WSAD.
This provides the additional benefit of installing the tag libraries and the sample
programs that come with the Collaborative Components package.
To install cs.ear on your machine, choose the Import option from the WSAD file
menu and select EAR File as the import source. On the EAR Import screen enter
a new project name and enterprise application project name. When you are
finished, your screen should look similar to the one in Figure 4-1 on page 89.
For assistance on finding the Collaborative Components Enterprise Application
(cs.ear) file, see 2.7, “Installed components of WebSphere Portal Extend” on
page 36.
88
WebSphere Portal 4.12 Collaboration Services
Figure 4-1 WebSphere Studio, with the Collaborative Components installed
Configure Collaborative Components
In the project you created above, expand the file tree to <project
name>/webApplication/config. Edit the CSEnvironment.properties file and enter
the host names for the Discovery Server, Domino Directory, and QuickPlace
servers.
##############################################################
#
# SAMETIME properties
# Only valid property is enabled. Other values configured
# through hostAddress.xml
##############################################################
CS_SERVER_SAMETIME.enabled=false
##############################################################
#
# QuickPlace properties
# enabled indicates whether or not QP creation is allowed.
##############################################################
Chapter 4. Collaborative Components
89
CS_SERVER_QuickPlace.enabled=true
CS_SERVER_QuickPlace_1.hostname=itso-QuickPlace.ibm.com
##############################################################
#
# DISCOVERY SERVER properties
##############################################################
CS_SERVER_DISCOVERY_SERVER.enabled=false
CS_SERVER_DISCOVERY_SERVER_1.hostname=my.server.com
##############################################################
#
# DOMINO DIRECTORY properties
# (LDAP server)
# Only valid property is hostname. Leave enabled flag as true.
##############################################################
CS_SERVER_DOMINO_DIRECTORY.enabled=true
CS_SERVER_DOMINO_DIRECTORY_1.hostname=itso-domino.ibm.com
Example 4-1 CSEnvironment.properties file
Tip: The use of Sametime awareness in the WebSphere Studio Application
Developer was not tested by the authors of this paper. However, this capability
should function, assuming the proper entries are included in the
hostaddress.xml file, as well as proper use of the peopleinit and peopleend
methods in your logic/code.
4.3.3 Writing a basic collaborative Hello portlet
The first portlet we are going to develop is the simplest portlet you can write
using the collaborative components. We will use the people tags to show how
easy it is to enable people awareness in a portlet.
Creating a basic JSP portlet
The first thing to do is to create a portlet project in WSAD. If you installed the
Portal Toolkit, you have the option to create a new portlet project. Select File ->
New Project, and then select Portlet project, as shown in Figure 4-2 on
page 91.
90
WebSphere Portal 4.12 Collaboration Services
Figure 4-2 Creating a new portlet project
Fill in the Portlet project fields in the wizard as shown in Figure 4-3.
Figure 4-3 Defining your new portlet project
On the next screen select the type of portlet you wish to create. See the Portlet
Development Guide in the WebSphere Portal Zone at:
http://www7b.software.ibm.com/wsdd/zones/portal/
Chapter 4. Collaborative Components
91
for detailed information about the different portlet types and best practices.
For simplicity we will use the JSP Portlet type in our examples. Select the JSP
portlet as shown in Figure 4-4.
Figure 4-4 Selecting the type of portlet project
You can use the default values in the next window or change the JSP Name to a
name that is more descriptive; see Figure 4-5 on page 93.
92
WebSphere Portal 4.12 Collaboration Services
Figure 4-5 Naming the portlet and JSP
Finally, press Finish and the system will create the new portlet project for you.
Once this process has completed, select the portlet perspective to view your new
project. If you are not familiar with these terms, check WSAD Help. Once you
have selected the portlet perspective, you can expand your Collaborative Hello
portlet to see the file structure you now have in place; see Figure 4-6.
Figure 4-6 Collaborative Hello portlet file structure
Chapter 4. Collaborative Components
93
In this example we just use the View mode portlet, so we have to set up the
CollabHelloView.jsp file under the webApplication\jsp\html directory. Do not use
the jsp file directly under the webApplication\jsp directory; this file is a duplicate
jsp that is never referenced.
Adding people awareness
To add people awareness to your JSP you must reference the associated tag
libraries. If you have not already imported cs.ear into WSAD as described in
4.3.2, “Setting up WebSphere Studio Application Developer” on page 88, you
must specifically import these tag libraries. These tag libraries are located in the
following directory on WebSphere Portal Server:
<WASROOT>\PortalServer\app\wps.ear\wps.war\WEB-INF\tld
Copy the tld files to your local file system or map a drive to your portal server.
From WSAD select File -> Import. On the Import screen select the File System
option and locate the tld files (Figure 4-7).
Figure 4-7 Adding the people awareness tag library
Select both the people.tld and menu.tld files. Although we will not directly use the
menu tags in this example, the people service tags require the menu tags to
94
WebSphere Portal 4.12 Collaboration Services
display the popup menu. Select the correct destination for tld files as shown
above.
Now you can edit your CollabHelloView.jsp and modify the default text. You can
go directly to the Source mode and copy the following code:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<%@ page language="java" import="com.lotus.cs.*, java.util.*" %>
<%@taglib uri="/WEB-INF/tld/people.tld" prefix="peopleservice" %>
<%@taglib uri="/WEB-INF/tld/menu.tld" prefix="menu" %>
<HEAD>
<META name="GENERATOR" content="IBM WebSphere Studio">
</HEAD>
<h1>Collaborative Components Hello JSP</h1>
<%
CSEnvironment environ = CSEnvironment.getEnvironment(request);
CSCredentials cred = environ.getCredentials(request);
%>
<BR>
<H2>Hello,
<peopleservice:person><%=cred.getUserLoginName()%></peopleservice:person>!<
H2>
This code is straightforward:
򐂰 Import the Collaborative Components library and the Java util library.
򐂰 Import the tag libraries for the people and menu tags.
򐂰 Obtain the environment from CSEnvironment. This step initializes the
Collaborative Components and is required for all programs.
򐂰 Obtain the credentials for the current user.
򐂰 Display the name of the currently logged-in user, surrounding this information
with people tags. The people service automatically looks up the user and
checks to see if that person is online.
4.3.4 Deploying the Collaborative Hello portlet
After you have completed coding your basic collaborative portlet, it is time to
deploy it on the WebSphere Portal Server and see if it works.
򐂰 Save your JSP file.
򐂰 Right-click your Collaborative Hello portlet project in the portlet perspective
view. Select the Export WAR option and save the WAR file on your file
system; see Figure 4-8 on page 96.
Chapter 4. Collaborative Components
95
Figure 4-8 Exporting your portlet in a WAR
򐂰 To deploy your portlet in WebSphere Portal, you have to log in as
Administrator using wpsadmin or another user who has the right to administer
portlets.
򐂰 Go to the Portal Administration Page Group and select the first tab, Install
Portlets.
򐂰 Select the file where you have exported your WAR file from WSAD.
򐂰 Click Install.
After you have installed your portlet, add your new portlet to an existing portal
page to see how it works. You do this under the “Work with pages” place in your
portal. Once you have added this portlet to a page, it should look similar to the
portlet shown in Figure 4-9 on page 97.
96
WebSphere Portal 4.12 Collaboration Services
Figure 4-9 Collaborative Hello portlet
When you click in the name you obtain a menu with several options: Chat, Send
e-mail, Show Profile, Find Documents Authored By (Figure 4-10 on page 98).
The last two options—Show Profile and Find Documents Authored By—appear
only if you have configured Lotus Domino Discovery Server in your environment
because they link with your LDS server to retrieve the information you are
requesting.
Chapter 4. Collaborative Components
97
Figure 4-10 Collaborative Hello portlet, pop-up menu
4.4 Advanced collaborative portlet samples
The Collaborative Hello portlet example was intended to show how easy it is to
use some of the functionality that collaboration components expose. The
following examples show other services you can use in your portlets to give the
collaboration power to your portal environment.
The source code for all of these samples is available online. See Appendix C,
“Additional material” on page 157 for more details on downloading this sample
code.
4.4.1 PeopleSample portlet
This portlet displays a view from the Notes address book database (names.nsf)
and enables collaboration on one of the view columns. This example
demonstrates the use of the DominoService object and People Service tags.
98
WebSphere Portal 4.12 Collaboration Services
Follow these steps to create the PeopleSample portlet:
򐂰 Create a new JSP portlet project in WSAD as shown in 4.3.3, “Writing a basic
collaborative Hello portlet” on page 90. Name this portlet PeopleSample and
accept the defaults on the portlet parameters page.
򐂰 By default the JSP view file for this portlet is view.jsp under the
webApplication\jsp\html directory. Enter the following code for this file:
Example 4-2 view.jsp for the PeopleSample portlet
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<%@ page language="java" import="com.lotus.cs.*, java.util.*" %>
<%@taglib uri="/WEB-INF/tld/people.tld" prefix="peopleservice" %>
<%@taglib uri="/WEB-INF/tld/menu.tld" prefix="menu" %>
<HEAD>
<META name="GENERATOR" content="IBM WebSphere Studio">
</HEAD>
<h1>Sample portlet using the Domino and People services</h1>
This JSP reads the names.nsf database from the target server and ST enables
the name field.<br>
<%
CSEnvironment environ = CSEnvironment.getEnvironment(request);
CSCredentials cred = environ.getCredentials(request);
DominoService ds = (DominoService)
CSFactory.getService(cred,CSFactory.DOMINO_SERVICE);
String viewname = "($VIMPeople)";
ViewInfo vi = ds.getViewInfo("names.nsf", viewname);
if (vi == null)
{
%>
<H2>Cannot locate the <%=viewname%> view in names.nsf</H2>
<%
}
else // valid view & database
{
%>
<TABLE>
<%
int start=1;
int nGets = 5;
int i, j;
String values[];
RowInfo[] ri = vi.getRowInfo(String.valueOf(start), nGets);
while(ri != null)
{
Chapter 4. Collaborative Components
99
// on the second and subsequent calls the getRowInfo() we
// overlap reads by one row as required by the API. Do not
// display this duplicate row.
for(i = (start == 1 ? 0 : 1); i < ri.length; i++)
{
values = ri[i].getValues();
// first column of this view is the name
%>
<TR><TD>
<peopleservice:person><%=values[0]%></peopleservice:person></TD>
<%
for(j=1; j < values.length; j++)
{
%><TD><%=values[j]%></TD>
<%
}
%>
</TR>
<%
}
if (ri.length < nGets)
break;
// last row
// Increment start by one less than the number of entries read from
// the view. This causes the next read to overlap the previous by
// one view entry. This is required because we must ensure that the
// start value refers to a valid row in the view.
start += ri.length - 1;
ri = vi.getRowInfo(String.valueOf(start),nGets);
}
%>
</TABLE>
<BR>
End Of Records
<%
}
// Very important:
ds.cleanup();
%>
clean up resources used by the Domino service
򐂰 Follow the steps in 4.3.4, “Deploying the Collaborative Hello portlet” on
page 95 to export the WAR file from WSAD and deploy this application on
WebSphere Portal Server.
򐂰 The output from this portlet should look similar to Figure 4-11 on page 101.
100
WebSphere Portal 4.12 Collaboration Services
Figure 4-11 PeopleSample portlet sample output
Key points about this portlet are:
򐂰 We use CSFactory.getService to construct the DominoService object. In this
example we do not specify a Domino server, so CSFactory uses the Domino
Directory server specified by the administrator in the
CSEnvironment.properties file. This is the preferred way to establish a
connection, rather than hard-coding the server into your JSP. If you wish to
connect to a different Domino server, use the form of getService that takes
the name of a specific Domino server as a parameter.
򐂰 Call getViewInfo on the DominoService object to open a database and view.
From this object you can read the view entries, obtain view categories, titles
for the columns, and other related information. In this example we open the
($VIMPeople) view rather than the Person view in names.nsf. We do this
because the Person view contains names in the wrong order (last name
followed by the first name). The PeopleService tags only recognize names in
abbreviated format (e.g., Joe Smith/Chicago/Acme) or common name format
(Joe Smith).
Chapter 4. Collaborative Components
101
򐂰 Call getRowInfo on a ViewInfo object to read entries from a view. getRowInfo
takes the starting view entry number (as a String) and the requested number
of entries as parameters. The view entries are numbered starting with 1. The
return value from this function is either an array of RowInfo objects or null in
the case of an empty view.
Note: The correct way to use the getRowInfo call to read an entire view is to
overlap your reads by one row. That is, read the first set of RowInfo objects,
then read the next set of RowInfo objects starting with the last one read on the
previous call. Discard the first RowInfo object (a duplicate) on your second
and subsequent calls. Failure to overlap your reads can produce unexpected
results. In particular, it is not valid to call getRowInfo with a starting row
number that does not exist in the view.
򐂰 Call the cleanup function on the DominoService object to release allocated
resources.
4.4.2 MenuSample portlet
This portlet demonstrates the features of the menu tags.
Follow these steps to create the MenuSample portlet:
򐂰 Create a new JSP portlet project in WSAD as shown in Section 4.3.3, “Writing
a basic collaborative Hello portlet” on page 90. Name this portlet
MenuSample and accept the defaults on the portlet parameters page.
򐂰 By default the JSP view file for this portlet is view.jsp under the
webApplication\jsp\html directory. Enter the following code for this file:
Example 4-3 view.jsp for the MenuSample portlet
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<%@ page language="java" import="com.lotus.cs.*, java.util.*" %>
<%@ taglib uri="/WEB-INF/tld/menu.tld" prefix="m" %>
<HTML>
<HEAD>
<META name="GENERATOR" content="IBM WebSphere Studio">
</HEAD>
<%
boolean showtest = false;
String testMessage = "Passed by parameter";
%>
<H2>Menu Tag Sample</H2>
<m:menucontext contextName="context1">
<m:menu menuName="menu1" menuID="mymenu_1">
<m:menuitem itemName="item 1" callbackFn="alert('item 1');" />
<m:menuitem itemName="item 2" callbackFn="alert('item 2');" enable="false"
show="<%=showtest%>" />
102
WebSphere Portal 4.12 Collaboration Services
</m:menu>
<m:menu menuName="menu2" menuID="mymenu_2">
<m:menuitem itemName="item 3" callbackFn="launchWithParam();" />
<m:menuitem itemName="toggle 5" callbackFn="toggleEnable();" />
<m:menuitem itemName="item 5" callbackFn="alert('item 5');"
enable="isEnabled();" />
</m:menu>
</m:menucontext>
<m:menucontext contextName="context2">
<m:menu menuName="menu1" menuID="mymenu_3">
<m:menuitem itemName="item 6" callbackFn="alert('item 6');" />
</m:menu>
</m:menucontext>
<script type="text/javascript" language="Javascript">
enabled=false;
function launchWithParam()
{
alert("this is the param passed in: " + context1.testparam);
}
function isEnabled()
{
return enabled;
}
function toggleEnable()
{
enabled = !enabled;
}
</script>
<p><a href="javascript:void(0)"
onclick=<m:menudisplay contextName="context1" menuName="menu1"
/>>menu1 in context1</a> shown on click</p>
<p><a href="javascript:void(0)"
onmouseover=<m:menudisplay contextName="context1" menuName="menu2"
paramName="testparam" paramValue="<%=testMessage%>" />>menu2 in
context1</a> shown on mouse over </p>
<p><a href="javascript:void(0)"
onclick=<m:menudisplay contextName="context2" menuName="menu1"
/>>menu1 in context2</a> shown on click</p>
</HTML>
Chapter 4. Collaborative Components
103
򐂰 Follow the steps in 4.3.4, “Deploying the Collaborative Hello portlet” on
page 95 to export the WAR file from WSAD and deploy this application on
WebSphere Portal Server.
򐂰 The output from this portlet should look similar to Figure 4-12.
Figure 4-12 Menu tag sample as it initially appears
Figure 4-13 Menu sample with first menu displayed
104
WebSphere Portal 4.12 Collaboration Services
Figure 4-14 Menu sample with second menu displayed
Figure 4-15 Menu sample after “toggle 5” selection
Figure 4-12 on page 104 shows the menu sample as it first appears. Clicking on
the first highlighted text brings up the menu shown in Figure 4-13 on page 104.
Hovering over the second line of highlighted text brings up the second menu.
Note that item 5 is greyed out in Figure 4-14. Clicking toggle 5 enables item 5, as
shown in Figure 4-15.
Key points about this portlet:
򐂰 We set up two menu contexts, context1 and context2. Under context1 we
have menu1 and menu2. Under context2 we have a different menu1.
򐂰 The menuitem tags under each menu tag define the menu selections. In each
menuitem tag the callbackFN parameter specifies the action to take when a
user selects the item. This action takes the form of a JavaScript call.
Chapter 4. Collaborative Components
105
򐂰 In context1, menu1, item 2 (code shown below) we have specified the enable
tag and set it to false (disable/grey out). We also specified the show flag and
set it to the value of showtest. Showtest is known at JSP compile time and is
set to false. This causes this item not to appear in the menu.
<m:menucontext contextName="context1">
<m:menu menuName="menu1" menuID="mymenu_1">
<m:menuitem itemName="item 1" callbackFn="alert('item 1');" />
<m:menuitem itemName="item 2" callbackFn="alert('item 2');" enable="false"
show="<%=showtest%>" />
</m:menu>
򐂰 In context1, menu2, item 5 (shown below) we have specified the enable tag
and set it to a JavaScript function. This function is evaluated whenever you
display the menu and determines whether item 5 will be enabled or greyed
out. Selecting the item labeled “toggle 5” calls a function toggling the value
that the isEnabled method returns (thus enabling or disabling item 5).
<m:menu menuName="menu2" menuID="mymenu_2">
<m:menuitem itemName="item 3" callbackFn="launchWithParam();" />
<m:menuitem itemName="toggle 5" callbackFn="toggleEnable();" />
<m:menuitem itemName="item 5" callbackFn="alert('item 5');"
enable="isEnabled();" />
</m:menu>
򐂰 The HTML code for the anchor tags demonstrates how to display a menu in
response to different JavaScript events. In the second example we pass a
value, testparam, using the paramName/paramValue tags. Any callback
function from this menu can evaluate the value of testparam as
context1.testparam.
<p><a href="javascript:void(0)"
onclick=<m:menudisplay contextName="context1" menuName="menu1"
/>>menu1 in context1</a> shown on click</p>
<p><a href="javascript:void(0)"
onmouseover=<m:menudisplay contextName="context1" menuName="menu2"
paramName="testparam" paramValue="<%=testMessage%>" />>menu2 in
context1</a> shown on mouse over </p>
<p><a href="javascript:void(0)"
onclick=<m:menudisplay contextName="context2" menuName="menu1"
/>>menu1 in context2</a> shown on click</p>
</HTML>
106
WebSphere Portal 4.12 Collaboration Services
4.4.3 An advanced collaboration sample
The functionality of this portlet application is to give the user a tool to easily
check the agenda for all the people who are in the enterprise directory. We can
consider this example as a portlet application because there are two portlets that
send and receive messages one from another. Portlet applications provide the
means to package a group of related portlets that share the same context.
The following collaboration components are used in this example:
򐂰 People library tags: We added in any name of both portlets the people tag to
have people awareness in the portlets.
򐂰 Menu library tags: We used these in order to have one extra menu option:
Show Agenda. This option is an extension of the menu options you have
when you enable people awareness in your portlets.
򐂰 Domino Service: We used this service in both portlets to get the rest of
collaboration services and access to the data.
򐂰 ViewInfo Service: In the first portlet we get the people data from the view to
present it in the portlet. In the second portlet we get the data from the
calendar of the person selected in the first portlet.
򐂰 Calendar Service: Once we have the view object, we need to get the
calendar entries for the person we selected in the first portlet.
򐂰 Portlet library tags: Using standard programming API portlet and JSP
portlet tag library to send the message between two portlets and to get one
parameter from the configuration of the second portlets.
Figure 4-16 on page 108 shows the architecture of the example and how it
works.
Chapter 4. Collaborative Components
107
Figure 4-16 Advanced collaboration example
We assume you are familiar with the structure of a portlet. Here we present part
of the portlet.xml file, which is the portlet descriptor generated by WSAD. Note
that we added the cache option and config param in one of the portlets.
Example 4-4 Part of the portlet.xml file
...
<portlet-name>AdvancedCollab Portlet</portlet-name>
<cache>
<expires>120</expires>
<shared>no</shared>
</cache>
...
<portlet-name>AdvancedCollab2 Portlet</portlet-name>
<cache>
<expires>0</expires>
<shared>no</shared>
</cache>
...
<concrete-portlet href="#Portlet_2">
<portlet-name>Advanced Collab2 Portlet</portlet-name>
<default-locale>en</default-locale>
<language locale="en">
<title>Advanced Collab2 Portlet</title>
108
WebSphere Portal 4.12 Collaboration Services
<title-short></title-short>
<description></description>
<keywords></keywords>
</language>
<config-param>
<param-name>Domain</param-name>
<param-value>itso</param-value>
</config-param></concrete-portlet>
...
The cache option is really interesting when you know that the data you are
presenting in the portlet is not going to change, or even if it changes is not
relevant for the end user. In our case it is not really important if somebody is
added in the people view. We can set up a 120-second time cache to avoid
calculating the data from the view portlet each time the page is recharged.
However, we cannot set up the same cache option for the second portlet
because we need the data for the agenda each time that the user selects one
person in the view of the first portlet.
It is useful, in order to avoid performance problems, to use this configuration
parameter to speed the load of our entire page into the portlets. We do not think
it is necessary to get the data from Domino each time the page is reloaded.
We use the config parameter for both portlets. The first portlet has a parameter
called View and the value is used to retrieve the data of this view from the
Domino Directory (names.nsf).
The config parameter for the second portlet is used to set up this application in
different domains without touching the code of the portlet, and to point to the
directory containing the images for the different entries in the calendar view. Also,
this is a way to show how easy it is to access a portlet configuration to get the
data from it.
There are several other ways to set up a parameter for a portlet. We chose the
config parameter so only the administrator of the portal will be able to modify this
parameter in Figure 4-17 on page 110.
Chapter 4. Collaborative Components
109
Figure 4-17 Setting the config parameter
The format for the URL Images parameter is:
http://itso-domino.ibm.com/icons/
Sender portlet
The sender portlet must implement the ActionListener interface and the
performedAction method because we are going to enable the portlet to send
messages to other portlets and manage the events.
In the doView() method we enable the portlet to send messages and redirect the
output to the AdvancedCollabSenderView.jsp file.
Example 4-5 Enabling the portlet to send messages
package com.ibm.wps.portlets.messaging;
import java.io.*;
import org.apache.jetspeed.portlet.*;
import com.ibm.wps.portlets.*;
import org.apache.jetspeed.portlet.event.*;
public class AdvancedCollabSender extends PortletAdapter implements
ActionListener {
public void init(PortletConfig portletConfig) throws UnavailableException {
super.init(portletConfig);
}
public void doView(PortletRequest request, PortletResponse response) throws
PortletException, IOException {
DefaultPortletAction action = new DefaultPortletAction("send");
110
WebSphere Portal 4.12 Collaboration Services
PortletURI sendURI = response.createReturnURI();
sendURI.addAction(action);
request.setAttribute("actionURI", sendURI.toString());
getPortletConfig().getContext().include("/jsp/AdvancedCollabSenderView.jsp",
request, response);
}
public void actionPerformed(ActionEvent event) {
PortletRequest request = event.getRequest();
String username = request.getParameter("username");
String portletName = request.getParameter("portletName");
if ( username != null && username.trim().length() > 0 ) {
DefaultPortletMessage message = new
DefaultPortletMessage(username);
try {
getPortletConfig().getContext().send(portletName, message);
} catch ( AccessDeniedException ade ) {
System.out.println("Could not send Message to "+ portletName);
}
}
}
}
In the actionPerformed() method we get from the request the username and
PortletName variables that correspond to the hidden fields in our form in the JSP
file. We use a post method, so when we submit the form in the request variable
we can obtain the values for the username and PortletName.
Then we send the message using the send method. If you use this method with
the first variable set to null you send the message to all the portlets of the page.
In this case we are sending the message to our second portlet. The message we
use is the defaultPortletMessage. You can extend this class to use another
message structure. We do not extend this class and pass the username in the
String object of the message.
Receiver portlet
This is the code for the receiver collaborative portlet, which must implement the
MessageListener interface and MessageReceived method. We get the message
in the MessageReceived Method and set the attribute in the session. Thus the
portlet in the jsp page using the usebean jsp directive can get the username
variable. In the doView() method we redirect to the
AdvancedCollabReceiverView.jsp.
package com.ibm.wps.portlets.messaging;
Chapter 4. Collaborative Components
111
import java.io.*;
import org.apache.jetspeed.portlet.*;
import com.ibm.wps.portlets.*;
import org.apache.jetspeed.portlet.event.MessageListener;
import org.apache.jetspeed.portlet.event.MessageEvent;
public class AdvancedCollabReceiver extends PortletAdapter implements
MessageListener {
public static final String USERNAME_KEY = "username";
public void init(PortletConfig portletConfig) throws UnavailableException {
super.init(portletConfig);
}
public void doView(PortletRequest request, PortletResponse response) throws
PortletException, IOException {
String username =
(String)request.getSession().getAttribute(USERNAME_KEY);
if (username == null) username="";
request.setAttribute("username", username);
// Invoke the JSP to render
getPortletConfig().getContext().include("/jsp/AdvancedCollabReceiverView.jsp",
request, response);
}
public void messageReceived(MessageEvent event) {
DefaultPortletMessage message = (DefaultPortletMessage)
event.getMessage();
PortletRequest request = event.getRequest();
request.getSession().setAttribute(USERNAME_KEY, message.getMessage());
}
}
AdvancedCollabSenderView.jsp
You can get the entire code from the additional material of this Redpaper. Here
we explain the most important lines of code we used in developing this example.
The jsp we use to send the message has first to get the DominoService
credentials and then obtain the data from the view. It also needs to read the value
of the View attribute we set up before from the portletRequest variable. All of this
is included in the following lines of code:
112
WebSphere Portal 4.12 Collaboration Services
...
CSEnvironment environ = CSEnvironment.getEnvironment(request);
CSCredentials cred = environ.getCredentials(request);
DominoService ds = (DominoService)
CSFactory.getService(cred,CSFactory.DOMINO_SERVICE);
String ViewName = portletRequest.getPortletSettings().getAttribute("View");
ViewInfo vi = ds.getViewInfo("names.nsf", ViewName);
...
To get the portletRequest variable you should initialize the portlet API through the
jsp directive:
<portletAPI:init />
This initialization allows you to access the portletRequest and portletConfig
variables of the portlet API.
The following lines of code show how to add other entries to the standard people
awareness menu that you obtain when you use the people tag library.
...
<menu:menucontext contextName="peoplemenu_moreContext">
<menu:menu menuName="peoplemenu_more" menuID="peoplemenu_more">
<menu:menuitem itemName="Show Calendar..."
callbackFn="ShowCalendar();" />
</menu:menu>
</menu:menucontext>
...
The important thing here is to preserve the contextName, menuName, and
menuID. In our example we use a callbackFn() to show the calendar. In this
function, to get the name that is between the tags, get the variable linkID (name
of the person). In the example we use this variable to set up the hidden fields in
our form and to submit the page.
...
function ShowCalendar() {
<%=portletResponse.encodeNamespace("submitForm")%>.<%=portletResponse.encod
eNamespace("username")%>.value=linkId;
<%=portletResponse.encodeNamespace("submitForm")%>.<%=portletResponse.encod
eNamespace("portletName")%>.value="AdvancedCollab2 Portlet";
<%=portletResponse.encodeNamespace("submitForm")%>.submit();
}
...
See the menu tag library description on how to use another JavaScript function
for passing parameters using name and value pairs into an array.
Chapter 4. Collaborative Components
113
The next thing we do in our example is to define the form, hidden fields, action,
and URI.
...
<form name="<%=portletResponse.encodeNamespace("submitForm")%>"
action="<%=actionURI%>" method="POST">
<input type="hidden"
name="<%=portletResponse.encodeNamespace("username")%>" value="">
<input type="hidden"
name="<%=portletResponse.encodeNamespace("portletName")%>" value="">
...
The actionURI variable contains the same value as the page, so when we submit
the page the URL will be the same, so we reload the page but in the request we
have set up the values for some fields.
To get the name of the view where we are going to retrieve the data we access
portletSettings via the portletRequest variable. We can do that because we have
initialized the portlet API with the Init jsp directive.
...
String ViewName = portletRequest.getPortletSettings().getAttribute("View");
...
Always remember to call cleanup() when using DominoService, or other Service
java objects, in order to free up connections back to your Domino environment.
The rest of the file is the same code we used for the people view in our previous
example.
AdvancedCollabReceiverView.jsp
This is the jsp file used to present the calendar data of the person selected in our
first portlet. The first thing to note in the code is that we use the usebean jsp
directive to get the value of the username variable.
...
<portletAPI:init />
<jsp:useBean id="username" class="java.lang.String" scope="request" />
...
We also initialized the portlet API to get the config variables Domain and URL.
These variables make the example independent from the environment.
...
String domain = portletRequest.getPortletSettings().getAttribute("Domain");
...
String urlicons= portletRequest.getPortletSettings().getAttribute("URL
Images");
114
WebSphere Portal 4.12 Collaboration Services
...
Once you have these variables you can access the user´s data: the MailServer
and MailFile fields. These are part of the set of methods that are provided by
DominoService. You can see more in detail in the API reference.
To write the output you should check whether there are some null pointer
variables. That is why we check every element before presenting the data in the
page.
<table><tr>
<%
for (int i=0 ; i < entrylist.length; i++)
{
entry = entrylist[i];
alttext = entry.getAlt();
rowtext = entry.getSummary();
iconid = entry.getIconName();
if (iconid != null)
{
iconid = urlicons + iconid;
%><td><img border="0" src="<%=iconid%>" /> </td><%
}
launchURL = urlBase + entry.getUNID() + "?opendocument" + "&date=" +
today.getISODate();
%><td><a href="javascript:window.open('<%=launchURL%>');" <%
if(alttext != null)
{
%>title="<%=alttext%>"<%
}
%>><%=(rowtext == null ? "" : rowtext)%></a></td></tr>
<%
}
%></table><%
And last but not least is the ds.cleanup() call. This is really important when you
are working in a production environment. You have to release the DIIOP
connections you created; otherwise, you run the risk of using up all the
connections in the DIIOP server. The DIIOP task has its own timeout setting and
releases connections then. But in a high concurrence environment it could be
insufficient to release the connections in the timeout frame.
4.4.4 Deploying Advanced Collaboration portlets
To deploy the AdvancedCollab example you should proceed as you did with the
other examples.
Chapter 4. Collaborative Components
115
Create an application page
In one of the PageGroups you already have, or in a new one, you can create a
page to test your example after you complete all the settings we explain in this
section (Figure 4-18). Add both portlets to the page. There’s no problem in how
the portlets are located in the page, or even if you put other portlets in the same
page.
Figure 4-18 Creating an application page
Config parameters
In this case you must remember to change the configuration parameter in the
AdvancedCollab2 portlet. You can access this setting by logging in to the portal
as user wpsadmin or a user with administrative rights.
򐂰 Select Portal Administration PageGroup.
򐂰 Select the Portlets tab.
򐂰 Select the ManagePortlets tab.
򐂰 Select the AdminCollab2 portlet in the list box.
򐂰 Select the Modify Parameters option.
Domino settings
You should have the following settings in the Domino server to allow the
AdvancedCollab example to work properly.
Create a view in the names.nsf file with Domino Designer with the following
formula in the first column:
116
WebSphere Portal 4.12 Collaboration Services
@Trim(@Subset(FirstName;1))+@If(Firstname !="";"
"+@Trim(@Subset(LastName;1)); @Trim(@Subset(LastName;1)) )
This formula returns a proper Name, which is placed in the first column of the
view.
Add the same columns we added, or other columns you want to show in the view.
In our example we selected the following:
Telephone: the formula isthe field OfficePhoneNumber
Company: the formula is the field Company.
Mail: the formula is the following:
name := @Name([Abbreviate]; @Subset(FullName;1));
@If(MailDomain != "" & MailAddress != ""; @Name([Abbreviate];MailAddress) +
" @ " + MailDomain; MailAddress != "";
@Name([Abbreviate];MailAddress);MailDomain != ""; name + " @ " +
MailDomain; name)
It is important that all the people documents have the first entry of the username
equal to the first column you just set up in the view, plus your organization; see
Figure 4-19.
Figure 4-19 People document setting
To enable people to see your agenda, check the “Read public documents”
checkbox in the ACL of the mail database (Figure 4-20 on page 118). It means
that everybody can see your calendar entries in your agenda unless you mark
them as private when you create or edit those entries.
Chapter 4. Collaborative Components
117
Figure 4-20 Setting ACL databases
Create some calendar entries in your demo user agendas via the Web interface
or the Notes Client. If you are testing in a demo environment, it is useful to check
the repeat field in the calendar entries for consecutive days. Also, you can create
different types of entries—meetings, appointments, anniversaries, etc.
So finally you can test your AdvancedCollab application in the page you created.
It looks similar to Figure 4-21.
Figure 4-21 Testing the AdvancedCollab example - 1
118
WebSphere Portal 4.12 Collaboration Services
And when you click a name you obtain the menu options shown in Example 4-22:
Figure 4-22 Testing the AdvancedCollab example - 2
You select Show Calendar and get the user’s agenda in the other portlet of your
page; see Figure 4-23.
Figure 4-23 Testing the AdvancedCollab example - 3
4.5 Best practices for collaborative portlet development
This section provides some general thoughts and considerations on developing
collaborative portlets. However, a significant amount of other documentation is
available on this topic—and anyone performing any serious portlet development
should be sure to carefully review this additional documentation.
See “Related publications” on page 159 for a listing of additional sources.
Chapter 4. Collaborative Components
119
4.5.1 Debugging recommendations
General debugging practices
There are multiple options for debugging your portlets in WebSphere Studio
Application Developer. The most advanced and integrated options involve using
the remote debugger capabilities in the WSAD tool to actually debug your
portlets on a separate WebSphere Portal Server, through the WSAD interface. If
you wish to take this approach, we recommend that you review the large amount
of documentation already covering this topic on the IBM WebSphere Developers
Domain at:
http://www7b.boulder.ibm.com/wsdd/library/techarticles/0203_khalifa/khalifa
2.html
http://www7b.boulder.ibm.com/wsdd/techjournal/0110_winchester/winchester.ht
ml
However, as the samples written for this paper were not overly complex, we took
an alternative approach to provide basic debugging capabilities—while also
simplifying development. In our approach, we wrote the portlets initially as
standalone JSPs and servlets that leveraged the Collaborative Components.
These standalone applications were then tested in the WebSphere Studio
Application Developer test environment itself, not remotely on a server. Once we
had verified that our basic collaborative code was working as planned, we then
converted our applications to portlets by wrappering them with the appropriate
portlet code. We would then deploy and test these portlets on the WebSphere
Portal server as needed.
We recommend this approach for basic portlet debugging, as the more advanced
remote debugging capabilities of WSAD can take additional time and effort to set
up and configure properly.
Portlet trace logging
Another recommendation for debugging is to enable tracing for the Collaborative
Components during your development and debugging. To enable this, access
Services -> Trace in the WebSphere Administration Console, and turn on tracing
for com.lotus.DominoService.
4.5.2 Portlet deployment considerations
When you deploy portlets you should be aware of the following:
򐂰 If you modify a portlet, you do not reinstall the portlet into WebSphere Portal
Server to see your changes. If the portlet application already exists, you will
receive an error when doing this. Instead, go into Portlet Application
Management, and choose to “update” your portlet application to see your
code changes.
120
WebSphere Portal 4.12 Collaboration Services
򐂰 You cannot have two portlets on a portal server with the same application
name. To install a new portlet application using an existing name, uninstall the
old one first.
򐂰 You cannot have two portlets with the same portlet name, which is in the
portlet descriptor file (portlet.xml).
򐂰 You cannot have two portlets with different names but with the same UID in
the portlet.xml file. WSAD automatically creates a unique UID for each portlet
in your portlet application.
4.5.3 Portlet performance considerations
WebSphere Portal uses the same portlet instance to generate the markup for
different pages for different users. There are a limited number of threads that
perform these tasks. Therefore, it is imperative to implement the portlet to do its
job as quickly as possible so that response time for a whole page is optimized.
Caching
A portlet container can provide a per-portlet cache, which stores the content of a
portlet. To configure the caching policy of a portlet, there are two properties in the
portlet’s deployment descriptor file (portlet.xml) that should be configured.
In the case of portlet access to Domino-based collaborative servers, this means
a connection is established each time with Domino, the data is read, and the
connection is destroyed. There is no connection pooling by default with the
Collaborative Components, so the performance hit of not caching includes both
connection setup and data retrieval.
Example 4-6 Cache-related properties in the portlet.xml file
<cache>
<expires>0</expires>
<shared>no</shared>
</cache>
Where:
򐂰 <expires>
Indicates the number of seconds after which the portlet's output is refreshed.
0 indicates that the portlet's output always expires, and that no caching is
performed. This is the default setting if the cache element is not present at all.
Any number greater than 0 indicates the number of seconds the portlet output
is cached. After the cache time expires, subsequent requests cause the
portlet to refresh its output.
Chapter 4. Collaborative Components
121
-1 indicates that the portlet’s output never expires. After the portlet is
initialized, its content is no longer refreshed.
򐂰 <shared>
Indicates whether the portlet output is cached and shared with all users, or
whether it is cached for each individual user. Specify “yes” or “no”.
For a discussion of the pros and cons of caching for a collaborative portlet
application, see 4.4.3, “An advanced collaboration sample” on page 107.
General portlet performance
The following general portlet performance thoughts have been taken directly
from the Portlet Developers Guide. However, because we consider performance
crucial to any production portlet, we have included a copy of this information
here.
򐂰 Limit the use of the synchronized methods or synchronized code blocks in the
processing of a portlet method.
򐂰 Limit the use of complex string operations. This includes:
– Minimize transient XSL style sheets as they cause a lot of temporary Java
object instantiations.
– Consider using a StringBuffer to replace temporary String objects.These
are more efficient in processing strings in general and also don't generally
instantiate other temporary String objects.
򐂰 Limit the use of long-running loops.
򐂰 Do not create large pools of threads.
򐂰 Minimize calls to external data sources. If possible, set your portlet to cache
its output.
򐂰 Use JSPs instead of XSL. JSPs with view beans are much faster and
instantiate less intermediate Java objects. The XSL engine creates a lot of
temporary strings.
򐂰 Portlet JSPs can be optimized for performance by reducing white space and
using the non-transferable JSP comment format (<%-- --%>) as opposed to
the HTML comment format (<!-- -->).
򐂰 Minimize Java object instantiations.
DominoService object
Depending on the type of request, the DominoService object uses either DIIOP
or HTTP to retrieve the data. There is a significant performance advantage to
designing your code to use functions relying on HTTP for their underlying
implementation. In addition, the use of DIIOP requires Domino R5 or higher—so
122
WebSphere Portal 4.12 Collaboration Services
code that calls DominoService functions using DIIOP will not function against
Domino R4 servers.
Keep the following in mind:
򐂰 All view-related functions except for getViewCategories use HTTP.
򐂰 Of the Document-related functions, only getOpenURL, getEditURL, and
deleteDocument use HTTP. All others require DIIOP.
򐂰 Querying a Domino server for a list of databases uses DIIOP.
򐂰 CalendarDayInfo functions use DIIOP for versions of Domino between 5.0
and 5.0.3.
The first time you invoke a function requiring DIIOP, an internal session helper
object is created to manage the Domino session.
Listing of DominoService calls using DIIOP
The following DominoService calls utilize DIIOP when communicating with
Domino, and should therefore be avoided when performance considerations are
crucial.
򐂰 Directory-related:
– public HashMap getDatabases
– public HashMap getCompleteDatabases
– public HashMap getDatabaseViewsWithAliases
– public HashMap getQuickPlaceDatabases
– public HashMap getQuickPlaceComponents
򐂰 Document-related:
– public HashMap getDocumentInfo
– public boolean updateDocumentInfo
– public String createDocument
– public boolean createDatabase
– public boolean addACL
– public lotus.domino.Session getSessionObject
– public lotus.domino.Document getDocumentObject
򐂰 View-related:
public String[] getViewCategories
Chapter 4. Collaborative Components
123
124
WebSphere Portal 4.12 Collaboration Services
A
Appendix A.
Collaborative Components:
classes/methods
This appendix describes key objects and methods available from the
Collaborative Components API for usage in your custom collaborative portlets.
For more detailed information about each of these classes, see the
documentation provided in the form of a Javadoc within the Collaboartive
Components enterprise application: the cs.ear file.
If you have installed/deployed the Collaborative components on your WebSphere
server, as described in 2.6, “Deploying the Collaborative Components (API)” on
page 34, you can find the documentation in the following location:
C:\WebSphere\PortalServer\app\wps.ear\wps.war\doc\Javadoc\CollabServices\Collab
Services\index.html
CalendarDayInfo
CalendarDayInfo encapsulates a day within a calendar's current time period. It
provides accessor methods to the list of calendar entries for the day, and facilities
for dealing with timeslots. To create a CalendarDayInfo object, use
DominoService.getViewInfo() to first create a ViewInfo, and then use
ViewInfo.getCalendarDayInfo().
© Copyright IBM Corp. 2002. All rights reserved.
125
To get the list of entries in the day, use getEntryInfo.
򐂰 getEntryInfo
public final EntryInfo[] getEntryInfo()
Returns the set of calendar entries for the day.
򐂰 getISODate
public final java.lang.String getISODate()
Returns a String representation for the day's date. ISO data format:
"yyyy-MM-dd" in all locales.
򐂰 getDate
public final java.util.Calendar getDate()
Returns a Java Calendar object for the day.
򐂰 getPreviousISODate
public java.lang.String getPreviousISODate(int grid)
Returns a String representation for the previous day's date. ISO data format:
"yyyy-MM-dd" in all locales. This is useful when implementing navigation
controls for the calendar.
Parameters:
grid - calendar style, one of ViewInfo.ONE_DAY, ViewInfo.TWO_DAYS,
ViewInfo.ONE_WEEK, ViewInfo.TWO_WEEKS, or ViewInfo.ONE_MONTH.
򐂰 getNextISODate
public java.lang.String getNextISODate(int grid)
Returns a String representation for the next day's date. ISO data format:
"yyyy-MM-dd" in all locales. This is useful when implementing navigation
controls for the calendar.
Parameters:
grid - calendar style, one of ViewInfo.ONE_DAY, ViewInfo.TWO_DAYS,
ViewInfo.ONE_WEEK, ViewInfo.TWO_WEEKS, or ViewInfo.ONE_MONTH.
򐂰 isToday
public boolean isToday()
Returns whether or not the day is the current day.
򐂰 isInTodaysMonth
public boolean isInTodaysMonth()
Returns whether or not the day is in the current month.
126
WebSphere Portal 4.12 Collaboration Services
ColumnInfo
ColumnInfo contains information about the columns in a Domino view. To create
a ColumnInfo object, use DominoService.getViewInfo() to first create a ViewInfo
and then use ViewInfo.getColumnInfo(). Note that the information returned is
ready-made for presentation (for example, no special processing is necessary for
hidden and response column information).
򐂰 getTitle
public java.lang.String getTitle()
Returns the title of the column.
򐂰 getWidthPercentage
public int getWidthPercentage()
Returns the width percentage of this column in the view (the column
percentages returned add up to 100).
򐂰 isCategory
public boolean isCategory()
Returns whether or not this column is a category view.
򐂰 isShowTwistie
public boolean isShowTwistie()
Returns whether or not this column has the possibility of needing a twistie.
Whether or not to show the twistie next to a row is governed by
RowInfo.useTwistie.
򐂰 isIcon
public boolean isIcon()
Returns whether or not the data is this column is icon data. To form the gif to
the icon, use the value returned by RowInfo.getValues() and construct the file
name of the image. For example, if a value of 009 is returned by this method,
the image name would be vwicn009.gif. Then, to construct a link in the UI,
use a path such as /cs/images/vwicn009.gif where /cs/images is the directory
where the view images are stored.
CSCredentials
򐂰 getUserName
public java.lang.String getUserName()
Returns a string representing the user name in Distinguished Name format.
Appendix A. Collaborative Components: classes/methods
127
򐂰 getUserLoginName
public java.lang.String getUserLoginName()
Returns the login name for the currently logged in user.
CSEnvironment
CSEnvironment is the starting point to instantiate and use Lotus Collaborative
Components.
The first two lines of code needed to start using Collaborative Components are:
...
CSEnvironment environ = CSEnvironment.getEnvironment(request);
CSCredentials cred = environ.getCredentials(request);
...
The getEnvironment method initializes Collaborative Components as follows:
sets up the environment properties (for example, location of Lotus Collaborative
servers); sets credentials for the logged-in user (using the HttpServletRequest);
sets up resource strings (loads the appropriate CSRes properties file for the
strings used by the person tag).
The CSEnvironment object may also be used to retrieve information about the
environment or logged-in user, or to retrieve the resources which you may wish to
store, per locale, in the CSRes properties files.
򐂰 getEnvironment
public static CSEnvironment
getEnvironment(javax.servlet.http.HttpServletRequest request)
This method gets the CSEnvironment - this is the starting point to use Lotus
Collaborative Services. From here, getCredentials, getResources,
getServers, etc. Note that you cannot use the CSEnvironment from an
unsecured portlet/jsp. Refer to the code example in the CSEnvironment
description.
Parameters:
request - must contain credentials for the user
Returns:
CSEnvironment from which CSCredentials may be obtained.
򐂰 getCredentials
public CSCredentials getCredentials(javax.servlet.http.HttpServletRequest
request)
128
WebSphere Portal 4.12 Collaboration Services
This method gets the CSCredentials object that is required to instantiate the
service objects. Refer to the code example in the CSEnvironment description.
Parameters:
request - CSCredentials is saved in the HttpSession
Returns:
CSCredentials, which may be used to instantiate service objects.
public static CSCredentials getCredentials(java.lang.String userName,
java.lang.String userPassword)
This method is provided for use only when the credentials in the
HttpServletRequest are not valid for the service object you wish to instantiate
(atypical); for example, for LDAP functionality (in DominoService), when the
LDAP directory is different from the WebSphere Portal directory.
Parameters:
userName - name of the user (prefer shortname)
userPassword - password of the user
Returns:
CSCredentials, which may be used to instantiate service objects.
򐂰 getResources
public java.util.ResourceBundle
getResources(javax.servlet.http.HttpServletRequest request)
This method returns the resources contained in the CSRes properties file
(uses locale).
Parameters:
request - ResourceBundle is saved in the HttpSession
Returns:
java.util.ResourceBundle which contains locale-specific Strings that are
appropriate for the current user's locale.
򐂰 isEnabled
public boolean isEnabled(java.lang.String serverType)
This method returns a boolean indicating whether or not the specified server
type is available in the environment.
Note: When running in a non-WP environment and specifying serverType
CSEnvironment.CS_SERVER_WebSphere_PORTAL_EXTEND, this method
always returns false.
Parameters:
Appendix A. Collaborative Components: classes/methods
129
serverType - One of the CSEnvironment server types (example:
CSEnvironment.CS_SERVER_QuickPlace)
Returns:
True if the specified serverType is available, false otherwise.
򐂰 getServers
public java.util.HashMap getServers(java.lang.String serverType)
This method returns a HashMap containing properties for a specified server
type in the environment. Index values in the HashMap are
CSEnvironment.CS_PROP_ENABLED,
CSEnvironment.CS_PROP_NUMSERVERS,
"1."+CSEnvironment.CS_PROP_HOSTNAME, "1."+CS_PROP_PROTOCOL,
"1."+CS_PROP_VERSION, "1."+CS_PROP_HOSTNAME, etc.
Parameters:
serverType - One of the CSEnvironment server types (example:
CSEnvironment.CS_SERVER_QuickPlace)
Returns:
A HashMap containing properties for a specified server type in the
environment.
CSFactory
The CSFactory object instantiates the Java service objects. The CSFactory has
two methods (two different versions of getService).
򐂰 getService
public static CSBaseService getService(CSCredentials cred, java.lang.String
serviceType)
Use this version of getService when you wish to use the Lotus Collaborative
servers that are configured in the environment.
Note: When using this version with CSFactory.DOMINO_SERVICE, this will
create a DominoService object for the Domino Directory server. To create a
DominoService object for another Domino server, use the other version of
getService.
Parameters:
cred - may be obtained using CSEnvironment.getCredentials
serviceType - may be one of: CSFactory.DOMINO_SERVICE,
CSFactory.DISCOVERY_SERVER_SERVICE,
CSFactory.QuickPlace_SERVICE, CSFactory.PERSON_SERVICE
130
WebSphere Portal 4.12 Collaboration Services
򐂰 getService
public static CSBaseService getService(CSCredentials cred,
java.lang.String serviceType,
java.lang.String server,
java.lang.String protocol)
Use this version when you wish to specify the Lotus server to connect to (or if
you wish to override the servers that are configured in the environment).
Parameters:
cred - may be obtained using CSEnvironment.getCredentials
serviceType - may be one of: CSFactory.DOMINO_SERVICE,
CSFactory.DISCOVERY_SERVER_SERVICE,
CSFactory.QuickPlace_SERVICE, CSFactory.PERSON_SERVICE
server - should be specified using the Internet name (example,
myserver.mycompany.com)
protocol - http (the default) or https.
DiscoveryServerService
The DiscoveryServerService object retrieves data from a Discovery Server.
The DiscoveryServerService methods fall into the following categories:
򐂰 Search APIs.
򐂰 APIs that return URLs for use in your UI.
򐂰 APIs which return core Discovery Server objects from a Discovery Server.
The following information presents examples of some common search queries
for the Search APIs (that correspond to the options found in the K-map user
interface):
򐂰 Searching for everything about a subject:
To search for knowledge management, pass knowledge management OR
knowledge* AND management* as the query to searchDocuments,
searchPeople, searchCategories, and searchPlaces (if places are installed
and configured with K-station).
򐂰 Searching for documents about a subject:
To search for knowledge management, pass knowledge management OR
knowledge* AND management* as the query to searchDocuments.
򐂰 Searching for documents authored by a specific person:
Appendix A. Collaborative Components: classes/methods
131
To search for John Doe, pass [$UpdatedBy] CONTAINS John Doe as the query
to searchDocuments.
򐂰 Searching for people by name:
To search for John Doe, pass [fullname] CONTAINS John Doe as the query to
searchPeople.
򐂰 Searching for people who know about a specific subject:
To search for knowledge management, pass [AffinityPublishedLeaf]
CONTAINS knowledge management OR knowledge* AND management* as the
query to searchPeople.
򐂰 Searching for people whose Profile contains a specific piece of information:
To search for knowledge management, pass knowledge management OR
knowledge* AND management* as the query to searchPeople.
򐂰 Searching Categories for specific information:
To search for knowledge management, pass knowledge management OR
knowledge* AND management* as the query to searchCategories.
These are methods you have in the DiscoveryServerService:
򐂰 init
public void init(CSCredentials cred,
java.lang.String server,
java.lang.String protocol)
Do not call the init() method; init is called internally by CSFactory as part of
the getService.
Specified by: init in interface CSBaseService
򐂰 getCursor
public com.lotus.KDSAPI.KDSCursor getCursor()
Returns the specified Discovery Server object. You must import
com.lotus.KDSAPI.* in order to use this method. Refer to the Discovery
Server javadoc for detailed information about this object.
Returns: the specified Discovery Server object.
򐂰 getFTSearch
public com.lotus.KDSAPI.KDSFTSearch getFTSearch()
Returns the specified Discovery Server object. You must import
com.lotus.KDSAPI.* in order to use this method. Refer to the Discovery
Server javadoc for detailed information about this object.
Returns: the specified Discovery Server object.
򐂰 getMetrics
132
WebSphere Portal 4.12 Collaboration Services
public com.lotus.KDSAPI.KDSMetrics getMetrics()
Returns the specified Discovery Server object. You must import
com.lotus.KDSAPI.* in order to use this method. Refer to the Discovery
Server javadoc for detailed information about this object.
Note: This method is not supported with DS 1.1.x. It is supported with DS 2.0
(and kdsapi.jar, version 2.0).
Returns: the specified Discovery Server object.
򐂰 getRepository
public com.lotus.KDSAPI.KDSRepository getRepository()
Returns the specified Discovery Server object. You must import
com.lotus.KDSAPI.* in order to use this method. Refer to the Discovery
Server javadoc for detailed information about this object.
Returns:the specified Discovery Server object.
򐂰 getRepositoryInfo
public com.lotus.KDSAPI.KDSRepositoryInfo getRepositoryInfo()
Returns the specified Discovery Server object. You must import
com.lotus.KDSAPI.* in order to use this method. Refer to the Discovery
Server javadoc for detailed information about this object.
Returns: the specified Discovery Server object.
򐂰 getTaxEdit
public com.lotus.KDSAPI.KDSTaxEdit getTaxEdit()
Returns the specified Discovery Server object. You must import
com.lotus.KDSAPI.* in order to use this method. Refer to the Discovery
Server javadoc for detailed information about this object.
Note: To use this method with DS 1.1.x, the requesting user must have kmap
editor or admin privileges.
Returns: the specified Discovery Server object.
򐂰 cleanup
public void cleanup()
Always call the cleanup() method when finished with the Service object. This
is important because if you do not clean up this object, you leave DIIOP
connections open in your Domino Server.
Specified by: cleanup in interface CSBaseService
򐂰 getProfileURL
public java.lang.String getProfileURL(java.lang.String fullName)
Returns the URL to the profile for a specified user.
Appendix A. Collaborative Components: classes/methods
133
Note: It is recommended that you use the fully-qualified name (the fullName
property from the findPeople results).
Parameters: userName - String, name of the user
Returns: the URL to the profile for a specified user.
򐂰 getKMapURL
public java.lang.String getKMapURL()
Returns the URL to the Discovery Server K-map UI.
򐂰 getProfileURL_DS11
public static java.lang.String getProfileURL_DS11(java.lang.String server,
java.lang.String commonName)
Returns the URL to the profile for a specified user in Discovery Server version
1.1 . This an optimized version (with minimal error checking) for use with
Discovery Server 1.1 only.
Parameters:
server - String, The fully qualified domain name of the Discovery Server
version 1.1
commonName - String, common name of the user
Returns: the URL to the profile for a specified user.
򐂰 getKMapURL_DS11
public static java.lang.String getKMapURL_DS11(java.lang.String server)
Returns the URL to the Discovery Server1.1 K-map UI. This an optimized
version (with minimal error checking) for use with Discovery Server 1.1 only.
Returns: the URL to the Discovery Server K-map UI.
򐂰 getDSControlCenterURL
public java.lang.String getDSControlCenterURL()
Returns: the URL to the Discovery Control Center UI.
򐂰 findPeople
public java.util.HashMap[] findPeople(java.lang.String currentQuery,
int start,
int limit)
Returns results from a specified people search.
Parameters:
currentQuery - String, contains query text to search on. Refer to the
DiscoveryServerService class description for more details.
134
WebSphere Portal 4.12 Collaboration Services
start - int, indicates the location (index) where the result set should begin.
Start with 1.
limit - int, number of results to return.
Returns:
HashMap array. Each element in the array contains a HashMap with the
following information about each person who was found in the search:
department (String), jobTitle (String), location (String), fullName (String),
name (String), profile (String), summary (String), rank (Double).
򐂰 findPlaces
public java.util.HashMap[] findPlaces(java.lang.String currentQuery,
int start,
int limit)
Returns results from a specified place search.
Parameters:
currentQuery - String, contains query text to search on. Refer to the
DiscoveryServerService class description for more details.
start: - int, indicates the location (index) where the result set should begin.
Start with 1.
limit: - int, number of results to return.
Returns:
HashMap array. Each element in the array contains a HashMap with the
following information about each place which was found in the search:
description (String), name (String), owner (String), ID (String), URL (String),
rank (Double).
򐂰 findDocuments
public java.util.HashMap[] findDocuments(java.lang.String currentQuery,
int start,
int limit)
Returns results from a specified document search.
Parameters:
currentQuery - String, contains query text to search on. Refer to the
DiscoveryServerService class description for more details.
start - int, indicates the location (index) where the result set should begin.
Start with 1.
limit - int, number of results to return.
Returns:
Appendix A. Collaborative Components: classes/methods
135
HashMap array. Each element in the array contains a HashMap with the
following information about each document which was found in the search:
modifiedDate (String), createDate (String), author (String), title (String),
docType (String), URL (String), ID (String), summary (String), rank (Double).
򐂰 getDocsCreatedByUser
public java.util.HashMap[] getDocsCreatedByUser(java.lang.String userName,
java.lang.String
currentQuery,
int start,
int limit)
Returns information about the set of documents created by the specified user.
Parameters:
userName - String, name of the user
currentQuery - String, contains query text to search on. Refer to the
DiscoveryServerService class description for more details.
start - int, indicates the location (index) where the result set should begin.
Start with 1.
limit - int, number of results to return.
Returns:
HashMap array. Each element in the array contains a HashMap with the
following information about each document which was found in the search:
createDate (String), title (String), URL (String), summary (String), rank
(Double).
DominoService
DominoService retrieves data (and, in some cases, writes data) from (to) Domino
databases. There are three types of DominoService methods:
򐂰 View Related (almost all methods use HTTP).
These methods obtain information from views. All the view-related methods
require you to create a ViewInfo object to access data. Example methods
from ViewInfo are getColumnInfo, getRowInfo, getCalendarDayInfo.
򐂰 Directory Related (get lists of information, often using IIOP or Domino LDAP).
For example, getServers, getDatabases, getEmailAddress, etc.
򐂰 Document Related (most methods use IIOP).
For example, getDocumentInfo, createDatabase, createDocument, etc.
򐂰 init
136
WebSphere Portal 4.12 Collaboration Services
public void init(CSCredentials cred,
java.lang.String server,
java.lang.String protocol)
Do not call the init() method; init is called internally by CSFactory as part of
the getService.
Specified by:
init in interface CSBaseService
򐂰 cleanup
public void cleanup()
Always call the cleanup() method when finished with the Service object.
򐂰 getSessionObject
public lotus.domino.Session getSessionObject()
Returns the Domino Java API Session object. Refer to the Domino Java API
documentation for usage of this object. You must import lotus.domino.Session
in order to use this method. Note that this method uses DIIOP and always
returns null when the server is Domino version ViewInfo.DOMINO_46
Returns:
Domino Java Session object.
򐂰 getCompleteDatabases
public java.lang.String[] getCompleteDatabases(java.lang.String
templateFilter)
Return a complete list of Domino database names and or directories on the
given server. Note that this method uses DIIOP and always returns null when
the server is Domino version ViewInfo.DOMINO_46 Use
DominoService.getDatabases if either (a) db filenames (nsf names) on the
server can contain the ampersand (&) character, or (b) db file names or titles
can contain the vertical bar (|) character, or (c) you are using the
templateFilter option and you wish to consider templates with names
containing R50 separate from those with names containing R60.
Parameters:
templateFilter - optional. Only databases with this template will be returned.
Use null otherwise. Note that using this option with a String such as
StdR50Disc (for Discussion dbs), will also return the dbs made with the R60
template (in this example StdR60Disc).
Appendix A. Collaborative Components: classes/methods
137
Returns:
String array with abc&xyz&xxxx.nsf|title as the value in each element where
the ampersand (&) character is used to designate a directory name (that is, in
this example, the database file name is abc\xyc\xxxx.nsf) and the vertical bar
(|) character is used to separate the nsf file name from the database title.
򐂰 getDatabases
public java.util.HashMap getDatabases(java.lang.String templateFilter,
java.lang.String startDirectory)
Return a list of Domino database names and directory names in the specified
start directory. Note that this method uses DIIOP and always returns null
when the server is Domino version ViewInfo.DOMINO_46.
Parameters:
templateFilter - optional. Only databases with this template will be returned.
Use null, otherwise.
startDirectory - A subdirectory to start from - null indicates the top level
directory.
Returns:
HashMap with database names as key and title as value. When the title
returned does not end in .nsf, this indicates a database directory name. To
traverse this directory, call this method again using that directory name for
startDirectory.
򐂰 getQuickPlaceDatabases
public java.lang.String[] getQuickPlaceDatabases()
Returns the list of QuickPlace databases. Note that this method uses DIIOP
and always returns null when the server is Domino version
ViewInfo.DOMINO_46.
Returns:
String array containing the names of the QuickPlace databases.
򐂰 getQuickPlaceComponents
public java.lang.String[] getQuickPlaceComponents(java.lang.String
database)
Return a list of QuickPlace components in a QuickPlace. Note that this
method uses DIIOP and always returns null when the server is Domino
version ViewInfo.DOMINO_46.
Parameters:
database - Full path of QuickPlace directory (example: QuickPlace\myQP)
Returns:
138
WebSphere Portal 4.12 Collaboration Services
Array of QuickPlace components (Home, Welcome, Calender...)
򐂰 getCompleteQuickPlaceComponents
public java.lang.String getCompleteQuickPlaceComponents(java.lang.String
database)
Return a list of QuickPlace components in a QuickPlace. Note that this
method uses DIIOP and always returns null when the server is Domino
version ViewInfo.DOMINO_46
Parameters:
database - Full path of QuickPlace directory (example: QuickPlace\myQP)
Returns:
QuickPlace components (Home, Welcome, Calender...)
򐂰 getDatabaseViewsWithAliases
public java.util.HashMap getDatabaseViewsWithAliases(java.lang.String
dbName, boolean showHidden, boolean showCalendar)
Return a list of views in a given Domino database. Note that this method uses
DIIOP and always returns null when the server is Domino version
ViewInfo.DOMINO_46.
Parameters:
dbName - nsf name of the database to retrieve views from. Be sure to use
either \\ or / between folder names.
showHidden - if true, include views that are hidden.
showCalendar - if true, include views that are calendar views.
Returns:
HashMap with view names as key and aliases as value. When there is more
than one alias, vertical bars are used as separators.
򐂰 getDatabaseViews
public java.util.HashMap getDatabaseViews(java.lang.String dbName)
Return a list of views in a given Domino database. Return does not include
hidden views and does return calendar views. Note that this method always
returns null when the server is Domino version ViewInfo.DOMINO_46.
Parameters:
dbName - nsf name of the database to retrieve views from. Be sure to use
either \\ or / between folder names.
Returns:
HashMap with view names as key and view unid as value.
Appendix A. Collaborative Components: classes/methods
139
򐂰 getServers
public java.util.HashMap getServers()
Returns a list of Domino servers in the domain which have the http-hostname
attribute set.
Returns:
HashMap, where the key is the Domino server name (distinguished name)
and the value is the host name (for example, name: CN = ecat-1, O = eCAT
value: ecat-1.lotus.com). The fully qualified domain name of a network host,
or its IP address as a set of four decimal digit groups separated by a dot (.).
򐂰 getDominoName
public java.lang.String getDominoName(java.lang.String fullName)
Converts a distinguished name into a Domino name (also referred to as the
Abbreviated name). For example, OU=CAM,O=Lotus will be converted to
/CAM/Lotus Note that this is simply a helper method—there is no LDAP query
made.
Parameters:
fullName - The distinguished name (DN).
Returns:
String The Domino Name (Abbreviated format).
򐂰 getMailServerFile
public java.lang.String[] getMailServerFile(java.lang.String userName)
Returns the names of the Domino mail file and mail server for a valid user in
the domain.
Parameters:
userName - The distinguished name (DN) or the Common Name (CN) of the
user. If null is passed in, it will return the logged in user's mail server and file.
Returns:
String[] - The first entry in the array is the mail host name. The second entry in
the array is the name of the mail file.
򐂰 getEmailAddress
public java.lang.String getEmailAddress(java.lang.String userName)
Returns the e-mail address of the user.
Parameters:
userName - The distinguished name (DN) or the Common Name (CN) of the
user. If null is passed in, it will return the logged in user's e-mail address.
140
WebSphere Portal 4.12 Collaboration Services
Returns:
String - The Internet e-mail address of the user.
򐂰 getDistinguishedName
public java.lang.String getDistinguishedName(java.lang.String userName)
Returns the distinguished name of the user.
Parameters:
userName - The short name (uid) or the Common Name (CN) of the user. If
null is passed in, it will return the logged in user's distinguished name.
Returns:
String - The comma-separated distinguished name of the user.
򐂰 getViewInfo
public ViewInfo getViewInfo(java.lang.String dbName, java.lang.String
viewName)
Returns view information about a view, encapsulated in a ViewInfo object.
Parameters:
dbName - The nsf name of the database. Be sure to use either \\ or / between
folder names.
viewName - The name of the view (can be alias).
Returns:
a ViewInfo object containing information about the specified view.
򐂰 getDocumentInfo
public java.util.HashMap getDocumentInfo(java.lang.String db,
java.lang.String View,
java.lang.String unid,
java.lang.String[] fields)
Returns values for fields in a document which are of type String. Note that this
method uses DIIOP and always returns null when the server is Domino
version ViewInfo.DOMINO_46.
Parameters:
db - Full path of NSF file
view - Not used view name of document to locate
unid - Document unid
fields - Array of field names
Returns:
Appendix A. Collaborative Components: classes/methods
141
name/value pairs of requested field names
򐂰 updateDocument
public boolean updateDocument(java.lang.String db,
java.lang.String view,
java.lang.String unid,
java.util.HashMap fields)
Updates a document in the db. Where a field name is supplied that is not
presently in the document, it creates the new field in the document. Note that
this method uses DIIOP and always returns false when the server is Domino
version ViewInfo.DOMINO_46. This method will only update fields of type
String.
Parameters:
db - Full path of NSF file
view - Not used view name of document to locate
unid - Document unid
fields - Array of field names. Only String Values allowed.
Returns:
True, if the document was successfully updated.
򐂰 deleteDocument
public boolean deleteDocument(java.lang.String db,
java.lang.String view,
java.lang.String unid)
Removes a document from the given database.
Parameters:
db - Full path of NSF file.
view - Not used view name of document to locate.
unid - Document unid.
Returns:
True, if the document was successfully deleted.
򐂰 createDocument
public java.lang.String createDocument(java.lang.String db,
java.util.HashMap fields)
Creates a document in the db. Note that this method uses DIIOP and always
returns null when the server is Domino version ViewInfo.DOMINO_46
Parameters:
142
WebSphere Portal 4.12 Collaboration Services
db - Full path of NSF file.
fields - Array of field names.
Returns:
String, UNID of the document or NULL if unable to create document.
򐂰 addACL
public boolean addACL(java.lang.String db,
java.lang.String aclName,
int Acltype,
int AclAccessLevel)
Adds a single ACL to an existing database.
Note: For R5 Domino versions, the Access Control property called Maximum
Internet name & password (Advanced setting) must be manually set to
Manager level before this method will work.
For Domino versions >= 6, when using this method after a call to
DominoService.createDatabase, this manual setting is not required (since the
createDatabase method will automatically set this setting to Manager. Note
that this method uses DIIOP and always returns false when the server is
Domino version ViewInfo.DOMINO_46.
Parameters:
db - Full path of NSF file
aclName - String name of acl. For a hierarchical name, the full name must be
specified, but can be in Abbreviated format.
Acltype - one of DOMINO defines ACLEntry (Ex
ACLEntry.TYPE_MIXED_GROUP).
TYPE_MIXED_GROUP
TYPE_PERSON
TYPE_PERSON_GROUP
TYPE_SERVER
TYPE_SERVER_GROUP
TYPE_UNSPECIFIED
AclAccessLevel - one of DOMINO defines ACL (Ex ACL.LEVEL_MANAGER)
LEVEL_NOACCESS
LEVEL_DEPOSITOR
LEVEL_READER
LEVEL_AUTHOR
Appendix A. Collaborative Components: classes/methods
143
LEVEL_EDITOR
LEVEL_DESIGNER
LEVEL_MANAGER
Returns:
True, if successful; false otherwise.
򐂰 createDatabase
public boolean createDatabase(java.lang.String db,
java.lang.String title,
java.lang.String template)
Creates a new Domino database from a database template. Note that this
method uses DIIOP and always returns false when the server is Domino
version ViewInfo.DOMINO_46. Note also that the title will not be set on
Domino versions < R6.
Parameters:
db - The name for the database (nsf file name)
title - The title for the database (this part of the functionality does not work on
Domino versions < 6).
template - The template name for the database (ntf file name)
Returns:
True, if database was created or it existed; false otherwise.
򐂰 getOpenURL
public java.lang.String getOpenURL(java.lang.String db,
java.lang.String view,
java.lang.String unid,
boolean validate)
Returns a URL to the specified document. Especially useful when server
protocol is unknown.
Parameters:
db - The name for the database (nsf file name).
view - String, the name of the view.
unid - String, the UNID of the document (could be returned by
RowInfo.getUNID or EntryInfo.getUNID).
validate - Boolean, whether or not to check if the returned URL is valid. In
most cases, use false here, since it is a significant performance hit to test this
connection.
144
WebSphere Portal 4.12 Collaboration Services
Note: With HTTPS, the test might fail even if the connection is, in fact, valid.
Validation does not include an authorization check.
Returns:
A fully-formed URL to the Domino Open action for the specified document (or
null if validate specified as true and the test connection failed).
򐂰 getEditURL
public java.lang.String getEditURL(java.lang.String db,
java.lang.String view,
java.lang.String unid,
boolean validate)
Returns a URL to the specified document. Especially useful when the server
protocol is unknown.
Parameters:
db - The name for the database (nsf file name).
view - String, the name of the view.
unid - String, the UNID of the document (could be returned by
RowInfo.getUNID or EntryInfo.getUNID).
validate - Boolean, whether or not to check if the returned URL is valid. In
most cases, use false here since this is a significant performance hit to test
this connection.
Note: With HTTPS, the test might fail even if the connection is, in fact, valid.
Validation does not include an authorization check.
Returns:
A fully-formed URL to the Domino Edit action for the specified document (or
null if validate specified as true and the test connection failed).
EntryInfo
The EntryInfo encapsulates an entry in a calendar. To retrieve entries for a
specific day in the calendar, first use ViewInfo.getCalendarDayInfo() to get a
CalendarDayInfo for the day, and then use CalendarDayInfo.getEntryInfo() to get
the set of entries (EntryInfos) for the day.
򐂰 getUNID
public java.lang.String getUNID()
Returns the universal ID of the document associated with this entry.
Appendix A. Collaborative Components: classes/methods
145
򐂰 getIconName
public java.lang.String getIconName()
Returns the name of the gif image that should be displayed with this entry.
򐂰 getValues
public java.lang.String[] getValues()
Returns a String array representing the values for the entry. Note that most,
but not all, calendar database designs return the values in the following
format:
(0)date (always format "yyyy-MM-dd")
(1)icon
(2)starttime
(3)separator
(4)endtime
(5)description
򐂰 getSummary
public java.lang.String getSummary()
This method is provided for convenient formatting of the values returned by
getValues. Note that this method currently only supports the format
MM/dd/yy.
򐂰 getAlt
public java.lang.String getAlt()
This method is provided for convenient formatting of a bubble help String for a
calendar entry. Note that this method currently only supports the format
MM/dd/yyyy hh:mm:s a.
PeopleService
PeopleService is an aggregation of all the information which Collaborative
Components can retrieve about a person. This object currently uses
DominoService and DiscoveryServerService. The difference between this
service and the person tag (people.tld) is that this service is for programmatic
access to the person information, whereas the person tag is a ready-made
component for UI. Refer to the Overview section in this javadoc for more details
about the person tag.
򐂰 init
146
WebSphere Portal 4.12 Collaboration Services
public void init(CSCredentials cred,
java.lang.String server,
java.lang.String protocol)
Do not call the init() method; init is called internally by CSFactory as part of
the getService.
Specified by:
init in interface CSBaseService
򐂰 cleanup
public void cleanup()
Always call the cleanup() method when finished with the Service object.
Specified by:
cleanup in interface CSBaseService
򐂰 getPersonInfo
public java.util.HashMap getPersonInfo(java.lang.String person)
Returns information about a specified person.
Parameters:
person - String, name of the person (accepts common name or distinguished
name format).
Returns:
HashMap. Keys are PeopleService.CS_PERSON_FULLNAME,
PeopleService.CS_PERSON_EMAIL,
PeopleService.CS_PERSON_DOMINONAME,
PeopleService.CS_PERSON_DOMINOMAILSERVER,
PeopleService.CS_PERSON_DOMINOMAILFILE,
PeopleService.CS_PERSON_DEPARTMENT,
PeopleService.CS_PERSON_JOBTITLE,
PeopleService.CS_PERSON_LOCATION,
PeopleService.CS_PERSON_PROFILEURL,
PeopleService.CS_PERSON_SUMMARY.
QPService
An instance of class QPService creates one to many QuickPlaces on a specific
server.
Appendix A. Collaborative Components: classes/methods
147
򐂰 init
public void init(CSCredentials cred,
java.lang.String server,
java.lang.String protocol)
Do not call the init() method; init is called internally by CSFactory as part of
the getService.
Specified by:
init in interface CSBaseService
򐂰 cleanup
public void cleanup()
Always call the cleanup() method when finished with the Service object.
Specified by:
cleanup in interface CSBaseService
򐂰 create
public java.lang.String create(java.util.Hashtable ht)
Creates a QuickPlace on the remote server, and returns the URL that
references it. This method uses just one parameter, a Hashtable, which holds
parameter names and values. Only one parameter is required: QPName. You
may add the following parameters to the Hashtable before each call. Add the
attributes via the put and get methods. Example:
qpObject.put("GroupManagerName","My Manager Name Group").
QPName (required) - String name of QuickPlace. Must be a legal QuickPlace
name.
QPTemplate (optional) - String name of the QuickPlace template that should
be used to create the QuickPlace.
QPDir (optional) - String directory to create the QuickPlace. Must be a legal
file directory name. If null, then QPName is used to make a valid directory
name.
GroupManagerName (optional) - String name of LDAP group that the
QuickPlace will use for Manager access .
GroupAuthorName (optional) - String name of LDAP group that the
QuickPlace will use for Author access.
GroupMemberName (optional) - String name of LDAP group that the
QuickPlace will use for Member access.
Parameters:
ht - Hashtable with parameters listed above.
148
WebSphere Portal 4.12 Collaboration Services
Returns:
String URL to the new QuickPlace.
RowInfo
RowInfo contains information about the rows in a Domino view (non-Calendar
view). To create a RowInfo object, use DominoService.getViewInfo() to first
create a ViewInfo, and then use ViewInfo.getRowInfo(). Note that the information
returned is ready-made for presentation (for example, hidden and response
column data does not have to be considered specially).
򐂰 getUNID
public java.lang.String getUNID()
Returns the universal ID of the document associated with this row.
򐂰 useTwistie
public boolean useTwistie()
Returns whether or not the document is a parent document and, therefore,
should be presented with a twistie next to it.
򐂰 getIndentLevel
public int getIndentLevel()
Returns the zero-based index level of the row (relevant in hierarchical or
categorized views only).
򐂰 getPositionString
public java.lang.String getPositionString()
Returns the position String for the row. This information is relevant when
implementing paging and requesting groups of rows through
ViewInfo.getRowInfo.
򐂰 getValues
public java.lang.String[] getValues()
Returns a String array representing the column values for the row. Note that
the information returned is ready-made for presentation (for example, hidden
and response columns do not have to be considered specially).
ViewInfo
A ViewInfo object is the first object to create in order to retrieve data from a
Domino view (for all types of views, including calendar views). A ViewInfo object
Appendix A. Collaborative Components: classes/methods
149
contains information about a Domino view, including view columns, rows,
categories, and calendar days (where appropriate). To create a ViewInfo object,
use DominoService.getViewInfo() with the names of the database and view
specified.
For example:
ViewInfo vi = ds.getViewInfo("testmail.nsf", "($all)");
where ds is a DominoService object.
򐂰 getVersion
public int getVersion()
Returns the Domino version (simplified) of the data source server.
Returns:
A constant indicating the Domino version range of the data source server. For
servers running 4.6, ViewInfo.DOMINO_46 is returned. For servers running
R5.0 and up, ViewInfo.DOMINO_5PLUS is returned. When the version of the
server cannot be determined (typically due to invalid credentials), getVersion
returns 0.
򐂰 getProtocol
public java.lang.String getProtocol()
Returns http or https, depending on whether SSL is enabled for the data
source.
򐂰 getViewCategories
public java.lang.String[] getViewCategories()
Returns the list of categories in a specified view. Returns the top level
categories only.
򐂰 isCalendarView
public int isCalendarView()
Returns 1 if the view is a calendar view, 0 if the view is not a calendar view,
and -1 if this information cannot be determined.
򐂰 getColumnInfo
public ColumnInfo[] getColumnInfo()
Returns column information about a view, encapsulated in an array of objects
of type ColumnInfo.
򐂰 getRowInfo
public RowInfo[] getRowInfo(java.lang.String startPosition,
int count)
150
WebSphere Portal 4.12 Collaboration Services
Returns row information about a view, encapsulated in an array of objects of
type RowInfo. To display the first page of rows, use startPosition 1. To display
the next page of rows, determine the position of the last row on the current
page (using RowInfo.getStartPosition) and use that startPosition.
Note that this “overlaps” the read by one row (be careful to trim off this
duplicate row from the RowInfo[] set when displaying). To determine when
you have reached the last page of row data, check to see if RowInfo.length
retrieved is less than the count specified.
Note: It is invalid to specify a starting row position that does not exist in the
view. This is the basis of the requirement that you overlap the view reads.
Parameters:
startPosition - the position in the view to start from.
count - the number of rows to return.
򐂰 getCalendarDayInfo
public CalendarDayInfo[] getCalendarDayInfo(java.lang.String ISOdate,
int grid)
Returns the calendar data, for a specified period of time, relative to a
specified ISO standard (yyyy-mm-dd) date. The information returned for the
time periods starting with ViewInfo.ONE_WEEK (and greater) start with the
preceding Monday and end with a Sunday. So if you ask for a Wednesday, for
example, 2002-04-17, with a grid of ViewInfo.TWO_WEEKS, the information
returned with be from 2002-04-15 (the Monday) through the following Sunday,
2002-04-28.
Parameters:
ISOdate - the start date, in the ISO standard format, yyyy-mm-dd. The default
is today's date (use null).
grid - amount of days to return: ViewInfo.ONE_DAY, ViewInfo.TWO_DAYS,
ViewInfo.ONE_WEEK, ViewInfo.TWO_WEEKS, or ViewInfo.ONE_MONTH. If
a value other than these is used, the default is ViewInfo.ONE_WEEK.
Note: Use these ViewInfo constants (rather than 1, 2, 7, etc.).
Appendix A. Collaborative Components: classes/methods
151
152
WebSphere Portal 4.12 Collaboration Services
B
Appendix B.
Collaborative Components:
tag libraries
© Copyright IBM Corp. 2002. All rights reserved.
153
People Service tags
The People Service tags generate a link menu allowing users to send e-mail to a
named person. On Sametime-enabled systems, they provide online status, as
well as the ability to chat and share applications.
On Discovery Server-enabled systems, they provide the ability to show the
expertise profile and to find documents authored by the named person.
To use these tags within your JSP, add the following lines to your page:
<%@taglib uri="/WEB-INF/tld/people.tld" prefix="peopleservice" %>
<%@taglib uri="/WEB-INF/tld/menu.tld" prefix="menu" %>
Note that the people tags have a dependency on the menu tags.
The following tags are available:
򐂰 person
Use this tag around each name to enable collaboration.
Example:
<peopleservice:person>
Jonathan Harris
</peopleservice:person>
򐂰 peopleinit
Initializes the people tag functionality. Do not use this function inside a portlet
as WebSphere Portal Server provides initialization and finalization for these
tags.
򐂰 peopleend
Finalizes the people tag functionality. Do not use this function inside a portlet.
154
WebSphere Portal 4.12 Collaboration Services
Menu Library tags
These tags allow developers to add pop-up menus to their Collaborative
Components applications. The menu is a Java applet.
To use these tags within your JSP, add the following line to your page.
<%@taglib uri="/WEB-INF/tld/menu.tld" prefix="menu" %>
The following tags are available:
򐂰 menuinit
Initializes the menu tag functionality. Do not use this function inside a portlet,
because the WebSphere Portal Server provides initialization for these tags.
Attributes: none
򐂰 menucontext
Begins the definition of one or more menus under a common context name.
Attributes:
– contextName
The name for this menu context. The contextName parameter must be
unique per portlet.
򐂰 menu
Defines a menu. The tag must be nested within a menucontext tag.
Attributes:
– menuName
The name of the menu. This attribute must be unique with a menu context.
Pass this name to menudisplay to activate a menu.
– menuID
The ID of a menu. This attribute must be unique within a portal.
򐂰 menuitem
Defines a menu item and its name, as well as the associated JavaScript
callback function.
Attributes:
– itemName
The text label for this selection in the menu.
– callbackFn
Appendix B. Collaborative Components: tag libraries
155
Specifies the JavaScript function to call when a user selects this menu
item.
– enable (optional)
A boolean value that determines whether this menu item is enabled or
greyed out. By specifying a JavaScript function instead of true or false,
you can enable or disable the menu item dynamically through JavaScript.
– show (optional)
A boolean value which determines whether this menu item will be shown
in the menu. Possible values are “true” and “false”. WebSphere evaluates
this option during page generation. You cannot modify this value
dynamically with JavaScript.
򐂰 menudisplay
Activates and displays the specified menu. You can optionally pass
parameters, which are then available to JavaScript functions as <context
name>.<parameter name>.
Attributes:
– contextName
Specifies the name of the menucontext tag that contains the menu.
– menuName
Specifies the name of the menu.
– paramName (optional)
Specifies the name of a parameter placed in the JavaScript environment.
You must specify a paramValue attribute to define the value for this
parameter.
– paramValue (optional)
Sets the value of a parameter. This tag must follow a paramName attribute
to specify the name of a parameter.
156
WebSphere Portal 4.12 Collaboration Services
C
Appendix C.
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/REDP0319
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 redbook form number, REDP0319.
Using the Web material
The additional Web material that accompanies this Redpaper includes the
following files:
File name
collabportletsamples.zip
© Copyright IBM Corp. 2002. All rights reserved.
Description
Zipped Portlet Samples
157
158
WebSphere Portal 4.12 Collaboration Services
Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the various topics covered in this Redpaper.
Related IBM Redbooks/Redpapers
򐂰 WebSphere Portal V4.1 Windows 2000 Installation, REDP3593
򐂰 WebSphere Portal V4.1 AIX 5L Installation, REDP3594
򐂰 WebSphere Portal V4.12 in a Linux Environment, REDP0310
򐂰 WebSphere 4.0 Advanced Scalability and Availability, SG24-6192
򐂰 WebSphere 4.0 Commerce Suite Handbook, SG24-6167
򐂰 Working with the Sametime Client Toolkits, SG24-6666
򐂰 Domino and WebSphere Together Second Edition, SG24-5955
򐂰 Enterprise Business Portals with IBM Tivoli Access Manager, SG24-6556
For information on ordering these publications, see “How to get IBM Redbooks”
on page 160.
Product documentation
򐂰 WebSphere Portal Library
A consolidated list of all product documentation, and other Portal-related
documentation sources.
http://www-3.ibm.com/software/webservers/portal/library.html.
򐂰 WebSphere Portal Infocenter
The InfoCenter is the main location for all product documentation, such as
installation instructions, usage instructions, troubleshooting, etc.
http://www7b.software.ibm.com/wsdd/zones/portal/V41InfoCenter/
򐂰 WebSphere Portlet API JavaDocs
Contains the Java documentation for the general portlet API
classes/methods/etc.
http://www7b.software.ibm.com/wsdd/zones/portal/portlet/4.1api/l
© Copyright IBM Corp. 2002. All rights reserved.
159
Note: The JavaDocs for the Collaborative Components API are not available
online. They can be viewed after installation as described in 2.7.1, “Key files”
on page 36.
Referenced Web sites
These Web sites are also relevant as further information sources:
򐂰 IBM WebSphere Portal Zone
Technical information for developers and administrators of WebSphere Portal
http://www7b.software.ibm.com/wsdd/zones/portal/
򐂰 IBM WebSphere Developer Domain
Technical information for developers and administrators of general
WebSphere applications
http://www7b.boulder.ibm.com/wsdd/
򐂰 Lotus Developer Domain
Technical information for developers and administrators of Lotus advanced
collaboration technologies
http://www.lotus.com/ldd
How to get IBM Redbooks
You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks
You can also download additional materials (code samples or diskette/CD-ROM
images) from that site.
IBM Redbooks collections
Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.
160
WebSphere Portal 4.12 Collaboration Services
Back cover
WebSphere Portal 4.12
Collaboration Services
Hints and Tips for
performing a
successful
installation
Use of the
Collaborative
Components API and
tags
Sample collaborative
portlets
The WebSphere Portal Family consists of three packaged
offerings: the Portal Enable offering is the base offering; Portal
Extend and Portal Experience add more functionality.
WebSphere Portal Extend allows your portal users to act on
information and applications via collaboration with other
portal users.
This Redpaper discusses the collaborative capabilities
included in the WebSphere Portal Extend v4.12 offering. It
covers an introduction to the WebSphere Portal Family and
the concept of Collaborative Portlets; installation and
deployment-oriented topics for getting a Collaborative Portal
Extend environment up and running; details about the
Collaborative Portlets available out-of-the-box with Portal
Extend; and best practices for the use of the Collaborative
Components API available with Portal Extend, including
several sample Collaborative Portlets that leverage this API.
This Redpaper is primarily intended for technologists involved
with collaborative WebSphere Portal projects. However, the
introductory content in each chapter may be useful to
managers who are responsible for such projects.
®
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