Front cover
Building a Component for
IBM Workplace
Get a solid overview of IBM Lotus
Workplace
Use Lotus Workplace Application
Development
Develop and use example
applications
Philip Monson
Jane Clark
Kalle Mikkolainen
Sami Shalabi
ibm.com/redbooks
Redpaper
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
The team that wrote this Redpaper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Chapter 1. Overview of Lotus Workplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Lotus Workplace terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 What is IBM Workplace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 IBM Workplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.2 The business value of IBM Workplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.3 The product families of IBM Workplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Introduction to Lotus Workplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.1 Lotus Workplace products and features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 How does WebSphere Portal fit? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.1 How do Lotus Notes and Domino fit? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5 IBM Workplace Client Technology and IBM Workplace . . . . . . . . . . . . . . . . . . . . . . . . 12
1.6 Developing applications: Opportunities for Business Partners and ISVs . . . . . . . . . . . 13
Chapter 2. Lotus Workplace Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . .
2.1 Architectural overview of Lotus Workplace 2.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.1 Lotus Workplace JVMs and containers: Opportunities for ISVs . . . . . . . . . . . . . .
2.1.2 Infrastructure Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Defining the Lotus Workplace Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.2 Configuring Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.3 Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.4 Accessing templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.5 Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.6 Required components for templates and applications . . . . . . . . . . . . . . . . . . . . .
2.2.7 Lotus Workplace Application development roles . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Lotus Workplace application development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Lotus Workplace Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.2 Lotus Workplace API Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.3 Lotus Workplace Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Using Lotus Workplace Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.1 Create a new Workplace Application Template . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.2 Editing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.3 Reusing the application to create new applications . . . . . . . . . . . . . . . . . . . . . . .
2.4.4 Adding portlets, themes and skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
16
16
17
19
19
21
21
22
22
22
23
23
24
24
24
24
26
33
33
33
35
Chapter 3. Introduction to application development in Lotus Workplace . . . . . . . . . .
3.1 Technologies for developing Lotus Workplace applications . . . . . . . . . . . . . . . . . . . . .
3.1.1 What is a portlet? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 Portal configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.3 Introduction to portlet communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
38
38
38
39
© Copyright IBM Corp. 2005. All rights reserved.
iii
iv
3.1.4 Communicating with Click-to-Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.5 Cooperative portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.6 WebSphere Portal Portlet API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.7 JSR168 Portlet API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.8 IBM Portlet Wiring Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.9 Struts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.10 Java Server Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Working with the Lotus Workplace API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Lotus Workplace APIs Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Collaborative Application Component Interfaces . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Component Services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.4 Application Infrastructure Services API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5 Workplace Mail Messaging SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.6 Lotus Workplace Instant Messaging SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.7 Lotus Workplace JSP tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Domino integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Adding Workplace Portlets to Domino Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Domino Integration using Lotus Workplace JSP tags . . . . . . . . . . . . . . . . . . . . . .
3.3.3 The portalizing process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.4 When to use a specific integration approach . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
39
40
41
41
41
42
42
43
44
45
46
48
48
49
49
50
51
51
51
51
53
Chapter 4. Building a Component for IBM Workplace . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Overview of the Domino Discussion Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 Building the Domino Discussion Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.1 Setting up the development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.2 Configuring the Lotus Workplace API Toolkit in WSAD . . . . . . . . . . . . . . . . . . . .
4.3.3 Building the Domino Discussion Collaborative Component EJB . . . . . . . . . . . . .
4.3.4 Building the Domino Discussion Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.5 Connecting the Portlet to the EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.6 Naming the Domino Component EAR file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.7 Removing unused code from the sample component. . . . . . . . . . . . . . . . . . . . . .
4.3.8 Generating the Installable Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Building the Domino Discussion Application Template . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.1 Setting up the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.2 Installing the Domino Discussion Component into Lotus Workplace . . . . . . . . . .
4.4.3 Building the Domino Discussion Application Template . . . . . . . . . . . . . . . . . . . . .
4.4.4 Building the Domino Discussion Application Template . . . . . . . . . . . . . . . . . . . . .
4.4.5 Creating an application using the Domino Discussion Application Template . . . .
4.4.6 Add members to the new application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5 Installing the Domino Discussion Component into WebSphere Studio. . . . . . . . . . . . .
4.6 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
55
56
56
57
58
58
59
71
72
73
73
73
74
74
75
76
77
80
81
82
83
Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
85
85
85
85
Building a Component for IBM Workplace
Preface
This IBM Redpaper provides an overview of the Lotus® Workplace™ platform architecture,
discusses application development technologies, and gives an introduction to developing
applications in Lotus Workplace. The final chapter gives an example of how to build a
collaborative component for Lotus Workplace using the API toolkit.
The target audience for this IBM Redpaper includes independent software vendors (ISVs),
application developers and others who would like to understand the Workplace platform.
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, Poughkeepsie Center.
Philip Monson is a Project Leader at the ITSO Lotus Center in Cambridge MA. Phil has been
with Lotus and IBM for 14 years, joining the company when the early versions of Lotus
Notes® were rolled out for internal use. He has served in management, technical, and
consulting roles in the IT, Sales and Development organizations.
Jane Clark is a Software Engineer in the Lotus Workplace ISV Technical Enablement Team,
based in North Reading, Massachusetts. Jane's team has responsibility for helping Lotus
Workplace ISVs and Corporate Developers develop applications that extend the Lotus
Workplace platform. Jane joined IBM in 2003 following the acquisition of Aptrix by IBM and
has 14 years experience in software development, technical training, business process
re-engineering and consulting using IBM and Lotus products, including 12 years with
IBM/Lotus Business Partners in Australia and the United States.
Kalle Mikkolainen is an IBM Software group consultant in Software Services for Lotus based
in Helsinki Finland. Kalle has over 10 years experience as a Lotus Notes and Domino®
application developer and previous experience as a software designer at the Finnish
industrial company Metso. Kalle has been with IBM for four years and has been doing Lotus
Workplace 2.0.1 proof of concepts for his customers.
Sami Shalabi is a Senior Software Engineer on the Lotus Workplace Server Team based in
Westford, Massachusetts. Sami is the lead architect of the collaborative application
infrastructure and has been with Lotus/IBM for seven years. Previous to Lotus Workplace,
Sami worked on both Lotus QuickPlace® and Lotus Domino. Sami holds both a Bachelor of
Science and Masters of Engineering in Electrical Engineering and Computer Science from
MIT.
© Copyright IBM Corp. 2005. All rights reserved.
vii
Thanks to the following people for their contributions to this project:
Mustansir Banatwala, Senior Software Engineer Lotus Workplace
Edward Basiul, Advisory Software Engineer
Miguel Estrada, Senior Technical Staff Member Lotus Workplace
Jaye Fitzgerald, Advisory Software Engineer, Application Infrastructure
Hardy Groeger, Senior Software Engineer
Christopher Karle, Advisory Software Engineer
Fernando Salazar, Senior Technical Staff Member
Dave Schlesinger, Lotus Workplace API Architect
Ajamu Wesley, Senior Technical Staff Member
Westford, MA
IBM US
Mike Lowry, Lotus CTO Office, Lotus Technology Advocate
Margaret O’Connell, Architect, Application Templating
Chris Reckling, Senior Product Manager, Lotus Workplace Application Development
Cambridge, MA
IBM US
Stanley Dunne, Software Architect
Mel Gorman, Lotus Workplace Developer.
Mulhuddart
IBM Ireland
Ralf Heindoerfer, Architect, Lotus Workplace Builder
Paderborn
IBM Germany
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
viii
Building a Component for IBM Workplace
Comments welcome
Your comments are important to us!
We want our papers to be as helpful as possible. Send us your comments about this
Redpaper or other Redbooks™ in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an email to:
redbook@us.ibm.com
򐂰 Mail your comments to:
IBM® Corporation, International Technical Support Organization
Dept. HYJ Mail Station P099
2455 South Road
Poughkeepsie, New York 12601-5400
Preface
ix
x
Building a Component for IBM Workplace
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. 2005. All rights reserved.
v
This document created or updated on March 21, 2005.
®
Send us your comments in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an email to:
redbook@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYJ Mail Station P099
2455 South Road
Poughkeepsie, New York 12601-5400 U.S.A.
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Cloudscape™
DB2®
Domino®
Eserver®
Eserver®
eServer™
Eserver™
Everyplace®
ibm.com®
IBM®
Lotus Notes®
Lotus®
Notes®
QuickPlace®
Rational®
Redbooks (logo)
Redbooks™
WebSphere®
™
Workplace™
Workplace Client Technology™
Workplace Collaborative Learning™
Workplace Messaging™
Workplace Team Collaboration™
Workplace Web Content
Management™
The following terms are trademarks of other companies:
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.
vi
Building a Component for IBM Workplace
1
Chapter 1.
Overview of Lotus Workplace
This IBM Redpaper provides an overview of the Lotus Workplace1 platform architecture,
discusses available application development technologies, and gives an introduction
developing applications. The final chapter highlights an example of how to build a component
for Lotus Workplace using the API toolkit.
In this chapter, we introduce the key concepts and technical considerations which apply to
developing applications with Lotus Workplace. This chapter provides an overview of key
issues such as:
򐂰
򐂰
򐂰
򐂰
򐂰
What is IBM Lotus Workplace?
How does WebSphere Portal fit?
How does Lotus Domino fit?
What is IBM Workplace Client Technology™ and how does it fit?
What is the value of developing applications for IBM Lotus Workplace?
1
This document discusses Lotus Workplace 2.0.1 products. Subsequent releases of these products will be
packaged together using the name IBM Workplace Collaboration Services.
© Copyright IBM Corp. 2005. All rights reserved.
1
1.1 Lotus Workplace terminology
This section defines important terminology we use in this paper.
򐂰 Enterprise Java™ Beans (EJBs) technology is the server-side component architecture for
Java 2 Platform, Enterprise Edition (J2EE). EJB technology enables rapid and simplified
development of distributed, transactional, secure and portable applications based on Java
technology.
򐂰 A Software Development Kit (SDK) is a tool set for developing applications in a particular
computer language or environment.
򐂰 An Application Program Interface (API) allows an application to work with an operating
system or with another program.
򐂰 A Service Provider Interface (SPI) is a common interface used to achieve compatibility
between Microsoft® Windows® applications.
򐂰 A Line of business (LOB) is any one particular business activity, such as accounting or
sales.
򐂰 Click to Action (C2A) is the framework that facilitates the exchange of compatible data
between portlets.
򐂰 Web Services Description Language (WSDL) is a new specification which describes
networked XML-based services.
򐂰 Service Data Objects (SDO) are designed to simplify and unify the way in which applications
handle data. Using SDO, application programmers can uniformly access and manipulate
data from heterogeneous data sources, including relational databases, XML data sources,
Web services, and enterprise information systems. SDO is defined in Java Specification
Requests 235 (JSR 235): Service Data Objects.
򐂰 IBM WebSphere Studio Application Developer is a comprehensive integrated
development environment for visually designing, constructing, testing and deploying Web
services, portals and Java™ 2 Enterprise Edition (J2EE) applications. WebSphere Studio
Application Developer accelerates J2EE development with a complete set of high
productivity tools, templates and wizards. For further information see:
http://www-306.ibm.com/software/awdtools/studioappdev/
򐂰 A Workplace Template is an XML file that defines a set of instructions for instantiating an
IBM Workplace Application
򐂰 A Workplace Application is a collection of portal pages that can be provisioned with portlets
and Workplace components.
򐂰 A Workplace Application Category is where similar Workplace applications are cataloged.
Each application resides in a category.
򐂰 A Workplace component is the unit of function that can be added and removed from a
Workplace application. It is represented by a portlet and Collaborative Component EJB.
򐂰 A Collaborative Component EJB is an EJB that implements the Collaborative Component
APIs. It provides APIs for manipulating an object of a given type.
򐂰 Membership is a group of people with specified roles in a given Workplace application.
򐂰 Workplace Component Parameters are variables that are requested at instanitation time by a
Workplace Component. For example a document library component may ask how often it
needs to archive content.
򐂰 The Workplace Application Properties define general information such as the name,
category, and owner of the Workplace application.
2
Building a Component for IBM Workplace
򐂰 A Java Archive (JAR) file is a platform-independent file format that permits many files to be
aggregated into one file.
򐂰 A Web Archive (WAR) file is a JAR archive that contains a J2EE Web module.
򐂰 An Enterprise Application archive (EAR) is a JAR archive that contains a J2EE application.
򐂰 A Portlet is a Java-based Web component, managed by a portlet container, that processes
requests and generates dynamic content.
1.2 What is IBM Workplace?
Before we can discuss the fundamentals of application development within Lotus Workplace,
we need to ensure a common understanding of IBM Workplace and its family of products. In
particular, we want to also clarify the role of WebSphere Portal, Domino and Lotus Workplace
within the greater IBM Workplace vision. It is also useful to talk about the evolution of Web
application servers and understand how Lotus Workplace was conceived.
In the mid-1990s, IBM consultants were working on client engagements to build Web
applications using HTML pages and CGI scripts. Over a period of time, these engagements
identified a number of services and capabilities that are common to creating Web
applications. It was the formalization of these patterns that led to the development of
WebSphere Application Server by IBM.
Also in the mid-to-late 1990s, a key requirement for clients was the ability to leverage their
investment in existing applications through their Web applications. There was a proliferation
of client engagements where consultants created custom-built portals. Following the creation
of WebSphere Application Server, developers were able to use the tools provided with that
product to more quickly built portals for their customers.
A series of proven, reusable patterns developed, identifying common characteristics of portal
applications and accelerating the application development process. These patterns formed
the basis for the new IBM WebSphere Portal product. WebSphere Portal works by combining
small applications, called portlets, into a unified display. It delivers a highly personalized
experience, which can be controlled centrally by setting access rights to the page and ports.
An important concept is that the page is defined independently of the portlets, so changes in
the details of the application do not affect the overall display or the management of the portal
Web site. WebSphere Portal provides application integration, collaboration, single sign-on
services and much mortality portals serve as unified access points to a collection of
applications over the Web to a broad variety of client devices. They provide a secure and
scalable environment that can be extended easily. For additional details, refer to 1.4, “How
does WebSphere Portal fit?” on page 10.
Over time, collaboration was added to these portal applications and they evolved into
dynamic workplaces. These collaboration elements complemented the portal environment to
provide simplified access to people, information and collaborative business processes. Again
a set of a series of reusable patterns developed that identified common characteristics of
these dynamic workplaces. Those patterns formed the basis for the creation of Lotus
Workplace.
Chapter 1. Overview of Lotus Workplace
3
Figure 1-1 The evolution of Lotus Workplace
1.2.1 IBM Workplace
IBM Workplace represents a vision of specific products and technologies, making more
people more productive in everyday business. IBM Workplace represents the front-end of
computing. It is made up of new and existing products that enable people to easily connect to
the information, applications and business processes they need, when they need them
through a wide spectrum of access points, from enterprise desktops to pervasive computing
devices.
IBM Workplace is comprised of new and existing products and technology including Lotus
Notes and Domino, WebSphere Portal, Lotus Workplace, WebSphere Everyplace®,
Workplace Client Technology, and provides high-performance, roles-based workplaces
provisioned for users. Even more, IBM Workplace uniquely combines the productivity gains of
the desktop with the cost advantages of the network.
Some tasks a typical user might perform in the course of a day are:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Talk to colleagues one-on-one or in meetings.
Write, find and share documents.
Execute actions to advance a business process.
Seek quick answers to questions.
Contribute to a team project.
Look up personal benefits information.
Learn about a new company initiative.
This user could do all the above without ever leaving his IBM Workplace or opening and
closing different applications. Entering his Workplace user interface (UI) with a single sign-on,
the user would have immediate access through the UI portlets to:
– The application supporting his business process
– The company's intranet, with a human resources section for benefits information and
an e-learning knowledge repository to get up to speed on the new initiative
4
Building a Component for IBM Workplace
– E-mail, instant messaging, group calendaring and scheduling, Web conferencing,
employee locator, and team project workspaces for communicating, meeting, and
interacting with colleagues
– Document management, built-in editors and other productivity tools for creating,
accessing, and sharing documents.
The vision of IBM Workplace is being able to use whatever access point you choose
throughout the day to interact with colleagues and find the information and business
applications you need when and where you need them. Whatever your mode of access, you
can see your online work environments through a consistent user interface. In addition to
employees, external constituents such as business partners, suppliers or customers can also
be connected to information sources and business processes appropriate to their roles.
This online environment is tailored to the user and based on role. With all required resources
at hand and presented within the business context, you can conveniently stay in this
environment to do all facets of your work throughout the day. Synchronization services enable
you to continue accessing your workplaces even when disconnected from the network. This
means you can access the same resources in the office, at a customer site, or in a car or
plane. You can also access your workplace through server-managed clients of choice,
whether a Web browser, a rich client, or a mobile device.
1.2.2 The business value of IBM Workplace
Organizations will adopt the IBM Workplace model in different configurations to serve
particular sets of objectives, but all will benefit from the advantages inherent in the model
itself. These advantages are:
򐂰 Server-managed client
The server-managed client model, which enables applications to be extended to a full
spectrum of client types that are deployed and managed from the server, allows
applications to more easily follow a user across their day, whether the user is working from
a disconnected mobile computer using a managed rich client, a connected workstation
with a browser, or a mobile client with a sometime-connected mobile device. Server
managed control of the user environment ensures that everyone has the latest
applications and upgrades in a timely fashion.
򐂰 Flexibility and choice
The standards-based flexibility and choice inherent in the IBM Workplace family of
capabilities supports both preservation of existing investments and future extensibility. The
IBM Workplace model adapts to the client's IT strategy by offering flexibility across
operating systems, clients, document editors, and applications. The Linux®, Windows and
MacOS environments are supported. This flexibility facilitates streamlining business
processes incorporating customers, partners, and suppliers and allows the IT
infrastructure to grow and change with evolving needs of the business.
򐂰 Open standards support
Interoperability is achieved by the open standards approach, which enables easier and
more effective integration with customers' existing IT investments. The extensible client
platform permits extending the value of existing Web, Java, .Net. C++ and Notes
applications, developing new applications, leveraging existing investments such as Office
documents and Java.Net and C++ applications, and integrating processes across the
enterprise.
򐂰 Security
Robust policy-managed access and control with built-in data management and security
features protect your organization's information assets. Applications using IBM Workplace
Chapter 1. Overview of Lotus Workplace
5
Client Technology benefit from local and server-managed encrypted data stores. The local
data store can synchronize with the server, allowing for policies and ACLs to be applied.
When documents are moved to the data store, they are more secure than if left on the file
server, where they are vulnerable to attack.
򐂰 Total Cost of Ownership
Simplification and server-managed control of the user environment, with no touch
deployment, administration and client updates, radically reduces the costs of managing
the environment. Standards-based interoperability with existing IT investments preserves
their value and eliminates the costs of forced rip-and-replace requirements. Giving
capabilities to users on demand and based on role, rather than cookie-cutter,
one-size-fits-all provisioning further helps to lower the total cost of ownership.
򐂰 Productivity and responsiveness
The IBM Workplace model helps your company be more productive in the business your
end users do everyday by giving them anytime and anywhere access to everything they
need to perform their jobs. With the simplified UI, end users have:
–
–
–
–
Easy access to applications, business processes and documents
Capabilities by component immediately available based on the user’s role
A new, rich user experience for Web-based applications
Use of documents and programs even when disconnected from the network and
synchronization of applications and data when signed on to the network
The cumulative effect is increased organizational productivity, efficiency, and
responsiveness.
1.2.3 The product families of IBM Workplace
The versatile, componentized capabilities available for assembling an IBM Workplace are
drawn from product families from IBM Software Group, all based on a common technology
platform.
򐂰 Lotus Workplace
Lotus Workplace is a family of integrated, Web-based collaborative products providing a
single, role-based interface to the collaboration tool a user needs.
򐂰 IBM WebSphere Portal
IBM WebSphere Portal offers integrated access to information, applications, and business
processes across the organization in a single role based interface
򐂰 Lotus Notes and Domino
Lotus Notes and Domino is a family of messaging and collaboration products, including
applications, that can be integrated into a business environment.
򐂰 IBM Workplace Client Technology
IBM Workplace Client Technology is available in two versions:
– Micro Edition 5.7
Micro Edition 5.7 offers mobile products and technologies for extending applications
and information to users working on devices such as PDAs or cell phones.
– Rich Edition
The Rich Edition enables development of applications that combine the benefits of a
rich user experience with the ease of deployment and manageability of browser-based
applications.
6
Building a Component for IBM Workplace
1.3 Introduction to Lotus Workplace
Lotus Workplace is an integrated family of collaborative products based on open standards.
Lotus Workplace offers flexible, server-managed client choices to deliver the right capability
to different users in a secure, dynamic work environment. Collaborative capabilities such as
sending e-mail, scheduling calendar events, attending training courses, exchanging instant
messages and having discussions, creating and managing shared documents, holding Web
conferences, and creating new IBM Workplace applications are integrated into a single user
experience. Lotus Workplace capabilities can be activated, administered, and provisioned
from a single location, simplifying management of the collaboration infrastructure.
Lotus Workplace employs a standards-based platform delivered on top of the WebSphere
and J2EE infrastructure. The base includes WebSphere Application Server, WebSphere
Portal, WebSphere Member Manager, IBM Directory Server (one of many LDAP options),
and a relational data store provided by IBM DB2®, Oracle or Cloudscape™.
With its J2EE platform, Lotus Workplace makes it easy for information technology
departments to deploy and manage because it leverages a central administration,
deployment and provisioning model. All collaborative capabilities can be easily activated and
controlled from a single point of administration, even as new Workplace products are
installed. When more capabilities are added, these can be displayed and managed within the
same Workplace. as in Figure 1-2.
Figure 1-2 Lotus Workplace: An integrated family of collaborative products
Chapter 1. Overview of Lotus Workplace
7
1.3.1 Lotus Workplace products and features
Lotus Workplace consists of the following sets of integrated products:
IBM Workplace Team Collaboration™
With IBM Workplace Team Collaboration users participate in online meetings, create libraries,
and interact with team members through online chats, threaded discussion forums, and
document sharing.
IBM Workplace Team Collaboration includes the following components:
򐂰 In Team Spaces, members participate in discussions and chats, share documents along
with a team calendar, and search for project information.
򐂰 With Web Conferences, moderators make online presentations to conference participants.
򐂰 With Applications, users access Workplace applications, HTML-enabled Domino
applications, and applications assembled from templates created or customized in
Workplace Builder.
򐂰 From the Documents online document libraries, users can create and maintain a list of
favorite document libraries.
򐂰 With Workplace Builder, IT departments can create and manage templates for
assembling Workplace applications and for editing existing Workplace applications. Users
can also design and customize forms for Workplace applications.
IBM Workplace Collaborative Learning™
IBM Workplace Collaborative Learning is a scalable, flexible product for managing
classroom-based and online learning activities, resources, curricula, and courseware
catalogs.
IBM Workplace Collaborative Learning includes the following features:
򐂰 Learning student experience provides an easy-to-use interface where students access
courses. Students can search for courses and organize them in personalized folders, as
well as preview, enroll in, and participate in courses online. Information about courses is
stored on the Learning Server, while the courses themselves are presented on the
Delivery Server.
򐂰 Learning management and delivery system components provide an administrative
interface that course developers and instructors can access from the Web to manage
resources, learning programs, and skills development.
򐂰 Authoring Tool lets course developers create course structure and content, assemble
course packages and import them to Lotus Workplace Collaborative Learning servers.
The Authoring Tool is used by course developers at their own workstations.
IBM Workplace Messaging™
IBM Workplace Messaging is a cost-effective, standards-based messaging product that is
security-rich, scalable, and easily deployed. It integrates with an organization's existing
corporate infrastructure and uses the organization's LDAP directory to automatically create,
delete, and authenticate user accounts, resolve addresses, and route mail. Lotus Workplace
Messaging supports a choice of client experiences from a standard browser to a rich client
experience.
IBM’s Workplace Messaging includes the following capabilities:
򐂰 With Mail, users send and receive e-mail messages.
8
Building a Component for IBM Workplace
򐂰 From Calendar and Scheduling, users maintain and manage calendar events and
schedule meetings.
򐂰 With the Personal Address Book, users maintain and manage contact information for
individuals and group mailing lists.
IBM Workplace Documents
IBM Workplace Documents is a program which provides systematic, controlled access to
critical documents. IBM Workplace Documents also provides a fundamental document
management capability that is standards-based and has integrated collaborative capabilities.
IBM Workplace Documents includes the following features:
򐂰 Document library capabilities provide document check-in and check-out, document
locking, and version control.
򐂰 Structured access provides an easy method for setting up library access so that
information needed organization-wide can be viewed easily, but selected information can
be viewed only by a limited audience.
򐂰 Document editors provide the power to modify popular document types, even when native
editors are unavailable.
򐂰 Choice of client experience provides either a browser or rich client experience.
򐂰 Document author, owner, and editor awareness through integrated instant messaging and
chat capabilities.
򐂰 Offline support through the rich client provides a secure method for users to create,
import, edit, and save documents, presentations, and spreadsheets by supporting offline
use and synchronization between local and server stores.
򐂰 Security offers users the ability to store documents outside the file system to increase
protection from viruses and other risks.
IBM Workplace Web Content Management™
IBM Workplace Web Content Management delivers powerful end-to-end Web content
management through multiple Internet, intranet, extranet, and portal sites.
IBM Workplace Web Content Management includes the following features:
򐂰 Content authoring is template-based, with a WYSIWYG rich text editor providing a guided
process that does not require technical skills.
򐂰 Versioning and rollback provides a method for creating multiple content versions that can
be used at different times or restored to previous versions, as needed.
򐂰 Automatic workflow processing ensures that the right people approve Web content before
it is published, assuring accuracy and relevancy of content.
򐂰 Integration of information from various sources allows reuse of information from
back-end systems, improving transactional performance.
򐂰 Personalized delivery lets authors create content once and reuse it on different Web sites
for users with different roles or preferences.
򐂰 Multiple database support gives users the ability to use Domino, DB2, Oracle, or DB2
Content Manager as repositories.
Chapter 1. Overview of Lotus Workplace
9
1.4 How does WebSphere Portal fit?
During the past several years, there has been an increasing demand to integrate disparate
content into a seamless J2EE Web application. J2EE has proven to be a popular platform for
business applications due to the open standards, scalability, flexibility, and open integration
capabilities it provides. The technology and framework of a portal enables developers to build
Web applications capable of aggregating and integrating disparate data. Accordingly, a portal
is defined as a server or set of servers that aggregate content and functionality, while relying
on a scalable infrastructure. See Figure 1-3.
A Portal is about.....
user interface . . .
... and Integration
A UI fram ework for integrating "other"
applications, content and processes.
Includes additional infrastructure like search,
single sign-on, directory management, etc.
P re s e
n ta tio
n
r a t io n
In te g
r
L a ye
r
L a ye
P o r ta
Address
v ic e s
l Ser
r
L a ye
Content
Aggregation
Search
Page
Page
Page
Page
Application
Integration
Portal 2
Portal 4
Portal
1
Team
Collaboration
Portal 3
Portal 6
Figure 1-3 WebSphere Portal integrates applications, content, processes, and people
Along with the need to render multiple streams of data, the application server evolved and
added support for portals, Additionally, most portals are now required to deliver personalized
content along with the possibility to customize the look and feel of the application.
Today portals serve as unified access points to a collection of applications over the Web to a
broad variety of client devices. They provide a secure and scalable environment that can be
extended easily.
A key part of the IBM Workplace strategy, WebSphere Portal integrates applications, content,
processes, and people in a single point of interaction for the user. It provides a simplified,
role-based user environment that allows people to interact with the on demand world in a
personalized way. The user interface enables collaboration in the context of the work at hand.
With a single sign-on, users can quickly access the dynamic information they need, execute
business processes across critical applications, and collaborate with other portal users inside
and outside the organization. See Figure 1-4 on page 11.
10
Building a Component for IBM Workplace
C o m b in in g P o r ta l a n d W o rk p la c e
U I a n d In te g ra tio n
C o n te n t
A g g re g a tio n
C o lla b o ra tiv e c a p a b ilitie s
Doc
M sg
A p p lic a tio n
In te g ra tio n
Te a m
C o lla b
L e a r n in g
C o lla b o ra tio n
M sg
Te a m
C o lla b
D ocum ent
M gm t
L e a rn in g
Te a m
C o lla b o ra tio n
M e s s a g in g
D oc
Figure 1-4 Collaboration elements complement the portal environment to provide new tools
1.4.1 How do Lotus Notes and Domino fit?
The Lotus Notes and Domino family of collaboration products provide the individual
collaboration components of an IBM Workplace. These products continue to provide large
enterprises as well as small and mid-size businesses with collaboration solutions for their
business challenges.
Over the past years, thousands of collaborative applications have been built to support
functions such as human resources, quality assurance, enterprise resource planning (ERP),
supply chain management, customer relationship management (CRM), and help desk. Lotus
Notes and Domino is an integral part of IBM Workplace. Releases 7 and 8 are in development
and future versions are planned.
Sharing today in the attributes of the IBM Workplace model, Lotus Notes and Domino offers a
choice of e-mail clients to fit the varying needs of users, with flexibility and choice in hardware
platforms and operating systems. With Lotus Notes and Domino 6.5, users have a single
point of access to their most valuable e-mail, collaboration and personal information
management (PIM) resources through the Lotus Workplace for Notes welcome page.
There is continuing support for disconnected use, and Domino's multi-tier security enables
centralized control of access rights ranging from the server level to individual fields on a form.
The extended portfolio of Notes and Domino products leverages the same administrative
framework.
Lotus Notes and Domino capabilities and applications can readily be integrated with portlets
into WebSphere Portal and Lotus Workplace products, thanks to standards-based
interoperability. Meanwhile, the development roadmap for Lotus Notes calls for leveraging the
IBM Workplace Client Technology in future releases so that Notes customers can enjoy the
benefits of Lotus Workplace.
Chapter 1. Overview of Lotus Workplace
11
1.5 IBM Workplace Client Technology and IBM Workplace
This section discusses the two editions of IBM Workplace Client Technology.
IBM Workplace Client Technology, Micro Edition 5.7
IBM Workplace Client Technology, Micro Edition 5.7 is a family of products and technologies
that enable enterprises to extend access to business processes and information to remote
and mobile workers anytime, anyplace and over a wide range of mobile devices.
Typically, a worker who needs mobile services is one whose job functions include:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Sales
Field service and support
Public safety
Inspection services
Utility services
Delivery services
Claims adjustment
The IBM Workplace Client Technology, Micro Edition family provides different capabilities to
different people, covering a plethora of situations.
Workers deployed in the field must perform tasks such as check prices, fill orders, verify
status or location, view and adjust schedules, report problems, input customer data, and
manage inventories. They might need only to look up information, or they might need to fully
engage with their company's back-end systems.
Some workers require multiple and complex applications on their mobile devices, or are
frequently out of range of network services. Others require only a simple browser, or
forms-based application, or perhaps just e-mail or PIM access and instant messaging. Some
need critical time-sensitive information pushed, or automatically downloaded without request,
to them in an emergency, or the ability to pull, request, maps and directions when traveling
between customer sites.
IBM Workplace Client Technology, Rich Edition
IBM Workplace Client Technology, Rich Edition is a client-side framework based on Eclipse
and is used for deploying and managing business applications.
Because of the way IBM Workplace Client Technology shares code and processing work
between clients and middleware servers, organizations that embrace this technology and the
applications built on it have the flexibility of client-side applications combined with the
server-side control associated with Web-based computing. Effectively, they have the best of
both worlds.
Not only is this a boon to IT administrators, but the end user is able to enjoy the richness of a
traditional client with security, fast response time, UI consistency, off-line support, and tighter
integration with desktop productivity applications.
Note: For further information about IBM Workplace Client Technology, see:
򐂰 IBM Workplace Client Technology (Rich Client Edition) Technology Overview
http://www.redbooks.ibm.com/abstracts/redp3884.html
򐂰 IBM Workplace Client Technology (Rich Client Edition) ISV Integration Guide
http://www.redbooks.ibm.com/abstracts/redp3883.html
12
Building a Component for IBM Workplace
1.6 Developing applications: Opportunities for Business
Partners and ISVs
Lotus Workplace provides a mechanism for creating applications by assembling components
in different ways, helping users become more productive in the context of their everyday
work.
A key difference between the way components can be assembled today using products like
WebSphere® Portal, is that with Lotus Workplace, development is now in the hands of end
users. End users of Workplace can easily create new applications using templates designed
to meet their specific needs, without needing the assistance of developers. Each template is
an XML representation of a set of components. The template determines their layout on a
page, and runtime configuration information. Your end users can now use their browser to
create, edit, and set access to the Workplace applications they own. For custom needs,
templates can be created by corporate developers using the Workplace Builder as described
in Section 2.4, “Using Lotus Workplace Builder” on page 24.
The software model used by IBM Workplace requires you to develop applications as
components. A business component is the basic building block of a Workplace application. It
encapsulates a business concept, process. Some examples are: mailbox, discussion, trouble
ticket, or search capability. A business component can be deployed and used independently.
It does not require other components to be useful.
With components, you and your applications become adaptable. You can combine
components in different ways to build solutions to complex problems. For example, a team
space incorporates discussion or document management components. A help desk
application might incorporate trouble ticket, mailbox, and search components. Business
components are reusable. You can use the same component in any number of solutions or
applications.
Lotus Workplace Applications are built from Templates. These applications can be distributed
and managed by business users and administrators to provide targeted functionality to
specific groups of users.
The Lotus Workplace application templates that ship with release 2.5 are:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Blank Template
Chat Room
Course Collaboration
Customer Support Team
Discussion
Document Library
Domino Application Access
Employee Human Resources Site
Event Planning
Human Resources Team
Marketing Team
Sales Team
Team Project
This makes Lotus Workplace more than just a collection of collaborative applications. Lotus
Workplace is a platform for building new collaborative applications and integrating with the
Workplace applications offered by Lotus. The success of Lotus Workplace, like any
application platform, is driven by the ability of our clients, Business Partners, ISVs, corporate
developers, solutions providers, and system integrators to build new Workplace applications,
Chapter 1. Overview of Lotus Workplace
13
extend the IBM Lotus applications to meet their needs, and their ability to integrate Lotus
Workplace with other systems.
Business Partners and ISVs can add tremendous value to the Lotus Workplace platform.
Business Partners can generate demand and grow their businesses by extending the value of
Lotus Workplace by customizing the Workplace to fit their customers’ needs. For their
customers, this can mean improving an organization's responsiveness and productivity,
lowering total cost of ownership, and in the end, increasing competitive advantage.
Extensible offerings and tools from IBM make it easy for Business Partners and ISVs to
satisfy customers with customized industry and segment-focused offerings. ISVs can choose
to take advantage of the many components already provided by the Workplace, or create new
custom components. IBM’s componentized approach to development makes it easier to
assemble new custom applications that meet the needs of a specific client or industry. It also
makes it simple to keep recombining those pieces in different ways in many different
solutions. The componentization model means more efficient application development, and
faster development cycles because the components are reusable. This means an increased
quality of applications and enhanced developer productivity.
In Lotus Workplace, the portal provides a set of services, such as page aggregation,
authentication, and themes, so you do not have to rewrite them yourself. On top of that, you
get a set of collaborative application services, including mail, presence notification, instant
messaging and team spaces.
The market is moving from stand-alone applications to applications that bring together a
number of different systems related to a user’s role. This move brings new opportunities for
Domino developers by allowing them to expose their products to a new audience interested in
J2EE applications, while leverage existing skills to develop new applications.
For ISVs already developing applications on open standards-based technologies such as
Java and Eclipse, their applications may be easily tweaked to integrate them with the Lotus
Workplace platform. A downloadable API toolkit gives you the information you need to
integrate with Lotus Workplace and to access component services. The example application
that is built and described in detail in Chapter 4 of this Redpaper demonstrates this capability.
The IBM Lotus Workplace Products API Toolkit 1.0 is available for download at this Web site:
http://www.lotus.com/ldd/lwpapi
14
Building a Component for IBM Workplace
2
Chapter 2.
Lotus Workplace Application
Architecture
This chapter provides an overview of the Lotus Workplace platform architecture, the Lotus
Workplace application model, and introduces some of the development tools available to
build applications in Lotus Workplace.
Some of the concepts introduced in this chapter are:
򐂰
򐂰
򐂰
򐂰
򐂰
Lotus Workplace Architecture
Lotus Workplace programming model
Creating and editing templates
Creating new Lotus Workplace applications from templates
Introduction to Application Development Tools including:
– Lotus Workplace Builder
– Lotus API Toolkit
© Copyright IBM Corp. 2005. All rights reserved.
15
2.1 Architectural overview of Lotus Workplace 2.0.1
This section describes the overall architecture upon which all of the Lotus Workplace
products are built. It is not intended to be a comprehensive and detailed review of the Lotus
Workplace architecture, but rather a high-level summary of the key technologies and their
various relationships.
Overall, Lotus Workplace architecture is broken into the concept of Workplace business
components, leveraging Workplace services, that run on top of IBM WebSphere Portal
services. All of the Workplace components share a common base infrastructure of IBM
WebSphere Application Server, WebSphere Portal, directory services and a relational data
store. This architecture is depicted in Figure 2-1.
Figure 2-1 Lotus Workplace architecture
2.1.1 Lotus Workplace JVMs and containers: Opportunities for ISVs
This section provides more detail on the distribution of the Workplace components across the
WebSphere Application Server, WebSphere Portal and Lotus Workplace protocol server.
One of the first questions that arises when understanding the architecture of any application
is where do the different pieces actually execute? In a J2EE world, these pieces are run in
something called a container.
Containers are logical constructions that allow for common management and administration.
Containers viewed as objects, either as data structures or parts of a pattern, also provide
programmers and designers with standard interfaces that provide services for higher-level
APIs. Both provide consistency in services and increase code stability and reusability.
There are several containers that are active and managed in a Workplace 2.0.1 environment.
Another important observation is that not only are there several containers, but there are
multiple instances of the same type of container running in different spaces. The opportunity
for ISVs is to extend the features of the Collaborative Application Services layer.
Important: As a general rule, in a Workplace environment, the bulk of the services
execute under the Portal server instance. The Workplace server provides a container for
the business services.
16
Building a Component for IBM Workplace
2.1.2 Infrastructure Architecture
There are three basic infrastructure elements that make up the Lotus Workplace Server.
There are also supporting elements such as a Relational Database, LDAP servers and HTTP
Servers, but the following components represent the core infrastructure.
򐂰 WebSphere Application Server
The WebSphere Application Server is the foundation on which all the other services and
components are built.
򐂰 WebSphere Portal
WebSphere Portal provides a foundation for the services and components used by
Workplace. Most importantly, most of the Lotus Workplace components run within
WebSphere Portal.
򐂰 Lotus Workplace protocol Server
Lotus Workplace protocol Server provides components that handle messaging and
scheduling requirements of a Workplace solution. The bulk of Workplace services run
within the WebSphere Portal server.
This logical Infrastructure can be seen when starting a Lotus Workplace Server. Table 2-1
lists the server names and what they represent.
Table 2-1 Components of Lotus Workplace infrastructure
Server name
Server
server1
WebSphere Application Server
WebSphere_Portal
WebSphere Portal server
LotusWorkplace_Server
Lotus Workplace protocol server
WebSphere Application Server
The WebSphere Application Server is the foundation on which all the J2EE code that is Lotus
Workplace runs. Multiple Java application server processes are started using WebSphere
Application Server capabilities.
The WebSphere Application Server provides the framework for services and components that
are essential to any J2EE application. These frameworks and containers include:
򐂰 EJB Container
򐂰 Web Container
򐂰 Java Virtual Machine (JVM)
There are many more. However, the important point is that WebSphere Application Server
provides many components that are the footing for Portal and Workplace.
The default application server installed with WebSphere Application Server is server1r.
Note: If an environment is going to support the Workplace rich client, then server1 must be
run. Keep in mind, however, that you do not have to run server1 when all users connect to
your Lotus Workplace environment with the browser only.
WebSphere Portal
The WebSphere Portal server runs many parts of Lotus Workplace products. The list of
services the WebSphere Portal runs includes most of the workplace messaging, team
collaboration, collaborative learning and document management services.
Chapter 2. Lotus Workplace Application Architecture
17
The Lotus Workplace user interface runs within WebSphere Portal. This user interface is
made up of the various Workplace portlets. Most users interact with Workplace through the
Portal server, and do not directly interact with the other servers.
The WebSphere Portal server also hosts many of the Workplace components or Enterprise
applications. Each of the Lotus Workplace Enterprise Applications, designated by the .ear
extension, are composed of portlets, a direct display to users, as well as Enterprise Java
Beans (EJBs) that are responsible either for containing the business logic or connecting to
another system that contains the business logic. These EJBs are the services that Workplace
provides.
It is also important for Lotus Workplace Administrators and installers to be aware of other
critical services WebSphere Portal provides. These services are especially important when
you need to trace the root of a problem. For example, if there is a user registry problem, then
you can consult WebSphere Member Manager (WMM) to find where this service is running.
The key facilities implemented in this layer include:
򐂰
򐂰
򐂰
򐂰
Portlet Container and API
WebSphere Member Manager (WMM)
Portal Document Manager (PDM)
WebSphere Portal Content Publisher (WPCP)
When creating custom components for Lotus Workplace, your portlet will execute in the
WebSphere Portal server container and might use facilities of this layer or call services in
other layers. Your portlets might either execute in the WebSphere Portal Container or in a
container that you create specifically for your application.
Lotus Workplace Protocol Server
The LotusWorkplace_Server contains mostly the messaging protocol elements of the Lotus
Workplace platform. The bulk of the actual Lotus Workplace services run within the
WebSphere_Portal server Java process.
For the most part, interaction with the services in Lotus Workplace Server occurs through
requests that come from the portlets running in the WebSphere Portal. However, there are
three situations where users interact with the server directly:
򐂰 Users accessing only Lotus Workplace Messaging from a standard POP3/IMAP client
򐂰 Incoming and outgoing SMTP traffic
򐂰 Instant messaging traffic
Other infrastructure elements
As mentioned at the beginning of 2.1.2, “Infrastructure Architecture” on page 17, there are
other equally important components that make up the Workplace Platform. These are
predominately HTTP services and back-end components.
HTTP
The HTTP server receives the HTTP and HTTPS requests originated by browser clients from
the network dispatcher and routes them to the protocol services on a Lotus Workplace
protocol server.
The HTTP Server can be collocated with other components or installed on a separate
computer. In clustered environments, you can set up multiple HTTP servers to receive
connections from a network dispatcher. Each HTTP server, in turn, then distributes new
requests across a cluster of Lotus Workplace protocol servers.
18
Building a Component for IBM Workplace
RDBMS and LDAP
IBM DB2 and Oracle provide database services to the Lotus Workplace infrastructure and
host the key Lotus Workplace databases.
Persistent storage of the data for the applications in Workplace, is stored in the database
server configured at install time. Generally, this includes several databases. Workplace
creates databases named WPS50, WPCP50, NAGANO, LWPCOM and LWPARC.
While it is beyond the scope of this document to go into great detail about the database
schemas, be aware that various components of the Workplace infrastructure write data to
different databases using different mechanisms. For example, skins and themes are stored in
the WPS50 database. The NAGANO tables store mail, and in the case of Team Collaboration
only servers, team calendar data. The LWPCOM database stores custom user persistence
data that is needed to tie users to places and applications. The LWPARC database is used
mainly for Messaging.
An LDAP server handles all authentication and user registry capabilities in a Lotus Workplace
infrastructure. WebSphere Member Management capabilities are also leveraged behind the
scenes by Lotus Workplace, working closely with the LDAP server to provide a complete view
of user data.
Tip: More information about the Architecture of Lotus Workplace can be found in the Lotus
Workplace 2.0.1 Products Deployment Guide,” SG24-6378.
http://www.redbooks.ibm.com/abstracts/sg246378.html
2.2 Defining the Lotus Workplace Programming Model
At the core of the Lotus Workplace concept is an architecture that connects collaboration
activities to the collaboration participants. We have already introduced the concept of
templates. A template is the glue that binds multiple components into a Workplace
application. Applications are the things that human beings interact with as they conduct their
business processes. To participate in this environment, and be part of Workplace
applications, you must adapt your components to work with the template system.
2.2.1 Templates
A Workplace application is made up of Workplace components. Lotus Workplace includes
many Workplace components such as Discussion, Team Calendar, Team Task List, Contact
List, Forms, Document Library, Search, People Finder. We can also add our own Workplace
components to an application, these may include a Domino Portlet or Portlets.
Hypothetically, we could deploy the portlets to a page and have a Workplace application.
However, with Lotus Workplace, we now have the ability to make our applications into
templates. A template defines the Workplace application, its pages, and the application
components deployed on each page. In this way, we can provide a preconfigured set of
portlets and pages for a specific business task.
These templates have the distinct advantage of being able to be modified by an end user and
the administrators. Administrators can also control the deployment with user roles and other
administrative features. See Figure 2-2 on page 20 for an overview of the template
development process.
Chapter 2. Lotus Workplace Application Architecture
19
Figure 2-2 Workplace template construction
To work with a template, you must have access to Workplace Builder, the toolkit for viewing
and editing templates. To see the Workplace Builder link, grant the user the user policy Allow
users to create Workplace Templates in the Administrative console for the Lotus
Workplace Server. See 2.4, “Using Lotus Workplace Builder” on page 24 for more information
about Workplace Builder.
A Template is reusable structure or configuration that connects a specific UI layout together
with options, settings and roles. The properties and use of templates are key aspects of
Workplace application development. In brief, a template is a pre-made configuration that is
both reusable and customizable. The following paragraphs describe these aspects of the
Workplace templates capability.
Figure 2-3 illustrates the relationship between templates, applications, components, and
Workplace Builder. In the standard scenario, Workplace Builder is used to create a new
template either from scratch or from an existing template. You can select Workplace
components or simple portlets from the Workplace Component Catalog and add them to the
current template. Given that Workplace Builder is using portlets as the handle to add or
remove components, each Workplace component needs to have a portlet as its UI
implementation in release 2.0.1. Nevertheless, you can still add any stand-alone portlet to a
template. However, be aware that such simple portlets would render exactly the same in
different application instances. Portlets that are part of a Workplace component could
represent application-specific data or configuration, depending on the particular application
instance.
Workplace
Component
(portlet)
Catalog
Select
Components
(portlets)
creates
IBM Workplace
Builder
designs
Template
(XML File)
IBM Workplace
Application
feed
Instantiation
Service
creates
Figure 2-3 The relationship templates, application, components and Workplace Builder
20
Building a Component for IBM Workplace
Workplace Builder also allows you to edit existing application instances. For authorized users,
the Workplace browser UI renders an Edit button within application instances. With this
button, you can edit the current application in Workplace Builder. You can alter the application
as you use it or save it as a new template. This feature allows simple iterative development of
new templates. Starting with a simple template and a single application instance, you can test
the application and apply any required customization to the running instance. After the
application fulfills all business requirements, you can save it as a new template. As a
template, you can provision the same functionality to other teams or workgroups over and
over again.
2.2.2 Configuring Templates
The template captures settings and data that represent a configuration for a collaborative
place. In outline, this configuration information includes the following:
򐂰 Page Layout
Page Layout is the UI layout of selected rendering elements. For the Portal environment,
this equates to the layout of portlets on pages. Other environments are also supported. In
the Workplace Client environment, the layout speaks to Eclipse platform Perspectives and
Views.
򐂰 Component identity
Component identity is comprised of the UI elements that need to be connected to specific
component implementations. In the Portal environment, this is done with the JNDI names
for component EJBs.
򐂰 Component parameters
The configuration can include per-component parameters that serve to customize or direct
the operation of each included component. An example parameter might be the maximum
length of a discussion forum posting. The discussion component reads this parameter and
uses it to limit the extent of entered data.
2.2.3 Membership
Each IBM Workplace has membership. Membership is the individuals and groups who are
assigned roles that determine their access to the application. The names of Workplace
members appear in the Members portlet displayed in every application. Generally, application
managers are Moderators, application users are Contributors or any other role you want to
define.
Workplace components can define roles for its content. A role grants access to a set of
actions or commands that apply to the content. For example, a discussion forum might define
the following roles:
򐂰 Reader: Able to read postings
򐂰 Author: Able to create postings
򐂰 Moderator: Able to delete postings
In a Workplace application, applications roles are defined in the context of the business
process. They can be named anything the application designer wants. For example, a Project
application might define the following roles:
򐂰
򐂰
򐂰
򐂰
Project Manager
Team Leader
Team Member
Project Reviewer
Chapter 2. Lotus Workplace Application Architecture
21
Application roles need to be mapped to the Workplace component roles. This mapping
ultimately determines what access a user receives when assigned to an application role. For
example, Project Manager would be mapped to Moderator in a discussion forum. Application
roles are mapped to Workplace component roles in Workplace Builder.
2.2.4 Accessing templates
Permission to work with Workplace templates is determined by user policies and assigned
template roles.
򐂰 User policies provide permission at the most fundamental level for users to work with
templates and applications. Workplace Administrators set user policies.
򐂰 Template roles provide permission to edit or use templates. Template roles are assigned
to users by template owners.
2.2.5 Applications
All Workplace applications are based on a template. When customizing an application, you
can choose to either modify the existing application or choose to modify the template on
which that application is based.
For an example of modifying an existing application, consider that you want to add your own
component to an existing Team Space. Furthermore, you want to have that modification
appear for all future Team Spaces. You have two choices:
򐂰 Modify the template by adding your component.
򐂰 Save an existing application as a template. This concept is very similar to Lotus Team
Workplaces (Quickplace).
Table 2-2 lists the Workplace applications that can be created using the templates provided
with Lotus Workplace.
Table 2-2 Applications created from templates
Workplace application
Description
Team Space
Participate in discussions and chats,
share documents and a team calendar,
and search for information related to a
project.
Discussion
Participate in threaded discussion forums
with teams.
Chat Room
Communicate with team members, view
archives of chat transcripts, and see a list
of chat participants.
Domino Application
Access HTML-enabled Domino
applications.
Document Library
Manage document versions, approvals.
2.2.6 Required components for templates and applications
Workplace information and membership are essential components of every Workplace
application. These components are displayed as the information portlet and the Members
portlet. Because these portlets must be available in every Template or Application, the delete
icon is not available. The information portlet is used to describe what the application is and
22
Building a Component for IBM Workplace
also acts as a home portlet for the application. It also contains the rename button so a user
with the correct privileges can change the name of the application. The Membership portlet is
used to store specific access rights to this application. The size limit of a Workplace
application is set by the Workplace application policy in the Administrative console for the
Workplace Server. The maximum size of a Lotus Workplace application is set at 60 MB by
default. There is a setting within the policy to allow a warning message to be displayed if the
size of the application approaches that limit.
2.2.7 Lotus Workplace Application development roles
There are two primary application development roles that apply to Lotus Workplace. They are
the Line-of-business (LOB) user and the J2EE Developer. This section describes these roles,
and the goals and skills that apply to each role.
Line-of-business user role
The line-of-business user (LOB user) is a business user whose primary goals are
business-related. In other words, they are using the software as a means to an end. For
example, the LOB user is concerned about lowering their costs, increasing customer
satisfaction, and maximizing revenue opportunities. They want to use a tool in order to do
simple customizations of the environment themselves, mainly so that they can get it done
quickly without having to use more expensive IT resources, who should be working on the
more complex issues of the day. It is important to note that LOB users are not professional
programmers, and they do not want to become programmers. They require tools that do not
look and feel like tools.
LOB users are further subdivided into novice and skilled users. Novice users are typically the
primary end-user of the system. They use the tools to create and customize an application
instance, manage membership access, change the theme, modify configuration parameters,
and create simple forms. Skilled users have more technical knowledge and awareness of the
overall capabilities of the Workplace system. Like novice users, persons in the skilled-user
role are often the end-users of applications they create. Skilled users also create application
templates to be used by others.
J2EE developer role
At the other end of the spectrum is the J2EE developer. This person is highly skilled in
producing complex, multi-tiered systems that help businesses operate efficiently. They can
and do build just about anything that is required to meet the organization’s business goals.
The J2EE developer typically has a computer science degree or equivalent and their primary
goals are IT-related goals. They require APIs and the ability to extend any platform with which
they work.
Role-specific tools
The Workplace tool that is available for the LOB user in Lotus Workplace 2.0 is called
Workplace Builder. The Workplace tool for J2EE developers is the Workplace API Toolkit.
Both of these tools are described in greater detail in 2.3, “Lotus Workplace application
development tools”.
2.3 Lotus Workplace application development tools
Lotus Workplace is more than a collection of collaborative applications. It is a platform for
building new collaborative applications and integrating them with the Workplace applications
offered by Lotus. The success of Lotus Workplace, like any application platform, is driven by
the ability of IBM clients such as Business Partners, ISVs, corporate developers, solutions
Chapter 2. Lotus Workplace Application Architecture
23
providers, system integrators, and so on, to build new Workplace applications, extend Lotus
applications to meet their needs, and integrate Lotus Workplace with other systems.
There are a number of development tools for IBM Workplace to assist Workplace developers
to leverage the latest industry standards and technology frameworks to create applications
with tools that are tightly integrated with each other. The IBM Workplace portfolio includes
tools to meet the needs of developers with a broad range of skills and business needs, such
as IBM's existing WebSphere portlet builders, WebSphere Studio and Rational® software
tools. In addition to these technologies, the portfolio of Workplace tools includes the new
additions in the following sections.
2.3.1 Lotus Workplace Builder
Designed for line-of-business users and customers with limited expertise in application
development, Workplace Builder assembles reusable components, or building blocks, into
applications for the Workplace platform. Applications can be saved as reusable templates,
reducing the time and expense of creating repeatable processes. Workplace Builder is
currently available in release 2.0 of Lotus Workplace product offerings. See 2.4, “Using Lotus
Workplace Builder” for more information about Lotus Workplace Builder.
2.3.2 Lotus Workplace API Toolkit
For ISVs, Business Partners, and clients who want deeper integration with the Workplace
platform, IBM provides a toolkit that includes sample code, documentation, APIs and service
provider interfaces. Developers using IBM WebSphere Application Developer can extend the
platform by building new components that can be assembled into templates and deployed to
any device. In addition, they can use collaborative functions such as sending mail or instant
messages as Web services from within their own business applications. The first version of
the Lotus Workplace API Toolkit is currently available, and follow-on releases are expected in
2005, including a Workplace Client toolkit. The Lotus Workplace API Toolkit is described in
detail in Chapter 3., “Introduction to application development in Lotus Workplace” on page 37.
One of the API’s, the Collaborative Application Component Interfaces API, is illustrated in
detail as an example application is created in Chapter 4., “Building a Component for IBM
Workplace” on page 55.
2.3.3 Lotus Workplace Designer
For clients who need more complex business applications and for developers with more
sophisticated programming skills, Lotus Workplace Designer provides a visual,
enterprise-level scripting tool that can be used for building stand-alone business applications
or to complement applications built with Lotus Workplace Builder. While more advanced than
Workplace Builder, this tool requires less Java experience than WebSphere Studio. The
Workplace Designer is scheduled for beta release in 2005.
2.4 Using Lotus Workplace Builder
Workplace Builder is an application assembly tool for the skilled line-of-business User and
J2EE developers. It is intended for the business unit of the enterprise who understand the
business model and business processes. These would likely be users who are business
analysts, application managers and designers. Workplace Builder is designed to help the
business user rapidly assemble components into applications that revolve around a business
process.
24
Building a Component for IBM Workplace
The Workplace Builder provides an easy to use interface for business users to assemble
applications. With Workplace Builder, it is simple to add greater business functionality to the
base Workplace product.
As an example, we are going to create a Workplace application for a Sales Team Discussion.
To do this, we will base the application on an existing template, the Discussion Template.
1. Sign into Lotus Workplace as an administrative user. If you have all the required roles and
policies, the Workplace Builder icon will be available at the top of the screen next to My
Favorites.
2. Click Workplace Builder to launch the Workplace Builder, as shown in Figure 2-4.
Figure 2-4 Launch Workplace Builder
Workplace Template Library
Once you have entered Workplace Builder, you see the Workplace Template Library. This
library displays the list of templates with which Template Editors, including Template Owners,
can view and work. Tasks you can perform from the Workplace Template Library include
creating new templates, importing and exporting template XML, assigning roles for template
access, Template Editor or Template User, deleting templates, and opening the template
editor.
Chapter 2. Lotus Workplace Application Architecture
25
Figure 2-5 The Workplace Template Library
Workplace Builder provides a number of different components that help you work with
templates, applications and forms.
Template editor
The Template editor displays a set of portlets for maintaining templates for Workplace
applications: Properties, Parameters, Pages and Layout, and Roles.
3. From the Workplace Template Library, click the Discussion template to open the template
editor.
Application editor
The application editor displays a set of portlets for maintaining a particular Workplace
application: Properties, Pages and Layout, and Roles.
4. From within a Workplace application, click Edit in the Workplace administration bar to
open the application editor.
Form Template Library
The Form Template Library displays the list of templates for forms that Workplace managers
can view and work with. Tasks performed from the Form Template Library include creating,
editing, and managing form templates.
5. From the Lotus Workplace toolbar, click Workplace Builder to display the Workplace
Builder place.
6. From the Workplace Builder place, click Form Template Library to display the list of form
templates.
2.4.1 Create a new Workplace Application Template
In this section, we create a new Workplace Application Template.
26
Building a Component for IBM Workplace
7. Click the New button. Several fields are presented to be completed:
– Template Name
This is a name that will represent the application. We used something called
Northeast Sales Discussion.
– Category
This is the area within Workplace from which the application will be available. We
wanted this application to be available form the applications area of Workplace, so in
this case we selected application.
– Description
This field is an optional description of the application. We entered some text to
describe the purpose of the application.
– Starting Point
This is probably the most powerful parameter on this page. It allows a user to base an
application on a previous template. In our case, we based it on the Discussion
template. This not only saves allot of work because we do not have to start from
scratch, but also allows new applications to be built upon a previous application.
8. Select the Discussion template as the Starting Point for our new application and click
OK.
Figure 2-6 Creating a new application based on the existing Discussion template
The application is then created and opened. Across the top of the screen we have the option
to Cancel, Save and Close, Save as (to make a copy) and Preview the application. Down the
left side is a list of all Builder Tabs in which configuration of the application can be performed.
The first tab is the properties tab and shows the information that was entered when the
application was created. See Figure 2-7 on page 28.
Chapter 2. Lotus Workplace Application Architecture
27
Figure 2-7 Properties of the Northeast Sales Discussion application
The next tab in Figure 2-8 represents Pages and Layouts and is an interface you might be
familiar with from the Administration area of WebSphere Portal and Lotus Workplace.
Figure 2-8 The Pages and Layouts interface
In the Pages and Layouts tab, you can add new pages, change the order of pages and set
the security of pages as well as other features. We can also drill into each page and place the
portlets or components where we want on those pages. We can also see all the components
that came from the Discussion Template. If we decided we no longer wanted all those
components, we could simply remove them by selecting the trash can icon beside those
pages.
9. In this case we are going to create one new page to display a Team Tasks list by clicking
the New Page button. See Figure 2-9 on page 29.
28
Building a Component for IBM Workplace
Figure 2-9 Creating a new page in the Northeast Sales Team Discussion Application for Team Tasks
10.In the Title field, type Team Tasks. Once we have added the new page to the Northeast
Sales Team Discussion Application, it appears on the Pages and Layout screen in
Figure 2-10.
Figure 2-10 The Team Tasks page now appears in the Pages and Layout tab
11.From the Pages and Layout screen it is possible to add components to pages. For our
page, we still need to add the team task list, so we choose to edit the Team Tasks Page
we just created. Click the pencil to the right of the page in the Pages and Layouts view.
See Figure 2-11 on page 30.
Chapter 2. Lotus Workplace Application Architecture
29
Figure 2-11 Viewing the Team Tasks Page prior to adding the new portlet
12.Add the Team Task List Portlet to our Page by selecting Add Portlet, searching for the
Team Tasks Portlet, then clicking OK.
Figure 2-12 Adding the portlet to the Team Tasks page
Modifying parameters
After setting up the pages with the required components and laying them out, do the
following:
13.Select the Parameters Page.
Each component of the application can expose parameters, this allows the business user
who is setting up a new application to customize and r further refine the application to suit
his or her business need. It is up to the component developers to expose which parts of
the component will be able to be refined when developing that component.
30
Building a Component for IBM Workplace
This example shows that in this application we can choose to modify some information
about the portlet and also some settings surrounding the team task portlet. At the moment,
the Description attribute is set and cannot be edited by a user. If we wanted to change that
it is just a matter of opening that parameter for editing and changing it to the required
value. See Figure 2-13.
Figure 2-13 Allowing the description parameter to be edited.
Once the parameter has been edited, we can see that it is now editable by the end-users
when a new application is created from this template. This method can give the business user
the power of varying the application to suit different needs without the need to change any
underlying code. When developing components intended to be used with Workplace Builder,
this should always be a consideration.
Modifying Roles
After editing the Parameters, set the roles by doing the following:
14.Click the Roles Tab.
Roles allow the designer to add application-specific roles to an application. In this way it is
possible to create granular roles that make logical business sense to this application.
15.We can add a role called Northeast Sales Forum Moderator in the Role field. That person
can create new forums, topics, replies and can edit or delete any posts within this
application.
16.After clicking New to create a new role, set the access as required. In this case we are
giving members of this role Moderator access over the discussion forum so they can work
with the forums as deemed appropriate.
See Figure 2-14 on page 32.
Chapter 2. Lotus Workplace Application Architecture
31
Figure 2-14 Modifying Roles within the template
Preview the template
At this point, it is possible to preview the template. At the top of the screen, locate the
preview button. This preview button allows the application builder to iteratively see what the
application will look like when it is completed.
Another subtle, but powerful, feature is that data can be prepopulated into the application. An
example is that in the team task there might be task that will occur every time that this
application is deployed. When the application is in preview mode, simply enter the task and
that data will be saved as part of the template. When you have completed previewing the
application click Done previewing (Figure 2-15) and then save the template. You are then
returned to the list of templates. You can now see the new template listed.
Figure 2-15 Previewing the new template
Create a new application
Now that a template has been defined, it is ready to be used to create a working
application.To create the application, do the following:
1. Click back to My Workplace and then the application page. Remember, we set the
category to application so it would be listed as a new application here.
32
Building a Component for IBM Workplace
2. Click the New button and our template is available. Complete the fields that represent the
name of the application and add a description. Ensure that you select the newly created
template in the template field.
3. After clicking OK, you are presented with a screen where you can set any
application-specific parameters. These are the parameters that we made editable and are
now being displayed to the application creator to further refine the template. Below these
parameters, you can see the parameters associated with the team task portlet.
Once the parameters are set, click OK and the application is ready to use and be available
to the users. At this point, it might be necessary to add users to their appropriate roles.
2.4.2 Editing the application
While using the application, its users might decide that they want some components in the
application changed. To achieve this, do the following:
1. Click the Edit button at the top of the screen. Only people in the Moderator role are able to
perform this task.
2. Once the application is in edit mode, the tab layout should be familiar. To edit the
application, click the Page and Layouts tab and then click the pencil icon to add the new
portlet to the page.
3. Once you are happy with the new layout and settings, click Done. The edited version of
the application is available immediately to users of the application.
2.4.3 Reusing the application to create new applications
The users of the application might find the changes incredibly useful. The next time an
application template is created, it will be possible to base that future application on the one
we have running here. In this manner, it is possible to build upon this application to create
new applications.
The user who creates an application becomes the default Moderator and can specify
additional moderators.
The application Moderator performs most of the administration tasks. The Moderator
specifies whether an application is open to all authenticated users or to application members
only. In addition to specifying membership of the application, Moderators edit the names and
descriptions of applications, and the layout of pages within applications.
Application Moderators can create applications from templates, as well as save new
applications as templates for reuse by other users to add value to the Lotus Workplace
platform.
2.4.4 Adding portlets, themes and skins
As with most WebSphere Portal-based products, Lotus Workplace is completely
customizable. Administrators customize Lotus Workplace through the standard WebSphere
Portal administration tasks Manage Pages and Themes and Skins. The administration tasks
allow you to add new pages to Lotus Workplace, edit existing pages, rearrange the order of
pages, edit the page layouts, and change the look and feel by using different themes and
skins.
The Lotus Workplace theme and default skins, WorkplaceSkin and WorkplaceBuilderSkin,
give Lotus Workplace its distinctive look. Themes, which are Java Server Pages (JSPs),
determine the look and layout of portal elements, which can include the toolbar, banner, place
Chapter 2. Lotus Workplace Application Architecture
33
bar, page bar, and screen. Skins represent the border rendering around components, such as
row containers, column containers, or portlets. You can choose to use alternate themes and
skins without affecting Lotus Workplace features.
򐂰 Themes determine the look and layout of the portal, including colors, fonts, and images
outside of the portlet content area (Home screen). Themes are the overall look and feel of
a portal page and often provide the initial navigation to portal pages. Each page can have
a separate theme if required.
򐂰 Skins represent the border rendering around components, such as row containers, column
containers, or portlets. Skins also provide navigation to levels deeper than the navigation
that is provided by the themes. Skins can use the theme name to select the graphics that
match the theme colors. Skins are installed independently from themes. However, the
administrator can set a default skin for a theme.
These JSPs reside in the corresponding subdirectory under the
was_root/installedApps/hostname/wps.ear/wps.war directory. Themes are located at
\themes\html\workplace\Default.jsp. The Lotus Workplace skin control file is located at
\html\workplace\control.jsp.
To access the themes and skins section of Lotus Workplace, do the following:
1. Log in to Lotus Workplace as an administrative user and click Administration. See
Figure 2-16.
Figure 2-16 Lotus Workplace Administration section
2. Next, navigate to Portal User Interface →Themes and Skins.
3. To customize your Lotus Workplace, click Add new theme or Add new skin and follow
the prompts to install your new theme or skin. See Figure 2-17 on page 35.
34
Building a Component for IBM Workplace
Figure 2-17 Installing new themes and skins
To update the Lotus Workplace logo on the login page to display your company logo, do the
following:
1. Specify the company logo.
A company's logo is displayed using the code in the default.jsp file in Example 2-1:
Example 2-1 Displaying your company logo
<img align="absmiddle"
alt='<wps:text key="title" bundle="nls.engine">Portal Title</wps:text>'
title='<wps:text key="title" bundle="nls.engine"/>'
src='<wps:urlFindInTheme file="logo.gif"/>'>
2. For the default theme, the logo.gif file is located in the
wp_root\app\wps.ear\wps.war\themes\html directory. To change the logo to your
company’s banner, either replace logo.gif or copy your company's logo to the default
theme's directory and modifying the file attribute in the code listed above. The text for the
alt attribute is read from the default.jsp file.
Tip: For more information about creating skins and themes, refer to the IBM WebSphere
Portal information center:
http://publib.boulder.ibm.com/pvc/wp/500/ent/en/InfoCenter/index.html
2.5 Summary
Lotus Workplace applications combine a number of components into one presentation. In this
chapter, we gave an architectural overview of the Lotus Workplace application architecture to
help ISVs, Business Partners, and clients understand where the opportunity exists for
extending the platform. We also discussed the Lotus Workplace application model and
introduced Lotus Workplace Builder which assembles components into new applications and
the Lotus Workplace API Toolkit which helps you create custom components. In the next
chapter, we provide an introduction to application development in Lotus Workplace.
Chapter 2. Lotus Workplace Application Architecture
35
36
Building a Component for IBM Workplace
3
Chapter 3.
Introduction to application
development in Lotus Workplace
We saw in the last chapter how a Lotus Workplace application combines a number of
components into one presentation. The last chapter also discussed the Lotus Workplace
application development tools available: Lotus Workplace Builder which assembles
components into new applications and the Lotus Workplace API Toolkit which helps in the
creation of custom components.
In this chapter, we look in more detail at the Lotus Workplace APIs and discuss other
technologies that can be used to create those components. These include:
򐂰
򐂰
򐂰
򐂰
򐂰
Portlets
Struts
Java Server Faces
WebSphere Portal Portlet APIs
Domino Integration methods
© Copyright IBM Corp. 2005. All rights reserved.
37
3.1 Technologies for developing Lotus Workplace applications
Lotus Workplace as an application platform centers on the advanced features such as
templates, custom components, and on tools such as the Workplace Builder, all of which are
covered in other sections of this Redpaper. However, there is a measure of customization and
application integration which can be accomplished by combining Workplace with other,
non-Workplace portlets using the aggregation and communication features offered by
WebSphere Portal. Some of these customizations, changing an existing Workplace page by
adding another portlet to it, for instance, are within the grasp of the line-of-business end-user.
Others are in the domain of the IT developers or administrators. These customizations
include updating an existing customer portlet to participate in Click-to-Action (C2A)
communications with Lotus Workplace. This section reviews the basics of this kind of
development and lists some of the features exposed by Lotus Workplace which can be used
at this scope.
3.1.1 What is a portlet?
Portlets are the heart of a portal. The term portlet refers to a small portal application, usually
depicted as a small box on a Web page. A portlet is a reusable Web module that runs on a
portal server. Portlets have predefined roles such as retrieving news headlines, searching a
database, or displaying a calendar. Web pages, Web services, applications, and syndicated
content feeds can be accessed through portlets.
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 WebSphere Portal component, similar to the
way a servlet runs on an application server. The portlet container provides a runtime
environment where 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.
Generally, portlets are administered more dynamically than servlets. For example, portlet
applications consisting of several portlets can be installed or removed while the WebSphere
Portal component is running. The settings and access rights of a portlet can be changed by
an administrator while WebSphere Portal is running, even in a production environment.
3.1.2 Portal configuration
WebSphere Portal provides a set of administrative tools for creating portal pages, installing
portal applications and portlets, and configuring and managing all of these entities. The basic
concepts of portal aggregation center on tying together multiple portlets that are useful
together into a page, and tying together multiple pages into places. Lotus Workplace adds
even more powerful concepts of templating and collaborative spaces, but this section focuses
on customization possibilities within the realm of the basic portal page and place concepts.
The individual portlets of Lotus Workplace can be mixed and matched with other portlets on a
portal page. The simplest scenarios are those where one or more portlets that are not from
Workplace are added to existing Workplace pages. When third-party portlets are added to
Workplace pages, they can opt to use the available Workplace theme resources or their own.
In these situations, the Lotus Workplace and non-Lotus Workplace portlets coexist without
interfering with each other. In some cases, they communicate with the Click-to-Action
features covered in 3.1.3, “Introduction to portlet communications” on page 39.
38
Building a Component for IBM Workplace
3.1.3 Introduction to portlet communications
WebSphere Portal provides a way for portlets to communicate with each other. In a
production portal, portlet communication could be used to copy common data between
portlets. This saves redundant typing for the user and makes WebSphere Portal easier to
use. For example, one portlet might display information about accounts while a second portlet
displays information about transactions that have occurred for one of the accounts over the
last 30 days. To do this, the transactions portlet needs to obtain the corresponding account
information when it displays the transaction details.
This is accomplished by communication between the two portlets, using portlet actions and
portlet messages. In this example, the account portlet creates a portlet action and encodes it
into the URL that is rendered for displaying transactions. When the link is clicked, the action
listener is called, which then sends a portlet message to send the necessary data.
Using this event and message feature help unify portlet applications that access disparate
back-end applications.
򐂰 A user holds the Ctrl key while clicking an action and chooses to have the selection saved
persistently as a connection between two portlets, called a wire. If a wire is present, the
next time the user clicks the icon, no selection menu is shown. Instead the wired actions
are automatically fired. Subsequent updates to that property are transferred without
further deliberate user choice.
Wires can also be created using the Portlet Wiring Tool.
򐂰 The source portlet can do a programmatic publish of properties to the broker when it
determines that property values have changed. Such property values are transferred to
the target only if wires have been created.
3.1.4 Communicating with Click-to-Action
Some Lotus Workplace portlets take advantage of WebSphere Portal's communication
feature called Click-to-Action. When two Lotus Workplace portlets with complimentary
Click-to-Action capabilities appear together on a portal page, the Click-to-Action mechanisms
will automatically add an icon plus pop-up menu to permit the user to initiate an action.
Likewise, third-party portlets can be adapted to participate in Click-to-Action and
communicate with those Lotus Workplace portlets.
Click-to-Action is a framework that facilitates exchange of compatible data between portlets.
A portlet that sends data to others is a source, and the portlet developer identifies the
candidate data by using special tags in the portlet JSP pages where the data gets displayed.
A portlet that receives data is a consumer. The portlet developer uses a WSDL file to declare
the actions which are available to be invoked, plus a special Click-to-Action wrapper portlet
that makes the actions visible to the Click-to-Action machinery. A given portlet can be both a
producer for some kinds of data and a consumer of others; furthermore, consumers can
specify output parameters for their actions which automatically trigger any compatible
actions, permitting chaining of actions.
Tip: Full documentation of Click-to-Action and adapting portlets for its use is available in
the IBM WebSphere Portal Information Center:
http://publib.boulder.ibm.com/pvc/wp/500/ent/en/InfoCenter/index.html
Some Workplace portlets are sources of Click-to-Action data, and third-party portlets which
are adapted as consumers of the same type will be able to accept data through
Click-to-Action when co-located on a page with these Lotus Workplace sources. The
Chapter 3. Introduction to application development in Lotus Workplace
39
procedures for adapting a portlet to be a Click-to-Action consumer are more involved than
making a source. Full details are outside the scope of this document, but, in brief, the process
includes:
1. Exposing one or more public methods which each take a single parameter of one of the
target types output by Workplace, such as String
2. Packaging a WSDL file with the portlet deployment that describes each method and its
bindings
3. Modifying a Web.xml and portlet.xml to nest the original portlet inside a Click-to-Action
wrapper portlet and to expose each method to the Click-to-Action broker mechanisms
3.1.5 Cooperative portlets
Cooperative portlets subscribe to a model for declaring, publishing, and sharing information
with each other using the WebSphere Portal property broker. Portlets subscribe to the broker
by publishing typed data items, or properties, that they can share, either as a provider or as a
recipient. Through the property broker, portlets can exchange information, or properties, with
each other. Such portlets are called cooperative portlets. Cooperative portlets can react to
changes to other cooperative portlets on the page, resulting in a simultaneous update to
multiple portlets with minimal user intervention.
Tip: For a complete description of cooperative portlets refer to:
򐂰 The IBM WebSphere Portal Information Center
http://publib.boulder.ibm.com/pvc/wp/500/ent/en/InfoCenter/index.html
򐂰 IBM WebSphere Portal V5: A Guide for Portlet Application Development, SG24-6076
http://publib-b.boulder.ibm.com/abstracts/sg246076.html
At runtime, the property broker matches the data type of output properties from a source
portlet with the data type of input properties from one or more target portlets. If a match is
determined, the portlets are capable of sharing the property. The actual transfer of the
property can be initiated by one of the following methods:
򐂰 A user launches a Click-to-Action event from an icon on the source portlet. The icon
presents a pop-up menu containing the list of targets for the action. After the user selects
a specific target, the property broker delivers the data to the target in the form of the
corresponding portlet action. Using the Click-to-Action delivery method, users can transfer
data with a simple click from a source portlet to one or more target portlets, causing the
target react to the action and display a new view with the results.
򐂰 The user can also broadcast the property to all portlets on the page that have declared an
action associated with a matching input property.
People Finder using a URL
The People Finder portlet is covered partially in the above Click-to-Action section. It offers
additional functionality available to third-party portlets by making some features URL
addressable. A custom portlet can construct a URL for the People Finder and set an Action
code and a MemberId. The PeopleFinder responds by opening the requested page of
information in a pop-up window. Complete documentation on this and the other features of
People Finder is located in the Lotus Workplace Information Center:
http://www-10.lotus.com/ldd/notesua.nsf/find/workplace
40
Building a Component for IBM Workplace
3.1.6 WebSphere Portal Portlet API
Portlets are a special subclass of HttpServlet, with properties that allow them to easily plug in
to and run inside WebSphere Portal. Portlets are assembled into a larger page, with multiple
instances of the same portlet displaying different data for each user. Portlets rely on
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. The Portlet API provides standard interfaces for these functions.
The portlet API defines a common base class and interfaces for portlets to separate cleanly
the portlet from WebSphere Portal infrastructure. In most respects, the portlet API is an
extension of the servlet API, except that it restricts certain functions to a subset that makes
sense for portlets running in the context of a portal. For example, unlike servlets, portlets
cannot send errors or redirects as a response. This is done only by WebSphere Portal itself,
which controls the overall response page.
Usually, many portlets are invoked in the course of handling a single request, each one
appending its content to the overall page. Some portlets can be rendered in parallel, so that
WebSphere Portal assembles all the markup fragments when all the portlets finish or time
out. Portlets that are not considered threadsafe are rendered sequentially.
The markup fragments that portlets produce can contain links, actions, and other content.
The Portlet API defines URL rewriting methods that allow portlets to transparently create
links, without the portlet needing to know how URLs are structured in the particular portal.
Tip: More information about the Portlet API can be found in IBM WebSphere Portal V5 A
Guide for Portlet Application Development, SG24-6076.
http://publib-b.boulder.ibm.com/abstracts/sg246076.html
3.1.7 JSR168 Portlet API
Unlike the WebSphere Portal Portlet API, the JSR 168 Portlet API enables developers to
build portlets for multiple portal servers. While it does not include all WebSphere Portal API
features, it is anticipated that this Java API will replace the WebSphere Portal Portlet API over
time.
3.1.8 IBM Portlet Wiring Tool
With WebSphere Portal release 5 IBM introduced the Portlet Wiring Tool.
With the Portlet Wiring Tool, you can configure connections, or wires, between portlets on a
page that register with the property broker. WebSphere Portal V5.0 introduced wires as an
enhancement to the Click-to-Action features of V4.2. Users' transfer selection choices can be
saved as wires between the portlets. The wire can be used to transfer automatically
properties to target portlets when specific interactions are performed in the portlet without
displaying the pop-up menu prompting the user for more information. Wires are created by
holding the Ctrl key and clicking an icon or hotspot in the portlet. A dialog is displayed that
allows the user to create a wire to other portlets on the page.
You can also view the properties that portlets on the page can send or receive. If a match is
available between two portlets, you can create a wire between the two portlets. Existing wires
can also be deleted using the tool. This is an alternative to the wire creation or deletion while
interacting with the portlets as described above. The wiring tool allows wires to be created in
situations which are not handled by the interactive approach. For example, the tool does not
require the existence of Click-to-Action menus to initiate wire creation, and can be used to
Chapter 3. Introduction to application development in Lotus Workplace
41
create multiple wires from a single source property. Using the interactive approach, a single
source can be wired to a single target or all targets, not an arbitrary subset.
3.1.9 Struts
Struts is a framework for building Java Web applications that can be used as the basis for any
portlet you develop.
Struts is a very popular framework for Web applications using a Model-View-Controller (MVC)
design pattern. The Struts framework is an open source subproject of the Apache Software
Foundation's Jakarta project and can be used to design Web applications.
The Struts open source framework was created to make it easier for developers to build J2EE
Web applications. Like a building, a Web application must have a solid foundation from which
the rest of the structure can grow. Using Struts as the foundation allows developers to
concentrate on building the business application rather than on the infrastructure.
The Struts framework has gained considerable attention because of its ease of use and
ability to fit the needs of today's developers in building applications fast. Struts combines
servlets, JSPs, custom tags and message resources into a unified infrastructure and saves
the developer the time it takes to code an entire MVC model, which is a considerable task.
The Model 2 approach is concerned with separating responsibilities in Web applications.
Application development and maintenance are much easier if the different components of a
Web application have clear and distinct responsibilities.
Tip: For more information about Struts, refer to:
򐂰 The IBM Redbook. WebSphere Studio 5.1.2 JavaServer Faces and Service Data
Objects, SG24-6361.
http://publib-b.boulder.ibm.com/abstracts/sg246361.html
򐂰 The Struts Web site:
http://struts.apache.org/
3.1.10 Java Server Faces
JavaServer Faces (JSF) is a framework for developing Java Web applications. The JSF
framework aims to unify techniques for solving a number of common problems in Web
application design and development, such as:
򐂰 User interface development
JSF allows direct binding of user interface (UI) components to model data. It abstracts
request processing into an event-driven model. Developers can use extensive libraries of
prebuilt UI components that provide both basic and advanced Web functionality.
򐂰 Navigation
JSF introduces a layer of separation between business logic and the resulting UI pages.
Stand-alone flexible rules drive the flow of pages.
򐂰 Session and object management
JSF manages designated model data objects by handling their initialization, persistence
over the request cycle, and cleanup.
42
Building a Component for IBM Workplace
򐂰 Validation and error feedback
JSF allows direct binding of reusable validators to UI components. The framework also
provides a queue mechanism to simplify error and message feedback to the application
user. These messages can be associated with specific UI components.
򐂰 Internationalization
JSF provides tools for internationalizing Web applications, supporting number, currency,
time, and date formatting, and externalizing of UI strings.
JSF is easily extended in a variety of ways to suit the requirements of your particular
application. You can develop custom components, renderers, validators, and other JSF
objects and register them with the JSF runtime.
Tip: For more information about Java Server Faces, refer to the IBM Redbook, IBM
WebSphere Portal V5 A Guide for Portlet Application Development, SG24-6076.
http://publib-b.boulder.ibm.com/abstracts/sg246076.html
3.2 Working with the Lotus Workplace API
Lotus Workplace is more than a collection of collaborative applications. It is a platform for
building new collaborative applications and integrating with the Workplace applications
offered by Lotus. The success of Lotus Workplace, like any application platform, will be driven
by the ability of Business Partners, ISVs, corporate developers, solutions providers, system
integrators, and so on, to build new Workplace applications, extend the IBM Lotus
applications to meet their needs, and integrate Workplace with other systems.
To meet this requirement, Lotus Workplace provides a number of public APIs (and SPIs) for
client use, which are described in this section. The Workplace public APIs supplement the
public APIs provided by the underlying WebSphere and Portal platforms, which are not
covered here.
The Workplace API provides Java developers with tools to build custom applications that can
leverage the Workplace Platform. With the toolkit it is possible to create applications that take
advantage of the frameworks created by workplace. The API includes APIs, SPIs and JSP
tags to help a developer to achieve this.
As with the WebSphere Portal API, the Lotus Workplace API has a clearly defined services
layer. We can use these services to interact with Lotus Workplace components. To see a view
of overall Lotus Workplace architecture, see Figure 3-1 on page 44.
Chapter 3. Introduction to application development in Lotus Workplace
43
Figure 3-1 Lotus Workplace platform architecture
Application development prerequisites
To create an application using the IBM Lotus Workplace Products APIs, the following
software is required:
򐂰 IBM Lotus Workplace Products API Toolkit 1.0
򐂰 Java Editor
WebSphere Application Developer 5.1.2 and Portal Toolkit 5022 are highly recommended,
and required to work with the Toolkit Collaborative Component sample program.
You can download the IBM Lotus Workplace Products API Toolkit from this Web site:
http://www.lotus.com/ldd/lwpapi
3.2.1 Lotus Workplace APIs Overview
The public Workplace APIs enable developers to do the following:
1. Access Workplace services or content from an external system
You can integrate the corporate Help Desk system with Lotus Workplace Messaging.
2. Access external services or content from Workplace
For example, you can create a portlet that displays data from the internal trouble ticket
database, and incorporate that portlet in a new team space application that also includes
the discussion portlet.
3. Extend and enhance the capabilities of Workplace
Use an API to create a small quick mail portlet to send mail without taking up as much
screen space as the Workplace mail portlet, or scan all e-mail messages for viruses
before delivering them to users.
44
Building a Component for IBM Workplace
4. Manage Workplace applications and application templates
You can manage Workplace applications on demand, manage applications across an
organization, or migrate applications from other systems to the Workplace platform.
The Workplace 2.0 platform provides the following APIs and SPIs:
򐂰
򐂰
򐂰
򐂰
Collaborative Application Component Interfaces
Workplace Mail Messaging SPI
Workplace Instant Messaging SPI
Workplace JSP tags
The Workplace 2.5 API Toolkit 2.5 adds the following APIs:
򐂰 Component Services API
򐂰 Application Infrastructure Services API
򐂰 IBM Workplace Client Technology (WCT) APIs
Use the IBM Lotus Workplace Products API Toolkit to distribute the public APIs to your
customers and business partners. The Toolkit includes documentation, samples, and, in
some cases, binaries for the APIs. Note that there are no public APIs for Workplace releases
before 2.0.
Note also that the IBM Workplace Client Technology 2.5 platform supports the Component
Services API, and provides additional APIs that expose the platform's unique capabilities.
The Workplace Client Technology APIs are not covered in this Redpaper.
The following sections describe each API and the IBM Lotus Workplace Products API Toolkit
in more detail.
3.2.2 Collaborative Application Component Interfaces
The Collaborative Application Component Interfaces enable developers to build business
components that can integrate with the Workplace collaborative environment and be used in
Workplace application templates, and ultimately, applications.
The Collaborative Application Component Interfaces are Java interfaces that a business
component developer implements in a stateless session EJB, called the collaborative
application component EJB. The interfaces allow Workplace to interact with the component.
There are several parts of this interface, but one example that could be developed is
discussed in detail in Chapter 4., “Building a Component for IBM Workplace” on page 55. In
that chapter, we discuss how to create a Lotus Workplace application using the Collaborative
Application Component Interface APIs. We create a Domino Discussion application, which
allows users to use a Domino discussion database inside a Lotus Workplace application.
Each Domino Discussion application will have its own Domino discussion database. The
Domino discussion database is created and maintained in Domino and is therefore
accessible through both Lotus Workplace and the Lotus Notes client.
To make use of these features, it is necessary to create a collaborative component. This
component is essentially a stateless session EJB that implements one of the Collaborative
Application Component Interfaces.
The Collaborative Application Component Interface methods are essentially callbacks from
Lotus Workplace to your component. They make it possible for your component to describe
itself to Lotus Workplace so that it can be intelligently managed by the environment,
configured by the user, and used in a template with other components.
Chapter 3. Introduction to application development in Lotus Workplace
45
To make your component collaborative, you implement any or all of the following interfaces in
your component’s collaborative component EJB. If you implement any of these interfaces, you
must implement the Life cycle interface.
The interfaces are described in the next sections.
Lifecycle
Use the Lifecycle interface to notify the component when an instance of that component is
created or destroyed, for example, when an application containing the component is created
or deleted, or when the component is added to a template. This allows the component to
create and destroy any resources needed while the application is running.
Membership
Use the Membership interface to notify the component when members are added to or
removed from community roles, and to get information about roles specific to the component.
This allows the component to grant or revoke member access to resources it manages. The
information the component provides about its own roles is used to map community roles to
component roles.
Sensor
Use the Sensor interface to get information about resources managed by the component, for
example, disk space usage, creation date, last modification date, and so forth. This
information is used, for example, to enforce Workplace policies that limit the amount of disk
space an application can use.
Templatable
Serialize the component to the application template's XML representation, and get
information about component parameters with the Templatable.
Transactional
Determine whether or not the component supports global transactions with the Transactional
interface. The Lifecycle and Membership interfaces both extend Transactional.
Note that the collaborative application component EJB not required to implement all of these
interfaces, only the ones needed by the business component. If the business component
does not need any of the interfaces, the collaborative application component EJB is not
required.
Refer to the example application created in Chapter 4., “Building a Component for IBM
Workplace” on page 55, which provides further detail on use of the Collaborative Application
Component APIs.
3.2.3 Component Services API
The Component Services API, which will first appear in the IBM Lotus Workplace API Toolkit
2.5 release, will enable developers to access services and content provided by the Workplace
business components.
Calendar
You can work with Calendar through the Component Services API and perform the following
functions:
򐂰 Create, delete, and modify calendar entries
򐂰 Schedule, cancel, reschedule meetings
46
Building a Component for IBM Workplace
Discussion
In the Discussion component, you can:
򐂰 Create, delete, and modify forums and postings
򐂰 Search and navigate forums
Document Library
From the Document Library, you can:
򐂰 Create, delete, and modify documents and folders
򐂰 Search and navigate documents
Mail
From the Mail component, you can:
򐂰 Create, delete, and modify messages, folders, and attachments
򐂰 Send mail
Web Conferencing
With Web Conferences, you can:
򐂰 Create, delete, and modify Web conferences
򐂰 Schedule, cancel, reschedule Web conferences
The services exposed by the Component Services API are implemented in the service tier of
the Workplace architecture, using stateless session EJBs. The EJB interfaces, as well as the
data objects they use, can be accessed using either Java or Web services. The Java API
exposes interfaces only, no classes (with a few exceptions), so that the API implementation
can change while retaining both source and binary compatibility with existing applications.
The general usage pattern for the Component Services API is summarized as follows:
1. The application locates the desired EJB or Web service. The Java API provides service
delegates used to access the EJB interfaces. Applications do not need to deal directly with
the EJBs.
2. The application invokes the appropriate method or service to request data or perform a
service such as send mail.
3. If data was requested, the application manipulates the data as needed, then invokes the
appropriate method or service to apply changes to the appropriate data stores.
The Component Services API will provide a number of data retrieval options that enable the
application to control how much data is transferred with each request. For example, when
accessing mail messages, the application can request all mail folders without any of the
messages they contain. Similarly, the application can request all of the messages in a
particular folder, but only the mail header information for each message, because that's all the
application requires. These options also allow the application to optimize data transfer based
on the available network bandwidth. Some of these capabilities will be available in the API
Toolkit 2.5 release. Others will be provided in future releases.
Because the Component Services API is implemented using EJBs, access to API methods is
managed by the EJB container, and requires the context of an authenticated user. In addition,
the Component Services API enforces Workplace and Portal access control as well as user
policies.
Chapter 3. Introduction to application development in Lotus Workplace
47
For more information about the Component Services API, refer to IBM Lotus Workplace API
Toolkit 2.5 release, when it becomes available. Note that the API Toolkit 1.0 release includes
preliminary Javadoc for the Component Services API, which will change for the final Toolkit
2.5 release.
3.2.4 Application Infrastructure Services API
The Application Infrastructure Services API enables developers to create, delete, and
manage Workplace applications and application templates.
The Application Infrastructure Services API provides the following services:
򐂰 Access application and template catalogs
򐂰 Create and modify applications and templates
򐂰 Manage application instances
The Application Infrastructure Services API and Component Services API share the same
architecture and usage characteristics. They differ only in the types of services they provide.
For more information about the Application Infrastructure Services API, refer to the IBM Lotus
Workplace API Toolkit 2.5 release when it becomes available.
3.2.5 Workplace Mail Messaging SPI
The Workplace Mail Messaging Java SPI enables developers to build e-mail message
handlers that intercept mail messages before delivery, and optionally block or redirect them or
modify message content. Message handlers can perform virus scanning, active content
filtering, spam filtering, or any other desired filtering operations. Message handlers are
installed as extensions to the Workplace mailbox service.
With the Mail Messaging SPI, a developer can create components that interact with the
messaging system of Workplace. For example, the developer can build applications that
redirect mail as it is routed. A typical application built with this SPI is a spam filter that lets you
block mail before it gets to the recipient’s inbox. Also you could develop a virus scanner for
incoming email using this SPI.
There are two specific interfaces a Java developer can work with, a handler and deliverer
interface. A handler looks at the message as it passes through the mail services. Your
component can then make decisions based on the content of that envelope. The handler can
then choose to either delete or move that mail to another part of the system before that mail
reaches a user’s inbox. A handler can also reject mail so it will not be delivered.
There are numerous interfaces to work with and the Information Center has more information
about these Interfaces. Use the following steps as a guideline to build a component that uses
these interfaces:
1.
2.
3.
4.
5.
Set the correct classpath so that code can use the required Mail Messaging SPI.jar files.
Write the extension code.
Register the mail processing extension.
Configure the mail processing extension.
Run the mail processing extension.
Note: The Workplace Mail Messaging SPI is included with Lotus Workplace Messaging
2.0, but documented in the Lotus Workplace API 1.0 Toolkit.
48
Building a Component for IBM Workplace
3.2.6 Lotus Workplace Instant Messaging SPI
The Lotus Workplace Instant Messaging Java Security Policy Index (SPI) enables developers
to intercept instant messages before delivery, and, optionally, block them or modify their
content. Message handlers can log or save messages, translate them, or perform any other
operations.
In Lotus Workplace 2.0, instant message handlers are implemented as Java components that
run in the same JVM as the WebSphere Portal server, for example, servlets or WebSphere
services.
The Workplace Instant Messaging API allows the developer to create components that
intercept Instant Messages before they are delivered to the recipient. An example of using
this SPI would be to build a component that logged all instant message conversations.
Another example would be an application that stopped messages that contained certain
words or phrases from being delivered based on a set of rules.
The Instant Messaging SPI is part of the presence and instant messaging services of Lotus
Workplace 2.0.1. The SPI is reachable via a servlet installed on the WebSphere Portal server.
The Instant Messaging SPI includes the following classes:
򐂰 MessagingListener
This interface receives events for each message going through the Session Initiation
Protocol (SIP) server.
򐂰 MessagingService
This interface is used to manage all MessagingListener instances.
򐂰 MessagingServiceFactory
This class is used to get an instance of a MessagingService object.
򐂰 Contact
This class represents a SIP contact. It is used to examine the contacts to whom messages
are being sent. For example usage, see ChatLoggingApp.java, the sample program
included in this toolkit (in lwpapi10\imspi\samples\chatlogging).
3.2.7 Lotus Workplace JSP tags
The JSP tags for Lotus Workplace are one type of Collaborative Component that allow
developers who write portlets for WebSphere Portal or other application servers to add Lotus
collaborative functionality to their portlets.
The Lotus Workplace JSP tags are included with IBM Lotus Workplace Team Collaboration
2.0. The Lotus Workplace API Toolkit provides documentation for the following JSP tags:
򐂰 Person tag,
򐂰 OnlineCenter tag
Person tag
Lotus Workplace introduced a new custom JSP tag called the Person Tag which renders a
live name on the page. The PersonTag is used in many Workplace portlets, and is also
available to third-party portlets. It automatically offers a number of rich interaction possibilities
with the other Workplace elements in a portal.
This tag is used for creating people awareness in your application. The Person tag provides
contextual collaboration functionality related to a named person. You can use the tag to
generate a link menu of collaborative actions, such as sending e-mail to a person. Future
Chapter 3. Introduction to application development in Lotus Workplace
49
work on the Person tag will concentrate on improved performance through LDAP caching,
and possibly on extended features.
The Person tags generate HTML and require Java and JavaScript to be enabled on the client.
Tip: For complete information about the Person tag and how it works with other related
JSP tags such as the Menu tag, refer to the documentation provided in the IBM
WebSphere Portal Information Center:
http://publib.boulder.ibm.com/pvc/wp/500/ent/en/InfoCenter/index.html
OnlineCenter tag
The OnlineCenter tag is required to provide presence awareness. It is already embedded at
the top of the page in the Lotus Workplace theme, but if you create a portlet in a pop-up
window, you need this tag in order to have presence awareness on the page. The Person tag
will not provide awareness in pop-up windows unless this tag is used. From the Online
Center, the user can change his or her online status and also open the Customize Status
pop-up to change the status message that other people see in the Person tag menu and in
their hover help text.
3.3 Domino integration
Lotus Workplace is a powerful platform for building new collaborative applications. Just like
Lotus Domino, the real value of the platform is in the ability of developers to build applications
that leverage and extend the collaborative abilities offered by the platform.
Just as there are several techniques for integrating Domino applications with WebSphere
Portal, there are several ways to approach integration with Lotus Workplace. We start by
looking at some simple ways to deploy a portlet into Workplace. We then move on to some
more advanced integration techniques using the Lotus Workplace Products API Toolkit.
Tip: Lotus Workplace is built on top of WebSphere Portal. So from an integration
development point of view, anything that you have constructed for WebSphere Portal is
able to be integrated into Lotus Workplace without change. The techniques and methods
we have covered for WebSphere Portal are valid and can be used in exactly the same way
in Lotus Workplace.
This makes Lotus Workplace a powerful environment for integrating Domino applications. We
cannot only leverage the infrastructure provided by WebSphere Portal, but now also integrate
and leverage the components that Lotus Workplace makes available.
Many organizations have made a strategic decision to use J2EE as the platform for their
business applications due to the open standards, scalability, flexibility, and open integration
capabilities it provides. They are left wondering how their current Domino infrastructure and
existing investments in deployed Notes and Domino applications will fit into their future IT
infrastructure. With Lotus Workplace, not only can our Domino applications use services at
the portal level, but now can be extended to the Workplace level.
However, at the same time, we can choose to use only the portal level and know that our
applications will work perfectly well in Lotus Workplace.
The important point is if it works on WebSphere Portal, then it will work on Lotus Workplace.
50
Building a Component for IBM Workplace
3.3.1 Adding Workplace Portlets to Domino Portlets
Perhaps the simplest and easiest way to have integration between Domino and Lotus
Workplace is to use the existing Lotus Workplace portlets with your Domino portlets to create
an integration application.
There are portlets within Lotus Workplace that can add value to a Domino application.
Imagine that it might be useful to have a user’s Lotus Workplace calender beside a custom
Domino meetings minutes database so the user can simply switch portlets and pencil a
meeting into their calender. This is a simplistic example of what is possible, but it would be
very easy to deploy Domino portlets to Lotus Workplace and build many such pages and
applications. Again the important point is that if it works in WebSphere Portal, it will work in
Lotus Workplace.
3.3.2 Domino Integration using Lotus Workplace JSP tags
As we write this paper, the JSP tags provide the most practical way of integrating Domino and
Workplace using the API. With the 1.0 release of the API it is possible to make use of the
collaborative components within Lotus Workplace to bring people awareness to a portlet and
give a user control of their online status.
Person tag
The Person tag displays a list of actions that can be performed when integrated with the
Lotus Workplace collaboration feature set. This tag automatically renders all the html required
for a user to perform those actions. Some examples of the actions that can be performed are:
򐂰
򐂰
򐂰
򐂰
򐂰
Send E-mail
Chat
Add to a Contact List
Show Profile
Find Documents Authored By
3.3.3 The portalizing process
Before talking about the term portalizing, we need to establish a common understanding of
the meaning of this term. Portalizing means the act of transforming an otherwise
free-standing application for use as a WebSphere Portal.
A Domino application can be represented by a single portlet, but there is usually not a
one-to-one relationship between applications and portlets. Most cases exhibit a one-to-many
relationship. Portal applications are usually made up of multiple portlets that use portlet
cooperation. By doing this, application functionality exposed in portlets can be combined in
many different ways, sometimes allowing the user to put information in a context that not
even the developer of the individual portlet has thought about.
It is also important to understand that the same portlet can be used in different Workplace
contexts with different user roles.
3.3.4 When to use a specific integration approach
Depending on the solution, a combination of several options will be the best case. So if
portlets built by the IBM Portlet Builder for Domino should be fine-tuned, it might be
necessary to use Domino JSP tags and the Domino Java API.
򐂰 Existing portlets
Chapter 3. Introduction to application development in Lotus Workplace
51
– To use existing portlets, no J2EE knowledge is necessary. The portlet can be selected
from the portlet catalog.
– Only simple information, Domino Server name, database name, and so on, need be
entered.
– Existing portlets offer only a very limited set of functionality for customizing.
– Existing portlets will be used by line-of-business and power users.
򐂰 Lotus Workplace Builder
– The Lotus Workplace Builder offers the user with limited J2EE knowledge the
possibility to integrate a set of portlets into Lotus Workplace.
– Only simple information must be provided to build the Workplace content.
– The Lotus Workplace Builder will be used by line-of-business and power users.
򐂰 IBM Portlet Builder for Domino
– The IBM Portlet Builder for Domino provides a complete and rapid integration tool to
bring valuable Domino-based information and data into WebSphere Portal.
– It is a portlet that creates other portlets that are tuned to specific tasks, databases, or
sets of databases.
– IBM Portlet Builder is a subset of WebSphere Portal Application Integrator technology.
– The target audience are line-of-business and power users.
򐂰 Bowstreet Portlet Factory
– The Bowstreet Portlet Factory is a third-party portlet building tool. It is comparable to
the IBM Portlet Builder for Domino, but has more possibilities for building and profiling
portlets.
– The target audience are line-of-business and power users, and developers who want
to reduce time in creating portlets.
򐂰 Domino JSP tags
The Lotus Domino Toolkit for WebSphere Studio is a plug-in for WebSphere Studio
Application Developer and WebSphere Studio Site Developer. It allows you to add Domino
6 custom tags to Java server pages (JSP), providing a simple way to blend Domino and
J2EE applications.
JSP tags are XML tags embedded in a JSP providing data access, data input, and
process control. The tags abstract the Domino objects for Java (Domino Java API) and
provide a quick development turnaround for building J2EE applications that use Domino
data and services
Domino JSP tags can be used for building portlets alone or to extend portlets created with
a builder.
The target audience are Java language developers and Domino developers with Java
language skills.
򐂰 APIs
– There are many APIs that can be used to create portlets for accessing Domino data.
– The target audience are Java language developers and Domino developers with
strong Java language skills.
b
Tip: For more information about Portalizing Domino Applications, refer to Portalizing
Domino Applications: Integration with Portal 5.02 and Lotus Workplace 2.0.1, SG24-6466.
http://www.redbooks.ibm.com/redpieces/abstracts/sg246466.html
52
Building a Component for IBM Workplace
3.4 Summary
IBM’s componentized approach to development makes it easier to assemble new custom
applications that meet the needs of a specific client or industry. It also makes it simple to keep
recombining those pieces in different ways to create many different solutions.This
componentization model means more efficient application development, and faster
development cycles due to the reusability of components. This means an increased quality of
applications and enhanced developer productivity.
Lotus Workplace portlets make excellent building blocks for customized portals and can
interact with third-party portlets through several mechanisms. Aggregating custom portlets
with Workplace portlets is a starting point for useful portal-based applications. The additional
communication features available through Click-to-Action and the community-centric features
exposed by the Person Tag and the People Finder make an array of rich features available
with little, sometimes very little, effort on the part of the non-Workplace elements.
In this section, we discussed the different techniques for creating components for use in Lotus
Workplace applications. There are many scenarios for creating Lotus Workplace
components. The simplest scenario is to combine the existing Lotus Workplace components
with other non-Workplace portlets, using the aggregation and communication features offered
by WebSphere Portal and using technologies such as Java Server Faces, Struts, WebSphere
Portal Portlet’s API and others discussed in this section. For developers wanting to create
new, custom components using the Lotus Workplace API toolkit, this chapter provided an
overview of the APIs and SPIs currently available for Lotus Workplace.
The next chapter contains an example of how to create a new business component using the
Collaborative Application Component Interface API.
Chapter 3. Introduction to application development in Lotus Workplace
53
54
Building a Component for IBM Workplace
4
Chapter 4.
Building a Component for IBM
Workplace
This chapter describes the creation, editing and customization of a Lotus Workplace
Application. In this chapter we show how we approached the creation of a Lotus Workplace
application, and how we created a custom component using the Lotus Workplace
Collaborative Application Component Interfaces.
In this chapter, we show you how to:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
Set up the development environment.
Design an application.
Create the required pieces: the EJB, portlets, and so forth.
Export to Lotus Workplace.
Create a customized Workplace template containing the required pieces.
Create a new example application based on the template.
© Copyright IBM Corp. 2005. All rights reserved.
55
4.1 Overview
Lotus Workplace is more than a collection of collaborative applications. It is a platform for
building new collaborative applications and integrating with the Workplace applications
offered by Lotus. The success of Lotus Workplace, like any application platform, is driven by
the ability of Business Partners, ISVs, corporate developers, solutions providers, system
integrators, and so on, to build new Workplace applications, extend the IBM Lotus
applications to meet their needs, and integrate Workplace with other systems.
To construct this example application, you need:
򐂰 Java programming experience and an understanding of the J2EE programming model,
including how to build an Enterprise Java Bean (EJB).
򐂰 A basic understanding of creating a WebSphere Portal server portlet using WebSphere
Application Developer and understand the concepts of WebSphere Portal server
administration.
The first three chapters of this paper have sections that explain these concepts and provide
links to additional resources.
4.2 Overview of the Domino Discussion Application
We mentioned earlier in this paper that each Lotus Workplace application is visualized as a
portal place that contains a collection of pages. Each page contains a collection of portlets
configured to display a specific set of data.
In this chapter, we discuss how to create a Lotus Workplace application using the
Collaborative Application Component Interface APIs. We will create a Domino Discussion
application, which allows users to use a Domino discussion database inside a Lotus
Workplace application. Each Domino Discussion application will have its own Domino
discussion database. The Domino discussion database is created and maintained in Domino
and is, therefore, accessible through both Lotus Workplace and the Lotus Notes client.
Tip: For the purposes of this paper, we created a Lotus Workplace component
demonstrating Lotus Domino integration. It is important to note this integration can be
achieved with any existing enterprise application.
Figure 4-1 on page 57 shows a high level architectural view of the Domino Discussion
application. The process of building this application involves building two important pieces:
򐂰 Domino Discussion Component is the piece that integrates the Domino discussion
database into the Lotus Workplace application, UI and back-end. It is comprised of a
portlet and a collaborative component EJB.
򐂰 Domino Discussion Application Template represents the template that end users can use
to create a new Domino discussion application.
56
Building a Component for IBM Workplace
Web
Web Browser
Browser
Application HTML
<html>
…
</html>
<body>
…
Lotus
Lotus Workplace
Workplace
(WebSphere
(WebSphere Portal)
Portal)
Domino
Domino
Server
Server
Domino Discussion
Template
HTTP
Discussion Notes
Template
discsw6.ntf
Discussion Application Place n
Discussion Portlet HTML
Discussion Application Place 2
Discussion Notes
Databases
Discussion Application Place 1
Discussion Page
iFrame
discN.nsf
Domino Discussion
iFrame Portlet
PortletData
BcId=“disc1.nsf”
</body>
</html>
NCSO.jar
Templatable
Lifecycle
Membership
Sensor
Domino
Discussion
Collaborative
Component
EJB
IIOP
disc2.nsf
HTTP
disc1.nsf
Transactional
http://dominoserver/disc1.nsf?OpenDatabase
Figure 4-1 Conceptual overview of example application
Building the Domino Discussion Component is done within WebSphere Studio Application
Developer. It involves building two pieces: a portlet, and a collaborative component EJB.
In this design, the portlet renders a simple HTML iFrame that points to the appropriate
database in Domino through HTTP. The collaborative component EJB implements all the
appropriate Collaborative Component interfaces needed to integrate the component with the
Lotus Workplace Application services. The Domino Discussion Collaborative Component
uses the Domino IIOP Java API to communicate and manipulate Domino artifacts. After the
component is built, we show you how to import the Domino Discussion Component into Lotus
Workplace.
The next piece of work takes place within Lotus Workplace and results in building the Domino
Discussion Workplace template. The new template is based on the existing Discussion
template. This new template replaces the Lotus Workplace discussion component with the
new Domino discussion component described earlier. In each Domino Discussion application
created from the template, the Domino discussion portlet is configured to point to a new
Domino Database. This database is integrated into all aspects of the application. These
include membership management, application life cycle, policy enforcement, and template
management.
4.3 Building the Domino Discussion Component
In this section, we discuss the development of the Domino Discussion Component. We begin
by describing how to setup the development environment, in detail how to build both the
Domino Discussion portlet, and the Domino Discussion Collaborative Component EJB.
Finally, we describe how to package it, making it ready for deployment.
Chapter 4. Building a Component for IBM Workplace
57
4.3.1 Setting up the development environment
You can setup your development environment to support testing and debugging your portlets
on the local development machine or on a remote server. We used WebSphere Studio
Application Developer V5.1.2 with Portal Toolkit V5.0.2.2. If you have a version of Portal
Toolkit prior to V5.0, remove it before installing Portal Toolkit V5.0. Also, make sure
WebSphere Studio is installed, but not running, before installing Portal Toolkit. For the local
debug configuration, you also need to have the CD labeled Portal Server available.
Portal Toolkit provides wizards to help you build, test, and deploy portlets using all of the
APIs, related classes and interfaces available in the portlet runtime environment. You can
also build portlets using your own development environment and tools. If you are not using
wizards to develop portlets, the following topics describe the mechanics of building a simple
portlet. With Portal Toolkit Version 5.0, you can set up a portlet development environment by
plugging in to WebSphere Studio. Portal Toolkit provides:
򐂰 Portlet projects, in which you can create basic portlets based on the PortletAdapter class
򐂰 WebSphere Portal configuration, with which you can publish your portlet application on
your local WebSphere Portal or remote WebSphere Portal
Your portlet appears on the debug page of your WebSphere Portal.
򐂰 Portlet application examples for enterprise applications
Tip: For comprehensive instructions on using WebSphere Studio refer to WebSphere
Studio Application Developer Version 5 Programming Guide, SG24-6957.
http://www.redbooks.ibm.com/abstracts/sg246957.html
4.3.2 Configuring the Lotus Workplace API Toolkit in WSAD
Download the Lotus Workplace API toolkit 1.0 from:
http://www.lotus.com/ldd/lwpapi
This section provides instructions for setting the necessary classpath variables in WebSphere
Application Developer. To use the Lotus Workplace API toolkit, set two classpath variables.
Classpath variables are used to configure the classpath information needed for compiling
your code.
The two classpath variables used by the sample are LWPAPI_HOME and WAS_HOME.
򐂰 LWPAPI_HOME specifies the location of the top-level API Toolkit directory lwpapi10 and is
used to locate API jar files provided with the Toolkit. The lwpapi10 directory is created
under the directory into which you extracted the Toolkit zip file. For example, if you
extracted the API Toolkit files to c:\LwpApiToolkit, you would set the LWPAPI_HOME
classpath variable to c:\LwpApiToolkit\lwpapi10.
򐂰 WAS_HOME specifies the location of the WebSphere Application Server on which Lotus
Workplace is installed, and is used to locate WebSphere and Lotus Workplace jar files that
are needed to build and run the sample.
The necessary .jar files are the following:
򐂰 WAS_HOME\AppServer\lib\jdom.jar
򐂰 WAS_HOME\AppServer\lib\wmm.jar
򐂰 WAS_HOME\WorkplaceServer\ps_extdir\lwputil.jar
58
Building a Component for IBM Workplace
When you work with the Workplace API toolkit in WebSphere Application Developer to build
the sample component, you will need these jar files to be accessible from your development
system. You can use one of the following procedures to do this:
򐂰 Ask your Lotus Workplace server administrator to provide you with these jar files and
install them on your development system using the same AppServer and
WorkplaceServer directory structure shown above. If you use this option, set the
WAS_HOME classpath variable to the directory on your system that contains the
AppServer and WorkplaceServer subdirectories.
򐂰 If you install Lotus Workplace on your development system, set the WAS_HOME
classpath variable to the WebSphere program directory (for example, c:\WebSphere).
Important: Running both a Lotus Workplace server instance and WebSphere Application
Developer on the same machine is very expensive for both CPU and memory usage. It is
better to copy the required files to a local directory on your WebSphere Application
Developer development machine.
After installing the required jar files, use the following steps to set the classpath variables in
WebSphere Application Developer:
1. Select Window →Preferences from the menu.
2. Expand the Java entry in the list and select Classpath Variables.
3. Select the New button and enter LWPAPI_HOME in the Name field.
4. Enter the API Toolkit directory path in the Path field, or select the Folder button then
navigate to that directory and select OK.
5. Repeat steps 3 and 4 for the WAS_HOME classpath variable, using the appropriate path
value.
6. Select OK to exit the dialog boxes.
By using the above procedure, you will set the classpath variables needed to use the Lotus
Workplace API toolkit in WebSphere Application Developer.
4.3.3 Building the Domino Discussion Collaborative Component EJB
This section discusses how to build your own Domino Discussion Collaborative Component
using the Collaborative Application Component Interfaces. This is needed so that the
component integrates with the Lotus Workplace application services. A collaborative
component is built as a stateless session EJB that implements one or more of the
Collaborative Application Component Interfaces. The Collaborative Application Component
Interface methods are essentially callbacks from Lotus Workplace to your component.
In the Domino Discussion Component, we implement all the Collaborative Component
Interfaces. Before starting to build the Component we first import the Workplace API Toolkit
1.0 sample and modify it to become the Domino Discussion Collaborative Component.
Importing the API toolkit sample files into your workspace
The Collaborative Component Sample file that ships with the Lotus Workplace API Toolkit 1.0
includes specific files for WebSphere Application Developer that make it easy to work with the
sample code. Use the following steps to import the project files included with the sample into
your workspace:
1. Open the IBM WebSphere Studio Application Developer development environment.
Chapter 4. Building a Component for IBM Workplace
59
2. From the File menu, select Import, and select Existing Project into Workspace from the
list.
3. Select the Browse button and navigate to the Toolkit directory
lwpapi10\lwpapi\samples\CollabComponent\CollabComponentEJB.
4. Select Finish to import the project file into the workspace.
5. Repeat steps 2- 4 for each of the other directories in
lwpapi10\lwpapi\samples\CollabComponent.
Tip: As you import each project, you may see errors referencing portlet-api.jar, wps.jar and
wpsportlets.jar because different versions of WebSphere Portal server store their jars in
different locations. This causes build errors because the sample application includes all the
possible paths. Do the following to delete the files and resolve these errors:
1. Right-click CollabComponentPortlet.
2. Select Properties.
3. Select Java Build Path.
4. Click the Libraries tab. The three missing libraries will have a small exclamation point
(!) icon beside them.
5. Select the three missing jars and Remove.
By using the above procedure, you will import the Lotus Workplace API Toolkit sample files
into your WebSphere Studio workspace.
Setting the name of the sample Component
After you import the sample files, you can specify the name that Workplace Builder will
display to identify the sample component. The component name is set to Sample Business
Component, but you can change it to something more meaningful, as follows:
1. In WebSphere Application Developer, expand the CollabComponentAdapterEJB
project.
2. Expand the ejbModule tree until you see the file ejb.properties.
3. Double-click ejb.properties to open it in the editor.
4. Change the value of the component.display.name property to Domino Discussion
Database Component. Do not change any other properties.
5. Select File Save.
Adding the Notes Jar into your WebSphere Studio workspace
Domino objects can be manipulated in Java using the Domino Java API. The java archive
that contains the necessary implementations needed to access a remote Domino server
through IIOP is called NCSO.jar. This file is located in:
<domino data directory>\domino\java\ NCSO.jar
Copy this file locally to your development system so that it can be imported and used by your
component. After copying locally, do the following:
1. In WebSphere Application Developer, right-click the CollabComponentEAR project.
2. Select Import → Filesystem.
3. Type in the location of the NCSO.jar file in the From directory field, for example:
c:\Lotus\Domino\data\domino\java)
4. Find NCSO.jar from the list and select it.
5. Click Finish.
60
Building a Component for IBM Workplace
Next, add the NCSO.jar to the classpath of the CollabComponentEJB:
1. In WebSphere Application Developer, open or edit ejbModule/META-INF/MANIFEST.MF.
2. Under Dependencies Select NCSSO.jar.
3. Select File →Save.
Implementing the Collaborative Component Interfaces
The Collaborative Component Interfaces are implemented in the CollabComponentEJB, in a
file called CollabComponentBean.java. Edit this file and follow the instructions below to
create the Domino Discussion Collaborative Component EJB. Make sure you replace the
existing implementation with the code outlined in the next five sections.
Implementing the Collaborative Component Lifecycle Interface
The Lifecycle interface is used by Lotus Workplace to notify the application component
whenever an instance of that component needs to be created or destroyed. This happens
when an application containing that component is created or deleted, or when the component
is added to an application template. The component can use this information to create or
initialize resources needed while the component is active.
The Lifecycle Interface is implemented by a collaborative application component EJB. The
component can use this information to create or initialize resources needed while the
component is active. See Example 4-1.
Example 4-1 The Lifecycle Interface
public interface LifecycleLocal extends TransactionalLocal {
String createInstance(InstanceDescription description)
throws WorkplaceException;
void removeInstance(String instanceId)
throws WorkplaceException;
Table 4-1 explains the elements in the interface.
Table 4-1 Lifecycle Interface summary
Method
Description
java.lang.String
createInstance(InstanceDescription
description)
Called when an instance of this component
needs to be created
void removeInstance(java.lang.String id)
Called when an instance of this component
needs to be destroyed.
Example 4-2 on page 62 displays the code used in the Domino Collaborative Component
implementation. To build the domino discussion collaborative component EJB, the following
code needs to be added to the CollabComponentBean.java file. It represents some
constants, and adds a function that creates an IIOP connection to the server. When using this
code, update the Domino connection settings by changing the values of the SERVER_NAME,
SERVER_USER, and SERVER_PASSWORD variables.
In addition, add the following import statement to CollabComponentBean.java:
import lotus.domino.*;
Chapter 4. Building a Component for IBM Workplace
61
Example 4-2 Helper code for CollabComponentBean.java
final
final
final
final
final
final
final
static
static
static
static
static
static
static
private
private
private
private
private
private
private
String
String
String
String
String
String
String
ROLEID_MANAGER
ROLEID_DESIGNER
ROLEID_EDITOR
ROLEID_AUTHOR
ROLEID_READER
ROLEID_DEPOSITOR
ROLEID_NOACCESS
=
=
=
=
=
=
=
"MANAGER";
"DESIGNER";
"EDITOR";
"AUTHOR";
"READER";
"DEPOSITOR";
"NOACCESS";
final static private String VARIABLE_CATEGORIES
= "Categories";
final static private String VARIABLE_CATEGORIES_DEFAULT_VALUE = "Discussion";
final
final
final
final
final
static
static
static
static
static
private
private
private
private
private
String
String
String
String
String
DBNAME_PREFIX
DISCUSSION_TEMPLATE
DATABASE_TITLE
ALL_AUTHENTICATED_DN
ALL_AUTHENTICATED_DOMINO_DN
=
=
=
=
=
"LwpDiscussion";
"discsw6.ntf";
"Discussion Forum";
"All Authenticated";
"-Default-";
final static private String SERVER_NAME
= "localhost";
final static private String SERVER_USER
= "Domino Admin";
final static private String SERVER_PASSWORD = "password";
private Session getNotesSession( )
throws NotesException
{
Session s = NotesFactory.createSession( SERVER_NAME, SERVER_USER, SERVER_PASSWORD);
return s;
}
Use the code in Example 4-3 to implement the Lifecycle interface.
Example 4-3 Code to implement Lifecycle interface in the example application
public String createInstance( InstanceDescription instanceDescription)
throws WorkplaceException
{
// create a unique database name
String dbName = DBNAME_PREFIX + new Date( ).getTime( ) + ".nsf";
try {
// find and read the category names collected by the create UI
String categories = VARIABLE_CATEGORIES_DEFAULT_VALUE;
List vars = instanceDescription.getVariables( );
if( vars != null) {
Iterator iter = vars.iterator( );
while( iter.hasNext( )) {
Variable variable = (Variable) iter.next( );
if( variable.getName( ).equals( VARIABLE_CATEGORIES)) {
categories = variable.getStringValue( );
break;
}
}
}
// create a notes database using the DISCUSSION_TEMPLATE
Session s = getNotesSession( );
// get a handle to the template database
62
Building a Component for IBM Workplace
Database templateDb = s.getDatabase( null, DISCUSSION_TEMPLATE);
Database db = templateDb.createFromTemplate( null, dbName, true);
db.setTitle( DATABASE_TITLE);
// set the domino database categories
db.setCategories( categories);
}
catch( Exception e) {
e.printStackTrace( );
throw new WorkplaceException( e);
}
return dbName;
}
public void removeInstance(String dbName)
throws WorkplaceException
{
try {
// find the database and mark it for deletion
Session s = getNotesSession( );
Database db = s.getDatabase( null, dbName);
db.markForDelete( );
}
catch( Exception e) {
e.printStackTrace( );
throw new WorkplaceException( e);
}
}
Implementing the Collaborative Component Membership Interface
The Membership interface in Example 4-4, is used by Lotus Workplace to notify the
application component whenever members are added to or removed from the community
associated with the application. The component can use this information to grant or revoke
access to resources that it manages. In addition, the Membership interface allows the
component to provide Workplace with a list of component-specific roles, which can be
mapped to community roles using Workplace Builder.
Example 4-4 Membership Interface
public interface MembershipLocal extends TransactionalLocal {
DataObjectList getRoles(String instanceId)
throws WorkplaceException;
void addMembers(String instanceId, DataObjectList members)
throws WorkplaceException;
void removeMembers(String instanceId, DataObjectList members)
throws WorkplaceException;
}
Table 4-2 on page 64 explains some of the elements of the code.
Chapter 4. Building a Component for IBM Workplace
63
Table 4-2 Membership Interface summary
Element
Description
DataObjectList getRoles(String instanceId)
Returns the list of Roles supported by the object
represented by the instanceId
void addMembers(String instanceId,
DataObjectList members)
Called when new members are added to
application. The list of members has the
associated roles
void removeMembers(String instanceId,
DataObjectList members)
Called when members are removed from the
application.
Example 4-5 displays the code for the Domino Collaborative Component implementation.
Example 4-5 Code to implement Membership interface in the example application
public DataObjectList getRoles(String arg0) throws WorkplaceException {
// create a DataObjectList of Role objects
// each Role represents a domino ACL role
ApplicationComponentFactory factory =
FactoryCreator.createApplicationComponentFactory( );
DataObjectList retVal = factory.createDataObjectList( );
List roles = retVal.getObjects( );
// MANAGER
{
Role role = factory.createRole( );
role.setRoleId( ROLEID_MANAGER);
List descriptors = role.getRoleDescriptors( );
ObjectDescriptor descriptor = factory.createObjectDescriptor( );
descriptor.setName( "Manager" );
descriptor.setDescription( "Any user allowed to modify anything about the
database." );
descriptor.setLocaleString( Locale.US.toString( ));
descriptors.add( descriptor );
roles.add( role );
}
// DESIGNER
{
Role role = factory.createRole( );
role.setRoleId( ROLEID_DESIGNER);
List descriptors = role.getRoleDescriptors( );
ObjectDescriptor descriptor = factory.createObjectDescriptor( );
descriptor.setName( "Designer" );
descriptor.setDescription( "Any user allowed to modify the design of the
database." );
descriptor.setLocaleString( Locale.US.toString( ));
descriptors.add( descriptor );
roles.add( role );
}
// EDITOR
{
Role role = factory.createRole( );
role.setRoleId( ROLEID_EDITOR);
64
Building a Component for IBM Workplace
List descriptors = role.getRoleDescriptors( );
ObjectDescriptor descriptor = factory.createObjectDescriptor( );
descriptor.setName( "Editor" );
descriptor.setDescription( "Any user allowed to create and edit documents in a
database." );
descriptor.setLocaleString( Locale.US.toString( ));
descriptors.add( descriptor );
roles.add( role );
}
// AUTHOR
{
Role role = factory.createRole( );
role.setRoleId( ROLEID_AUTHOR);
List descriptors = role.getRoleDescriptors( );
ObjectDescriptor descriptor = factory.createObjectDescriptor( );
descriptor.setName( "Author" );
descriptor.setDescription( "Users who need to contribute documents to a
database." );
descriptor.setLocaleString( Locale.US.toString( ));
descriptors.add( descriptor );
roles.add( role );
}
// READER
{
Role role = factory.createRole( );
role.setRoleId( ROLEID_READER);
List descriptors = role.getRoleDescriptors( );
ObjectDescriptor descriptor = factory.createObjectDescriptor( );
descriptor.setName( "Reader" );
descriptor.setDescription( "Users who only need to read documents in a
database, but not create or edit documents." );
descriptor.setLocaleString( Locale.US.toString( ));
descriptors.add( descriptor );
roles.add( role );
}
// DESPOSITOR
{
Role role = factory.createRole( );
role.setRoleId( ROLEID_DEPOSITOR);
List descriptors = role.getRoleDescriptors( );
ObjectDescriptor descriptor = factory.createObjectDescriptor( );
descriptor.setName( "Depositor" );
descriptor.setDescription( "Users who only need to contribute documents, but
who do not need to read or edit their own or other users\' documents." );
descriptor.setLocaleString( Locale.US.toString( ));
descriptors.add( descriptor );
roles.add( role );
}
// NOACCESS
{
Role role = factory.createRole( );
role.setRoleId( ROLEID_NOACCESS);
Chapter 4. Building a Component for IBM Workplace
65
List descriptors = role.getRoleDescriptors( );
ObjectDescriptor descriptor = factory.createObjectDescriptor( );
descriptor.setName( "No Access" );
descriptor.setDescription( "Disallow access to the database." );
descriptor.setLocaleString( Locale.US.toString( ));
descriptors.add( descriptor );
roles.add( role );
}
return retVal;
}
public void addMembers( String dbName, DataObjectList members) throws
WorkplaceException
{
try {
Session s = getNotesSession( );
Database db = s.getDatabase( null, dbName);
ACL acl = db.getACL( );
List memberList = members.getObjects( );
for ( int i = 0; i < memberList.size( ); i++ ) {
MemberRoles memberRoles = (MemberRoles) memberList.get( i );
Role role = (Role) memberRoles.getRoles( ).get( 0);
Member member = memberRoles.getMember( );
int level = ACL.LEVEL_NOACCESS;
if( role.getRoleId( ).equals( ROLEID_MANAGER)) {
level = ACL.LEVEL_MANAGER;
}
else if( role.getRoleId( ).equals( ROLEID_DESIGNER)) {
level = ACL.LEVEL_DESIGNER;
}
else if( role.getRoleId( ).equals( ROLEID_EDITOR)) {
level = ACL.LEVEL_EDITOR;
}
else if( role.getRoleId( ).equals( ROLEID_AUTHOR)) {
level = ACL.LEVEL_AUTHOR;
}
else if( role.getRoleId( ).equals( ROLEID_READER)) {
level = ACL.LEVEL_READER;
}
else if( role.getRoleId( ).equals( ROLEID_DEPOSITOR)) {
level = ACL.LEVEL_DEPOSITOR;
}
else if( role.getRoleId( ).equals( ROLEID_NOACCESS)) {
level = ACL.LEVEL_NOACCESS;
}
// Deal with all authenticated users case
// All Authenticated maps to the ACL name "-Default-"
String dn = member.getDistinguishedName( );
if( dn.equals( ALL_AUTHENTICATED_DN)) {
dn = ALL_AUTHENTICATED_DOMINO_DN;
}
66
Building a Component for IBM Workplace
// create the ACL entry if it is not found
ACLEntry aclEntry = acl.getEntry( dn);
if( aclEntry == null) {
aclEntry = acl.createACLEntry( dn, level);
}
else {
aclEntry.setLevel( level);
}
}
// save the ACL list
acl.save( );
}
catch( Exception e) {
e.printStackTrace( );
throw new WorkplaceException( e);
}
}
public void removeMembers(String dbName, DataObjectList members) throws
WorkplaceException
{
try {
Session s = getNotesSession( );
Database db = s.getDatabase( null, dbName);
ACL acl = db.getACL( );
List memberList = members.getObjects( );
for ( int i = 0; i < memberList.size( ); i++ ) {
MemberRoles memberRoles = (MemberRoles) memberList.get( i );
Member member = memberRoles.getMember( );
String dn = member.getDistinguishedName( );
// Deal with the All Authenticated Users case
// -Default- can not be deleted
if( dn.equals( ALL_AUTHENTICATED_DN)) {
dn = ALL_AUTHENTICATED_DOMINO_DN;
ACLEntry aclEntry = acl.getEntry( dn);
if( aclEntry != null) {
aclEntry.setLevel( ACL.LEVEL_NOACCESS);
}
}
else {
ACLEntry aclEntry = acl.getEntry( dn);
if( aclEntry != null) {
aclEntry.remove( );
}
}
}
acl.save( );
}
catch( Exception e) {
e.printStackTrace( );
throw new WorkplaceException( e);
}
}
Chapter 4. Building a Component for IBM Workplace
67
Implementing the Collaborative Component Templatable Interface
Lotus Workplace uses the Templatable interface to incorporate the application component in
an application template. This interface allows the component to save information about itself
when the template is saved in XML format.
The Templatable interface code in Example 4-6, is implemented by a collaborative application
component EJB.
Example 4-6 Templatable Interface code
public interface TemplatableLocal {
InstanceDescription describeInstance(String instanceId)
throws WorkplaceException;
DataObjectList getVariables(String instanceId)
throws WorkplaceException;
}
Table 4-3 shows a description of the elements.
Table 4-3 Templatable Interface summary
InstanceDescription describeInstance(String
instanceId)
Returns and InstanceDescription which includes
template related information such as variables
collected at instantiation.
DataObjectList getVariables(String instanceId)
Returns the variables to be collected at
instantiation.
Example 4-7 shows the code used in the Domino Collaborative Component implementation:
Example 4-7 Code to implement Templatable interface in the example application
public InstanceDescription describeInstance( String dbName) throws WorkplaceException
{
ApplicationComponentFactory factory =
FactoryCreator.createApplicationComponentFactory( );
InstanceDescription retVal = factory.createInstanceDescription( );
try {
retVal.setContextData( "");
DataObjectList doVariables = getVariables( dbName);
List listVariables = doVariables.getObjects( );
retVal.getVariables( ).addAll( listVariables);
}
catch ( Exception e) {
throw new WorkplaceException( e );
}
return retVal;
}
public DataObjectList getVariables( String dbName) throws WorkplaceException
{
ApplicationComponentFactory factory =
FactoryCreator.createApplicationComponentFactory( );
DataObjectList retVal = factory.createDataObjectList( );
68
Building a Component for IBM Workplace
List variables = retVal.getObjects( );
// Database Category
{
Variable variable = factory.createVariable( );
variable.setName( VARIABLE_CATEGORIES);
variable.setStringValue( VARIABLE_CATEGORIES_DEFAULT_VALUE);
variable.setDescription( "You can enter the list of categories under which you
would like the database to appear in the Domino database catalog." );
variable.setPrompt( "Please enter the list of domino database categories for
this discussion?" );
variables.add( variable);
}
return retVal;
}
Implementing the Collaborative Component Sensor Interface
Lotus Workplace uses the Sensor Interface to incorporate the application component in an
application template. This interface allows the component to save information about itself
when the template is saved in XML format.
The Sensor Interface (Example 4-8) is used to get information about resources managed by
the component, for example, disk space usage, creation date, last modification date, and so
on. This information is used, for example, to enforce Workplace policies that limit the amount
of disk space an application can use.
Example 4-8 Sensor Interface
public interface SensorLocal {
public DataObjectList getSensorValues(String bcId)
throws WorkplaceException;
}
Table 4-4 explains the elements of the Sensor Interface.
Table 4-4 Sensor Interface summary
Element
Description
DataObjectList getSensorValues(String bcId)
Returns information about the object that has the
id bcId
Example 4-9 displays the code used in the Domino Collaborative Component
implementation:
Example 4-9 Code to implement Sensor interface in the example application
public DataObjectList getSensorValues(String dbName) throws WorkplaceException
{
//Get the factory
ApplicationComponentFactory factory =
FactoryCreator.createApplicationComponentFactory( );
DataObjectList retVal = factory.createDataObjectList( );
List attributes = retVal.getObjects( );
Chapter 4. Building a Component for IBM Workplace
69
try {
Session s = getNotesSession( );
Database db = s.getDatabase( null, dbName);
Date created = db.getCreated( ).toJavaDate( );
Date modified = db.getLastModified( ).toJavaDate( );
long size = (long)db.getSize( );
Attribute createdAtt = factory.createAttribute( );
createdAtt.setDateValue( created );
createdAtt.setName( SensorLocal.CREATED_DATE );
attributes.add( createdAtt );
Attribute modifiedAtt = factory.createAttribute( );
modifiedAtt.setDateValue( modified );
modifiedAtt.setName( SensorLocal.LAST_MODIFIED_DATE );
attributes.add( modifiedAtt );
Attribute sizeAtt = factory.createAttribute( );
sizeAtt.setLongValue( size );
sizeAtt.setName( SensorLocal.SIZE_BYTES );
attributes.add( sizeAtt );
}
catch (Exception e ) {
throw new WorkplaceException( e );
}
return retVal;
}
Implementing the Collaborative Component Transactional Interface
The Transactional interface is used to determine whether or not the component supports
global transactions (XA). The Lifecycle and Membership interfaces both extend
Transactional.
public interface TransactionalLocal {
public boolean isTransactional( );
}
Table 4-5 shows a description of the code element.
Table 4-5 Method Summary
Element
Description
boolean isTransactional( )
Returns true if the component supports Global
Transactions. False if the component manages its
own transaction.
Example 4-10 displays the code for the Domino Collaborative Component implementation:
Example 4-10 Code to implement Transactional interface in the example application
public boolean isTransactional( )
{
return false;
}
70
Building a Component for IBM Workplace
4.3.4 Building the Domino Discussion Portlet
The Domino Discussion Portlet in Example 4-11 is a very simple portlet that will produce the
following HTML:
Example 4-11 Domino Discussion portlet HTML
<DIV style="margin: 6px">
<IFRAME SRC="/<discussion database name>?OpenDatabase" WIDTH=100% HEIGHT=700></IFRAME>
</DIV>
In Example 4-7 the Domino server name is assumed to be on the same system as the Lotus
Workplace server. The discussion database name is the name (with the path) of the Domino
Discussion database.
The HTML in Example 4-11 will create an HTML iFrame and point it to the Domino HTTP
server. The Domino server will return the HTML markup for the Discussion Database in this
iFrame.
In Lotus Workplace, the value returned from the createInstance method will be stored in the
portlet's PortletData object in a variable call BcId. In the Domino Database component, the
create instance returns the database name. Therefore, the value of BcId can be used to
create a URL to the Domino server.
To create a new Portlet that displays the HTML in Example 4-11, do the following:
1.
2.
3.
4.
5.
6.
7.
8.
Select File →New →Project.
Select Portlet Development and select Portlet Project.
Click Next.
Type DominoDiscussionProject for the Project name and accept all the defaults.
Click Next three times.
Change the Portlet Name to Domino Discussion Portlet.
Click Finish.
Edit the generated file and replace it with the code in Example 4-12. Make sure to switch
to the Source tab from Portlets in WebSphere Application Developer.
Example 4-12 WebContent/dominodiscussionportlet/jsp/html/DominoDiscussionPortletPortletView.jsp
<%@ page session="false" contentType="text/html" import="java.util.*,
org.apache.jetspeed.portlet.*"%>
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
<portletAPI:init/>
<%
PortletData pData = portletRequest.getData( );
String bcId = (String) pData.getAttribute( "BcId");
String url = "/" + bcId + "?OpenDatabase";
%>
<DIV style="margin: 6px">
<IFRAME SRC="<%=url%>" WIDTH=100% HEIGHT=700></IFRAME>
</DIV>
Chapter 4. Building a Component for IBM Workplace
71
4.3.5 Connecting the Portlet to the EJB
In the Lotus Workplace API, there are three code artifacts that need to be connected together
to make all the Workplace J2EE artifacts know about each other. Figure 4-2 shows how these
relationships work.
WAR
Domino Discussion Portlet
WP_BUSINESS_OBJECT
ejb/DominoDatabaseCollabAdatperEJBHome
EAR
JNDI = ejb/DominoDatabaseCollabAdapterEJBHome
CollabComponentAdapterEJB
ejb-ref
(ejb/CollabComponent)
CollabComponentEJB
JNDI = ejb/DominoDatabaseCollabEJBHome
Figure 4-2 Relationship of JNDI names in a Workplace Component
To connect the components together, you need to modify three xml files:
1. The first involves modifying the portlet's portlet.xml.
2. The second involves modifying the CollabComponentAdapterEJB ejb-jar.xml.
3. Finally, modify the CollabComponentEJB ejb-jar.xml.
To edit the Domino Discussion Portlet, do the following:
1.
2.
3.
4.
5.
6.
Navigate to the DominoDiscussionPortlet.
Edit the WebContent/WEB-INF/portlet.xml file.
Expand Concrete Portlet Application and click the expanded item.
Scroll down to Setting Parameters and click Add.
Change the new parameter to WP_BUSINESS_OBJECT.
Change the value to ejb/DominoDatabaseCollabAdapterEJBHome.
This should result in the addition of the following XML in Example 4-13 under the
concrete-portlet element.
Example 4-13 XML added under the concrete-portlet element
<config-param>
<param-name>WP_BUSINESS_OBJECT</param-name>
<param-value>ejb/DominoDatabaseCollabAdapterEJBHome</param-value>
</config-param>
To edit the CollabComponentEJB, do the following:
1. Navigate to CollabComponentEJB.
1.
2.
3.
4.
Edit ejbModule/META-INF/ejb-jar.xml.
Click the Beans tab.
Select CollabComponent.
Replace the JNDI name field under WebSphere Bindings with
ejb/DominoDatabaseCollabEJBHome.
To edit the CollabComponentAdapterEJB, do the following:
1. Navigate to CollabComponentAdapterEJB.
72
Building a Component for IBM Workplace
2. Edit the ejbModule/META-INF/ejb-jar.xml file.
3. Click the Beans tab.
4. Select Adapter.
5. Replace the JNDI name field under WebSphere Bindings with
ejb/DominoDatabaseCollabAdapterEJBHome.
6. Click the References tab.
7. Select Adapter → EjbLocalRef ejb/CollabComponent.
8. Replace the JNDI name field under WebSphere Bindings with
ejb/DominoDatabaseCollabEJBHome.
4.3.6 Naming the Domino Component EAR file
An additional step is needed to give the generated EAR file a name that matches its
definition. This requires modifying the application.xml of the CollabComponentEAR. To
modify this file, do the following:
1.
2.
3.
4.
Navigate to the CollabComponentEAR file.
Edit META-INF/application.xml.
Click the Overview tab.
Change the value of Display Name to Domino Discussion Component.
4.3.7 Removing unused code from the sample component
As part of the sample component, an unused EJB is part of the EAR file and it needs to be
removed. To remove the EJB, do the following:
1. Go to CollabComponentEAR.
2. Edit META-INF/application.xml.
3. Click the Module tab.
4. Select CollabComponentServiceEJB.jar and click Remove.
5. Remove the unused Projects:
a. Select the CollabComponentPortlet project.
b. Right-click and select Delete.
c. Click OK.
6. Repeat steps 5a through 5c for CollabComponentServiceEJB and
CollabComponentServiceEJBClient.
4.3.8 Generating the Installable Artifacts
This section provides instruction on how to use WebSphere Application Developer to
generate the .EAR and .WAR files that you need to deploy the example application. Before
you can deploy the example application, you have to export the required .EAR and .WAR
files.
After you are finished with all your changes, use the Rebuild All command on the
WebSphere Application Developer Project menu to rebuild all projects. You should see no
errors at this point. If you do see any other errors in your Tasks view, resolve them before
continuing. After you resolve any errors, use the following instructions to generate the sample
.EAR and .WAR files in WebSphere Application Developer.
Chapter 4. Building a Component for IBM Workplace
73
1. To generate the .EAR file for the sample EJBs, do the following:
a. Right-click the CollabComponentEJB project and select Generate →Deployment
and RMIC code.
b. Make sure all listed projects are selected and select Finish to generate the code.
c. Right-click the CollabComponentEAR project and select Export from the menu.
d. Select EAR file from the list.
e. Enter a destination path name, such as DominoDiscussion.ear, for the .EAR file.
f. Select Finish.
2. To generate the .WAR file for the sample portlet, do the following:
a. Right-click the DominoDiscussionPortlet project and select Export from the menu.
b. Select WAR file from the list.
c. Enter a destination path name for the .WAR file such as
DominoDiscussionPortlet.war.
d. Select Finish.
By using the above steps, you generate the .EAR and .WAR files that you need to deploy
your sample application.
4.4 Building the Domino Discussion Application Template
In this section, we discuss the development of the Domino Discussion Application Template.
We start by describing how to set up the development environment and then move on to how
to install the Domino Discussion Component. We then discuss building the Domino
discussion application template. Finally, we discuss how to create an application using this
template.
4.4.1 Setting up the environment
You can set up your development environment to test and debug your portlets on the local
development machine or on a remote server using Lotus Workplace 2.0.1 or IBM Workplace
Services Express 2.0. You need a Web browser and access to the local file system where the
server is installed.
Additionally, you need to install a Lotus Domino server version 6.5 and start both the DIIOP
and HTTP servers. In this deployment, single signon is configured between the Lotus
Workplace server and Lotus Domino server. Finally, both servers are running on the same
physical system.
The screen shots used throughout this section are taken from an IBM Workplace Services
Express 2.0 deployment.
Tip: Complete information about configuring single signon can be found in the following
books:
򐂰 Lotus Domino 6.5.1 and Extended Products Integration Guide, SG24-6357
http://www.redbooks.ibm.com/abstracts/sg246357.html
򐂰 Lotus Security Handbook, SG24-7017.
http://www.redbooks.ibm.com/abstracts/sg247017.html
74
Building a Component for IBM Workplace
4.4.2 Installing the Domino Discussion Component into Lotus Workplace
In this section, we discuss how to install the Domino Discussion Component.
Installing the EAR file
To install the Domino Component on the Lotus Workplace server, we begin by deploying the
sample .EAR file. This .EAR file contains the Collaborative Application Component Adapter
EJB, the Collaborative Application Component EJB, and the Collaborative Application
Component Service EJB. To install the .EAR file, do the following:
1. Copy the lwp20api10.jar and lwp20api10_impl.jar files from the Toolkit directory
lwpapi10\lwpapi\lib into the <WAS_HOME>\PortalServer\shared\app\lotusworkplacelib
directory on the target server. <WAS_HOME> is your WebSphere Application Server
program directory (for example, c:\WebSphere).
You only have to do this the once. If you do not have access to the file system of the
WebSphere server, ask your server administrator to deploy these jar files for you.
2. Stop and then restart LotusWorkplace_Server, WebSphere_Portal, and server1.
3. Run the WebSphere Administrative console of the target deployment machine by
browsing to http://machineName.subDomain.domain:9091/admin. Make sure that you
specify Port 9091. Console 9091 specifies the Portal Server where 9090 specifies the
Application Server.
4. Log in as a user with administrative privileges.
5. Click Applications-Install New Application in the left-hand panel. Make sure you select
a unique application name.
6. At the Preparing for the application installation screen under the Path selection, browse
your machine file system for the .EAR file that you generated from WebSphere Application
Developer, DominoDiscussion.ear, and then click Next. This specifies the .EAR that you
want to upload and install.
7. Click Next at the Generate Default Bindings pane.
8. Click Next at the Step 1: Provide options to perform the installation pane.
9. At the Step 5: Map modules to application servers pane, specify the WebSphere Portal
server from the Clusters and Servers list. Select all of the check boxes under Modules.
Click Apply and then Next when you have finished.
10.At the Step 6: Map security roles to users/groups pane, select the lwpUser check box
under Role. Click Next.
11.At the Step 7: Summary pane, click Next. You are now presented with a results pane.
12.When the results pane has completed and you see the ·...installed successfully·
message, click Save to Master Configuration.
13.At the Save screen, click Save.
14.Browse back to the Applications-Enterprise Applications link in the left-hand panel.
Click the check box next to the name of your newly installed application .EAR. Click Start
to start the application. By using the above procedure, you will have deployed the sample
.EAR file to the Lotus Workplace server.
Installing the Portlet
To install a portlet, a Web archive (WAR) file for the portlet must exist in a local directory. The
install process uploads the WAR file to the server, installs the portlet, adds it to the portlet
catalog and activates the portlet. Perform the following steps to install a portlet:
Chapter 4. Building a Component for IBM Workplace
75
1. Browse to Lotus Workplace using the following URL:
http://yourmachineName.yoursubDomain.yourdomain:9081/lwp/workplace.
2. Logon as a user with administrative privileges.
3. Go to the Workplace Administration user interface by clicking the Administration tab.
4. At the Workplace Administration user interface, click the Portlets selection in the left-hand
panel to expand it.
5. Click Install.
6. At the Install portlets screen, browse your machine file system for the portlet .WAR file
(DominoDiscussionPortlet.war) from WebSphere Application Developer. Click Next.
This specifies the portlet .WAR that you wish to upload and install.
7. In the Install portlets screen, you will see the message The following portlets will be
installed: followed by the name of your Domino Discussion Component portlet. Click
Install to install the portlet. This might take a few minutes.
8. At the results screen that appears after the portlet has installed, select Portlets-Manage
Applications from the left-hand panel. This will allow you to see a screen that will present
a list of all successfully installed portlets.
9. Use the following steps to change access control on the new portlet so that other users
can see it:
a. On the Portal Administration Page, click Access → Resource Permissions.
b. Select Portlets from the Resource Types list.
c. Find the sample portlet that you installed above, and click the Assign Access icon
(key icon) next to the portlet.
d. Add the permission all authenticated portal users, select Done and Save your
changes.
4.4.3 Building the Domino Discussion Application Template
All Workplace applications are based on templates. A template defines the Workplace
application, its pages, and the application components deployed on each page. You use
templates to create multiple applications that share a common structure. This section
provides step by step instructions for creating a Domino Discussion Application template.
Using the Workplace Builder, you can create and modify templates for Workplace
applications.
When working with Templates there are two areas in Lotus Workplace with which you
interact. They are:
򐂰 Workplace Template Library
The Workplace Template Library displays the list of templates. Workplace Template
Library allows users to create new templates, assign roles for template access (Editor or
User), delete templates, and modify the templates.
See Figure 4-3 on page 77.
76
Building a Component for IBM Workplace
Figure 4-3 Lotus Workplace 2.0.1 Template Library
򐂰 Lotus Workplace Builder
The Workplace Builder is used to edit an instance of an application or template. It allows
users to edit application or template properties, modify the page structures, modify the
application roles, and update the component parameters.
Figure 4-4 Workplace Builder
4.4.4 Building the Domino Discussion Application Template
In this section we create a new template for the Domino Application. In Lotus Workplace you
can create templates, using other templates as a starting point. Basing a new design on an
Chapter 4. Building a Component for IBM Workplace
77
existing one is a good model for building the Domino Application Template. We will start by
using the Discussion Template in Lotus Workplace.
To build the Dominio Discussion Application Template, do the following:
1. Browse to Lotus Workplace using the following URL:
http://yourmachineName.yoursubDomain.yourdomain:9081/lwp/workplace
2. Logon as a user with administrative privileges.
3. Navigate to the Template Library by clicking the Templates link in the action bar.
4. At the Workplace Template Library screen, click New.
5. At the New Workplace Template screen in Figure 4-5, fill in the form by providing the
information as described in the next steps.
a. Template name: Domino Discussion
b. Category: Team Space
c. Starting Point: Discussion
Figure 4-5 Creating the new Domino Discussion Workplace template
6. Click OK when you have finished. This might take a few minutes.
The next step is customizing the new template to include the Domino Discussion component.
We will replace the Lotus Workplace discussion component with the Domino Discussion
component. To this make this change, use the following steps:
1. In Workplace Builder, click Pages and Layouts from the left-hand panel.
2. At the Pages and Layouts screen, click the pencil icon on the right side of the page on the
Discussions line of the table displaying the available pages.
3. At the Page Content screen, click the trash can icon for the Discussion Forums portlet
and click OK.
4. Click Add Portlets.
5. At the new Page Content screen, type the name that you had given to the portlet into the
Search For field. In this case, it is Domino Discussion. Click Search to search for your
portlet name.
6. At the Search results screen, click the check box for your portlet. Click OK.
7. At the new Page Content screen displaying the name of your portlet, click Done.
78
Building a Component for IBM Workplace
The next step is customizing the new template to update the application roles and map them
to the appropriate roles in the domino discussion component.
1. In Workplace Builder, click Roles in the left-hand panel.
2. At the Roles screen, select the Moderator role.
3. At the Roles screen in Figure 4-6, make sure Moderator is mapped to Manager in the
Domino Discussion Component, DominoDatabaseCollabAdapterEJBHome.
Figure 4-6 Setting Moderators Roles for new Domino Discussion template
4. Change the Description to Can manage and moderate the discussions.
5. Click OK.
6. Return to the Role name field, and click the Contributors role.
7. Make sure Moderator is mapped to Reader in the Domino Discussion Component,
DominoDatabaseCollabAdapterEJBHome.
See Figure 4-7 on page 80.
Chapter 4. Building a Component for IBM Workplace
79
Figure 4-7 Setting Contributors Roles for new Domino Discussion template
The final step is to save the new template. In Workplace Builder, click Save and Close from
the top bar.
4.4.5 Creating an application using the Domino Discussion Application
Template
In this section, we create a new application using the Domino Discussion template. Because
the template was created in the Team Space category, we need to do all our work there.
Follow these directions to create a new Domino Discussion application:
1. Browse to Lotus Workplace using the following URL:
http://yourmachineName.yoursubDomain.yourdomain:9081/lwp/workplace
2. Logon as any user.
3. Go to the Team Space tab. See Figure 4-8.
4. Click “New…” in the Team Spaces portlet.
5. Type in the name of the discussion and select the Domino Discussion template.
6. Click OK.
7. You are presented with the template parameters to define. This is caused by getVariables
API call in the component we built.
Figure 4-8 Domino Discussion template parameters
80
Building a Component for IBM Workplace
8. Accept the defaults and click OK. See Figure 4-9.
You have now successfully created a new application using the new Domino Discussion
template. This application is fully integrated with all Lotus Workplace application events.
Figure 4-9 The Domino Discussion Application
4.4.6 Add members to the new application
When users create applications, they manage application membership and perform
additional tasks to manage the applications. The user who creates an application becomes
the default moderator. The default moderator can also be changed. A user with moderator
access can specify additional moderators, groups and members for the application. See the
Application’s portlet Help for more information about using and managing Workplace
applications.
To add members to the application, do the following:
1. Open the application from the My Workplace in the Team Space section.
2. Select Manage Members from the Actions list of the Members portlet. See Figure 4-10 on
page 82.
Chapter 4. Building a Component for IBM Workplace
81
Figure 4-10 Members portlet on the Team Space application Homepage
3. Select a role to view and Manage members.
4. Click the Add Members button in Figure 4-11 to add members from the portlet.
Figure 4-11 Portlet to add members to your application
4.5 Installing the Domino Discussion Component into
WebSphere Studio
As described in Appendix A., “Additional material” on page 85, there are additional materials
for this Redpaper. The file REDP3952.zip includes all the code used to create the Domino
discussion component. Included in the zip file are WebSphere Studio project files and the
final binaries that can be installed in a Lotus Workplace deployment.
To import the WebSphere Application Developer project files into your workspace, do the
following:
1. Unzip REDP3952.zip into c:\redbooks
2. Open the WebSphere Application Development environment.
82
Building a Component for IBM Workplace
3. From the File menu, select Import, and select Existing Project into Workspace from the
list.
4. Select the Browse button and navigate to the directory
c:\redbook\REDP3952\wsad\CollabComponentAdapterEJB
5. Select Finish to import the project file into the workspace.
6. Repeat steps 2-4 for each of the other directories in c:\redbook\REDP3952\wsad.
By using the above procedure, you can import the Domino Discussion Component files into
your WebSphere Studio workspace.
4.6 Additional Resources
The following resources are provided for further information about related subjects:
򐂰 Visit the IBM DeveloperWorks site for the three part white paper on Workplace Application
Development written by Hardy Groeger and Mel Gorman:
http://www-106.ibm.com/developerworks/lotus/library/lwp-appdev1/
http://www-106.ibm.com/developerworks/lotus/library/lwp-appdev2/
http://www-106.ibm.com/developerworks/lotus/library/lwp-appdev3/
򐂰 Search the Lotus domain on the IBM Redbooks Web site for the latest Redbooks and
Redpapers about other Workplace topics:
http://publib-b.boulder.ibm.com/redbooks.nsf/portals/Lotus
Chapter 4. Building a Component for IBM Workplace
83
84
Building a Component for IBM Workplace
A
Appendix A.
Additional material
This Redpaper refers to additional material that can be downloaded from the Internet as
described here.
Locating the Web material
The example files associated with this Redpaper are available on the Internet from the IBM
Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/REDP3952
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select the Additional materials tab on the left and open the directory that corresponds with
the Redpaper form number, REDP3952.
Using the Web material
The additional Web material that accompanies this Redpaper includes the following files:
File name
read_me_first.rtf
REDP3952.zip
Description
File explaining how to install the sample code
Zipped Code Samples
How to use the Web material
Create a subdirectory (folder) on your workstation (e..g. c:\redbooks), and unzip the contents
of the Web material zip file into this folder.
© Copyright IBM Corp. 2005. All rights reserved.
85
86
Building a Component for IBM Workplace
Back cover
®
Building a Component for
IBM Workplace
Redpaper
Get a solid overview
of IBM Lotus
Workplace
Use Lotus Workplace
Application
Development
Develop and use
example applications
This IBM Redpaper provides an overview of the Lotus® Workplace™
platform architecture, discusses application development
technologies, and gives an introduction to developing applications in
Lotus Workplace. The final chapter gives an example of how to build a
collaborative component for Lotus Workplace using the API toolkit.
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
The target audience for this IBM Redpaper includes independent
software vendors (ISVs), application developers and others who would
like to understand the Workplace platform.
.
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