Read REDP3952.book text version

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 16 16 17 19 19 21 21 22 22 22 23 23 24 24 24 24 26 33 33 33 35 37 38 38 38 39 iii

© Copyright IBM Corp. 2005. All rights reserved.

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

39 40 41 41 41 42 42 43 44 45 46 48 48 49 49 50 51 51 51 51 53 55 56 56 57 58 58 59 71 72 73 73 73 74 74 75 76 77 80 81 82 83 85 85 85 85

iv

Building a Component for IBM Workplace

Preface

This IBM Redpaper provides an overview of the Lotus® WorkplaceTM 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 RedbooksTM in one of the following ways: Use the online Contact us review redbook form found at:

ibm.com/redbooks

Send your comments in an email to:

[email protected]

Mail your comments to: IBM® Corporation, International Technical Support Organization Dept. 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: [email protected] 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:

CloudscapeTM DB2® Domino® Eserver® Eserver® eServerTM EserverTM Everyplace® ibm.com® IBM® Lotus Notes® Lotus® Notes® QuickPlace® Rational® Redbooks (logo) RedbooksTM WebSphere® WorkplaceTM Workplace Client TechnologyTM Workplace Collaborative LearningTM Workplace MessagingTM Workplace Team CollaborationTM Workplace Web Content ManagementTM

TM

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 TechnologyTM 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 JavaTM 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 JavaTM 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 CloudscapeTM. 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 CollaborationTM

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 LearningTM

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 MessagingTM

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 ManagementTM

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 . . .

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

Address Search

... and Integration

r a t io n In te g r L a ye P o r ta v ic e s l Ser r L a ye

Content Aggregation

n ta tio

n

r L a ye

Page

Page

Page

Page

Application Integration

Portal 2

Portal 4

Team Collaboration

Portal 1

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

Doc M sg

Te a m C o lla b

C o lla b o ra tio n

C o lla b o ra tiv e c a p a b ilitie s

A p p lic a tio n In te g ra tio n

L e a r n in g

Te a m C o lla b

M sg D oc

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

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 server1 WebSphere_Portal LotusWorkplace_Server Server WebSphere Application Server WebSphere Portal 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 Template (XML File)

IBM Workplace Builder

designs 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 Team Space Description Participate in discussions and chats, share documents and a team calendar, and search for information related to a project. Participate in threaded discussion forums with teams. Communicate with team members, view archives of chat transcripts, and see a list of chat participants. Access HTML-enabled Domino applications. Manage document versions, approvals.

Discussion Chat Room

Domino Application Document Library

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 Browser Web Browser

Application HTML

<html> ... </html> <body> ...

Lotus Workplace Lotus Workplace (WebSphere Portal) (WebSphere Portal)

HTTP

Domino Discussion Template

Domino Domino Server Server

Discussion Notes Template

discsw6.ntf

Discussion Application Place n Discussion Portlet HTML Discussion Application Place 2 Discussion Application Place 1 Discussion Page

Discussion Notes Databases

iFrame

Domino Discussion iFrame Portlet

PortletData BcId="disc1.nsf"

discN.nsf

</body> </html> Templatable Lifecycle Membership Sensor Transactional

NCSO.jar

IIOP

Domino Discussion Collaborative Component EJB

disc2.nsf

HTTP disc1.nsf

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 java.lang.String createInstance(InstanceDescription description) void removeInstance(java.lang.String id) Description Called when an instance of this component needs to be created 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 DataObjectList getRoles(String instanceId) void addMembers(String instanceId, DataObjectList members) void removeMembers(String instanceId, DataObjectList members) Description Returns the list of Roles supported by the object represented by the instanceId Called when new members are added to application. The list of members has the associated roles 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) DataObjectList getVariables(String instanceId) Returns and InstanceDescription which includes template related information such as variables collected at instantiation. 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 DataObjectList getSensorValues(String bcId) Description 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 boolean isTransactional( ) Description 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

JNDI = ejb/DominoDatabaseCollabAdapterEJBHome

EAR

ejb-ref (ejb/CollabComponent)

CollabComponentAdapterEJB

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® WorkplaceTM 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. .

INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information: ibm.com/redbooks

Information

REDP3952.book

98 pages

Report File (DMCA)

Our content is added by our users. We aim to remove reported files within 1 working day. Please use this link to notify us:

Report this file as copyright or inappropriate

1257669


You might also be interested in

BETA
REDP3952.book