ibm workplace managed client 2.6 on linux · 2006. 4. 23. · ibm workplace managed client 2.6 on...

ibm.com/redbooks

IBM Workplace Managed Client 2.6 on Linux

Ingo BoernigVijil E. Chenthamarakshan

Trevor JohnstonShane Kilmon

IBM Workplace Managed Client and the Linux desktop

Installation and configuration information

Build a sample application

Front cover

http://www.redbooks.ibm.com/



April 2006

International Technical Support Organization

SG24-7208-00

© Copyright International Business Machines Corporation 2006. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADPSchedule Contract with IBM Corp.

First Edition (April 2006)

This edition applies to Release 2.6 of IBM Workplace Managed Client.

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

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixThe team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixAdditional contributors to this Redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1. Introduction to IBM Workplace Managed Client on Linux . . . . 11.1 What is Workplace Managed Client? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 Linux on the desktop today . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2.1 Benefits of a corporate Linux desktop. . . . . . . . . . . . . . . . . . . . . . . . . 61.2.2 Linux desktop classifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.2.3 Applications available on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3 Why use Workplace Managed Client on a Linux desktop? . . . . . . . . . . . . 101.3.1 Application support added by Workplace Managed Client . . . . . . . . 101.3.2 Workplace Managed Client in the desktop segments . . . . . . . . . . . . 111.3.3 End-to-end Linux client/server environment . . . . . . . . . . . . . . . . . . . 12

1.4 Architectural overview of Linux desktop solution using Workplace Managed Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.4.1 High-level architectural overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.4.2 Application abstraction layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.4.3 The Workplace Managed Client framework . . . . . . . . . . . . . . . . . . . 15

1.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2. IBM Workplace Managed Client applications. . . . . . . . . . . . . . 192.1 Applications overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.2 Messaging applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.2.1 Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2.2 Instant messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.3 Notes plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.3.1 Connecting to a Domino server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.3.2 Working with the Notes plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

2.4 Activity Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452.4.1 Activity Explorer overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452.4.2 Using the Activity Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

2.5 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.5.1 Working with document libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

© Copyright IBM Corp. 2006. All rights reserved. iii

2.5.2 Working with documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542.6 Team spaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572.7 Embedded browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592.8 External applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

2.8.1 Workplace Collaborative Learning . . . . . . . . . . . . . . . . . . . . . . . . . . 602.8.2 Workplace Web Conferencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Chapter 3. Workplace Managed Client 2.6 on Linux installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

3.1 Configuring a Workplace Collaboration Services 2.6 server for Managed Client support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

3.1.1 What is the SCI? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643.1.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663.1.3 The installation process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683.1.4 SCI setup summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783.1.5 Uninstalling the SCI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793.1.6 Configuring access to the Managed Client and setting policies . . . . 83

3.2 Installing Workplace Managed Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903.2.1 Client installation introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903.2.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913.2.3 Installing the base platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943.2.4 Provisioning the Managed Client . . . . . . . . . . . . . . . . . . . . . . . . . . 1003.2.5 Post-installation tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053.2.6 Uninstalling the Managed Client . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Chapter 4. IBM productivity tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134.1 Launching the IBM productivity tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144.2 Document formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

4.2.1 OASIS OpenDocument Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194.2.2 IBM productivity tools native format . . . . . . . . . . . . . . . . . . . . . . . . 1204.2.3 Microsoft Office formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

4.3 Template support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224.4 Adding fonts to IBM Workplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Chapter 5. Building a sample application for the IBM Workplace Managed Client platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

5.1 Workplace Managed Client platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275.2 The sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1285.3 Configuring the development environment . . . . . . . . . . . . . . . . . . . . . . . 130

5.3.1 Installing an IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305.3.2 Installing the Managed Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315.3.3 Installing the IBM Workplace Managed Client Tool . . . . . . . . . . . . 1315.3.4 Creating a new toolkit project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315.3.5 Testing the development environment . . . . . . . . . . . . . . . . . . . . . . 135

iv IBM Workplace Managed Client 2.6 on Linux

5.3.6 Creating a runtime configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375.4 Creating the List View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395.5 Creating the Detail View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445.6 Linking views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

5.6.1 Communicating selection changes in the List View . . . . . . . . . . . . 1465.6.2 Saving tasks from the Detail View. . . . . . . . . . . . . . . . . . . . . . . . . . 146

5.7 Adding commands to menus and action bars . . . . . . . . . . . . . . . . . . . . . 1485.7.1 Adding to the Workplace Managed Client menus . . . . . . . . . . . . . . 1485.7.2 Adding to the Workplace Managed Client action bars . . . . . . . . . . 150

5.8 Saving tasks to the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515.9 Live names and instant messaging integration . . . . . . . . . . . . . . . . . . . . 1545.10 Deploying the sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Chapter 6. Troubleshooting IBM Workplace Managed Client . . . . . . . . . 1656.1 Logging and tracing in Workplace Managed Client 2.6. . . . . . . . . . . . . . 166

6.1.1 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666.1.2 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

6.2 Using IBM Support Assistant for self-help and data collection . . . . . . . . 1736.2.1 IBM Support Assistant Search component . . . . . . . . . . . . . . . . . . . 1756.2.2 IBM Support Assistant Support Links component. . . . . . . . . . . . . . 1806.2.3 IBM Support Assistant Service component. . . . . . . . . . . . . . . . . . . 181

6.3 Troubleshooting the productivity tools. . . . . . . . . . . . . . . . . . . . . . . . . . . 1876.4 Troubleshooting provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886.5 Troubleshooting the Notes plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

6.5.1 Logging and tracing for the Notes plug-in . . . . . . . . . . . . . . . . . . . . 1926.5.2 Collecting Notes diagnostic data. . . . . . . . . . . . . . . . . . . . . . . . . . . 193

6.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Appendix A. Installing IBM Workplace Managed Client on other Linux distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Prerequisites for the Linux installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Installation and tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Configuration for Workplace Managed Client. . . . . . . . . . . . . . . . . . . . . . . . . 199

Appendix B. Ericom PowerTerm WebConnect for IBM Workplace . . . . . 201IBM Workplace and Ericom enterprise-wide application access and delivery 202

How Ericom PowerTerm WebConnect integrates with IBM Workplace . . 202Workplace Managed Client-based PowerTerm WebConnect solution . . . 204Browser-based Ericom PowerTerm WebConnect solution . . . . . . . . . . . . 204

Ericom PowerTerm WebConnect for IBM Workplace features . . . . . . . . . . . 205Access to established applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Access to Microsoft Windows applications . . . . . . . . . . . . . . . . . . . . . . . . 207Centralized administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Security aspects and single sign-on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Contents v

True, seamless windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Availability, performance, and scalability . . . . . . . . . . . . . . . . . . . . . . . . . 209

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Appendix C. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

vi IBM Workplace Managed Client 2.6 on Linux

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. 2006. All rights reserved. vii

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

AIX 5L™AIX®Cloudscape™DB2 Universal Database™DB2®developerWorks®Domino®Eserver®Everyplace®Extreme Blue™

IBM®iSeries™Lotus Notes®Lotus®Notes®POWER™pSeries®Rational®Redbooks (logo) ™Redbooks™

Sametime®WebSphere®Workplace Client Technology™Workplace Collaborative Learning™Workplace Managed Client™Workplace Messaging®Workplace™zSeries®

The following terms are trademarks of other companies:

Java, JDBC, JVM, J2EE, StarOffice, Sun, Sun Java, Sun Microsystems, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Excel, Microsoft, PowerPoint, Visual Basic, Windows, Win32, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Intel, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

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

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

viii IBM Workplace Managed Client 2.6 on Linux

Preface

With IBM® Workplace™ Managed Client™ Release 2.6 on Linux®, IBM offers a strategic end-to-end Linux solution that provides both the benefits of Linux and IBM Workplace Collaboration Services. This IBM Redbook provides a technical overview of IBM Workplace Managed Client and examines why it is a smart, strategic choice. In addition, we provide a detailed description and best practices for deploying, installing and configuring the product. We focus on the following topics:

� Benefits and positioning of a Linux client. Why Workplace Managed Client on Linux?

� Overview of the product features and functionality.

� Technical and architectural overview of the client.

� Description of how to install the client on Red Hat Enterprise Linux and other Linux distributions.

� Possibilities and benefits for an end-to-end Linux solution (IBM Workplace server and IBM Workplace Managed Client on Linux).

� Example of a sample application and customization based on the underlying Eclipse framework.

The team that wrote this redbookThis redbook was produced by a team of specialists from around the world working at the International Technical Support Organization, Cambridge Center.

Ingo Boernig works as an IT Architect in Enterprise Linux Services for IT-Services and Solutions GmbH, a German subsidiary of IBM Global Services. Based in Dortmund, Germany, he focuses on collaboration and desktop services with the Linux operating system. He has more than six years experience in the Linux industry and more than 10 years of experience with Linux. Before joining IBM in 2004, Ingo Boernig worked as IT Architect for

SUSE, a leading Linux distributor recently acquired by Novell, Inc.

© Copyright IBM Corp. 2006. All rights reserved. ix

Vijil E. Chenthamarakshan is a Staff Software Engineer at IBM India Software Labs. He was involved in the development of several components for IBM Workplace Managed Client and is currently working with IBM Research to integrate Unstructured Information Management tools into Workplace Managed Client. He holds a master’s degree in technology from Indian Institute of Technology, Bombay.

Trevor Johnston is a Software Engineer in the IBM Dublin Software Lab. He first joined IBM in 2003 as an intern with the Extreme Blue™ program and returned to IBM full time in 2004. He works on IBM Workplace Collaborative Learning™, where he specializes in IBM Workplace Managed Client integration and search capabilities. His areas of expertise include Java™ and Linux on the desktop. This is his first IBM Redbook.

Shane Kilmon is an Advisory Software Engineer with IBM in Westford, MA. He is a member of the Reliability, Availability, and Serviceability (RAS) Engineering team, focused on improving the overall reliability, availability, and serviceability of our software products. He has been with IBM/Lotus® for 10 years and coauthored the IBM Redbook Domino Web Access 6.5 on Linux, SG24-7060.

John Bergland is a Project Leader at the International Technical Support Organization, Cambridge Center. He manages projects that produce Redbooks™ about Lotus software products. Before joining the ITSO in 2003, John worked as an Advisory IT Specialist with IBM Software Services for Lotus, specializing in Lotus Notes® and Domino® messaging and collaborative solutions.

Additional contributors to this RedbookThanks to the following people for their contributions to this project:

Larissa Schoeffing is an IT Specialist in the Lotus Technical Sales team at IBM Software Group. She has experience with IBM WebSphere® Portal and Workplace Services Express/Workplace Collaboration Services since the very first versions of these products. Her main focus is on portal infrastructure, deployment models, back-end application integration, and application development. Larissa has conducted lectures at several conferences and published internal and external papers on these topics.

x IBM Workplace Managed Client 2.6 on Linux

Nallu C. Reddy, Lotus Program Director, Lotus Linux Marketing, IBM Software GroupIBM, Bethesda, MD, U.S.

Greg T. Kelleher, On Demand Business Senior Program Manager, Worldwide Linux and Open Source Desktop Strategy and Market Development, IBM Systems and Technology GroupIBM, Cambridge, MA, U.S.

Pamela J. Stanford, Lotus Director, IBM Workplace Client Technology™, IBM Software GroupIBM, San Antonio, TX, U.S.

Become a published authorJoin us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers.

Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability.

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

ibm.com/redbooks/residencies.html

Comments welcomeYour comments are important to us!

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

� Use the online Contact us review redbook form found at:

ibm.com/redbooks

� Send your comments in an e-mail to:

[email protected]

Preface xi

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html



http://www.redbooks.ibm.com/contacts.html

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. HYTD Mail Station P0992455 South RoadPoughkeepsie, NY 12601-5400

xii IBM Workplace Managed Client 2.6 on Linux

Chapter 1. Introduction to IBM Workplace Managed Client on Linux

In this chapter, we introduce the IBM Workplace Managed Client technology and demonstrate how the concepts of Workplace Managed Client fit into a Linux client strategy by extending the features of a Linux client environment with corporate collaboration features and centrally manageable applications.

1

© Copyright IBM Corp. 2006. All rights reserved. 1

1.1 What is Workplace Managed Client?IBM Workplace Managed Client is a server-managed application that hosts key collaboration applications and productivity tools and can easily be extended using the Eclipse-based application development framework. It offers offline support for e-mail, calendaring, scheduling, and document management.

In traditional client/server environments, there are two different types of client technologies. There is the complete server-centric thin client approach, where all the application information is stored on the server. This is favorable for the management abilities, but disadvantages include a total dependence on a permanent network connection and less interactive features for the users.

The other type, the rich client technology, is capable of offline usage and delivers a more interactive and intuitive user interface, but needs a lot of work from a management and configuration perspective.

IBM Workplace Managed Client is a hybrid of those two traditional approaches, delivering a server-managed rich client application, that can be used in online and offline modes. Figure 1-1 illustrates how Workplace Managed Client leverages the advantages of the thin client and the rich client simultaneously.

Figure 1-1 Workplace Managed Client: Leveraging the advantages simultaneously

Goal: Rich

applications

with rich userexperience

Rich, Windows-centric applicationswith connection to network, serverresources(for example,Microsoft Office, Lotus Notes)

portal-like

enhanced

2 IBM Workplace Managed Client 2.6 on Linux

The following main characteristics summarize IBM Workplace Managed Client as compared to other client technologies:

� A centrally managed, policy-based client provisioning system that ensures that initial installations and maintenance updates can be applied on the server side and that users can experience those new updates dynamically client side

� A synchronizing secure data store that is locally offline accessible and centrally manageable (for backups, and so on)

� A componentized architecture that allows for gradual extension and that can be distributed on demand

� An application development platform that end users and third-party vendors can use to extend the framework to their needs

Workplace Managed Client includes the following applications:

� A messaging framework for sending and receiving e-mails and instant messaging for real-time chat sessions

� An embedded Web browser to access additional portlets on the server side and to directly browse the Web

� A document library that is synchronized to the server and can be shared with other team members

IBM Workplace Managed Client includes office productivity editors for creating, editing, and sharing a variety of document types including word processing, spreadsheet, presentations, and project management. The IBM productivity tools are compatible with Open Office applications and support the open standard OASIS OpenDocument Format (ODF). The IBM Workplace Managed Client productivity tools can also be used to create, edit, and save documents in a variety of other formats - including Microsoft® Office application formats. By supporting open standards document formats, IBM Workplace Managed Client ensures cross-platform and cross-application document exchange without being locked into the proprietary vendor formats.

Chapter 1. Introduction to IBM Workplace Managed Client on Linux 3

IBM Workplace Managed Client also offers a new collaboration tool called Activity Explorer. Activity Explorer lets teams of users manage projects through an ad hoc workflow that groups together information objects that are related to an ongoing project and are shared among team members. The information objects can be documents, files, and notes. The ad hoc workflow is presented in graphical, hierarchal format and makes it easier to refer to past work, visualize project status, and discover opportunities for further progress.

For Lotus Notes users, there is a Notes plug-in available (the Linux version is currently in a beta stage) that provides access to all Lotus Notes databases inside the Workplace Managed Client framework.

Technically, Workplace Managed Client is a platform-independent Java application based on the Eclipse framework (http://www.eclipse.org). Workplace Managed Client provides an application development and integration platform where ISVs can integrate their software in a platform-independent manner to serve Linux and Microsoft Windows®-based client computers.

The main focus of this framework is the centrally managed client environment that is automatically provisioned, installed, updated, and administrated from a central server to all possible client machines. There is no need for a special software distribution or maintenance software.

OpenDocument: The OpenDocument Format (ODF), short for the OASIS OpenDocument Format for Office Applications, is an open document file format for saving and exchanging editable office documents such as text documents (including memos, reports, and books), spreadsheets, charts, and presentations. This standard was developed by the OASIS industry consortium, based on the XML-based file format originally created by OpenOffice.org.

OpenDocument is the only standard for editable office documents that has been vetted by an independent recognized standards body, has been implemented by multiple vendors, and can be implemented by any supplier (including closed source software vendors and developers using an open source license).

Note: IBM Workplace Managed Client comes with a Lotus Notes plug-in to access the Notes e-mail and database application on Linux. At the time of this writing, the Linux version of this plug-in is still in beta, with the final version expected in the second half of 2006. This plug-in provides nearly full Notes client functionality. This is the first time a rich client on the Linux platform can access Lotus Notes databases using a supported environment.


http://www.eclipse.org

IBM Workplace Managed Client is part of the IBM Workplace family of products extending the capabilities of IBM Workplace Collaboration Services.

1.2 Linux on the desktop todayDespite the ongoing success story of Linux systems in the server market, in the desktop market, Linux seems to be still a niche player. There are different reasons for that, depending on the part of the market.

In the home user segment, Linux is struggling with the lack of availability of entertainment software and the support of a broad range of recent hardware products. Other requirements such as safe Internet access, Web browsing, e-mail, and office functionality can be fulfilled easily.

On corporate desktop systems, Linux is frequently used as base system for thin clients and increasingly for limited, transactional workstations. Another frequent deployment of Linux workstations is the development or engineering workstation in technically oriented research departments or universities.

Companies use Linux on desktop systems to lower both their initial licensing cost and also the total cost of ownership (TCO). A Linux desktop is easy to secure and easy to manage from a central system so that the operating costs can be reduced significantly.

A recent survey by the Open Source Development Lab (OSDL) Desktop Linux Working Group (http://www.osdl.org/dtl/DTL_Survey_Report_Nov2005.pdf) states that 50% of all 3300 participating companies already use Linux on the desktop in some way. Overall, the number of installed workstation is still low but increasing, backed by the well-known decisions of cities such as Munich (http://www.muenchen.de/Rathaus/dir/limux/english/147197/index.html) and Vienna.

Open Source Development Lab (OSDL): OSDL, home to Linus Torvalds, the creator of Linux, is dedicated to accelerating the growth and adoption of Linux in the enterprise. Founded in 2000 and supported by a global consortium of IT industry leaders, OSDL is a non-profit organization that provides state-of the-art computing and test facilities in the United States and Japan available to developers around the world. The founding members of OSDL are IBM, HP, CA, Intel®, and NEC. For a complete list of OSDL member organizations, see the OSDL Member Roster page:

http://groups.osdl.org/osdl_members/osdl_roster


http://www.osdl.org/dtl/DTL_Survey_Report_Nov2005.pdf

http://www.muenchen.de/Rathaus/dir/limux/english/147197/index.html


1.2.1 Benefits of a corporate Linux desktopAs the OSDL survey pointed out, there are several reasons for deploying Linux on desktops. The top reasons are:

� Employees requesting Linux (user demand)

Technical users in engineering or development departments like to have a highly customizable work environment that fits their needs.

� Competitors successfully deploying Linux

� Total cost of ownership (TCO)

Using deployment frameworks, a Linux desktop system is easy to manage and maintain, which reduces the administration costs. Additionally, Linux systems can be used on older or limited hardware to serve as a thin client or browser workstation.

� Reduction of license cost

When using Linux on a large number of workstations, licensing can be reduced by saving Microsoft Windows OS seat licenses, Microsoft Office licenses, and client access licenses (CAL), adding up to considerable amount of money.

� Security

Linux systems are considered reasonably secure systems, so a change might improve the situation regarding viruses and trojans considerably.

� Availability of source code

This ensures the protection of investments into the system code and also the possibility of modification to circumvent bugs or making local improvements.

� Corporate direction

� Unhappy with current desktop OS

� Use of open standard protocols

The use of open standard protocols ensures that there are less integration issues and that all data belonging to the company remains accessible, regardless of any licensing issues. It is the key issue in reducing dependencies on single software vendors.

1.2.2 Linux desktop classificationsThe OSDL Desktop Linux Working Group classifies different types of Linux workstations, starting from a fixed function kiosk type desktop up to the full-featured, multimedia consumer desktop.


The fixed-function kiosk usually runs only one or two specialized applications and can be served by other IBM Workplace client technologies such as the browser or the mobile client. Because we focus on the corporate desktop market, we still have four different types of workstations to analyze. Later, we see how IBM Workplace Managed Client fits into these segments.

Figure 1-2 OSDL Linux workstation classifications

Technical workstationA technical workstation refers to workstations in a development or engineering environment. Users communicate through e-mail and instant messaging and make extensive use of development tools or graphical CAD/CAM applications. Linux can be a good option if the key development or engineering software is available.

Transactional workstationUsers using these desktop machines typically run multiple customized business applications, most of which are structured or forms-based. They also browse the Web and collaborate through basic e-mail. E-mail usage is limited to within the company, and generally the users do not have operating system expertise. These users might use simple server-based office productivity applications that might be remote or available through HTML. Because most of the business applications are available through terminal emulation or HTTP access, this is the most likely type of workstation that can be converted to Linux.

Basic office workstationEmployees in the business world use desktop computers to drive company processes and productivity using word processing, presentation, and


spreadsheet applications. These users use the applications to create and view simple documents such as memos, letters, presentations, and spreadsheets.

Generally, these users require only basic compatibility (including basic import and export compatibility) with other document formats, such as Microsoft Office. These are not “power” office users, so they do not require complex functions such as scripting. They require basic browser functionality to access information such as corporate guidelines, parts information, and loan information. They use e-mail to communicate information and to send documents through attachments.

Users can be converted to Linux if the corporate e-mail system can be provided and the needed business applications can be made available on the Linux desktop.

Advanced office workstationAdvanced office workstations users use desktop computers to drive company processes. They use arbitrary Windows applications that are dependent on Windows application program interfaces (APIs) such as Microsoft Foundation Classes, Internet Explorer, and Windows APIs. They are highly skilled in the Windows user interface, and they depend on being able to interact with the Windows operating system and Windows-based applications to do their jobs.

Users of these general-purpose desktops employ applications to create and modify complex documents for use within and outside of their companies. They depend on the Microsoft Office data format, and their skills center on the Microsoft Office user interface, functionality, and feature sets. Often people in this consumer segment do not want to move away from Windows.

1.2.3 Applications available on LinuxPresently, a Linux desktop comes with of a variety of applications or application types that are needed on a corporate desktop:

� Native Linux applications, typically open source applications. Examples include Openoffice.org, Mozilla Firefox, simple e-mail, a file manager, and basic desktop functionality.

� Support for Java applications, which are platform independent and can be used on any operating system supporting Java.

� Browser-based applications, centrally hosted applications that can be used while online.

� Support for terminal client technology. Centrally managed applications can be accessed using PowerTerm WebConnect for IBM Workplace to run Windows applications (Appendix B, “Ericom PowerTerm WebConnect for IBM Workplace” on page 201).


� Support for the X11 and VNC protocols for running X Window System Linux and UNIX® applications.

� Support for established host-based applications with terminal emulation programs using PowerTerm WebConnect for IBM Workplace (see Appendix B, “Ericom PowerTerm WebConnect for IBM Workplace” on page 201). This enables you to access IBM mainframe, IBM Eserver® iSeries™, IBM Eserver pSeries®, and other established hosts using 35 different terminal types, such as 3270, 5250, VT, Wyse, and Televideo.

Linux desktops have the following disadvantages:

� Relatively poor support of large, commercial, closed source applications (Microsoft, Adobe, AutoCAD, and so on).

� Relatively poor support of corporate collaboration software (Lotus Notes, Microsoft Exchange, Novell GroupWise).

The OSDL survey also investigated the top applications that need to be available on a Linux desktop. The survey reports the following ranking:

1. E-mail/messaging

2. Office productivity tools (word processing, spreadsheets, presentation, and so on)

3. Browser

4. Database applications

5. Developer tools (editors, compilers, development environments)

6. Business specific applications (manufacturing tools, construction applications, and so on)

7. Internally developed applications

8. Secure remote access/virtual private network (VPN)

9. Personal information manager (PIM)

10.Audio and video players

11.Instant messaging

It is noticeable that e-mail is ranked higher than any other application, for example, office productivity tools or even the browser. Therefore, e-mail is the key feature and a competitive e-mail client is a must in a Linux desktop deployment.


1.3 Why use Workplace Managed Client on a Linux desktop?

The survey results show that the key application for a corporate Linux desktop will be support for an enterprise-ready, corporate e-mail system. Additionally, we see that office productivity tools, personal information managers, and instant messaging are also high-priority applications for a Linux desktop.

Here, IBM Workplace Managed Client for Linux can add significant value to a standard desktop. Together with the Notes plug-in, which also adds support for a wide range of enterprise collaborative applications, Workplace Managed Client can provide the missing link to complete desktop functionality.

1.3.1 Application support added by Workplace Managed ClientAs stated earlier, Workplace Managed Client delivers a more complete application development framework and thus a rich number of new applications to Linux. The most prominent and directly integrated are:

� E-mail/messaging

� Data access tools

� Document management

Secure document data store, editors for word processing, spreadsheet application, presentation tool integrated into the collaborative tools.

� Team collaboration tools

Document library, discussion forums, and so on.

� Embedded Web browser, based on the open source Mozilla framework

Using the embedded browser, you can seamlessly access additional portlets on the server side. Examples are team spaces and Web conferences.

� Terminal services through Ericom PowerTerm

Ericom PowerTerm provide a comprehensive tool to access established and Windows applications. (See Appendix B, “Ericom PowerTerm WebConnect for IBM Workplace” on page 201 for further details about this topic.)

� Lotus Notes applications with the Notes plug-in

Support of Lotus Notes applications on the Linux desktop, providing integration into the Lotus Notes corporate messaging system.

In addition, users can develop their own custom rich client applications, exploiting the collaborative features offered by the Workplace Managed Client platform.


1.3.2 Workplace Managed Client in the desktop segmentsLooking into the different desktop segments we introduce in 1.2.2, “Linux desktop classifications” on page 6, Workplace Managed Client offers key benefits to a Linux desktop.

Technical workstationIn a technical environment, most of the daily work is done using special engineering or development applications. Office work, such as occasional presentations, is done on a basic level, usually without using any advanced or even scripting functionality.

Workplace Managed Client productivity tools satisfy requirements for most of these users, potentially delivering both simplification and savings on desktop licenses.

E-mail and collaboration tasks are very important for this set of users, but because the standard Linux desktop has several e-mail applications, it lacks an integration into the corporate e-mail system. With Workplace Managed Client, users in this segment have the option of using the native messaging that comes with IBM Workplace Collaboration Services, or using the Notes plug-in to access the corporate Notes infrastructure.

Transactional workstationsFor transactional workstations, there are often one or two main business applications that are used for most of the daily work. Some of these applications are established applications on host systems, some are centrally accessible using a Web browser, and some might also be local applications.

Workplace Managed Client can integrate those applications as a plug-in inside a uniform workplace using the integrated Web browser or the Ericom PowerTerm plug-in for established applications.

Additionally, Workplace Managed Client adds messaging and collaboration functionality and provides the possibility to view and modify office documents and send them as attachments.

Cost savings are archived by lowering desktop licensing costs and TCO by exploiting the central server management capabilities.

Basic office workstationThe users of basic office workstations are mostly over served by fully functional office solutions for their daily work. Users can easily do most tasks using the productivity tools of Workplace Managed Client, which are integrated into a


collaborative workplace, for example, central document libraries and discussion groups.

Most users will see a productivity benefit in this close integration of office programs into collaboration tools. Using the standard e-mail function or the Notes plug-in, these workstations are easily integrated into the corporate messaging strategy.

Migrating these type of users to a Linux desktop with IBM Workplace Managed Client and productivity tools can yield the largest savings in license costs for the company and can also lower TCO by making use of the central, role-based management of the client.

Full-featured office desktopsOn a full featured desktop with a large number of different applications, it is necessary to ensure that all applications will run on the Linux environment to satisfy the user’s specific requirements.

If this is not possible, you can use Workplace Managed Client on Windows in addition to the other applications to establish a standard platform for messaging, collaboration, and even for productivity tools. If the organization is focusing on open standards for office documents, namely the OASIS OpenDocument standard, Workplace Managed Client comes into play.

After establishing Workplace Managed Client as a standard application on Windows, you can re-centralize the most widely used Windows applications using Windows terminal servers and integrate these applications into Workplace Managed Client using the Ericom PowerTerm plug-in.

In a final step, even some of these workstations can then migrate to Linux, because they only rely on the Workplace Managed Client functionality.

1.3.3 End-to-end Linux client/server environmentUsing IBM Workplace Collaboration Services and Workplace Managed Client for Linux, you can achieve an entirely end-to-end Linux solution. Workplace Managed Client adds offline functionality, so from now on, there is a fully functional messaging and collaboration framework available that can be run from a server to client on Linux. In addition to the low TCO Linux client manageability functions, Workplace Managed Client adds server-managed application support to also lower the TCO for the desktop applications.

Using Workplace Managed Client with the Lotus Notes plug-in, Linux clients can access Lotus Notes databases in a supported environment. The corresponding Lotus Domino server can also be operated on a Linux system.


1.4 Architectural overview of Linux desktop solution using Workplace Managed Client

Having seen why Workplace Managed Client is an important tool to deliver collaborative applications to the Linux desktop, we now focus on the key architectural principles on which Workplace Managed Client is built.

1.4.1 High-level architectural overviewThe IBM Workplace Managed Client application runs locally on the client machine, but its application components, called plug-ins, are managed by the corresponding IBM Workplace Collaboration Services, an extended IBM WebSphere Portal server.

You install the application from the browser, by clicking a download link in the portal view of the server. The application downloads and installs locally on the client. While running, Workplace Managed Client continuously looks for updates on the server, so there is no need for any software distribution mechanism.

The application data is handled in a similar manner. Initially, all application data is stored on the server and accessible through Workplace Collaboration Services portlets. When installed, Workplace Managed Client creates an encrypted local storage using its own Derby database.

Using this secure local storage, users can work offline and make changes to their documents. After establishing a new connection, all data will be replicated to the server and is available for other authorized users and data protection services.

Derby: Derby is the open source version of the IBM Cloudscape™ database. It provides a full-featured, robust, small-footprint database server that is simple to deploy and reduces the cost of embedded and Web-based applications. For more information about Cloudscape, see:

http://www.ibm.com/software/data/cloudscape/


http://www.ibm.com/software/data/cloudscape/

Figure 1-3 illustrates the architectural overview of the Workplace Managed Client data structure and the communication with the Workplace Collaboration Services server.

Figure 1-3 Architectural overview

1.4.2 Application abstraction layersIBM Workplace Managed Client is a platform-independent, multilayer application that runs on multiple operating systems including Microsoft Windows and Linux. The main abstraction layer is the Java virtual machine runtime environment, which enables the application to run on different operating systems and processor platforms.

The layer above the Java runtime environment (JRE) is partly provided by the open source Eclipse platform, which does the basic graphical toolkit leveraging the Standard Widget Toolkit (SWT) framework. Workplace adds more functionality to that layer, such as logging, credential stores, and the portal integration.

Applications that build on this framework can leverage the Workplace and the Eclipse interfaces to represent the business logic and the application views.

IBM Workplace ClientTechnology Platform

WebSphere Portal

AggregationsRealize aggregations

ApplicationProvide application componentsAccess and use services

Base Client Platform + ExtensionsFetch component updatesSynchronize dataProvide basic services supportInitiate aggregation requests

Aggregation DefinitionsDefine templatesDefine pages

IBM Workplace Collaboration ServicesApplication componentsApplication services

Base Portal + ExtensionsProvision application componentsProvide data synch supportProvide aggregation engineProvide services for all client types

Secure StoreData Stores

ApplicationComponent

Catalog

ApplicationComponents


Figure 1-4 shows the application layers starting from the operating system up to the business application logic.

Figure 1-4 Application layers: Operating system up to the business application logic

1.4.3 The Workplace Managed Client frameworkThe conceptual software stack of IBM Workplace Managed Client consists of several layers, where the core platform is built using the Eclipse open source client framework. The Workplace platform extensions are implemented as plug-ins to Eclipse to extend the framework. On top of this framework, the Workplace application leverages all the underlying components. Figure 1-5 on page 16 illustrates how building on a standard open source framework (Eclipse), Workplace Managed Client adds functionality in an API layer and delivers some of the applications itself.

Business Component Projection

Operating System

JRE

IBM Workplace Client Technology Platform

Platform Runtime

Workbench

JFace

SWT

Help Alerts Cred Store

UpdateManager

ServiceLocator

App ManagerLogging

J2EE Client Container

PortalIntegrationPreferences WMM


Figure 1-5 Building on a standard open source framework (Eclipse)

The Eclipse frameworkEclipse is an open source client framework for application development tools. It can be used and redistributed royalty-free by ISVs to build their own tools and plug-ins.

Eclipse itself comes with some basic tools such as a text editor, project navigation, and task management. This can be extended using plug-ins in Java. By implementing different kinds of plug-ins, Eclipse can become a platform for any kind of client framework. As an example, IBM WebSphere Studio is a rich collection of Eclipse plug-ins, as is Workplace Managed Client.

The main benefits of Eclipse as a foundation of the client framework is the cross-platform approach combined with a rich UI framework using the SWT technology that leverages platform-native widgets, which integrate well into the different client desktop environments.

Generic contributions layerThis layer contains contributions from IBM to the Eclipse project that will be integrated into future Eclipse releases. These contributions include:

� System tray integration

� Postinstall configuration

� Locked-down desktop for secure terminals and kiosks

� Dynamic plug-ins that can be loaded at runtime

Mail Docs

Workplace Shared Application Components

Extension Services

Core Platform and Frameworks

Generic Contributions

Generic UI Components

Eclipse RCP

...

Workplace PlatformExtensions

WorkplaceApplications

IBM WorkplaceClient Technology

Platform

IBM Workplace Client Technology Platform and Applications


Extension services layerThis layer is part of IBM Workplace Managed Client and contains many enterprise client value-add services. Some of these services have counterparts on the server side. Examples are:

� Portal integration into the Workplace Collaborative Services portal

� Replication of local data with the server

� Secure local credentials store that allows for offline login

� Single sign-on (SSO) with operating system

Generic UI componentsUser interface components that reside in this layer are generic, tie into extension services, and can be used in applications built by IBM, end customers, and other providers. Example components include:

� Managed store explorer viewer

� Live names

� View intercommunication (client-side broker)

� Custom table widget

Workplace applications reside on top of these layers and can leverage all of the underlying technology. Because the basic architectural concepts such as local storage, replication, and authentication are handled in the lower layers, application development can concentrate on the functional requirements of the desired project.

1.5 SummaryThis chapter demonstrates that IBM Workplace Managed Client for Linux is a valuable add-on in real-world client scenarios, and being based on open standards, it can easily be extended using custom build plug-ins. In the following chapters we provide a deeper introduction to the provided features, a comprehensive installation and configuration overview, and a demonstration of a simple plug-in example.


Chapter 2. IBM Workplace Managed Client applications

In this chapter, we discuss the applications that make up the features and functionality of IBM Workplace Managed Client. We include the following features that are available to the user from the client menus and application switcher:

� Messaging

� Lotus Notes plug-in

� Activity Explorer

� Documents

� Team spaces

� Web browser

� Web Conferencing

� Learning

2


2.1 Applications overviewAs discussed in Chapter 1, “Introduction to IBM Workplace Managed Client on Linux” on page 1, applications in an IBM Workplace Managed Client environment are composed one or more Eclipse “features,” which are generally a number of Java plug-ins aggregated into a single functional unit. The application layer in the Managed Client is considered separate from the Eclipse-based platform we install.

In general, the runtime platform is stored in the directory specified during the installation of the initial client. By default on Linux platforms, this is /opt/IBM/Workplace Managed Client. Upon first execution of the client platform, it contacts the server that has been set up to be the provisioning server in order to install the applications. These are installed to a directory in an Eclipse workspace that is created in the user’s home directory, $HOME/IBM/RCP/<WorkspaceID>/<username>/applications.

The applications directory contains all of the features and plug-ins that provide the rich experience surrounding the work, or business component, the user is trying to accomplish. For example, the default perspective for each application (mail, calendar, instant messaging, team spaces, and so on) is provided in the application layer. Any content particular to a business component, such as menu items, help text, views, globalization files, preferences, and so on, is considered part of the application and stored here.

It is important to note the distinction between the platform layer and the applications. The platform base is generally the same in all IBM Workplace Managed Client installations. The user experience and workflow is driven by the applications installed, and in a managed environment, this can be different for particular users. Therefore, not all of the options discussed in this chapter is available for each user. The majority of them are only displayed to those users who have them enabled in their user policy, which is controlled by the server

Note: In this hierarchy, <WorkspaceID> is the unique workspace identifier that the client generates and stores in $INSTALL_DIR/rcp/rcpinstall.properties, where $INSTALL_DIR is the location of the client platform files (/opt/IBM/Workplace Managed Client by default). The identifier is a nine-digit number used by the client to identify a user’s persistent application space. It is found throughout the .properties file, but the main field is, the following line, which should be the very first line of the file:

rcp.installId

This workspace identifier regenerates each time a new installation of the client occurs if the old client has been completely removed.


administrator. If any of these are not available in your default client image, contact your IBM Workplace Collaborative Services system administrator or help desk to determine whether or not the server is configured to use these features and if your policy has them enabled. See 3.1.6, “Configuring access to the Managed Client and setting policies” on page 83 for more information about setting user policy access. For more information about how to check your policies locally, see Chapter 6, “Troubleshooting IBM Workplace Managed Client” on page 165.

2.2 Messaging applicationsThe “messaging” applications include the standard personal productivity functionality included with IBM Workplace Managed Client and viewed in the Messaging perspective selected in the application switcher. These include:

� Mail� Calendar� Instant messaging

Important: The applications we discuss in this chapter are some of the out-of-the-box applications that we ship with IBM Workplace Managed Client. One of the strengths of Workplace Managed Client is the extensibility of the architecture to include third-party applications. Virtually anyone can create an Eclipse application and integrate it into IBM Workplace Managed Client. There are numerous resources to do so, including a chapter in this book (Chapter 5, “Building a sample application for the IBM Workplace Managed Client platform” on page 125), the IBM Workplace 2.6 API Toolkit, and the IBM Redpaper IBM Workplace Managed Client: ISV Integration Guide, REDP-4119, available at:

http://www.redbooks.ibm.com/abstracts/redp4119.html

Chapter 2. IBM Workplace Managed Client applications 21

http://www.redbooks.ibm.com/abstracts/redp4119.html

Figure 2-1 Default Messaging perspective of IBM Workplace Managed Client

2.2.1 MailIBM Workplace Managed Client provides standards-based messaging functionality that is security-rich, scalable, and easily deployed. It offers a wealth of functionality critical to a robust mail experience:

� Support for a variety of mail views (Inbox, Drafts, and All Documents).

� Support for creating rich text messages (for example, attachments, boldface, bullets, images, and so on).

� Attachment viewers and converters.

� Mail Signature Phrase: Ability to add signatures to outgoing mail messages in either rich or plain text.

� Support for a Personal Address Book to store contacts important to you locally.


� Integrated instant messaging: Presence awareness, so a user can see immediately if the people on a mail list or the author of a document are online. If so, the user can initiate a chat just by clicking the person’s name.

� Integration with the document service: Archive e-mail directly into the document library.

� End-user spam filtering: Users can “vote” any message as spam by selecting “Delete Message as Junk Mail” from the Actions menu.

� Out-of-office notifications.

� Block mail send for quota enforcement.

� Drag and drop of mail messages between folders.

� Type-ahead: Users can quickly access names they use the most (in mail and calendar portlets).

� Save content and all attachments of one or more messages in a ZIP file.

� Attention indicators: Provides users with more information about their messages (for example, graphically indicates if the recipient of the message is listed in the To field or the CC field).

� Mail threading: Uses secondary highlighting to show the relationship between messages.

The mail interface is much the same as any other enterprise messaging application with which a user might be familiar. It offers standard functionality such as rich text capabilities, attachment support, creation of folders for organizing, spell checking, out of office notification, encryption and signature stamping of messages, and the ability to tag messages as junk mail, which blocks any similar messages sent to you in the future. We focus on some of the more interesting aspects that make up the messaging experience in IBM Workplace Managed Client.

Offline supportThe client enables users to work with their mail file after switching the client to Offline mode. When going offline, the client synchronizes the server-side copy of the mail file so that the local client has the most recent updates stored in the encrypted Cloudscape data store. The user is able to create new messages and reply to existing ones, and features that do not rely on server access, such as spell check and address completion, work while the client is disconnected. Of course, the address completion requires that the recipient is listed in the user’s Personal Address Book. The user can also create meetings or other calendar entries while offline.

IBM Workplace Managed Client uses a dedicated Outbox folder to store messages that have been sent but not yet synchronized with the server. So, after


composing a new message, or replying to or forwarding an existing one, the Outbox folder’s reference count is incremented by one, and the message waits for the user to connect and synchronize with the server. While it is waiting, the message can be edited or deleted by the user, so no message is final while working in offline mode.

Figure 2-2 Mailbox folders, including Outbox

After the user connects and synchronizes with the server, the messages in the Outbox folder are sent and placed in the Sent folder.

Attention indicatorsThis helpful feature might be overlooked at first. The default Inbox view shows a concise list of the mail a user has yet to read or simply has not filed or deleted. It shows the priority and type of message, who the message is from, the subject, date and time received, and size. But what is that blue circle, or that blue semicircle, as shown in Figure 2-3?

Figure 2-3 Attention indicators in the Inbox

These are the attention indicators in the messaging client. These show, at a glance, whether or not the e-mail was sent only to the user (blue circle), to a group of people including the user (blue semicircle), or the user was CCed in the note. If the field is blank for a particular message, the user was probably BCCed. These indicators can be useful to quickly determine which messages might need the user’s direct attention and are another factor to include when prioritizing.

Note: Attention indicators can be turned on or off in the client’s mail preferences.


Mail threadingThe Inbox also supports the concept of mail threads to show what mail messages are related to others in your Inbox. This uses subtle shading of subsequent messages when one message in the thread is selected. For example, using the default color scheme in the Red Hat Bluecurve windowing environment (GNOME), selecting a message in your Inbox causes that message to be highlighted in blue, and any messages visible in the Inbox that are related to the selected one are hightlighted in light blue, as shown in Figure 2-4.

Figure 2-4 Message thread highlighting and online awareness

Online awarenessThe mail subsystem is also tied very closely to the instant messaging capabilities the client offers. Virtually any field in the mail perspective that contains a user name is live name enabled, meaning that the user is able to see whether or not the person is online and available to chat through instant messaging. As shown in Figure 2-4, the users with a person icon next to their name are available online. For example, when the user A right-clicks the live name of user B, user A has the option to chat with the user B. If a user is in the Inbox, right-clicks a person with which that user wants to chat, and chooses Reply with Chat, the subject of the e-mail message is pasted into the user’s text entry field of the chat window. This way, recipients will automatically have some context regarding why they are receiving the chat request from the user.

Note: Figure 2-4 shows the mail messages in the thread one after the other, because no other mail was delivered between the messages in this thread. Messages do not have to be contiguous; the highlighting works no matter where in the Inbox the messages are.

Note: The awareness indicators in the mail subsystem are the same as the ones in the full Contacts pane of the instant messaging subsystem. This means that the icons in your mail will change depending on if the person is away from their desk or is in Do Not Disturb mode.


2.2.2 Instant messagingThe instant messaging subsystem of the client is a standards-based framework for supporting chat communication between one or many users. The client-side interface uses Standard Widget Toolkit (SWT) and JFace UI controls to access Session Initiation Protocol (SIP) and SIP for Instant Messaging and Presence Leveraging Extensions (SIMPLE) services that are provided by the IBM Workplace Collaborative Services server.

The client includes a panel in the Messaging perspective for the user to create an Instant Contacts list (a buddy list), which is a tree structure the user can organize with personal or public groups, as shown in Figure 2-5. The entries in the Instant Contacts list can be edited to change the name displayed and can be dragged and dropped in the UI to move between personal groups.

Figure 2-5 Instant Contacts list

The chat interface allows a set of rich text capabilities, including selecting your font and point size on the fly, along with boldface and italics, and a host of emoticons to personalize your chat sessions. There are also preference settings to enable you to save your chat sessions automatically, set a preferred font style, or show time stamps with each response in a chat window.

The client also offers n-way chat, meaning that you are able to share a chat session with more than one person. Establish this group chatting d by using the Invite Others button from within an existing chat session, or by selecting multiple people from your Instant Contacts list (using the Ctrl key while clicking individual names).


Figure 2-6 Example chat session

Another example of the close tie between the mail applications and instant messaging is seen when you want to save a transcript of a chat session. When selecting File → Save from the menu, you can save to a local file, which will save the output to an HTML file on your desktop, or save to Chat Transcripts. Chat Transcripts is a folder in your mail file that can be seen in the default Messaging perspective. See Figure 2-2 on page 24.

Also, as mentioned in “Online awareness” on page 25, the instant messaging framework provides the LiveNames objects required to handle presence awareness in any people fields used in the client. These include a viewer and controller to display and update status for the targeted fields. For more information about these, see the IBM Workplace API Toolkit, and Chapter 5, “Building a sample application for the IBM Workplace Managed Client platform” on page 125.

CalendarThe calendar in IBM Workplace Managed Client is easy to use and has a host of standard calendar and scheduling capabilities and also some added integration with Lotus Domino calendar users.

Important: The rich text capabilities do not work with browser-based chat partners.


Some of the standard capabilities of the client include:

� Support multiple calendar entry types: Appointment, Reminder, All day event, Anniversary

� Create, accept, decline, cancel, and reschedule meeting capabilities

� Calendar views: Includes one day, five days, one week, and monthly displayed in the Messaging perspective

� Support for roles in team calendars

� Support for international calendars: Gregorian, Japanese, Buddhist, Islamic-civil, and Taiwanese

The calendar is docked in the bottom-right corner of the messaging view. This can be expanded to open as a full tab in the main portion of the client, in which the user can choose to view a single day, five days, a full week, or a month at a time. The “dock,” however, give a concise snapshot of what is going on for a particular day, and most of the calendar features can be accessed there. Figure 2-7 shows the default docked view of the calendar.

Figure 2-7 Default docked view of the calendar

Clicking the down arrow on the calendar dock opens a menu in which the user can create any type of calendar entry, open the calendar in the main view, or create a summary view of the days activities.

Creating a new calendar entry enables you to add multiple types of invitees, Required, Optional, or FYI and enables repeating events. When a meeting is


scheduled, the chairperson can add or remove invitees, view invitee response status, or reschedule. Figure 2-8 shows the summary snapshot.

Figure 2-8 Summary snapshot of docked calendar

One good feature the calendar offers is the ability to include Notes calendar users in meeting invites sent using IBM Workplace Managed Client. If a chairperson invites a user that uses Notes mail and calendar, the user can respond as normal from their Notes client, with or without comments. The user’s Notes calendar is updated to contain the meeting information, and the chairperson is able to view the user’s response status as well. There are some limitations to the interoperability, including:

� No rich text support. It gets converted to plain text when sending.

� The chairperson cannot do a busytime look up to review the Notes user’s schedule.

� The Notes user is unable to counter the invite and propose a new time. Users can only accept or decline, with or without comments.

As with the mail functionality, the calender features can be accessed and used while offline. When going offline, the client synchronizes all calendar data to the local data store. After doing so, the user is able to respond to any invitations, create new calendar events, or modify existing events. When the client goes back online, the changes are synchronized, and responses, invitations, and so on are sent.


2.3 Notes plug-inAt the time of writing this book, the Lotus Notes plug-in for Linux is currently available only as a beta release. We believe it is a very important feature to cover in this book and so include it here.

Usually, the Notes plug-in is used as a replacement of the messaging services provided by Workplace. Although the messaging applications of Workplace Managed Client have some basic Lotus Notes integration, such as mail exchange and calender communication, Lotus Notes offers more, for example, access to Domino-based TeamRooms, Domino discussion groups, and custom-built Notes/Domino applications.

Users of IBM Workplace Managed Client inside a company that uses Lotus Notes need more integration and access to all shared Notes databases. This is the functionality the Notes plug-in provides, embedded into the client framework.

Note: As with the other elements that make up the Messaging perspective of the client, any name field in the calendar is also live-name enabled, so offers presence awareness. This is, of course, only available when the client is in online mode.


Figure 2-9 shows Workplace Managed Client with the Notes plug-in as a replacement of the internal messaging application.

Figure 2-9 Workplace Managed Client with Notes plug-in

2.3.1 Connecting to a Domino serverNew users of IBM Workplace Managed Client and the Notes plug-in have to connect to a Lotus Domino server first to get access to their mail file and the associated databases. This procedure is similar to the first access of a Domino server after installing a new Notes client.

Lotus Notes users must know the name and the TCP/IP address of their Domino server and their password or their personal Notes ID file, depending on the policy on the server.


To connect to a Domino server, perform the following steps:

1. At the initial start of Workplace Managed Client, click Lotus Notes icon on the left. The plug-in starts with the initial connection setup wizard, as shown in Figure 2-10.

Figure 2-10 The plug-in starts for the first time with the connection setup wizard

2. The next dialog box asks for your name and standard Domino mail server, as shown in Figure 2-11.

Figure 2-11 Enter your name and the name of your Domino server


3. If the server cannot be found, another dialog box requests a TCP/IP address for that server. This is usually necessary if the server is not located in the same subnet.

4. If you received your Notes user ID file separately or are connecting to an existing account, you are prompted for the location of your ID file. Click Browse to open a dialog box and search for your file, or simply type the location of the ID file into the field. See Figure 2-12. All Notes data will be secured with these credentials.

Figure 2-12 Location of your personal Notes ID file

5. The Notes ID file is secured with your Notes password. Therefore, at this stage, type your password into the Notes password dialog box, as shown in Figure 2-13.

Figure 2-13 Notes plug-in prompts for your password


Now, the standard setup is complete. You can add more connections to other types of services or set up a replication schedule that fits your needs before starting up the application. Figure 2-14 and Figure 2-15 show the replication settings. Setting up a replication schedule is useful for Notes databases.

Figure 2-14 Replication

Figure 2-15 Setting up replication


A detailed replication scheme can be entered in the same way. Figure 2-16 shows how a Notes client does this.

Figure 2-16 Configuring the replication schedules

Now the setup is complete. Before entering the application, the message shown in Figure 2-17 opens.

Figure 2-17 The plug-in is ready to work

2.3.2 Working with the Notes plug-inBecause the Notes plug-in is an independent application inside the Workplace Managed Client framework, it uses its own local databases and also its own server connections, namely to a Lotus Domino server in the network.


In the same way, the Notes plug-in uses its own credentials and a separate password. So, by clicking the Notes icon the first time in the Workplace Managed Client session, the Notes password dialog box opens.

Therefore, “Notes-in-Workplace” users need to log in twice to access their e-mail. At least it is possible to use the same password if you use the Domino LDAP service as a central LDAP source for Workplace.

After entering the password, Notes starts with the welcome page shown in Figure 2-9 on page 31. Use the Notes Applications panel to start the Workspace view, as shown in Figure 2-18.

Figure 2-18 Workspace view of Notes databases inside Managed Client


While using the Notes plug-in, the Workplace Managed Client menus adapt to the Notes environment. Therefore, you can create a new Notes database using the File → Database → New menu, as shown in Figure 2-19. This menu is only available when the Notes plug-in is active.

Figure 2-19 Creating a new Notes database inside of Workplace Managed Client

In the same way, you can right-click a database icon on the workplace and create local replicas similarly as in the usual Notes client.


You can view and adjust replication settings in the Replication view, as shown in Figure 2-20.

Figure 2-20 Replication view

In contrast to the full Notes client, there are certain UI elements that do not display in the Notes plug-in. There is no tool bar at the bottom of the plug-in where full Notes client users expect to have things such as the network activity indicator, document security indicator, and location switcher. In order to perform actions such as switching locations, the user must use the menu options.

Note: Although the Notes plug-in does not have the full tool bar at the bottom of the client that full Notes users expect, the status messages that Notes displays are all captured in the IBM Workplace Managed Client’s status bar, including things such as replication progress, quick search messages, and new mail alerts.


Another set of Notes UI elements not in the Notes plug-in are the “smart icon” bars. These icons give quick access to a number of operations that Notes client users might use frequently, such as looking at document or database properties, modifying text formatting, or attaching documents to messages. For example, when composing messages using the Notes editor, users must use key shortcuts or select the Text menu displayed in the top frame to change any of their text properties, use the permanent pen, attach or import files, or perform other common activities.

Figure 2-21 Reading mail is more convenient with a hidden Notes Applications panel

Tip: Because Workplace Managed Client makes extensive use of panels on the left side of the window, which reduces the size of the usable area on the right, it is useful to hide these panels by clicking the small arrow on the right side of the frame, as shown in Figure 2-21 on page 39.


An aspect of running the Notes plug-in under IBM Workplace Managed Client that users might find confusing is the availability indicator at the top right of the window (see Figure 2-22). Though this is displayed in the Notes plug-in view, keep in mind that this indicates the availability of the user on the IBM Workplace Instant Messaging service. It does not pertain to the embedded Lotus Sametime® services with which full Lotus Notes client users might be familiar. Currently, there is no Sametime services for the Notes plug-in for Linux.

Figure 2-22 Instant Messaging availability indicator in the Notes view


The Workplace Managed Client Notes plug-in gives full access to the Lotus calender, and it is possible to communicate with other Notes users by proposing new appointment times, viewing schedules, and accepting meeting dates. Figure 2-23 shows the calendar.

Figure 2-23 Access your Lotus Notes calender using the plug-in inside Workplace Managed Client


Other Notes applications and databases are accessible using the plug-in, such as Notes discussion forums or document libraries, as shown in Figure 2-24.

Figure 2-24 Notes Discussion forum inside the plug-in


Documents stored in the Notes document library can be opened and edited using the editors of the productivity tools in the same framework. This is extended functionality over the pure Notes client, where you have to install a separate office suite to do this. Figure 2-25 shows the Notes document library.

Figure 2-25 Notes Document Library

Another very good integration point between the IBM Workplace Managed Client interface and the Notes plug-in is access to the IBM Workplace Managed Client document libraries when attaching files to new documents in the Notes plug-in. Selecting File → Attach when in a rich text field of an open document in the Notes plug-in opens a dialog box enabling the user to browse the file system. The dialog box also contains a button enabling the user to select files accessible from the client’s Documents perspective. Therefore, users can attach files from either their private document library or one of the server-based document libraries to which they have access directly to a Notes document. See Figure 2-26 on page 44 and Figure 2-27 on page 44. Additionally, when


detaching or saving an attachment stored in a Notes document, the user has the choice of saving it to a document library.

Figure 2-26 File → Attach dialog box

Figure 2-27 Select an item from a document library


Overall, the Notes plug-in under Linux is a great mechanism to access a more complete Notes experience from Linux platforms than what has been available previously. It is a great way to help integrate Linux desktops into enterprise Notes environments that have previously not had comprehensive Notes application support for their Linux users.

2.4 Activity ExplorerIn this section, we describe Activity Explorer.

2.4.1 Activity Explorer overviewThe Activity Explorer represents a large step forward in collaborative productivity tooling. It enables users to organize related work items (instant messaging chats, mail messages, documents, discussion threads, and so on) into activities, which can be used by a single person or shared among teams. It is intended to merge the strengths of real-time (synchronous) communication, such as instant messaging where people focus on a particular problem simultaneously, with the rich collaboration features of shared workspaces, in which people interact asynchronously as they view, edit, or respond to documents or discussion threads saved on a server. It helps to organize workflow and reduce the scatter effect of various sources of information.

Using Activity Explorer, people create and share five types of objects: persistent chats, files, folders, notes, and screen captures. Any shared object can stand alone as a complete interaction, or it can be the starting point for a complex discussion in which multiple shared objects are connected into a hierarchically structured document collection known as an activity, or activity thread. As a project progresses and components of the project begin to take shape, members add branches related to each component to the activity thread. Eventually, the activity thread becomes a blueprint or map of the project, providing both a visual representation of the way in which ideas evolved over time and a repository for the collected knowledge of the project.

The membership list for an object determines who can use it. When a user creates an object, the user specifies a list of people with whom to share the object. These people become the initial members of the object. As a member, a user has full control of the object. Members can open the object, modify it, post responses to it, add new members, or even delete it.

Membership in an activity is dynamic and heterogeneous. By default, when a member posts a response to another object, the response inherits the membership list of the parent object. But any member can add or remove


members from the list at any time. Furthermore, the membership list of any object in an activity is independent of the lists for other objects.

Collaboration between members can be synchronous or asynchronous, depending on the type of object and whether other members of the object are currently present in the object. For example, persistent chat and shared screen objects can be used synchronously if multiple members of the object are active at the same time. When multiple members of a persistent chat or shared screen are present at the same time, if one member makes a change to the object, the change is displayed to the other members as it is made, in real time.

By contrast, shared file and shared note objects can only be used asynchronously. When a member opens a shared file or shared note, a temporary, local copy of the object downloads to the member’s computer. Any changes that the member makes occur in this local copy of the object. When the member completes work on the object and saves it, the edited local copy replaces the version of the object on the server. Therefore, if multiple members edit a shared file or shared note at the same time, when they save their work, only the last version saved to the server will remain.

To encourage communication among members, Activity Explorer goes beyond the use of generalized people awareness by embedding awareness information in every shared object. When any member uses an object, the object is activated. To indicate that an object is active, Activity Explorer highlights the object in green. Object-level awareness helps to reduce sharing conflicts and promotes opportunistic collaboration, because a member knows when another member is at work on an object that they have in common and can coordinate their workflow in real time.

In addition to providing awareness information, Activity Explorer also provides an alert system to inform members when an object is being used or has changed. As soon as a member activates an object, other members receive alerts informing them that the object is in use and what actions have been taken. Members can set preferences to control the types of alerts they receive. Figure 2-28 shows an example alert.

Figure 2-28 Alert to members

The Activity Explorer also uses visual indicators to inform a user when changes have been made while he or she has been offline. Activities are marked with a red exclamation point to indicate that a change has occurred, and individual


objects are marked with a yellow star burst to show what objects have been modified, as shown in Figure 2-29.

Figure 2-29 Activity object has changed

2.4.2 Using the Activity ExplorerIn order to use the Activity Explorer, a user needs:

� IBM Workplace Managed Client (activities are not supported through a browser interface).

� A user policy on the server that has instant messaging, both use and create access to document libraries, and access to the Activity Explorer application.

After the application is provisioned to the client, and the policy is enabled properly, the user can access the Activity Explorer view from the application switcher. The center frame in the Activity Explorer view contains two tabs, one called Activity List, which shows the user the complete list of activities the user is a member of, and the other called Activity Tree, which gives a hierarchical view of each of the activities.

Important: These user policy settings are required due to how the Activity Explorer stores content and manages alerts and communication among members. For example, if instant messaging is not enabled, functionality such as real-time object updates are not be possible. Also, users disconnected from instant messaging (IM) can send alerts, but not receive them, as though they were connected, but put themselves into Do Not Disturb mode.

In addition, if a client is in full offline mode, the Activity Explorer is disabled. Users can access the Activity Explorer view, but are unable to perform any operations on activities.

Note: The distinction between the Activity List and Activity Tree tabs is that the Activity List only shows root objects by default, while the Activity Tree allows the user to navigate down to each of the shared objects within an activity. See Figure 2-30 for an example. The Activity List can be configured to show all, or a subset, of activities in the Activity Explorer preferences.


The other UI elements include a Details pane on the top left, and an Activity Thread pane on the lower left. The Details pane provides information about the particular shared object selected, including who created it and when, who last modified it and when, and whom the members are. The Activity Thread pane is similar to the Activity Tree tab, in that it enables the user to see a hierarchical view of all of the objects, but it does this for only one activity at a time. Selecting an object somewhere in the depths of an activity presents the entire activity chain in the Thread pane.

Figure 2-30 Overall Activity Explorer view

The user can create new activities or shared objects at any time. It is usually a good idea to use a shared folder as the root object of an activity thread, given the hierarchical nature of activities. Having one folder to parent an activity makes them easier to track. After a new activity has been created (using the New Activity button), the user can use the Post button to create a shared object associated with that activity. These are the types of shared objects.

Shared foldersFolders in an activity are simply containers and do not actually have any content of their own. They can be used to organize the other types of objects by whatever common theme they might have. Objects must be created as


responses to the folder, and unfortunately, folders do not support drag and drop from other activities (to reorganize), but do support drag and drop from things such as a document library or the user’s file system.

Shared notesThis opens a small memo-pad application with some rich-text capabilities that users can use to enter comments, questions, or share information. This is not tied to a document library, so there is no versioning or locking capability. The server retains the version that is the last saved by any member. Figure 2-31 shows a shared note object.

Figure 2-31 Shared note object

Shared filesThis is any type of document that users want to share. It can be taken from a user’s file system, a document library, or any other document repository. As with shared notes, when editing a shared document, the user is modifying a local copy which, when saved, is put back on the server. This means that the new version replaces any existing version stored on the server.

Shared snapshotsThese are screen captures that can be viewed by all members. When creating a new snapshot, a transparent dialog box opens that has a title bar and a Capture

Tip: Create new objects by dragging and dropping any other object type, not just shared folders.

Tip: Creating a shared file object is as easy as dragging a file from a document library or your desktop to a user in your Instant Contacts list.


Snapshot button, as shown in Figure 2-32. The window can be resized and dragged around the desktop, and the user can see the desktop widgets behind the dialog box in order to ensure that it will capture exactly what is intended. After clicking the Capture Snapshot button, the image is taken, and the other members are alerted to the new object. Anyone can then mark up the image with a rudimentary “pen,” which the other members can see in real time.

Figure 2-32 Shared Snapshot Tool

Persistent chatsThese helpful little objects are similar to standard one-to-one or n-way chat sessions in that they can be used for synchronous collaboration with one or many other users. However, persistent chats can also be used for asynchronous communication. When the chat is created, it is saved to the server, and its contents are automatically updated and preserved in the shared object. That way, the entire conversation is preserved in the object, and when the object is closed, no context is lost. At any time, members can reopen the object and continue the conversation with other online members, or simply add to it for others to pick up when they are available. One key limitation here is that standard chat sessions initiated through the Instant Contacts panel cannot be converted to persistent chat objects. A persistent chat must be started by posting a new shared object to an activity.

When creating a new shared object (of any type), the object form has a field that enables the user to specify with whom the user wants to share the object. The user can build the initial member list in this field, name the object, and then create it.

Important: IBM Workplace Managed Client enables a user to be online, but disconnected from the instant messaging server. Persistent chat and shared snapshots cannot be created while disconnected from IM. Existing objects of these types can be viewed, but not modified.


From here, we leave it to you to further discover the possibilities available with the Activity Explorer. It is a very promising application that introduces a new and very powerful collaboration paradigm, and when used effectively, can significantly improve many types of project workflows.

2.5 DocumentsThe documents feature in IBM Workplace Managed Client offers a client-side interface into IBM Workplace Documents library services. This includes the capability to create, edit, and store documents, presentations, spreadsheets, and project plans. Libraries and documents can be accessed directly on a server to gain locking and versioning capabilities, or a user can synchronize them to a local, encrypted data store for increased security and flexibility of use.

IBM Workplace Managed Client documents functionality is tied very closely with the use of the IBM productivity tools. For a more detailed discussion of the IBM productivity tools, see Chapter 4, “IBM productivity tools” on page 113.

2.5.1 Working with document librariesDocument libraries are the containers that hold the various types of content that a user or group wants to store. They are generally structured using a hierarchy of folders and contain documents to be shared by multiple people. Figure 2-33 on page 52 shows the Documents view.


Figure 2-33 Documents view

When working online, the user is presented with a list of all of the libraries to which they have access, including those stored on the server and those stored locally. This list can be filtered by the user to show only public libraries, libraries created by the user, or libraries placed in the user’s Favorite list.

Online libraries contain the most recent changes from any user using the library. The server provides locking capabilities so that multiple people cannot modify the same document concurrently while online. Users can also import new documents to a library, provided the server administrator has enabled this in the user policy. To import, simply select the library/folder to which to import and drag and drop the file from the local file system into the client window. Alternately, there is an Import button available in the selected library.

For any library that the user owns, that user can use the library’s context menu (right-click) and select Manage Libraries. The embedded browser is displayed in the Documents view and opens to the Documents portal page. From here, the user can select which library to manage and either modify the library (add, delete, and modify folders and documents), or manage user access in the Members view. The Web UI is the only way to manage user access to libraries.


While accessing a library on a server, the user can choose to make the library available offline (see Figure 2-34). Offline libraries perform significantly better than those used online. After making the library available offline, the user can modify documents within the library or add or delete library content (depending on the level of access).

Figure 2-34 Right-click a library to open this menu

When working offline, the user must synchronize regularly to make sure changes are reflected in the server copy as well. In some cases, conflicts can occur. After synchronizing, users might see a Synchronization Conflicts folder that appears in the library. If so, the user can select the conflict document within that folder and resolve the conflict as appropriate.

In addition to any libraries created on the server, replicated locally, or both, every user has a private document library that is stored on their local machine and cannot be shared or synchronized with a server. The name of this library is the same as your user name, and because it is not shared on the server, users who want to preserve their data need to back it up manually. Although users are not able to share this private library with server-based users, users can copy individual documents from this library to any server-based library in which they are able to create documents.

Important: For synchronization, select either Refresh Document Library from the libraries context menu (right-click the library) or the Tools → Synchronize Now menu option. The document libraries do not synchronize through SyncML as our messaging applications do. IBM Workplace Documents uses a remote Portal Content Management (PCM) interface to a WebSphere Portal Content Publishing store on the server. Due to this, document library synchronization can still occur when normal SyncML interfaces are not available.


2.5.2 Working with documentsLibraries can contain virtually any type of file to share among teams and can be populated by importing, dragging and dropping, or selecting a library or folder and choosing to create a new document. While in a library, a user can click the New button, and select one of the following types:

� Document

� Spreadsheet

� Presentation

� Project Plan

Selecting one of these items opens an embedded version of one of the IBM Workplace productivity tools editors (see Figure 2-35 on page 55).

Note: The default format of these newly created documents is the OASIS OpenDocument Format (ODF), although they can be saved in other productivity tool formats as well (Microsoft Office and IBM productivity tools native formats). See Chapter 4, “IBM productivity tools” on page 113 for more information.


Figure 2-35 Embedded document editor

Another option for creating new documents in IBM Workplace Managed Client 2.6 is to create one from a template. If a template (Microsoft Office, ODF format, or IBM productivity tools native templates) is stored in the library, you can right-click the template and select New Document from this Template, as shown in Figure 2-36 on page 56, or simply double-click the template to open a new document.


Figure 2-36 Creating a new document through a template

You can edit existing documents using either system tools or the IBM productivity tools. In most cases, IBM Workplace Managed Client on Linux opens productivity documents (word processing, spreadsheet, and presentation) in the one of the IBM productivity tools editors. This is because Microsoft Office is not supported on Linux, and the IBM productivity tools editors support a wide variety of productivity document formats. Libraries that contain documents of other formats, such as an image format, will open them based on whatever utility is associated with that file format, for example, clicking a PNG file can open the Eye of GNOME photo editor.

The 2.6 version of the client also offers a good mechanism to preserve data integrity when editing documents on the server. If a user is editing a document, and a network error is detected (for example, the user is unable to connect to the

Important: There are other options for creating and editing documents. With IBM Workplace Managed Client 2.6, ISVs can integrate their own tools into the Documents application so that additional third-party tools can be available directly within the client. Although this is beyond the scope of this book, see the IBM Workplace 2.6 API Toolkit for samples of how this can be done.


server), the client automatically switches to offline mode and prompts the user to save the document as a new copy in a local library, as shown in Figure 2-37.

Figure 2-37 Save a new local document when the server is unavailable

One of the powerful elements of using IBM Workplace Documents is the ability to use document version history. If a library owner has enabled versioning, the user can select Create Archive Version of the document. This allows version histories to be saved, and only the document on which the user is currently working will be considered as the current version. If the user wants to change the current version, the user simply needs to open a version from the Version History list, and select Promote to Current Version. Versioning is only available when working with libraries online.

2.6 Team spacesIBM Workplace Collaboration Services provides team collaboration capabilities beyond just document sharing. It also includes team spaces that serve as forums groups can use to carry on discussions and share information in a thread-based


hierarchy. Each TeamRoom can contain multiple forums that can be created to track various topics. Access and permissions to TeamRooms are provided by the TeamRoom owner.

Figure 2-38 Team Spaces view

The team spaces client interface is fairly simple. Click Team Spaces on the application switcher to load the list of available team spaces. In this view, a user can choose which team spaces to show, select which are favorites, search for team spaces by keyword, or open a particular team space. Double-click a team space to launch the embedded browser, which either provides the server login window, or takes the user directly to the TeamRoom on the server, if that user has previously authenticated with the server.

All team space interaction is done through the browser interface, either embedded or externally. There is no native client UI for using team spaces. In the client, using the embedded browser provides full functionality when working with a team space. The user can select various forums, create topics, create and edit documents with the text editor, and delete documents or threads provided that the user has sufficient access. Figure 2-39 on page 59 shows accessing team spaces in the client.


Figure 2-39 Accessing Team Spaces

Team spaces cannot be made available offline. They are strictly hosted on the server, thus are not available in the embedded browser if Workplace Managed Client is in offline mode.

2.7 Embedded browserWith the embedded browser, a user can access all aspects of IBM Workplace functionality from within the context of IBM Workplace Managed Client. Because certain portions of the IBM Workplace product functionality are only offered through Web interfaces (team spaces, for example), having a mechanism to access them from within the client in a seamless manner is important.

Although the embedded browser is available on the fly when accessing functionality that requires a Web interface, the client extends the usefulness of the browser by allowing access to it directly from the application switcher. By clicking the Web Browser icon on the switcher, the browse launches in the central frame of the client. It acts as a fully functional Web browser, because it is executing the Mozilla 1.4.3 core that is installed with the client platform. Use it as


a standard Web browser, including the normal navigation controls, bookmark support, and most of the other useful and expected feature.

2.8 External applicationsIn Workplace Managed Client 2.6, two core Workplace applications are accessible only with the use of an external browser window. These are IBM Workplace Collaborative Learning and IBM Workplace Web Conferencing.

The applications each have an icon in the Managed Client page switcher which, when clicked, opens a browser. The new browser window displays the same portal page that users see when accessing the respective applications through a browser.

2.8.1 Workplace Collaborative LearningIBM Workplace Collaborative Learning provides online learning functionality (commonly known as e-learning) within the Workplace environment.

Large companies and other organizations spend large amounts of money on training their employees and customers. The need for a standards-based, flexible, and secure delivery method for course content is clear. Workplace Collaborative Learning is a flexible delivery vehicle for standards-compliant educational content that also provides full management and reporting functionality.

Tip: The default URL that is displayed when launching the browser through the Web browser icon is controlled by a policy set by the administrator. To override this setting, the user can edit this file: $WORKSPACE/.metadata/.plugins/org.eclipse.core.runtime/.settings/com.ibm.rcp.ui.browser.prefs

Modify the following line:

com.ibm.rcp.ui.browser.initialUrl=<your URL here>

Tip: Neither Collaborative Learning nor Web Conferencing are enabled by default in the Managed Client. For a description of how to enable this feature, see the Release Notes or Workplace Managed Client 2.6 User's Guide, available at:

http://www.ibm.com/developerworks/workplace/documentation/clienttechnology/



To review its features:

� Delivery of Sharable Content Object Reference Model (SCORM) and AICC content. These are the de facto standards for electronic course content.

� Scheduling of instructor-led training.

� Combine virtual (electronic) and physical (scheduled) lessons into so-called blended learning.

� Integration with IBM Live Virtual Classroom.

� Skills database to track skills and competencies.

� Detailed reporting of student progress; find areas of difficulty across your courses.

2.8.2 Workplace Web ConferencingIBM Workplace Web Conferencing is a tool that enables you to collaborate in real time with colleagues, suppliers, and customers.

Participants can share documents, share screens, and co-edit documents in real time without the need for lengthy e-mail exchanges or the expense and hassle frequently associated with travel.

Some of the features of Workplace Web Conferencing include:

� Supported in any Web browser with Java support.

� Virtual whiteboard.

� Polling tool to help reach a group consensus.

� Recording and playback tools.

� A free-of-charge audio adaptor enables control of the teleconference (purchased and billed from third-party providers) from the meeting room interface. Moderator can mute participants, raise and lower volume, or have the conference call them directly.

� Encrypt Web conferences to restrict meeting content to authorized viewers.

� Instant messaging integration.

Note: There is one set of IBM Workplace Managed Client applications that we do not cover here. In many of the screen captures, you might be able to see an Applications icon on the application switcher. This provides access to the client’s data access designer and viewer tools, which enable the user to create new, or edit existing Cloudscape database applications. Although this functionality is important, it is an extensive topic to cover and beyond the scope of this book. For more information about the data access tools, refer to the client help system.


Chapter 3. Workplace Managed Client 2.6 on Linux installation and configuration

This chapter explores the installation and configuration process required to provide an end-to-end Linux-based IBM Workplace Managed Client solution. It considers all stages of deployment, from server through to workstation.

We cover the following procedures:

� Configuration of an IBM Workplace Collaboration Services 2.6 server for Workplace Managed Client support.

� Role-based access to Workplace Managed Client and its individual applications.

� Installation of Workplace Managed Client.

Throughout, we describe the processes at work behind the scenes. This background knowledge will help when creating advanced configurations.

In addition, we explore any considerations specific to the Linux platform.

3


3.1 Configuring a Workplace Collaboration Services 2.6 server for Managed Client support

Unlike the browser, the Managed Client is not supported by a newly installed Workplace Collaboration Services server. The server client installer (SCI) is a separate software bundle, provided by IBM, that configures a Workplace Collaboration Services server for Managed Client support.

This section explains the rationale for a server client installer and proceeds to cover the SCI installation and configuration in some detail.

3.1.1 What is the SCI?What does the term “server client installer” mean? At first, it resembles an oxymoron. In reality, the SCI encapsulates the operations and software artifacts that must be carried out or be present on the Workplace Collaboration Services server to allow clients to install and run the Managed Client. Because clients download the Managed Client from the server, all the client components must be present on the server.

The SCI performs, at a very high level, the following functions:

� Add Rich Client Platform Markup Language (RCPML) to the WebSphere Portal list of supported markups.

� Create RCPML-aware portal pages for each Managed Client application.

� Create an Eclipse update site containing all of the features and plug-ins that make up the Managed Client.

� Copy the Managed Client installer binaries onto the server.

Note: Note that depending on which Linux distribution you are running, also refer to Appendix A, “Installing IBM Workplace Managed Client on other Linux distributions” on page 195. In this appendix, we test installations of Workplace Managed Client on SUSE Linux 9.3, Debian Testing, and Ubuntu 5.10. In each case, the information contained in this appendix allowed us to successfully install the Workplace Managed Client.

Tip: In 3.2, “Installing Workplace Managed Client” on page 90, we describe the installation process for end users. This section is only for administrators.


For more information about what happens at each step, consult the following sections. If you do not want to assimilate all of this information right now, do not worry; the SCI installation is straightforward.

Rich Client Platform Markup Language (RCPML)The installer’s first task is to add RCPML to the list of output types supported by WebSphere Portal. HTML is not the only markup supported by Portal; indeed, even right out of the box, it supports Wireless Markup Language (WML), a markup language for mobile devices. RCPML is simply another XML-like markup language, one specific to the Managed Client.

RCPML provides the following functions:

� Specifies which Eclipse views are required to display the application.

� Specifies the application’s layout.

It does contain other information, such as where to download the plug-ins, but these two points are the most important.

Portal pagesThe SCI creates one portal page for each Managed Client application. Each page supports RCPML markup. During the provisioning process, the client downloads each RCPML page. Each portlet specifies which Eclipse view is to be used to render it in the Managed Client and a list of all that view’s required Eclipse plug-ins.

The layout and position of portlets on a portal page is mirrored in its corresponding application page in the Managed Client. In addition, access settings on these pages govern access to Managed Client applications.

Tip: A greater understanding of the SCI operations will help when we begin making customizations, such as setting more advanced access policies (3.1.6, “Configuring access to the Managed Client and setting policies” on page 83).

Important: RCPML is not a replacement for hand-crafted SWT code. It does not describe individual SWT widgets within a view. This is a common expectation (and misconception) upon introduction to RCPML. Other upcoming IBM technologies (for example, visual editors) will abstract away the need to code SWT when developing Workplace applications.

Chapter 3. Workplace Managed Client 2.6 on Linux installation and configuration 65

It should be clear now how closely linked WebSphere Portal and the Managed Client are and how the client can benefit from WebSphere Portal features, such as access policies.

Eclipse update site and installer executableAn Eclipse update site contains a set of Eclipse plug-ins and features (in JAR file format) with a list of the plug-ins and features. This is a common distribution method for the third-party Eclipse plug-ins that the Managed Client leverages.

During the provisioning process, the Managed Client downloads all the required plug-ins and features from such an update site.

The SCI creates and populates the update site on your HTTP server.

It also places the installer executable, for both Microsoft Windows and Linux platforms, on your HTTP server. However, the executables do not form part of the update site.

3.1.2 PrerequisitesThe section lists the prerequisites.

Workplace Collaboration Services 2.6 server The first and most important prerequisite is a properly configured Workplace Collaboration Services 2.6 server.

Although the details of installing a Workplace Collaboration Services server is outside of the scope of this book, in this section, we review the components that make up a Workplace Collaboration Services server. We use these terms throughout the remainder of this chapter.

Tip: As implied, the client maps portlets to views. To complete the analogy, each page as a whole is an Eclipse perspective. The Managed Client contains code to build perspectives at run time. This is a feature that the base Eclipse platform does not support by itself.

Information: It might be puzzling that the Managed Client has its own set of portal pages. Can it use the same portal pages as the browser?

In practice, we do not necessarily want to mirror every single portlet in the client and vice versa. Perhaps, with maturing technology, this will be the case. Currently, however, Workplace maintains a separate set of pages for the browser and Managed Client.


The Workplace Collaboration Services server, consists of the following components:

� The application server is the underlying Java 2 Platform, Enterprise Edition (J2EE™) platform. In the context of Workplace, this is IBM WebSphere Application Server. This ultimately sits under all of the other components, namely the portal server and the Workplace Collaboration Services server itself. In addition to the core environment, it provides clustering and fail-over support to all applications running inside it.

� A portal provides a single point of access to information, applications, and people. Portals are typically provide a customized experience to end users. IBM WebSphere Portal is a J2EE-based portal server that sits on top of the WebSphere Application Server platform.

� Workplace Collaboration Services server runs in WebSphere Portal. It is a collaborative application platform running in the J2EE and WebSphere Portal environments. It inherits the clustering, failover, and customability of the two underlying platforms.

For further information about installing and configuring Workplace Collaboration Services server and WebSphere Portal, refer to IBM Workplace Collaboration Services: Release 2.5 Deployment Guide, SG24-6777, available at:

http://www.redbooks.ibm.com/abstracts/sg246777.html

HTTP serverWebSphere incorporates a basic HTTP server. This can be used to serve Workplace content. However, Managed Client support mandates the use of a dedicated HTTP server. This is necessary to operate the Eclipse update site.

This book assumes that IBM HTTP Server is installed.

Note: For additional details about installing and configuring a Workplace Collaboration Services server, see the Workplace Collaboration Services 2.6 Information Center:

http://publib.boulder.ibm.com/infocenter/jwphelp/v2r6m0/index.jsp

In addition, refer to the WebSphere Application Server and WebSphere Portal Information Centers:

� WebSphere Application Server:

http://www.ibm.com/software/webservers/appserv/was/library/library5.html

� WebSphere Portal:

http://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html#500


http://www.redbooks.ibm.com/abstracts/sg246777.html




3.1.3 The installation processIn this section, we describe how to install the SCI on a non-clustered Workplace Collaboration Services server with either a local or remote external HTTP server. The only difference between the two scenarios is that a remote HTTP server requires you run the SCI twice, each time with slightly different options. We attempt to make the instructions as simple as possible. However, when following these instructions, you might skip certain steps depending on whether you are running the SCI on the Workplace Collaboration Services server or HTTP server.

The SCI is distributed on a pair of CDs. We assume that you are comfortable with mounting and unmounting CDs in Linux.

Perform the following steps:

1. The installer executable, named setupLinux.bin, is on disk 1 in the top-most folder. Whether you copied the CD contents to your disk or are working directly from CD, run the installer now by either double-clicking its icon in a file manager or entering its full path into a terminal.

Important: Owing to loose coupling between WebSphere and the HTTP server, the instructions can be easily tailored to any HTTP server.

Note: If you operate a clustered deployment, use this section as a reference, but consult the information center for full details about the differences between the procedure for a clustered installation:

http://publib.boulder.ibm.com/infocenter/jwphelp/v2r6m0/index.jsp?topic=/com.ibm.wcs26.ic.doc/infocenter/i_inst_t_install_prov_server.html

For information center documentation about the installation on non-clustered deployments, see:

http://publib.boulder.ibm.com/infocenter/jwphelp/v2r6m0/index.jsp?topic=/com.ibm.wcs26.ic.doc/infocenter/i_inst_c_rcpinstall_in_lwp_install.html

Tip: If your server has only one CD drive, it might be prudent to copy the entire contents of each CD to a temporary location on your server’s hard drive, for example, disk 1 to /opt/sci/disk2 and disk 2 to /opt/sci/disk2.


http://publib.boulder.ibm.com/infocenter/jwphelp/v2r6m0/index.jsp?topic=/com.ibm.wcs26.ic.doc/infocenter/i_inst_t_install_prov_server.html



2. First, select a language for the installation process, as shown in Figure 3-1. In this guide, we select English.

Figure 3-1 Language selection

Tip: The SCI also has a command line mode. Access this using the -console switch:

./setupLinux.bin -console

This can be useful if, for example, you use Telnet or SSH to access your Workplace Collaboration Services server or are on a high latency link to your Workplace Collaboration Services server.

We assume that you use the graphical installer.

Important: Of course, you can run the installer as the root user. However, it can (and, many UNIX purists argue, should) be run as whatever user has read/write access to the WebSphere folder.

Whatever the case, it is highly unlikely that the SCI will attempt anything dangerous if you run it as the superuser.


3. The next dialog box, shown in Figure 3-2, welcomes you to the installer. Click Next.

Figure 3-2 SCI welcome

4. At the dialog box containing the licenses associated with the SCI and its technologies, if you agree to the license terms, click Next.


5. Now, the SCI prompts for an installation location (Figure 3-3). Because most SCI components integrate with WebSphere Portal and the HTTP server, this leaves only the installation logs and the uninstaller to be placed in this location. The default value should be OK. Click Next.

Figure 3-3 SCI installation location prompt


6. Select a typical installation or a custom installation, as shown in Figure 3-4. If you operate a local HTTP server, select Typical, click Next, and proceed to step 7.

If you operate a remote HTTP server, select Figure 3-4. On the following page, select only WebSphere Portal content, IBM WebSphere Everyplace® Device Manager, and IBM Workplace Collaboration Services Contents. With the appropriate components selected, click Next.

Figure 3-4 Typical or Custom installation selection


7. The next dialog box, shown in Figure 3-5, is the first of three important SCI dialog boxes. SCI probes a few common installation locations (such as /opt/websphere and /opt/IBM/Workplace) and has probably populated the field. The default configuration URL is usually correct (localhost is fine in this case). However, you must enter the Portal administrator’s user name and password. Click Next.

Figure 3-5 WebSphere Portal server configuration


8. Provide the WebSphere Application Server configuration, as shown in Figure 3-6. Again, SCI probes your machine for the correct value. It does not probe for the application server’s cell name. Enter the cell name. Click Next. If you operate a remote HTTP server and are at this point installing only the Workplace components (see step 14 on page 78), proceed to step 10 on page 76.

Figure 3-6 WebSphere Application Server configuration

Tip: The WebSphere Application Server cell name is often, though not necessarily, the machine’s host name, that is, its fully qualified domain name minus the domain name portion. For example, isv4 is the host name portion of the fully-qualified domain name isv4.cam.itso.ibm.com.

This convention might not be applicable in a clustered environment.


9. Figure 3-7 shows the final interactive dialog box, prompting for the HTTP server configuration. Assuming that we use IBM HTTP Server and it is installed under /opt/httpserver, we enter the value /opt/httpserver/htdocs/en_US. Adapt this value appropriately if the HTTP server is installed in a different location or set to a different locale. When satisfied that the location is correct, click Next.

Figure 3-7 HTTP server configuration

Tip: SCI only needs a path to the content root, that is, the top-most folder from which content is served. Because SCI simply copies the files to that location, the type of HTTP server is irrelevant.


10.The next dialog box outlines the procedure and presents an estimate for the required amount of required disk space, as shown in Figure 3-8. Click Next to begin the installation.

Figure 3-8 SCI installation location and required amount of disk space


11.An installation progress monitior illustrates the progress toward completion, as shown in Figure 3-9.

Figure 3-9 SCI setup progress monitor

12.At some point. you will be prompted for the path to the second SCI CD. Enter the path and click OK to continue, as shown in Figure 3-10.

Figure 3-10 Entering the path to the second SCI CD

13.After some moments, the installation finishes. The final dialog box displays the path to the SCI log files (useful if something unexpected happened). It recommends that you consult the Information Center for more information about any further setup steps. Click Finish. See Figure 3-11 on page 78.


14.If you operate a remote HTTP server, we must now rerun the SCI on the HTTP server. Repeat steps 1-12. However, when you reach step 6, select Typical followed by only the Update bundles, Installation files, and CD Script options. Continue as before, remembering that the selections cause certain steps (for example, step 7, the WebSphere Portal configuration dialog box) to be omitted.

Figure 3-11 SCI successful installation message

3.1.4 SCI setup summaryThis section contains a concise summary of the previous, more in-depth steps:

1. Start the installer (setupLinux.bin on the first SCI disk).

2. Choose a directory for the log files and uninstaller.

3. Select the Typical installation if you have a local HTTP server; otherwise, select Custom. Then, select WebSphere Portal content, IBM WebSphere Everyplace Device Manager, and IBM Workplace Collaboration Services Contents for the Workplace Collaboration Services server. Select Update bundles, Installation files and CD Script for the HTTP server.

Tip: In most cases, the only further setup is to restart the Workplace Collaboration Services server. Do so now.


4. Enter the portal server configuration information.

5. Enter the application server configuration information.

6. Enter the HTTP server configuration information.

7. If necessary, rerun the SCI on the remote HTTP server.

3.1.5 Uninstalling the SCIIn this section, we describe how to uninstall the SCI.

You might want to perform this procedure if you are upgrading the version of the client supported by the server.


1. The SCI uninstaller is in the _uninst directory in the SCI install directory you specified during the installation. The executable is called uninstaller.bin. Run this executable either by double-clicking its icon in a file manager or typing its full path into a terminal.

Note: If you operate a remote HTTP server, then, similarly to the installation process, you must run the SCI twice, once on the Workplace Collaboration Services server and then again on the HTTP server. As with the installer, be prepared for slight differences between the uninstallation procedures on the Workplace Collaboration Services server and HTTP server.

Important: Unlike the client, which can, if absolutely necessary, be removed manually, the SCI installs files into many different directories. It also modifies some of the WebSphere Portal configuration files. For this reason, we do not recommend a so-called manual uninstallation of the SCI and do not describe it here.

Tip: The uninstaller, like the installer, supports command line operation. Supply the -console parameter to the uninstaller executable.


2. Select a language for the uninstallation process, as shown in Figure 3-12. In this example, we select English. Click OK.

Figure 3-12 Uninstaller language selection

3. The next dialog box simply welcomes us to the uninstaller. Click Next.

4. Select which components of the SCI to uninstall, as shown in Figure 3-13. We choose all components, because it is unlikely you want any one component to remain by itself. All components are selected by default. Click Next.

Figure 3-13 SCI uninstaller component selection


5. The next dialog box, shown in Figure 3-14, prompts for the Workplace administrator’s user name and password. SCI remembers the user name entered when installing the SCI, but you must enter the password. Click Next.

Figure 3-14 User name and password entry


6. Now, SCI pauses for a few moments while it processes the XMLAccess files on the server. When finished, it displays a confirmation of the procedures it will carry out, as shown in Figure 3-15. If everything looks acceptable, click Next.

Figure 3-15 SCI uninstaller confirmation message


7. The uninstaller pauses for a few minutes while the SCI is uninstalled. When finished, it displays a successful uninstallation message. Click Finish.

Figure 3-16 SCI uninstaller successful uninstallation message

8. Restart the Workplace Collaboration Services server.

9. If you operate a remote HTTP server, run the uninstaller on the HTTP server. Repeat steps 1-8, bearing in mind that certain steps might be omitted because different components are being removed.

3.1.6 Configuring access to the Managed Client and setting policiesOne of the most attractive features of the client from an administrator’s point of view is its centrally-managed deployment model. In this section, we put the managed into Managed Client.


1. Open a browser at the WebSphere Application Server administrative console.

Note: Even if you do not want or require a sophisticated setup, you must at least enable the client’s download link on the Workplace welcome page.


2. Navigate to IBM Workplace Software → Users → Manage User Policy.

3. Open the Default User Policy. This is the set of policies for the core set of Workplace applications. A section of the page appears in Figure 3-17.

Figure 3-17 The default user policy page

4. The most essential setting for Managed Client use is in the Allowed clients section. Select the Rich client option. Additionally, note that you cannot disable the browser client.

5. A number of other settings for the core Workplace applications are available on this page. A full discussion is outside the scope of this book, but here are some of the more important policies:

– Allow mail enables or disables mail. Similar options exist for the calendar and address book.

– Allow import/export of files sets whether users can import and export to and from the file system into document libraries.

– Allow Workplace Designer gives access to the Workplace Designer tool.

– Allow Notes Application plug-in grants access to the Managed Client Notes plug-in. Note that at the time of writing, the Notes plug-in for Linux is in a late-beta stage of development.

Tip: The URL to the console is generally of the form http://isv4.cam.itso.ibm.com:9091/admin, where isv4.cam.itso.ibm.com is the fully qualified domain name of your WebSphere server. Log in as the administrator.


6. Click OK to save the user policy.

Finer-grained controlWebSphere supports the creation of additional user policies. For example, you might want to roll out the Managed Client to only a few departments.

To achieve this, create a user policy covering only the users in that department. For example, if rich client access is disabled in the default profile but enabled in the department’s profile, just that department has access to the rich client.

By combining profiles, almost any configuration is possible. However, a full discussion of Workplace user policies is outside of the scope of this book.

Configuring access to Managed Client applicationsAccess to Managed Client applications is controlled chiefly by the policies on each application’s portal page. This section outlines the basic concepts; however, a full description of portal security is outside of the scope of this book. We simply outline how you can apply portal security concepts to Managed Client applications.

Important: We do configure policies for access to individual Managed Client applications in the WebSphere administration console. For that functionality, see the following section.

Tip: Access to any portal application is also governed by the policies on its portal page. The Managed Client shares exactly the same access control mechanisms.



1. Using a browser, log in to Workplace as the WebSphere Portal administrator. Click the Administration link at the top of the page. This opens the Portal administration console, as shown in Figure 3-18.

Figure 3-18 Portal Administration console


2. Click Access (at the top of the page). Then, click Resource Permissions (at the side). This opens a list of portal pages, as shown in Figure 3-19. Click Pages.

Figure 3-19 List of portal pages


3. Managed Client application pages are under the WorkplaceRCPPages node. Navigate there using the table or simply search for WorkplaceRCPPages. When found, click the WorkplaceRCPPages link. A list of all the Managed Client application pages opens, as shown in Figure 3-20.

Figure 3-20 List of Managed Client application pages

Tip: You might have to navigate through several pages to find the WorkplaceRCPPages node.


4. Click the key symbol adjacent to the application in question. In this example, we select Documents. The portlet changes its contents to display a list of portal roles, as shown in Figure 3-21. Each role represents a set of permissions. For example, administrators can delete and modify pages, but users can only read the page. The pencil icon beside each role name enables you to add a group to that role; whoever is in the group is granted the role along with all that role’s privileges.

Figure 3-21 List of portal roles

With this knowledge, it is possible to create advanced policies. Suppose you create a new application intended for use by only one department. After the application is deployed, you can execute the following series of steps to limit its rollout to only that department:

1. Create a group containing all the users in a particular department.

2. Find the page under Resource Permissions.

3. Add that group (and only that group) to the Users role for the page.


Finer-grained controlPortal enables you to set permissions on individual portlets on a page. For example, Workplace Learning grants only administrator access to the My Skills portlet. When normal users access Workplace Learning, the skills portlet is not displayed.

This concept transfers to the Managed Client. The Managed Client enables you to restrict access to just certain views within the Managed Client application. The procedure works exactly as that described in the previous section, this time modifying the roles on portlet resources rather than on page resources.

3.2 Installing Workplace Managed ClientIn this section, we describe the installation of Workplace Managed Client.

3.2.1 Client installation introductionThe Managed Client installs in two stages:

1. First, the core client platform is installed.

2. When run for the first time, the client undergoes a process known as provisioning. During this process, the client contacts the portal server for a list of available applications and then downloads all the required components.

Typically, the Managed Client installer launches the client immediately after installing the core platform. This forces provisioning to take place and makes it appear as though the two stages are one.

Tip: If the settings do not seem to take effect, ensure that the all_authenticated_portal_users role is not assigned to any of the other roles, for example, Editors. Editors, for example, have all the rights that Users do in addition to editing rights. Because WebSphere Portal assigns the highest-ranked role to the user, in that case, any groups associated with the Users role is simply ignored.

Tip: This is not dissimilar to how a browser works. Think of the browser as the core platform and the HTML it fetches from a server as the applications.


This section describes the installation procedure on a typical Linux desktop. Is there such a thing? Here is how we have qualified a typical Linux workstation for the purposes of this book:

� It is essentially a single-user system because only one user logs in on a day-to-day basis.

� The OS is installed on the local disk.

Note the similarities with a typical Windows workstation.

Note also that we are not considering how the workstation is used, but how it is deployed (1.2.2, “Linux desktop classifications” on page 6).

Because this is the most common type of Linux workstation deployment and the one most tested by the Managed Client, this is the installation procedure we describe in this guide.

3.2.2 PrerequisitesThis section provides the prerequisites.

Supported platformThe supported platform for Workplace Managed Client 2.6 is Red Hat Enterprise Linux Workstation 3, Update 4.

Configuring the browser for JavaFor the client download link to initiate the Managed Client installer automatically, Java must be configured properly in the user’s browser. Although it is not required to install the Managed Client through the download link, we strongly advise that you install it this way.

In this section, we outline the steps required to configure Java on both Mozilla and Firefox browsers under Red Hat Enterprise Linux Workstation 3, Update 4.

Tip: Appendix A, “Installing IBM Workplace Managed Client on other Linux distributions” on page 195 describes how you can install the client some unsupported, albeit common, Linux distributions.

Tip: Owing to the large number of possible combinations of both distributions, browsers, and JREs, it is not possible to publish a definitive guide even for the supported platform. However, the instructions in this section should be generic enough for use with any distribution.



1. Obtain either the IBM or Sun™ Java™ runtime environment (JRE). Download the Sun JRE from their Web site. In either case, we recommend a 1.4 or later JRE.

2. Install the JRE into a suitable location on the client workstation. In this guide, we choose /opt/. For example, if we choose IBM JRE Version 1.4.2, the JRE is in /opt/IBMJava2-142/. Make a note of the directory name; in this book, we substitute $JAVA_HOME with that value.

3. The final step is to create in our browser’s plug-ins directory a symbolic link to the browser plug-in shared library provided by the JRE. We must locate some files and directories:

a. Where is the browser’s plug-in directory? On a standard Red Hat Enterprise Workstation 3 Update 4 machine, the Mozilla plug-in directory is /usr/lib/mozilla-1.4.3/. Firefox does not come with this distribution, but if you have downloaded it from http://www.mozilla.com/firefox/ and extracted it to /opt, the plug-ins directory is simply /opt/firefox/plugins. In this book, we substitute $PLUGIN_DIR with this value.

b. Where is the JRE browser plug-in shared library? It is called something similar to libjavaplugin_oji.so. For an IBM JRE, it is probably in the jre/bin directory under the directory into which you installed the JRE. With a Sun JRE, it is probably in jre/plugin/i386/ns610 or jre/plugin/i386/ns610-gcc32. In this book, we substitute $PLUGIN_SO with this value.

c. Now, to create the link, enter:

cd $PLUGIN_DIRln -s $PLUGIN_SO

4. To verify that the plug-in is successfully installed, enter about:plugin into the address bar of your browser (Mozilla or Firefox). Verify that Java is listed.

Important: The IBM JRE supplied with Red Hat Enterprise Linux Workstation 3, Update 4 is Version 1.3.1 and incompatible with Mozilla and Firefox. You must use a later edition of the JRE.

Tip: If there are multiple directories with names of the form /usr/lib/mozilla-X.X.X, try the directory with the highest number.

Tip: For a list of all possible plug-in shared libraries, use this command:

find $JAVA_HOME -iname *oji*.so


http://www.mozilla.com/firefox/

Increasing the allowed number of open filesOne problem that can occasionally occur when running the Managed Client under Linux is that automatic updates fail. This can happen with a major update, involving a large proportion of the client’s components. Although the Managed Client will simply report an error, the cause is most likely that the client has exceeded the maximum permitted number of open files.

In this section, we describe how to increase the default value (which is 1024).


1. Open the /etc/security/limits.conf file in a text editor.

2. Add the following lines:

* soft nofile 4000* hard nofile 4000

3. Save the file.

4. To verify the success of the operation, log in to the system as an ordinary user. Open a terminal and execute the following command to ensure that the default value has been changed:

ulimit -a

This sets the maximum number of open files for ordinary users to 4000. This value should be sufficient for any client upgrade.

Tip: Finding the right plug-in shared library can simply be a case of trial and error, trying each possible library.

Tip: The steps here are appropriate for a Red Hat Enterprise 3 Update 4 Workstation Edition. This process varies among distributions and so it is not possible to cover every system here.


3.2.3 Installing the base platformPerform the following steps:

1. Log in to Workplace. If the server is properly configured, the Welcome page displays a download link. Figure 3-22 shows the relevant portlet. Click the IBM Workplace Managed Client link.

Figure 3-22 Client installer download link

Important: If accessing a Red Hat Enterprise 3 Update 4 Workstation Edition system through SSH, the directives in the limits.conf file are ignored. Change this behavior by adding the following line to the SSH server’s configuration file. Follow these steps:

1. Open the /etc/ssh/sshd_config file in a text editor.

2. Add this line:

UsePrivilegeSeparation no

3. Restart the SSH server with this command:

/etc/init.d/sshd restart


2. The next page displays a short preamble to the installer, as shown in Figure 3-23. Assuming that your browser supports Java, click Start Download to start the installation. You might be asked whether you want to install the applet; in that case, click Yes.

Figure 3-23 Client installer preamble and Download button

Tip: If your browser does not support Java, clicking the Start Download button enables you save the installer executable to disk. It is called setup_wct_platform.bin. Save it to a suitable location, open a file manager, and double-click the file. Alternatively, run the installer from a terminal by entering the full path to the executable.


3. Figure 3-24 shows the first page of the Managed Client installer. Click Next. Read the license terms. If you accept the license terms, click Next again.

Figure 3-24 Managed Client installer Welcome dialog box


4. Provide an installation location, as shown in Figure 3-25. There are two problems with the default installation location:

– It is not writable by normal users. If we attempt to install here as a non-superuser user, the installation will fail.

– The core platform is not designed for use by multiple users. Concurrent updates and multiple client provisioning from this installation location will cause problems for all users concerned.

Accordingly, we suggest that you install the core platform into a directory named WorkplaceManagedClient (no spaces) inside your home directory. For example, if your home directory is in /home/users/trevorj, enter /home/users/trevorj/WorkplaceManagedClient into the box. After entering the correct path, click Next. The next dialog box displays the client’s installation location and the expected space required. Click Next again.

Figure 3-25 Installation location prompt

Tip: How do we find the path to our home directory? The simplest method is to open a terminal. On Red Hat Enterprise Linux Workstation 3, Update 4 systems, select System Tools → Terminal from the menu. Enter pwd into the terminal and press Enter. The terminal displays the path to your home directory.


5. After you enter the location, the installer confirms the installation directory and indicates the size of the client installation, as shown in Figure 3-26.

Figure 3-26 Confirming installation location and size of Managed Client installation files


6. Now the core platform is installed. The progress meter in Figure 3-27 monitors the progress.

Figure 3-27 Core platform installation progress meter


7. When the core platform finishes installing, the installer gives you the option to launch the client and, in doing so, provision the client, as shown in Figure 3-28. If you click Cancel, the installation finishes now. The client will provision whenever you first run it. Most likely, you want to provision now, so click Next and proceed to 3.2.4, “Provisioning the Managed Client” on page 100.

Figure 3-28 Core platform installer prompt to provision now or later

3.2.4 Provisioning the Managed ClientEach end user must provision the client when the user runs it for the first time.


1. After the Managed Client welcome window closes, provide your user name, password, and provisioning URL, as shown in Figure 3-29 on page 101. The client queries the provisioning URL for a list of applications and their required components. After entering the correct details, click Next.


Figure 3-29 Provisioning URL prompt

Tip: Depending on whether you started the installer from the download link or manually, the URL field might already be populated. If not, your Workplace administrator should have furnished you with the correct URL. If not, the URL is probably the same as the one you use to access Workplace through a browser, for example:

http://isv4.cam.itso.ibm.com/lwp/myworkplace

Tip: Observe how the provisioning URL is (usually) the same as that used by the browser. This is further evidence for the notion that the browser and Managed Client simply provide two different views of the same thing.


2. Now the client provisions. The progress meter shown in Figure 3-30 monitors the progress. In this time, the client downloads all of the Eclipse plug-ins and features required to run the Managed Client applications. Depending on the speed of your network connection and your computer’s own speed, this process can take several minutes.

Figure 3-30 Provisioning progress meter


3. When provisioned, the client prompts for a login server and a login port, as shown in Figure 3-31. Do we just give the client a provisioning URL? The answer is that the provisioning server can be different from the login server. Again, the field might be prepopulated depending on how you started the installation. If it is blank, enter the fully qualified host name of your Workplace Collaboration Services server, unless your administrator has indicated otherwise. Click Next.

Figure 3-31 Login server prompt

4. The last dialog box simply tells you to click Finish. Do so to launch the client.

Tip: Do not enter http:// or any trailing directories (for example, /lwp/myworkplace) in the host name field. http:// and trailing directories are only meaningful in a URL.

All the client requires here is a host name.


5. If the installation and provisioning process completed successfully, the login prompt shown in Figure 3-32 opens. Enter your password and click Login to launch the client.

Figure 3-32 Managed Client login prompt

6. Depending on whether your company has a self-signed SSL certificate or not, you might be prompted to accept the SSL certificate, as shown in Figure 3-33 on page 105. If you know your company’s signature, it can be verified here. Of course, it is very unlikely that you know the signature; however, at this point, it is usually safe to accept the certificate. To prevent further prompting, select Trust this certificate and click OK.

Tip: If at some point in the future the client mysteriously prompts you to accept the server’s certificate, it is possible that you are experiencing a so-called man in the middle attack. In that case, it is appropriate to be concerned.

When running the client for the first time, however, the prompt is to be expected if your company uses a self-signed certificate.


Figure 3-33 SSL acceptance prompt

The Managed Client installation is complete.

3.2.5 Post-installation tasksIn this section, we describe an optional procedure that you might want to perform after installing the client.

Immediately before terminating, the Managed Client installer sets the permissions on the core platform’s directory (and all the files and subdirectories inside) as world-writable.

Depending on the workstation deployment strategy employed at your location, this might present a significant security risk.


Perform the following steps to tighten the permissions:

1. Open a terminal. On Red Hat Enterprise Linux Workstation 3, Update 4, select System Tools → Terminal from the menu.

2. Assuming the recommended installation directory of $HOME/WorkplaceManagedClient, enter the following command:

chmod -R o-rwx WorkplaceManagedClient

Now, your Managed Client platform is inaccessible to any other user.

3.2.6 Uninstalling the Managed ClientIn this section, we describe the steps to uninstall the Managed Client.

Using the uninstallerThe Managed Client installer also creates an uninstaller. In a typical scenario, use this to uninstall the client. This section describes the process.


1. The Managed Client uninstaller is in the _uninst directory under the install directory into which you installed the client. The executable is called uninstaller.bin. Run this executable by double-clicking its icon in a file manager or typing its full path in a terminal.

Tip: A common permission setting on home directories is to completely disable access to all other users. This denies access to all users to any files or directories contained inside, including your Managed Client core platform.

To view the settings on your home directory, enter the following command in a terminal:

ls -l ~/..|grep $USER

You will see lines of the following form:

drwx------ 31 ieu93287 users 8192 Dec 19 16:42 ieu93287

The first word is significant; examine the last three characters. If they are all dashes, as in this example, the permission flags on your Managed Client core platform directory are irrelevant.

Note that the executable (x) flag is often set on home directories to give limited access to items in your home directory. In such a scenario, perform the following instructions.


2. The first dialog box welcomes us to the uninstaller, as shown in Figure 3-34. Click Next.

Figure 3-34 Managed Client uninstaller Welcome dialog box

Tip: If you use our recommended installation directory, the uninstaller is in $HOME/WorkplaceManagedClient/_uninst/uninstaller.bin.

Note: Unlike the installer, the uninstaller does not support the -console switch. For a text mode uninstallation, use the -silent switch. Note that when passed this switch, the uninstaller will not prompt you with any questions; it simply silently uninstalls the product.


3. The next dialog box prompts you to remove all local data and configuration settings, as shown in Figure 3-35. This refers to files that might have been created in the provisioning process, such as application components, preference settings, and the local data store. We assume that you want to remove them. Select Yes and then click Next.

Figure 3-35 Client uninstaller prompt to remove configuration data


4. Next, the uninstaller displays a confirmation notice, as shown in Figure 3-36. This notice informs you from which directory the client will be uninstalled and what product will be uninstalled. If the information is correct, click Next to begin the uninstallation.

Figure 3-36 Client uninstaller confirmation notice


5. The process takes several minutes. When complete, the uninstaller displays a successful uninstallation message, as shown in Figure 3-37. Click Next.

Figure 3-37 Client uninstaller successful uninstallation message

6. The last dialog box requests that you log out. Click Finish and log out.

Manually removing the filesYou can manually remove all Managed Client files from our computer. This is of use in two situations:

� You tried the Managed Client uninstaller but it has failed for some unknown reason. You want to wipe all Managed Client files and reinstall.

� You employ a sophisticated Linux desktop strategy (thin clients, for example). Perhaps, you somehow manually duplicated the installation onto users’ desktops, or there is just one central installation shared by all users. In such a scenario, the uninstaller might not function as expected.

Tip: Why does the client ask us to log out? The client installer sets up a preload facility for the Managed Client. See the next section for an explanation of the term preloading.


We review all the files and directories that the Managed Client creates. Use your own judgement in deciding whether to remove the respective files and directories.

� In the installation process, we choose a location for the core platform. In 3.2.3, “Installing the base platform” on page 94, we install the core platform in the $HOME/WorkplaceManagedClient/ directory. Generally, this directory is not modified after installation.

� When the client provisions, it creates a directory under the IBM/RCP directory in your home directory. This folder stores all applications, data stores, and preferences. The name of this folder takes the form of a nine-digit number, unique to each installation of the client.

Important: If you are reading this section for the former reason, consult 6.4, “Troubleshooting provisioning” on page 188 first. This contains a comprehensive guide to non-destructive repair of your provisioning directory.

Tip: Unless the client supported by the server has undergone a major update, the contents of this directory will not be modified after the installation. Consequently, this directory needs to be the last directory to remove in the event of problems.

Tip: If you are having serious problems with the client, the contents of this folder are almost certainly the cause. If deleted, the client will have to be re-provisioned. Note that you will lose your preference settings and local data stores. See 6.4, “Troubleshooting provisioning” on page 188 for information about non-destructive repair of this directory.

Tip: If you find multiple folders under the $HOME/IBM/RCP directory, obtain the exact path by examining the installation’s rcpinstall.properties text file. This file is in the RCP directory, under the directory in which the Managed Client was installed. With our recommended installation directory, the full path to this file is $HOME/WorkplaceManagedClient/rcp/rcpinstall.properties. Open this file and find the value for rcp.installId; this reveals the nine-digit code used by this particular installation of the Managed Client.


� When run for the first time, the installer creates some artifacts for two of the more popular desktop environments, GNOME and KDE:

– Icons for the GNOME desktop are in the $HOME/.gnome-desktop/ directory.

– A script is copied into the KDE Autostart folder. This is typically in $HOME/.kde/Autostart. Its purpose is to preload the Managed Client binaries into memory.

Tip: Preload is a technique used to decrease observed application startup times. Most of the time required to start an application is consumed by loading the binary into memory. Preloading loads the binaries in the background before the user starts the application manually.


Chapter 4. IBM productivity tools

IBM Workplace Managed Client includes a set of open standards-based productivity tools that support a variety of formats including the OASIS OpenDocument Format (ODF) and Microsoft Office document formats. You can use the IBM Workplace Managed Client productivity tools to create, edit, and save documents to ensure cross-platform and cross-application document exchange, without being locked into the proprietary vendor formats. The tools are also closely tied to the client itself to offer a full suite of embedded editors for inline creation and editing of documents stored in a server-based document library.

In this chapter, we discuss the tools that come with the Managed Client (provided the user’s policy permits the use of the productivity tools), the ways in which they can be launched, and some tips about how to integrate the tools fully into your Linux environment. We do not discuss the features available in each of the editors, but highlight some of the differences in handling of other document formats. Use the IBM productivity tools internal help system for a complete description of all the functionality available in the editors.

4


4.1 Launching the IBM productivity toolsThe IBM productivity tools can be run either embedded in the IBM Workplace Managed Client or as applications run directly from the desktop. You can launch them in a number of ways:

� Using the “IBM Productivity Tools” desktop icon

This opens a blank application with a dialog box asking the user what type of application to create. The default launch behavior can be changed by selecting File → Preferences in the application. See Figure 4-1.

Figure 4-1 IBM Productivity Tools Preferences

� Using a file manager application and opening a file that is one of the tools’ associated file types

Using Nautilus or a similar graphical file manager, double-click a word processing document, presentation, spreadsheet, or project file to open the appropriate editor.


Figure 4-2 File Type Associations Preferences menu

The productivity tools store the file associations in MIME-type files in:

– $HOME/.gnome/application-info/seditor.applications– $HOME/.gnome/mime-info/seditor.keys– $HOME/.gnome/mime-info/seditor.mime

If there are any problems opening files of different types that you expect the editors to handle, the user can check to make sure that these three MIME files contain the appropriate entries to associate the editors with that file type.

Tip: The IBM productivity tools make it simple to change the file associations for various office editor tools. Simply go to the File → Preferences menu, select File Type Associations, and select the formats you want to have the IBM productivity tools open by default, as shown in Figure 4-2. Note that the Microsoft Office file types are not selected by default and must be changed in the preferences menu in order to launch the editors automatically.

Chapter 4. IBM productivity tools 115

� Using IBM Workplace Managed Client to open a file contained within a document library

Opening or creating a file in a document library launches an embedded editor. You can do this from a productivity file or from a productivity template. For more information, see 2.5.2, “Working with documents” on page 54.

� Launching the desktop editors from a browser using the WebSphere Portal Document Manager Web interface to a document library

When using the Web interface to a document library, select a document and click the Edit button. A document description page opens in the browser. Click the Open File button to launch the local editor associated with that file type. After making the modifications, save the changes in the editor, close the editor, and in the browser, select to either Publish the changes to the document library or save it as a private draft.

Note: In order to shorten the time it takes to launch the productivity tools, IBM Workplace Managed Client installs a script called preload.sh in $HOME/.kde/Autostart/.

As mentioned in 3.2.6, “Uninstalling the Managed Client” on page 106, this script loads portions of the productivity tools binaries and libraries into memory. It is executed whenever the user logs in, or whenever Workplace Managed Client is launched. It stays in the process table and monitors to see whether or not the SodcPreload task is running. If not, it launches it. So, if SodcPreload is killed in any manner, the preload.sh script automatically restarts it.

If IBM only supports the client and productivity tools under GNOME on Linux, why is it that they put this script in a KDE directory? Unfortunately, we do not know the answer to this question.

Turn off this preloading capability in the productivity tools preferences. See Figure 4-3.


Figure 4-3 Productivity Tools preloading preferences

After launching the selected editor, a feature-rich office application opens that provides extensive functionality for producing complex documents.

As mentioned in the introduction to this chapter, we cannot cover all of the features of the editors. However, there are a few options and configuration settings that users need to know how to access.

After launching an editor (except the Project Planner), select Tools → Document Editor Options. This opens a dialog box that enables the user to customize many aspects of the editor’s behavior, including a large number of globalization features. From this menu, you can specify the global automatic font replacement settings, default language preferences, and behavior of different aspects of the individual editors, such as the default fonts to use for different text

Note: For a more detailed look at the scope of functionality offered by the productivity tools, refer to the IBM Redpaper IBM Workplace Client Technology Productivity Tools for IBM Lotus Workplace Documents 2.0.1, REDP-3947. This paper is based on an earlier version of the productivity tool suite, but provides a comprehensive look at its core capabilities.


settings within the word processor. This allows for very flexible customization of the editor properties and can be tailored to suit almost any locale. Figure 4-4 shows the language settings.

Figure 4-4 Document editor options

4.2 Document formatsThe document formats currently supported by the IBM productivity tools editors include:

� OASIS OpenDocument Format (ODF)

� IBM native format, which is derived from OpenOffice 1.1

� Microsoft Office format documents

In addition to word processing, spreadsheet, and presentation formats, there is also a Project Planner tool to create Gantt charts and handle most project management needs. The project planner is compatible with Microsoft Project (2000 and 2003 versions) and can import and export data in Microsoft Project XML files.

Note: The Project Planner is not fully feature compatible with Microsoft Project. In this version, it contains approximately 30% of the functionality of the full Microsoft Project product. However, the functionality currently offered is sufficient to handle many different project types and tasks.


When creating new documents in the editors, the document is saved in the appropriate ODF format by default. The editors enable a user to create files in the other formats as well. In the editors launched through the desktop program icon, this is done by saving the document with the extension associated with the format in which the user wants to save it. For example, if a user is creating a presentation and wants to save it in Microsoft PowerPoint® format, the user simply saves it with a name of <filename>.ppt. This exports the document into a PowerPoint-compatible format. Creating content through the client’s document library interface enables a user to select the document format through the UI. For example, after opening the new document, select the New Document options toggle, and choose the desired format in the File type field, as shown in Figure 4-5.

Figure 4-5 Creating a document in a different format

4.2.1 OASIS OpenDocument FormatThe OASIS OpenDocument Format (ODF) is a standardized, XML-based document format specification that is tailored to office application needs. It is the default format used by the IBM productivity tools and is also supported by other


open office application utilities such as OpenOffice, Sun Microsystems™ StarOffice™, and KDE KOffice.

ODF is the default format of the IBM productivity tools, and any new document created by the editors is generated in the appropriate ODF format. There are some advanced features described in the ODF specification that the productivity tools currently do not implement. Items such as custom shape support, presentation headers and footers, Synchronized Multimedia Integration Language (SMIL), and XForms support are planned for future releases.

The ODF format uses the following file extensions:

� .odt, .ott (OpenDocument Text, OpenDocument Template Text)

� .ods, .ots (OpenDocument Spreadsheet, OpenDocument Template Spreadsheet)

� .odp, .otp (OpenDocument Presentation, OpenDocument Template Presentation)

4.2.2 IBM productivity tools native formatThe IBM productivity tools are derived from the OpenOffice 1.1 document suite and was the original formatting used by the IBM productivity tools. The default document format is now ODF, but the original format is still available, and documents can be opened, created, and saved in the native IBM productivity tools format. This format does not support the full set of features offered by the most recent ODF standard.

IBM productivity tools native documents use the following file extensions:

� .sxw, .stw (word processing/text document, word processing/text template)

� .sxc, .stc (spreadsheet document, spreadsheet template)

� .sxi, .sti (presentation document, presentation template)

4.2.3 Microsoft Office formatsThe IBM productivity tools can also handle documents in Microsoft Office file formats. They can open most documents created with Microsoft Office 97, 2000, and XP, although there are some features that are unsupported or handled differently through the IBM editors. Therefore, some manual reformatting might

Note: For more information about OASIS standards and ODF, visit the following Web site:

http://www.oasis-open.org/



be required if a user is trying to convert Microsoft format documents to ODF or IBM productivity tools native format. Some Microsoft-specific technologies such as handling OLE objects and the ability to run Visual Basic® scripts are unavailable, although Visual Basic scripts can be opened for viewing, and the editors will try to display OLE objects correctly.

Some functionality common to multiple Microsoft Office editors that we do not support are:

� AutoShape

� Microsoft WordArt graphics

� Microsoft Office form fields and certain controls

� Document encryption

Some other functions that the IBM editors might have difficulty include:

� Microsoft Word:

– Revision marks (change tracking)– Indexes– Tables, frames, and multicolumn formatting

� Microsoft Excel®:

– Pivot tables– New chart types– Some functions and formulas– Cell formatting conditions– Maximum row limit of 32000

� Microsoft PowerPoint:

– Tab, line, and paragraph spacing– Master background graphics– Grouped objects– Multimedia effects– Animated characters and text

The file extensions associated with these documents are:

� .doc, .dot (Microsoft Word document, Microsoft Word template)

� .xls, .xlt (Microsoft Excel document, Microsoft Excel template)

� .ppt, .pot (Microsoft PowerPoint document, Microsoft PowerPoint template)


4.3 Template supportAs mentioned in 2.5.2, “Working with documents” on page 54, beginning with IBM Workplace Managed Client 2.6, the productivity tools now support using document templates to create new office documents. You can do this through templates stored in document libraries or locally on the user’s desktop machine. While using a document library, double-click a template file to open a new document of the type the template represents, that is, a new presentation, new word processing document, new spreadsheet, and so on, in the embedded version of the document editors.

In the non-embedded editors, select File → New → From Template and the appropriate document type. This launches a file browser dialog box to enable you to select the locally stored template to use.

The IBM productivity tools support templates from the three document formats, ODF, IBM productivity tools native format, and Microsoft Office. Of course, when opening a new document using one of the templates, it is in the same format as the template that created it. This does not mean that it is tied to this format. When choosing to save the template-based document, you can select another file format to save it under, and it will be exported into the desired format.

In addition to the ability to create new documents from templates, the editors enable you to modify the templates themselves. There are limitations, however. The editors cannot modify Microsoft Office templates and save them back into their original format. Modifications can only be saved in ODF or IBM productivity tools native template format. When saving the modified template, it prompts for a new file to save it to and gives it a default ODF file extension. You keep the default ODF format or change the extension to one of the IBM productivity tools templates (.st*) and save the changes.

There are other limitations to the IBM productivity tools template support. There are certain things that the tools cannot do. For example, when opening a new document using a Microsoft Office template, the editors do not recognize and use any macros that exist in the template. Also, in Version 2.6, IBM does not bundle any default templates with the productivity tools.

4.4 Adding fonts to IBM WorkplaceIn this section, we describe how to add fonts to the Linux operating system, which can then be used by the IBM productivity tools. This is of interest if:

� Your company has a body of existing documents that use a particular format.

� Style guidelines require you to use certain fonts.


� You want to improve seamless migration from Windows platforms. Missing favorite fonts can be very disconcerting.

The process of adding fonts to a Linux system differs somewhat from other platforms. We attempt to demystify the process.

We describe how to install TrueType fonts in a typical Red Hat Enterprise Linux Workstation 3, Update 4 workstation. These fonts appear the same in print as they do on screen. They are very common in the Windows and Macintosh worlds. Linux supports these fonts with no special configuration.


1. TrueType fonts are typically in /usr/X11R6/lib/X11/fonts/TTF. Log in as root (the superuser) and copy the TrueType font files into this location. Use a graphical file manager or the command line.

2. Restart the font server. Enter this command (again as the superuser):

/etc/init.d/xfs restart

After installing the new fonts, the IBM productivity tools can access them when the application restarts.

Important: We cannot describe the font installation process for every possible Linux platform. The approach described here can be adapted easily to any X configuration that uses a font server.

Tip: Red Hat uses a font server. This is an external daemon dedicated to serving fonts to one or more X servers. Its configuration file is in /etc/X11/fs/config. Here, you will find the definitive list of directories that the font server searches for fonts.

Important: Even if we restart the font server while it has X servers connected to it, it will not impact any users’ logins for more than a brief moment.


Chapter 5. Building a sample application for the IBM Workplace Managed Client platform

The IBM Workplace Managed Client platform enables developers to extend its capabilities by developing new applications. In this chapter, we describe the basic features offered by the platform for application development and also illustrate the usage of some of the public APIs through a sample application.

5

Note: To download the sample code used in building this sample application, refer to Appendix C, “Additional material” on page 211 and the following FTP site:

ftp://www.redbooks.ibm.com/redbooks/SG247208



Important: IBM DOES NOT WARRANT OR REPRESENT THAT THE CODE PROVIDED IS COMPLETE OR UP-TO-DATE. IBM DOES NOT WARRANT, REPRESENT OR IMPLY RELIABILITY, SERVICEABILITY OR FUNCTION OF THE CODE. IBM IS UNDER NO OBLIGATION TO UPDATE CONTENT NOR PROVIDE FURTHER SUPPORT.

ALL CODE IS PROVIDED “AS IS,” WITH NO WARRANTIES OR GUARANTEES WHATSOEVER. IBM EXPRESSLY DISCLAIMS TO THE FULLEST EXTENT PERMITTED BY LAW ALL EXPRESS, IMPLIED, STATUTORY AND OTHER WARRANTIES, GUARANTEES, OR REPRESENTATIONS, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF PROPRIETARY AND INTELLECTUAL PROPERTY RIGHTS. YOU UNDERSTAND AND AGREE THAT YOU USE THESE MATERIALS, INFORMATION, PRODUCTS, SOFTWARE, PROGRAMS, AND SERVICES, AT YOUR OWN DISCRETION AND RISK AND THAT YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGES THAT MAY RESULT, INCLUDING LOSS OF DATA OR DAMAGE TO YOUR COMPUTER SYSTEM.

IN NO EVENT WILL IBM BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES OF ANY TYPE WHATSOEVER RELATED TO OR ARISING FROM USE OF THE CODE FOUND HEREIN, WITHOUT LIMITATION, ANY LOST PROFITS, BUSINESS INTERRUPTION, LOST SAVINGS, LOSS OF PROGRAMS OR OTHER DATA, EVEN IF IBM IS EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THIS EXCLUSION AND WAIVER OF LIABILITY APPLIES TO ALL CAUSES OF ACTION, WHETHER BASED ON CONTRACT, WARRANTY, TORT OR ANY OTHER LEGAL THEORIES.


5.1 Workplace Managed Client platformThe IBM Workplace Managed Client platform consists of a set of core plug-ins that provide a basic set of features. It is based on the Eclipse platform and serves as a base framework to build extensible, sophisticated, rich client applications. The IBM Workplace Managed Client application leverages the framework offered by the platform to provide a rich set of features for collaboration.

Developers can use the IBM Workplace Managed Client Tool to extend the features offered by Workplace Managed Client by developing their own applications. These applications are themselves plug-ins developed for the Workplace Managed Client platform and can be deployed and provisioned through a Workplace Collaboration Services server.

Using the Workplace Managed Client, you can build applications that:

� Provide a rich user experience that is much more responsive than traditional browser-based applications.

� Enable offline application access.

� Provide local data access.

� Provide authentication with single sign-on (SSO).

� Support server-based application provisioning and policy management.

� Provide an extensibility framework for both Microsoft Windows and Linux, which enables you to upgrade or scale back applications as business needs change.

In addition, applications can also use the features offered by IBM Workplace Collaboration Services such as:

� Messaging

� Document libraries

� Instant messaging

� Presence awareness (live names)

An application that extends the Workplace Managed Client platform can itself serve as an extension point for another application. Therefore, it becomes easier to develop a set of loosely coupled, extensible applications that interact with each other to solve business problems.

Chapter 5. Building a sample application for the IBM Workplace Managed Client platform 127

5.2 The sample applicationIn this chapter, we develop a simple application to demonstrate some of the capabilities of Workplace Managed Client. The application is an issue tracking system where a user can log issues and tasks that need to be resolved. We call the application Task Manager. Figure 5-1 on page 129 shows the main window of the application.

Note: For more comprehensive information about planning, developing, deploying, and packaging applications for the Workplace Managed Client, refer to IBM Workplace Managed Client API Toolkit Version 2.6 User’s Guide, available at:




Figure 5-1 Overview of the sample application built in this chapter

Key features of the sample applicationThe primary features of the Task Manager application are:

� The application has two panes: A task list pane that displays all the tasks and a task detail pane that displays information about a particular task selected from the task list window.

� A user can create new tasks, modify an existing task, and delete tasks.

Overview list of tasks to accomplish

Details of taskStatus and priority Ability to chat

with task owner when online


� The tasks can be persisted in a database.

� Each task can be assigned to a user.

� Each task shows the presence awareness of the user to whom it is assigned.

� If the user to whom a task is assigned is online, you can chat with that user using instant messaging by double-clicking the user’s icon in the task detail window.

This chapter demonstrates some important processes that are typical in the development of a rich client application, such as:

� Designing the visual layout of an application in the Workplace Managed Client platform. We see how the IBM Workplace Managed Client Tool can simplify this process.

� Creating multiple views that exchange data between them.

� Storing data in the local, encrypted Cloudscape database.

� Showing the online/offline status of a user, presence awareness.

� Integrating instant messaging with end-user applications.

5.3 Configuring the development environmentThis tutorial uses the Managed Client Tool to ease the development process. Managed Client applications take the form of Eclipse plug-ins and, because of this, share much the same development process. The tool performs such Managed Client-specific tasks as laying out Eclipse views and deploying the application.

5.3.1 Installing an IDEThe tool supports both the Eclipse (Version 3.0 and later) and IBM Rational® Application Developer (Version 6.0 and later) integrated development environments (IDEs).

Note: Workplace Managed Client 2.6 does not support instant messaging integration with end-user applications. However, we demonstrate this feature in our application because it can be very useful to promote ad hoc collaboration in many applications. The APIs that we use to achieve this feature might change in future versions.


5.3.2 Installing the Managed ClientThe Managed Client itself must be installed on your computer. There is no special installation process for development.

5.3.3 Installing the IBM Workplace Managed Client ToolThe first task is to download the IBM Workplace software development kit (Workplace SDK). The IBM Workplace Managed Client Tool is contained inside, in the form of an Eclipse update site. The SDK contains instructions about how to install the tool. Nevertheless, here is an overview of the process:

1. Extract the IBM Workplace SDK to a suitable location on your machine.

2. Extract the IBM Workplace Managed Client tool to a suitable location on your machine.

3. From inside your IDE, select Help → Software Updates → Find and Install from the menu.

4. Select Search for new features to install and then click Next.

5. Click New Local Site and navigate to the tool's update site. This is in wcsapi26/wmc/tools/WMCTool in the directory in which you extracted the SDK.

6. Ensure that the tool’s local site is selected in the list of sites to include in the search and click Next.

7. Select IBM Workplace Managed Client Tool and follow the remaining on-screen instructions to complete the installation.

5.3.4 Creating a new toolkit projectIn this section, we commence work on our sample application.

Tip: The tool requires the Eclipse Modeling Framework (EMF), Eclipse Graphical Editing Framework (GEF), and Visual Editor tools. These come preloaded with Rational Application Developer, but must be installed manually on Eclipse.

Tip: We point the Eclipse plug-in development tools at the Managed Client installation to allow for the development of additional plug-ins.



1. Select File → New → Other from the IDE menu. This opens the new project wizard, as shown in Figure 5-2. Select IBM Workplace → Workplace Managed Client Application Project. Click Next.

Figure 5-2 New project wizard

Tip: We create a new project before testing the development environment. We do this because we need a test project.


2. Now we see the new IBM Workplace Application wizard, as shown in Figure 5-3. Enter TaskManager for the Project name. Click Next.

Figure 5-3 IBM Workplace Application wizard


3. Select a layout for the application, as shown in Figure 5-4. Our application has two views, one sitting on top of another. This corresponds to the first image in the Please select layout section. Additionally, select Automatically create default views. This creates place holder projects for both views into which we can insert our code. Click Finish.

Figure 5-4 Page Layout

4. After a short wait, we see that the wizard has created four new projects:

– com.ibm.redbooks.taskmanager

– com.ibm.redbooks.taskmanager.MainPage

– com.ibm.redbooks.taskmanager.pane1

– com.ibm.redbooks.taskmanager.pane2


5. The last two project names do not look very good. Let us change their names to something meaningful.

Click the com.ibm.redbooks.taskmanager.pane1 project and press F2. Change the name of the view to com.ibm.redbooks.taskmanager. Similarly, change the name of com.ibm.redbooks.taskmanager.pane2 to com.ibm.redbooks.taskmanager.DetailView, as shown in Figure 5-4 on page 134.

Figure 5-5 Renaming the project

5.3.5 Testing the development environmentThe tool also eases the test phase of development. It can create Eclipse runtime configurations that boot the client, complete with any applications from the current workspace.


1. First, set the plug-in development environment (PDE) target platform. This is the Eclipse platform against which plug-ins are developed.

a. Select Window → Preferences → Plug-in Development → Target Platform, as shown in Figure 5-6 on page 136.


b. Browse to the Eclipse subdirectory of the directory into which you installed the client (for example, /opt/IBM/Workplace Managed Client/eclipse). After a brief pause, Eclipse should find all the plug-ins contained inside.

Click OK.

Figure 5-6 Setting the PDE target platform


2. Instruct Eclipse to use the JVM™ supplied with the client:

a. Select Window → Preferences → Java → Installed JREs, as shown in Figure 5-7.

b. Click Add. Locate the JVM directory. For a 2.6 client installed under /opt/IBM/Workplace Managed Client, the exact path is /opt/IBM/Workplace Managed Client/rcp/eclipse/features/com.ibm.rcp.jre.linux.feature_1.3.0/jre. Give the JVM a name and click OK.

c. We return to the Preferences window. Click OK to return to the list of JVMs. Select the new JVM that you configured. This makes it the default JVM.

Figure 5-7 Configuring the default JVM

5.3.6 Creating a runtime configurationPerform the following steps:

1. From the Package Explorer view, select the TaskManager project. From the menu, select Run → Run.


2. Select IBM Workplace Managed Client from the list of configurations (on the left side of the window) and then click New. When correctly configured, this creates a runtime configuration similar to that shown in Figure 5-8.

Figure 5-8 Runtime configuration for the sample application


3. Click Run. If the setup process was successful, a Hello World application opens, as shown in Figure 5-9.

Figure 5-9 The Hello World application

5.4 Creating the List ViewAs noted earlier, our application has two views: a List View that shows all the tasks in a table and a Detail View that shows the details of a particular task that is selected in the table. This section describes the implementation of the List View.

Creating domain objectsBefore we start implementing the view, let us think about the problem domain. Our basic domain object is a task. A task contains a title, a description, a due date, a priority, a status, and a contact person. The Task Manager holds a list of tasks at any time. Let us create a new class called Task. Remember, the new Task class will be used by both our views (List and Detail). Therefore, creating the Task class in any of the view projects is not a good idea. So, we create a new plug-in project and create the Task class in that project.



1. From Eclipse menu, select File → New → Project → Plug-in Development → Plug-in Project.

Figure 5-10 Create a new plug-in project


2. Use com.ibm.redbooks.taskmanager.task as the Plug-in ID, as shown in Figure 5-11. Our plug-in will not make any contributions to the UI. Therefore, clear the This plug-in will make contributions to the UI check box. Click Finish.

Figure 5-11 Change plug-in parameters


3. Now, let us create the Task class. Right-click the src folder in com.ibm.redbooks.taskmanager.task plug-in and select New → Class. You can create the class in the com.ibm.redbooks.taskmanager.task package. See Figure 5-12.

Figure 5-12 Creating the Task class


4. Now, we add the different member variables for the Task class. We also create constructors and getters and setters. See Example 5-1.

Example 5-1 The Task class

public class Task {private String title;private Date dueDate;private int priority;private int status;private String description;private String contact;

public Task() {}

public Task(String title, String description, Date dueDate, int priority, int status, String contact) {setTitle(title);setDescription(description);setPriority(priority);setDueDate(dueDate);setStatus(status);setContact(contact);

}// Getters and setters for all the fields not shown for brevity.

}

5. We now add a table to the List View using the SWT Tableviewer widget to display the list of tasks. The Tableviewer uses the model view controller (MVC) design pattern to display items. Example 5-2 shows the source code snippet for creating the task table. The createItems method picks up the list of tasks from the database and is explained in 5.8, “Saving tasks to the database” on page 151.

Example 5-2 Creating the List View

/** * A sample composite to get you started on WCT View Development */public class MyComposite extends Composite implements {

private Table todos;private CheckboxTableViewer tviewer;private ViewPart view;private Table table;

//...private void createColumns() {

TableColumn column = new TableColumn(table, SWT.LEFT);


column.setText("");column.setWidth(20);

TableColumn status = new TableColumn(table, SWT.LEFT);status.setText("Status");status.setWidth(100);

//More columns are created in a similar fashion...}private void initialize() {

table = new Table(this, SWT.SINGLE | SWT.FULL_SELECTION | SWT.CHECK);

createColumns();

// Show the column headerstable.setHeaderVisible(true);table.setLinesVisible(true);table.setVisible(true);table.setBounds(new Rectangle(0, 0, 900, 300));

tviewer = new CheckboxTableViewer(table);tviewer.setContentProvider(new TaskContentProvider());tviewer.setLabelProvider(new TaskLabelProvider());tviewer.setSorter(new ViewerSorter());tviewer.setInput(createItems());

setSize(new org.eclipse.swt.graphics.Point(580, 300));}

5.5 Creating the Detail ViewThe Detail View enables users to view more information about a particular task that is selected in the List View. Users can also edit various fields related to a task and the same changes will be reflected in List View. Let us create a form to layout all the widgets for the different fields. To facilitate the creation of forms, we created a utility class in the com.ibm.redbooks.taskmanager.detail.views package, named GridUtils. The GridUtils class will help us to quickly create labels, buttons, and text boxes without setting the parameters for each of them separately. We do not go into the details of this class. For more information about using layouts, event handling, and various widgets in SWT and JFace, refer to

Tip: For a quick introduction to using Eclipse GUI components (SWT and JFace), see the IBM developerWorks® article, Using the Eclipse GUI outside the Eclipse Workbench, Part 1: Using JFace and SWT in stand-alone mode, at:

http://www.ibm.com/developerworks/library/os-ecgui1/



SWT/JFace in Action: GUI Design with Eclipse 3.0 by M. Scarpino et al. Example 5-3 shows the code for creating the form. You will notice that there is a LiveButton class. We talk more about this class in 5.9, “Live names and instant messaging integration” on page 154.

Example 5-3 Creating the Detail View

public void createControls(Composite parent){Group group = new Group(parent, SWT.PUSH);GridLayout l = new GridLayout();l.numColumns = 2;group.setLayout(l);GridData gridDataDetail = new GridData(GridData.HORIZONTAL_ALIGN_FILL);gridDataDetail.horizontalSpan = 1;gridDataDetail.horizontalAlignment = GridData.FILL;gridDataDetail.grabExcessHorizontalSpace = true;group.setLayoutData(gridDataDetail);GridUtils.makeLabel(group, "Title:", "");mTitle = new Text(group, SWT.SINGLE | SWT.BORDER);GridUtils.setLayoutData(mTitle, "fill=h");GridUtils.makeLabel(group, "Description:", "");mDescription = new Text(group, SWT.BORDER | SWT.MULTI | SWT.WRAP

| SWT.V_SCROLL);GridUtils.setLayoutData(mDescription, "fill=h size=1x80");

GridUtils.makeLabel(group, "Due Date:", "");mDueDate = new Text(group, SWT.SINGLE | SWT.BORDER);GridUtils.setLayoutData(mDueDate, "fill=h");// live names.GridUtils.makeLabel(group, "Contact Name:", "");mLiveName = new LiveNameButton(group, SWT.NONE);// restrict the live name's height to that of a normal text field.GridData gd = new GridData(GridData.GRAB_HORIZONTAL

| GridData.FILL_HORIZONTAL);gd.heightHint = mDueDate.computeSize(SWT.DEFAULT, SWT.DEFAULT).y + 4;mLiveName.setLayoutData(gd);

GridUtils.makeLabel(group, "Priority:", "");mPriority = new Combo(group, SWT.READ_ONLY | SWT.DROP_DOWN);GridUtils.setLayoutData(mPriority, "size=150");mPriority.add("Medium");mPriority.add("High");mPriority.add("Low");

GridUtils.makeLabel(group, "Status:", "");mStatus = new Combo(group, SWT.READ_ONLY | SWT.DROP_DOWN);GridUtils.setLayoutData(mStatus, "size=150");mStatus.add("Not Started");mStatus.add("Started");mStatus.add("Completed");

}


5.6 Linking viewsQuite often, we want our views to communicate with each other. In our example, when we select a task in the List View, our Detail View refreshes its contents to reflect the selection. Also, when we make changes to a task and save the changes, in the Detail View, the corresponding changes are reflected in the List View. This means that views communicate changes to other views. In this section, we look into how different views in our application communicate with each other.

5.6.1 Communicating selection changes in the List ViewOur List View has a table you can select. This view can easily publish UI selections by registering itself as a selection provider with their workbench site, as follows:

view.getSite().setSelectionProvider(tviewer);

The Detail View implements the ISelectionListener interface and registers itself as a listener:

getSite().getPage().addSelectionListener((ISelectionListener) this);

The Detail View then updates its contents based on the selection in the List View:

public void selectionChanged(IWorkbenchPart arg0, ISelection arg1) {StructuredSelection sel = (StructuredSelection)arg1;if((sel.getFirstElement() != null) && (sel.getFirstElement() instanceof

Task)){Task selectedTask = (Task)sel.getFirstElement();detailComposite.updateView(selectedTask);

}}

5.6.2 Saving tasks from the Detail ViewNext, we want changes saved to a task in the Detail View to be reflected in the List View. We use the property change listener paradigm to notify the List View about changes in the Detail View. Unlike selection providers, we implement the semantic of property change providers.


Example 5-4 shows the code in the Detail View to keep track of listeners.

Example 5-4 Code to keep track of listeners

private static List mListeners = new ArrayList();

public static void addPropertyChangeListener(IPropertyChangeListener listener) {

if(!mListeners.contains(listener))mListeners.add(listener);

}

public static void removePropertyChangeListener(IPropertyChangeListener listener) {

mListeners.remove(listener);}

Whenever the user clicks the Save button, the code shown Example 5-5 is invoked to notify all listeners about changes in the current Task.

Example 5-5 Notify all listeners

public void notifyListeners(Task newValue){for (Iterator iter = mListeners.iterator(); iter.hasNext();) {

IPropertyChangeListener element = (IPropertyChangeListener) iter.next();

element.propertyChange(new PropertyChangeEvent(this, "TaskInfo" , null , newValue));

}}

The List View registers for notifications in the Detail View and then implements the IPropertyChangeListener interface and registers for property change events in the Detail View:

DetailView.addPropertyChangeListener(this);

Whenever the user saves a task by clicking the Save button the Detail View, the propertyChange() method in List View plug-in is invoked to save the task to the database (or insert the task to the database if it is a new task), as shown in Example 5-6.

Example 5-6 propertyChange() method

public void propertyChange(PropertyChangeEvent event) {

if (event.getProperty().equals("TaskInfo")) {Task val = (Task) event.getNewValue();


StructuredSelection selectedItem = (StructuredSelection) tviewer.getSelection();

if (selectedItem != null) {Task sel = (Task) (selectedItem.getFirstElement());if (sel != null) {

sel.setTitle(val.getTitle());sel.setDescription(val.getDescription());sel.setDueDate(val.getDueDate());sel.setPriority(val.getPriority());sel.setStatus(val.getStatus());sel.setContact(val.getContact());tviewer.refresh();

}isNew = false;try {

TaskDatabaseUtil.deleteAllTasks();Iterator it = ((List) tviewer.getInput()).iterator();while (it.hasNext()) {

Task t = (Task) it.next();TaskDatabaseUtil.persist(t);

}} catch (SQLException e) {

e.printStackTrace();}

}}

}

5.7 Adding commands to menus and action barsOur application needs to provide the ability to create new tasks, to save an existing task after modifying it, and to delete tasks that no longer need to be tracked. We add these commands to the menu bar and action bar. An action bar is a special toolbar that conforms to Workplace Client Technology styling. Eclipse actions can be contributed to it just like any other toolbar manager.

5.7.1 Adding to the Workplace Managed Client menusFirst, we add a menu item to save all tasks. To do this, we need to extend the org.eclipse.ui.actionSets extension point, as shown in Example 5-7 on page 149.

The example shows several things. First, we add a new menu item called Tasks. This menu item has a Save command. We specify a label and icon to be displayed on the menu bar and specify a class com.ibm.redbooks.taskmanager.detail.actionSet.ActionTaskSave that specifies


the action to be executed when the menu item is clicked. The class implements IActionDelegate. When the user clicks the menu, the UI instantiates the given action class, casts it to IActionDelegate, and calls its run method. This ensures that the action class is instantiated only when the user clicks the command.

Example 5-7 Partial plugin.xml that shows addition of commands to menus

<extension point="org.eclipse.ui.actionSets"> <actionSet label="Tasks" visible="false" id="com.ibm.redbooks.taskmanager.detail.actionSet" > <menu label="Tasks" path="additions" id="com.ibm.redbooks.taskmanager.detail.actionSet.menu"> <groupMarker name="additions"/> </menu> <action label="Save"

menubarPath="com.ibm.redbooks.taskmanager.detail.actionSet.menu/additions" toolbarPath="Normal" icon="icons/save.gif"

class="com.ibm.redbooks.taskmanager.detail.actionSet.ActionTaskSave" id="com.ibm.redbooks.taskmanager.list.actionSet.ActionTaskSave"/> </actionSet></extension>

The ActionTaskSave class can directly implement the IActionDelegate, but we have another problem if we want to add the same command to an action bar. The Workplace Managed Client action bar requires that the action class responsible for handling actions needs to implement the IAction interface. We want to use the same action for handling the action bar action, too. Therefore, we first create a subclass of Action called GenericAction, which also implements IWorkbenchDelegate. We use this class as a super class of all our action classes, including the ActionTaskSave class. Example 5-8 shows the GenericAction class, and Example 5-9 on page 150 shows ActionTaskSave class.

Example 5-8 Partial implementation of the GenericAction class

package com.ibm.redbooks.taskmanager.detail.actionSet;

public class GenericAction extends Action implements IWorkbenchWindowActionDelegate{

public void run(IAction action)


{ mAction = action; run(); }//... Rest of the methods omitted...

}

Example 5-9 Partial Implementation of the ActionTaskSave class

class ActionTaskSave extends GenericAction {public ActionTaskSave() {

super();setText("Save");setToolTipText("Save");setImageDescriptor(DetailPlugin

.getImageDescriptor("/icons/new.gif"));}

public void run() {//...view.notifyListeners(getTaskDetails());

}}

We can add New and Delete menu items in a similar fashion.

5.7.2 Adding to the Workplace Managed Client action barsWe now add an action bar to the List View. It will contain two actions: New and Delete. Perform the following steps:

1. Add a dependency to com.ibm.rcp.ui plug-in and com.ibm.rcp.ui.widgets plug-in. Example 5-10 shows the plugin.xml file.

Example 5-10 Partial plugin.xml showing the dependencies for action bars

<plugin id="com.ibm.redbooks.taskmanager.list" name="List Plugin" version="1.0.0" provider-name="" class="com.ibm.redbooks.taskmanager.list.ListPlugin">...<requires>...

<import plugin="com.ibm.rcp.ui"/><import plugin="com.ibm.rcp.ui.widgets"/>

</requires>...


</plugin>

2. Modify the MyComposite class to add an action bar, as shown in Example 5-11.

Example 5-11 MyCompostite class

class MyComposite {private void initialize() {

setLayout(new GridLayout(1,false));mActionBar = WidgetFactory.createActionBar(this, SWT.RIGHT | SWT.FLAT);table = new Table(this, SWT.SINGLE | SWT.FULL_SELECTION | SWT.CHECK

|SWT.BORDER);createColumns();

//...makeActions();contributeToRealActionBars();

}

private void contributeToRealActionBars(){mActionBar.add(mActNew);mActionBar.add(mActDel);

}

private void makeActions() {mActNew = new ActionTaskNew();mActDel = new ActionTaskDel();

}}

Similarly, we can create another action bar in the Detail View and add the Save command.

5.8 Saving tasks to the databaseIBM Workplace Managed Client supports creating, accessing, and migrating database data to and from the client. Workplace Managed Client supports the use of any JDBC™-compliant database. Workplace Managed Client comes with an embedded IBM Cloudscape database, currently at Version 10. Although it is not obligatory for Workplace Managed Client applications to use the IBM Cloudscape database, it is well worth considering because it provides a number of advantages, including:

� Pure Java relational database

� No administration on the client system required


� Very compact size of approximately 2 MB

� Embeddable database

� Full support for SQL-92

� Tools, such as ij, provided to simplify data manipulation

The IBM Workplace Client Technology platform adds additional functionality to the standard Cloudscape database, such as encrypted access to the database using keys stored in the local credential store.

Creating a databaseDatabase creation is an operation that is usually performed once. It is standard to place it in some initialization code, either during the installation or in a plug-in start() method. To create a local database, perform the following steps:

1. Import the plug-ins com.ibm.workplace.database.db2j.jdbc, com.ibm.rcp.database, and com.ibm.rcp.database.db2j as required plug-ins in the Eclipse plugin.xml file. Example 5-12 shows the partial Eclipse plugin.xml file with plug-in dependencies for database access and initialization.

Example 5-12 The partial Eclipse plugin.xml file

<requires> <import plugin="com.ibm.workplace.database.db2j.jdbc" /> <import plugin="com.ibm.rcp.database"/><import plugin="com.ibm.rcp.database.db2j"/>

... </requires>

Useful links:

� Cloudscape product page:

http://www.ibm.com/software/data/cloudscape

� For more information about IBM Cloudscape:

http://www.ibm.com/developerworks/db2/zones/cloudscape/

� The IBM Cloudscape Information Center provides in-depth details about Apache Derby (open source Cloudscape) and Cloudscape:

http://publib.boulder.ibm.com/infocenter/cscv/v10r1/index.jsp





2. Create a class called DatabaseUtil with a method to load the Workplace Managed Client database driver com.ibm.workplace.db2j.jdbc.WCTDB2jDriver required during the database initialization. Example 5-13 does this, using the loadDbDriver method.

Example 5-13 The partial implementation of DatabaseUtil.java

import java.sql.Connection;import java.sql.DriverManager;import java.sql.SQLException;

public class DatabaseUtil {

private static final String CSDRIVER = "com.ibm.workplace.db2j.jdbc.WCTDB2jDriver";

//The loadDbDriver method loads the WMC specific JDBC database driver//using the String specified in CSDRIVERpublic static void loadDbDriver() throws Exception {

java.sql.Driver driver = (java.sql.Driver) Class.forName(CSDRIVER).newInstance();

}

public static Connection getConnection(String dbname,boolean isCreateDB)throws Exception {loadDBDriver();// database connection code goes here//.....

}public static void shutdownDbDriver()

throws Exception {// database shutdown code goes here

}}

3. In the same DatabaseUtil class, create a method to retrieve the database connection. In the connection URI, set the value for the connection property create to true to create the new database. If the local data store must be encrypted, set the value for the connection property encryption to true. Otherwise, set it to false.

Format the connection URI as follows, delimiting the properties with semicolons:

jdbc:wct:<database_name>;<connection_property1>; <connection_property2>

Where the connection_property can be one or more of the properties described in Table 5-1 on page 154.


Table 5-1 Connection properties

5.9 Live names and instant messaging integrationIn this section, we discuss live names and instant messaging integration.

Live name supportUntil now, we have, for the most part, used only those parts of the platform that belong to Eclipse. In this section, we use the Workplace APIs themselves by incorporating collaborative functionality into Task Manager.

It is desirable to associate a contact name with each task. If we do this, then why not make the contact name label active? It will indicate whether the user is currently online and, if so, allow us to initiate a chat session with that user.

Workplace Managed Client 2.6 gives us these capabilities and more. Let us briefly describe the specification for a live name-aware SWT control:

� The (custom) control as a whole consists of three (standard) SWT controls. These are laid out horizontally inside the custom control.

� The first, left-most, control is the contact’s e-mail address. This is displayed next to an icon indicating the contact’s instant messaging status. In addition, the contact’s e-mail address changes color to indicate that the user is online.

� To the awareness label’s immediate right is a button labelled Chat. Clicking this initiates an instant messaging session.

� To the immediate right of that button is another button, this one labelled Change. Clicking this button opens a dialog box that lets us change the e-mail address currently displayed.

Connection property Description

create Boolean value that specifies whether or not the JDBC driver should create the specified database if it does not exist. The default value is false.

shutdown Boolean value that specifies whether or not the database should be unloaded from the Java virtual machine. The default value is false.

encryption Boolean value that specifies whether or not the JDBC driver should open or create an encrypted database. If the value of this property is true, the JDBC driver retrieves the encryption key from the local credential store to open the database and encrypt it.


Figure 5-13 illustrates the end result.

Figure 5-13 Preview of live name integration

Let us tour the code:

1. First, we must add some hooks into DetailComposite. We will implement the awareness controls inside one single SWT Composite. We describe how that is accomplished in the next step. For now, this simply means that we can treat all three awareness controls as one. A nice side effect of this is that the changes to DetailComposite are minimal.

Place the code shown in Example 5-14 in DetailComposite immediately before the code that creates the Priority drop-down list.

Example 5-14 Code for DetailComposite

GridUtils.makeLabel(this, "Contact Name:", "");mLiveName = new LiveNameButton(this, SWT.NONE);GridData gd = new GridData(GridData.GRAB_HORIZONTAL | GridData.FILL_HORIZONTAL);mLiveName.setLayoutData(gd);

2. As the previous source seems to indicate, our awareness control will be called LiveNameButton. will implement it as a custom Composite. Its constructor takes the form shown in Example 5-15 (also note the introduction of a member variable).

Example 5-15 LiveNameButton

// online users are shown in this colour.private Color onlineColor;

public LiveNameButton(Composite parent, int style){


super(parent, style);

// layout.GridLayout gridLayout = new GridLayout(3, false);gridLayout.marginHeight = gridLayout.marginWidth = 0;setLayout(gridLayout);

createLiveNameListener();

// controls.createLiveNameLabel();createChatButton();createChangeButton();

// create our colour for online users.onlineColor = new Color(Display.getCurrent(), 0, 128, 0);

createDisposeListener();}

The remaining steps describe each method that the constructor calls.

3. The first method called by the LiveNameButton constructor is createLiveNameListener(). This is an appropriate time to introduce the Workplace Live Names API. In fact, the Managed Client provides two separate Live Names APIs. They differ in their complexity (and, accordingly, flexibility):

– LiveNameViewer is a list of live names. Each name indicates the associated user’s instant messaging status. A context menu is provided with options including retrieving detailed user information and starting an instant messaging chat. The drawback is that the list of names cannot be modified after the control is created.

– LiveNameController implements a series of awareness-related callbacks. Based on the callback messages, we can implement whatever UI we want. The drawback is increased complexity.

We use LiveNameController in this sample application.

Tip: A custom Composite is one possible approach we can use to create our own SWT controls. To start, we extend Composite. In the constructor, we create all of controls we need; we can also set a layout manager for the contents of the custom Composite. Each control’s parent should be the object itself (to which this yields a reference). To the outside world, all of the controls contained inside are invisible: they see only the enclosing Composite.


Each instance of a LiveNameController object returns awareness events for a single user. Its constructor takes a String argument, which corresponds to the user name or e-mail address of the user, and an ILiveNameListener argument. The ILiveNameListener instance receives awareness event callbacks for the specified user. Before destroying the object, we call removeLiveNameListener().

Our control is interested in just one user at any given time. Accordingly, it maintains one LiveNameController object and one ILiveNameListener.

Example 5-16 shows the code for createLiveNameListener and the member variables it introduces into LiveNameButton.

Example 5-16 createLiveNameListener code

// status of the currently displayed user.protected short status;// currently displayed awareness icon.private Image icon;// listens for awareness events on the current name.private ILiveNameListener liveNameListener;

private void createLiveNameListener(){

// live names listener.liveNameListener = new ILiveNameListener(){

public void statusChanged(String liveName, short status, Image icon, Object object)

{

Tip: In the Workplace world, a live name is a string of text representing a user that is somehow active. It dynamically displays their instant messaging status and enables us to start a chat session simply by double-clicking the name.

Tip: The Managed Client Toolkit API contains a more in-depth introduction to the Live Names API. Here, we introduce only enough concepts to make our application function.

Important: A new LiveNameController is created and destroyed for each call to setUser(). The ILiveNameListener exists for the lifetime of the LiveNameButton instance. The same instance can be attached and removed from any number of LiveNameController instances.


LiveNameButton.this.icon = icon;LiveNameButton.this.status = status;refreshLiveNameLabel();

}};

}

The member variable liveNameListener is an anonymous inner class. Notice how statusChanged() gives us not only the status, but a also suitable awareness icon (the same as used by IBM Workplace Messaging®). These are recorded and the awareness list refreshed with a call to refreshLiveNameLabel().

We show the code for refreshLiveNameLabel() later.

4. Let us examine the code that builds the SWT controls. First of all, the awareness label itself is contained in createLiveNameLabel(). Somewhat anti-climatically, it is just three lines long. A standard SWT CLabel suffices, as shown in Example 5-17.

Example 5-17 Standard SWT CLabel

private CLabel clabel;private void createLiveNameLabel(){

clabel = new CLabel(this, SWT.LEFT);GridData gd = new GridData(GridData.GRAB_HORIZONTAL |

GridData.FILL_HORIZONTAL);clabel.setLayoutData(gd);

}

We make CLabel a member variable because refreshLiveNameLabel() will need to reference it.

5. The components we add to our Composite appear in left-to-right order. With this in mind, the next component is the Chat button. Again, the code for this is quite simple, as shown in Example 5-18 on page 159.

Information: The following code requires the com.ibm.eworkplaces.pim.ui.blended plug-in. This is part of Workplace Messaging.

Beware that the Chat class (and, indeed, the com.ibm.eworkplace.pim.ui.blended plug-in itself) is not part of the Workplace API. Therefore, it is subject to change after Workplace 2.6. However, for Workplace 2.6, this code works.


Example 5-18 Chat button

private void createChatButton(){

Button chatButton = new Button(this, SWT.NONE);chatButton.setText("Chat...");chatButton.addSelectionListener(new SelectionListener(){

public void widgetDefaultSelected(SelectionEvent arg0) {}public void widgetSelected(SelectionEvent arg0){

new Chat(LiveNameButton.this, email, "The task", true);}

});

GridData gd = new GridData();gd.widthHint = BUTTONS_WIDTH;chatButton.setLayoutData(gd);

}

Note how the Chat constructor requires a parent control, e-mail address (or user name), and a subject.

6. The right-most and final control is the Change button. When pressed, this opens a modal dialog box. The user is asked to enter a user’s e-mail address. The awareness label then refreshes to display that user. If the e-mail address is known to Workplace, the label is a live name.

The code, as shown in Example 5-19, is similar in form, but quite different in function, to the code for the Chat button.

Example 5-19 Change button

private void createChangeButton(){

Button searchButton = new Button(this, SWT.NONE);searchButton.setText("Change...");searchButton.addSelectionListener(new SelectionListener(){

public void widgetDefaultSelected(SelectionEvent arg0) {}public void widgetSelected(SelectionEvent arg0){

InputDialog dlg = new InputDialog(Display.getCurrent().getActiveShell(), "Change contact", "Enter the

contact name\'s email address", (email == null ? "" : email), null);if (dlg.open() == Window.OK)

setUser(dlg.getValue());}

});


GridData gd = new GridData();gd.widthHint = BUTTONS_WIDTH;searchButton.setLayoutData(gd);

}

The parts to note are the use of a JFace dialog box to ask for user input and the subsequent call to setUser(). We discuss setUser() in the next point.

7. With the UI and live name code in place, we can now add the final essential part of the puzzle. This is the code to change the user displayed in the awareness label, as shown in Example 5-20.

Example 5-20 Change the user displayed in the awareness label

// this object gives us online/offline event notification.private LiveNameController lnc;

public void setUser(String email){

this.email = email;

// destroy listener.if (lnc != null)

lnc.removeLiveNameListener(liveNameListener);

// new listener.if (email != null)

lnc = new LiveNameController(null, email, liveNameListener);else

icon = null;

// refresh the label.refreshLiveNameLabel();

}

This code depends on refreshLiveNameLabel(), as shown in Example 5-21. Remember that our ILiveNameListener anonymous inner class also calls this code whenever the monitored user changes status.

Example 5-21 refreshLiveNameLabel() method

private void refreshLiveNameLabel(){

Display display = PlatformUI.getWorkbench().getDisplay();display.asyncExec(new Runnable(){

public void run(){

clabel.setText(email == null ? "" : email);clabel.setImage(icon);


clabel.setForeground((email != null) && (status != ILiveNameListener.STATUS_OFFLINE) ? onlineColor : null);

}});

}

Lastly, note how the calls to CLabel are run explicitly inside the UI thread. This caters for calls originating from ILiveNameListener.statusChanged(), which will arrive on a non-UI thread.

8. The final method, createDisposeListener(), creates a handler that executes when the component is about to be destroyed. Example 5-22 shows this code.

Example 5-22 createDisposeListener() method

private void createDisposeListener(){

// clean up.clabel.addDisposeListener(new DisposeListener(){

public void widgetDisposed(DisposeEvent e){

if (email != null)lnc.removeLiveNameListener(liveNameListener);

onlineColor.dispose();}

});}

The listener explicitly cleans up two resources:

– The color used when the monitored user is online.

– The current ILiveNameListener (if any).

5.10 Deploying the sample applicationTo deploy our sample application onto a real, live, Workplace server, we use the toolkit's export facility. This is perhaps the toolkit’s most valuable feature. Its output is called a deployable set.

Tip: One of the chief differences between SWT and many other UI toolkits, Swing in particular, is that OS resources must be destroyed explicitly. This in stark contrast to many peoples’ expectations of object-oriented programming. Nevertheless, we must destroy the color. We also choose this time to deregister our ILiveNameListener.


Contained inside is everything we will need:

� XMLAccess scripts to create and delete the application’s RCPML-enabled portlet instances and portal page

� A miniature Eclipse site, the contents of which can be integrated with your primary Eclipse update site

� Full instructions of how to deploy it


1. From the Eclipse menu, select File → Export. This opens the Eclipse export wizard selector, as shown in Figure 5-14. Select IBM Workplace Managed Client Deployable Set. Click Next.

Figure 5-14 Export wizard selection


2. The Managed Client Toolkit export wizard is contained in just one page, as shown in Figure 5-15. From the list of applications, select the sample application. It is probably called com.ibm.redbooks.taskmanager. For the Destination, select whatever is appropriate for your system. The wizard creates a new directory with the name of the application; inside will be the deployable set. In this example, we select our home directory. When ready, click Finish.

Figure 5-15 Managed Client Toolkit export wizard

3. Our deployable set is in the new directory. Full instructions for deploying the set are contained in a plain text file called DeployInstructions.txt. Follow these instructions to deploy the application.

This completes the application.


Chapter 6. Troubleshooting IBM Workplace Managed Client

As we described in the preceding chapters, IBM Workplace Managed Client is a robust and flexible rich client for our customers and provides much of the functionality today’s business users require to maximize their daily productivity. Therefore, given that we have this wonderful, indispensable product that everyone will rely on to perform their day-to-day activities, what happens if something goes wrong? The good news is that IBM Workplace Managed Client has been developed with serviceability in mind from its early stages. It offers a number of helpful features and capabilities that enable users who experience any problems to both:

� Troubleshoot and correct issues themselves

� Provide IBM Support with the proper information required to aid in correcting the issue

This chapter provides details about many of these features and offers tips and techniques for minimizing the impact of errors and problems on your productivity.

6


6.1 Logging and tracing in Workplace Managed Client 2.6

At the center of any product’s troubleshooting capabilities is its logging subsystem. Errors and events that occur during the normal operation of a product are critical in helping to determine what might have led to any abnormal conditions. This section describes how IBM Workplace Managed Client handles logging and tracing and how it can be used to tailor log content to whatever needs investigation.

6.1.1 LoggingIBM Workplace Managed Client has a Java Specification Request (JSR) 47 compliant logging API that all components of the client use to produce consistent log messages to a unified location.

Any application or component that uses this logging API has its output sent to the user’s $WORKSPACE/logs/rcp0.log file, which is the main log file for the client.

The log file has a default size limit of 2 MB, at which point the logger will rename each of the existing log files to rcp<#+1>.log, and the rcp0.log will roll over to rcp1.log. A new rcp0.log will then be created to continue logging the client’s messages. Also, by default, there is a maximum of 12 generations of log files that will be preserved. Therefore, when rolling new log files at startup, or when the log reaches its maximum size, anything after rcp11.log will be discarded.

Important: It is important to note that $WORKSPACE/logs is the first place to look to find the products logs. This is where most problem determination data is found. $WORKSPACE corresponds to $HOME/IBM/RCP/<WorkspaceID>/<username>/.

We describe <WorkspaceID> more fully in 2.1, “Applications overview” on page 20. In summary, it is a unique identifier that the client uses to find a user’s application and configuration data.

Tip: The rcp0.log file always pertains to the most recent iteration of the client code being executed. At client startup, the initialization code looks for any existing rcp#.log files. If it finds them, it renames each to rcp<#+1>.log in order to preserve the history of client execution. So, rcp0.log will be renamed to rcp1.log, rcp1.log to rcp2.log, and so on. The new rcp0.log will then be created to handle logging calls for the current instance of the client.


If a user or administrator wants to modify any of the default settings for the logger, the appropriate way to do so is to edit the user’s $INSTALL_DIR/rcp/plugin_customization.ini file.

As mentioned earlier, the client logger is JSR 47 compliant, so it implements the configuration properties described by the java.util.logging.FileHandler specification.

To modify the default logger properties for the file size, and the number of files to preserve, a user adds these lines to the plugin_customization.ini file:

com.ibm.rcp.core.logger.RCPFileHandler.limit=<file size in bytes>com.ibm.rcp.core.logger.RCPFileHandler.count=<number of files to preserve>

It is important to note that these settings are case-sensitive and will not work if RCPFileHandler is not properly typed with the cases shown in the previous example. Also note that the .limit setting is specified in bytes, rather than kilobytes (KB) or megabytes (MB).

Note: For more information about JSR 47 and the java.util.logging API, refer to:

http://www.jcp.org/en/jsr/detail?id=47http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html

Important: At the time of writing this book, the client logger is not obeying the settings of these properties in the plugin_customization.ini file. This should be fixed in a future release of the client. We document this method because it is the preferred mechanism for modifying log and trace settings for the client in order to consolidate all configuration changes pertaining to the logger.

Until this problem is fixed, the user or administrator can change these properties by editing the file:$INSTALL_DIR/rcp/eclipse/features/com.ibm.rcp.platform.feature_1.3.0.0400/bootjars/properties/logger.properties

The settings to modify are:

log.size=<size in bytes>log.generations=<number of files to preserve>

We advise you not to modify any of the other settings in this file, and truly, make modifications to this file only if absolutely necessary.

Chapter 6. Troubleshooting IBM Workplace Managed Client 167

http://www.jcp.org/en/jsr/detail?id=47

http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html

In order to learn anything useful from the log file, you need to understand what the format of the log output is. Each log entry is formatted something like this:

2005/12/13 09:25:06.677 80 INFO common CLFOL0002I:Synchronization started :: thread=Worker-3 ::loggername=com.ibm.workplace.replication.common

Where:

� 2005/12/13 09:25:06.677 This is the date and time (to milliseconds).

� 80 This is a sequence number indicating the order in which this log record was created, relative to the instantiation of the JVM. This is helpful in cases where threading causes log entries to be out of order. This sequence number always enables a user to see in what order the messages were created, which might differ from when they were written to the log.

� INFO This is the severity associated with the event. We discuss severities more in this section.

� commonThis is the short name of the logger writing this event, which generally corresponds to the last part of the package name of the Java class of the logger.

� CLFOL0002I: This is the unique message ID (and a trailing :) associated with the event. We discuss this more in this section.

� Synchronization started This is the message text associated with the message ID that precedes it.

� ::thread=Worker-3 This is the name of the thread writing the event

� ::loggername=com.ibm.workplace.replication.common The is the full name of the logger used to write the event. It corresponds to a package name that can be used to set tracing levels. See 6.1.2, “Tracing” on page 170.

The severity of the entry corresponds to the JSR 47 specification of severity levels for events. The levels can be (from most critical to least critical):

� SEVERE

� WARNING

� INFO

� CONFIG


� FINE

� FINER

� FINEST

By default, the client logs any messages that are a severity INFO or higher. Anything lower than that is considered trace and can be turned on as needed, which we describe in the next section.

The message ID for each entry is composed of a number of different identifiers, with the following structure:

CCCSSNNNNT

Where:

� CCC is a registered component ID to identify the IBM product.

� SS is a subcomponent identifier assigned by the IBM Workplace product teams.

� NNNN is a unique four-digit serial number that is generated as part of the build process.

� T is a severity indicator representing E for ERROR, W for WARNING, or I for INFO.

In addition to standard log entries written by applications, the rcp0.log file can contain entries that are generally written to the SystemErr.log and SystemOut.log files that reside in the same directory. In cases where a component does not use the proper API to log a message, output to the standard Java system out and system error is captured, formatted in a similar fashion (without message IDs and the other identifiers), and written inline to the rcp0.log file. Entries of this nature look similar to the following entry:

2005/12/13 09:24:15.321 14 INFO err>> Invalid Menu Extension (Path is invalid): org.eclipse.ui.edit.text.gotoLastEditPosition ::thread=main ::loggername=err>>

As you can see from this sample, the output is formatted slightly differently. In the space for the short name of the logger, and in the full logger section at the end of the entry, we see the string err. This indicates that the message was generated by someone writing to the SystemErr.log file. The equivalent for the SystemOut.log file has out as the string.

Tip: Note that if there are problems experienced very early in launching the Eclipse base, look in the $WORKSPACE/.metadata/.log file for messages logged by Eclipse. After the platform’s logger is initialized, the rcp0.log file also contains the output generated by the core Eclipse engine.


Another piece of information that can fall under the “logging” umbrella is the output contained in another file in the $WORKSPACE/logs directory. At startup, the client produces a file called config0.log that contains a large amount of client environment information, including the user policy data that is influencing various aspects of the client’s behavior. As described earlier in this book, the server-side user policies control the what a user is able to do with Workplace Managed Client. If a user reports some type of problem that might be related to a policy issue, reference this config.log file to determine what policy setting with which the client is operating. For example, if a user is unable to create a document library, check the config0.log file to confirm that the following parameters are both set:

isDocumentManagementEnabled:trueisCreateDocumentApplicationEnabled:true

The config0.log file also contains a wealth of other data, such as the flags passed to both Eclipse and the JVM when starting the client, the overall Java environment the client is running, a complete list of client features that have been provisioned, and the entire plug-in registry, which contains a list of all the plug-ins installed and their versions. Needless to say, this is a very important file to review whenever a problem arises in executing the client.

6.1.2 TracingFrom an overall serviceability perspective, logging and tracing are very similar in concept and implementation in IBM Workplace products. The only real distinctions are the amount and type of details that gets put in the log file and globalization issues (what gets translated and what does not). That said, tracing is a very important part of problem determination, and users need to understand how to control tracing levels in case they need to provide detailed log output to IBM Support.

Note: The config0.log file might contain two sets of data from the same execution of the client code. If a change to the policy data is detected relative to the previously cached policy settings, the old and new policy settings will both be dumped to this file. To make sure that you review the correct data, each set of policy data is preceded by a line that contains the date and time stamp of the time the policy is cached. For example:

Dec 15, 2005 10:36:31 AM com.ibm.workplace.policymanager.rcp.RcpPolicy setCachedPolicy

Ensure that the settings you check are the most recent. Also, similar to the behavior of the rcp0.log file, when the config0.log file is created, the previous configuration log is renamed to config1.log. In the case of the configuration logs, there will only ever be two of them at most.


To control the tracing level for a particular component of the client, the user must modify the Java logging level for the specific packages in that product component. To do so, the user must edit the $INSTALL_DIR/rcp/plugin_customization.ini file.

$INSTALL_DIR is the location the user chose to install to when first installing the client (the default is /opt/IBM/Workplace Managed Client). In this file, the user can add an entry such as:

com.ibm.workplace.mail.level=FINEST

This will set the FINEST level of tracing on the mail package in order to trace errors that occur in the client when using the mail facilities.

Another thing to understand about setting tracing is that it follows the package hierarchy so that setting trace on a lower-level package overrides any setting for a package that is higher in the hierarchy. For example, if the plugin_customization.ini file specifies the following trace setting, all packages under that hierarchy will log at the default INFO level:

com.ibm.wkplc.bl.rcp.infra.level=INFO

If a user also adds the following setting, the views package (and any package under it) would log at the FINEST level, while the rest of the packages under the com.ibm.wkplc.bl.rcp.infra layer would continue to log only INFO or higher severity messages:

com.ibm.wkplc.bl.rcp.infra.views.level=FINEST

Note: In most cases, trace output is intended to be used by IBM Support to facilitate troubleshooting. Users generally do not need to understand the content.

Important: This is the pattern to follow for all trace settings:

<package_name>.level=<severity>

Where <severity> is SEVERE, WARNING, INFO, FINE, FINER, or FINEST. The severity must be set with all uppercase letters in order to be recognized. Also, changes to trace levels are not dynamic. IBM Workplace Managed Client must be restarted for changes to take effect.

For more information about the java.util.logging.Level specification, see:

http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html



How do you know what packages to trace? In most cases, only do tracing under the direction of someone from IBM Support. Trace logs are usually only helpful to people who have a detailed understanding of the underlying architecture and code of the product. However, here are packages for some common areas of the product that might be useful when needing to set trace levels for particular issues.

Table 6-1 Common packages

Functional area/component Package

Messaging UI and services

General mail and calendar activities com.ibm.eworkplaces.pim.client.common

General mail features com.ibm.workplace.mail

com.ibm.workplace.mailbox

Out of office feature com.ibm.eworkplaces.pim.ui.docedit

General calendaring features com.ibm.workplace.calendar

com.ibm.workplace.calsched

Calendar view UI com.ibm.eworkplaces.pim.ui.calendar

Calendar datepicker feature com.ibm.eworkplaces.pim.ui.datepicker

Calendar data retrieval com.ibm.eworkplaces.pim.client.datamodel

Instant messaging

General IM features com.ibm.workplace.sip

com.ibm.workplace.bl.rcp.infra

com.ibm.wkplc.bl.rcp.infra

com.ibm.wkplc.bl.rcp.infra.views

Live names feature com.ibm.rcp.ui.livenames.widgets

com.ibm.eworkplaces.pim.ui.blended

Provisioning

com.ibm.rcp.provisioning

com.ibm.rcp.update

com.ibm.pagebuilder.requirements

Synchronization


Note that in most cases, setting tracing as described earlier sends extra information to the rcp0.log file for the component in question. For one particular package, com.ibm.workplace.replication, setting trace adds more verbose output to the rcp0.log file, but also creates a set of XML files in the $WORKSPACE/logs directory. These files are per-sync session traces of synchronization requests and responses. The file names all follow the pattern of:

x_y_req.xmlx_y_resp.xml

Where x is the session identifier, and y is the session package identifier. Each synchronization session requires multiple packages (with a minimum of four) to complete the transaction. Therefore, each time the client synchronizes, it creates at least eight files, with the session counter (x) incremented by 1. If the client is shut down and restarted, the session counter returns to 1, and any existing files are overwritten.

6.2 Using IBM Support Assistant for self-help and data collection

IBM Support Assistant is an Eclipse-based customer self-help utility developed by IBM. It is freely distributed and is enabled for use with many IBM Software products. IBM Support Assistant provides a framework to facilitate many

com.ibm.workplace.replication

Activity Explorer

com.ibm.workplace.ae.client

Tip: When trying to diagnose a problem, if you are not sure what packages to trace, look at the default messages that are being produced when the problem occurs. If there is an exception, or an error of SEVERE, WARNING, or INFO severity that you want to get more information about, check the loggername at the end of that message. Normally, you can set your tracing based on the package listed there.

Tip: If you run the client with synchronization trace turned on for any length of time, you can generate a large number of files. It is best to turn this trace on, reproduce the condition you are trying to debug, and then turn the trace off again in order to minimize the amount of output generated.

Functional area/component Package


common activities users need to perform when investigating or reporting problems users might have with IBM product solutions.

IBM Support Assistant provides these services:

� A search interface to enable users to search multiple product and support information repositories concurrently

� A consolidated set of links to helpful product Web sites and forums

� Inline data collection and problem submission capabilities

The product teams that want to leverage IBM Support Assistant can develop product-specific IBM Support Assistant plug-ins that contain the interfaces and information pertinent to their individual product. When IBM Support Assistant launches, it builds much of its user interface based on the product plug-ins that are installed. IBM Workplace Managed Client automatically installs plug-ins for the products in which most IBM Workplace users and administrators are interested, including:

� IBM Workplace product family (server and client)

� IBM Cloudscape

� IBM DB2® Universal Database™ (UDB)

� IBM WebSphere Application Server

� IBM WebSphere Portal

� IBM Directory Server

IBM Support Assistant, when provisioned with IBM Workplace Managed Client, is installed to $WORKSPACE/applications/com.ibm.esupport.client.lwp.feature, which we refer to as $ISA_DIR. All of the IBM Support Assistant plug-ins

Important: For more information about IBM Support Assistant, see:

http://www.ibm.com/software/support/isa

The most current version of IBM Support Assistant is 2.0, with 3.0 expected sometime in early 2006. The version of IBM Support Assistant that ships with IBM Workplace Managed Client is Version 1.0, and lacks some of the functionality described on the Web page. We describe IBM Support Assistant Version 1.0 in this chapter.

There is work being done to incorporate the latest versions of IBM Support Assistant into future releases of Workplace Managed Client. However, there are IBM Workplace product plug-ins available for IBM Support Assistant V2.0 that can be downloaded from links at the IBM Support Assistant site.



(including the product-specific plug-ins) are installed in $ISA_DIR/eclipse/plugins/.

IBM Support Assistant is integrated with Workplace Managed Client and is accessed directly from the client’s Help menu, as shown in Figure 6-1.

Figure 6-1 IBM Support Assistant launched through the Help menu

After selecting IBM Support Assistant from the Help menu, it either opens a new Mozilla browser session or launches within a currently running Mozilla or Firefox browser. The user interface contains four main tabs: Search, Support Links, Service, and User Guide.

6.2.1 IBM Support Assistant Search componentThe default page that opens when launching IBM Support Assistant is the Search page (or tab), as shown in Figure 6-2 on page 176.


Figure 6-2 IBM Support Assistant default view

This interface enables you to perform searches across a multitude of sources concurrently. The target information sources are based on the product plug-ins installed, along with some targets that IBM Support Assistant sets by default, as shown in Figure 6-3 on page 177. The targets include:

� Product support documents hosted on the IBM support Web sites, such as:

– Technotes

– FAQs

– Product documentation

– APARs

– Redbooks

� IBM developerWorks articles

� IBM public newsgroups and forums

� Google


� Local Eclipse-based help systems (that is, the IBM Workplace Managed Client help)

Figure 6-3 IBM Support Assistant Search target selection

The search request is simultaneously sent to each of the targets selected by the user. The utility waits for the results from the targets, and then aggregates the results and presents them to the user in a panel of the UI, as shown in Figure 6-4 on page 178.


Figure 6-4 IBM Support Assistant search result list

You can then select the result set to review, and the right side panel presents a set of document titles and some of the content that is around the search strings found in the document. The document titles are all hyperlinks to the document on the target Web site, so you can browse the result set, and if a document looks appropriate, click the title to be taken directly to the full article. See Figure 6-5 on page 179.


Figure 6-5 IBM Support Assistant search results

The search functionality is very useful for error messages or questions about functionality that users do not understand or know how to access. For example, if the user gets an error message and needs to correct whatever behavior is causing it, the user simply enters the error string in the search field and selects the document sources to search. Then, IBM Search Assistant presents the user with a great deal of information, all without having to call the company help desk or IBM Support.

Tip: Even though a result set might show a large number of results, IBM Support Assistant by default only caches and displays 32 of them. The thinking is that if you have more results, you can probably refine your search to get more targeted, accurate results. If you truly need to display more than the first 32 hits in a result set, you can edit the following file and change the defaultResponseCount value to something larger:$ISA_DIR/eclipse/plugins/com.ibm.esupport.client.webapp_1.0.0.0400/search/conf/multisearch-cfg.xml

Note that this requires a recycle of IBM Workplace Managed Client.


6.2.2 IBM Support Assistant Support Links componentThe Support Links tab in the IBM Support Assistant interface provides users with “one-stop-shopping” for links to all of their product information needs. It contains links to the individual product home pages, support sites, and any IBM-sponsored newsgroups or forums that exist. Therefore, to obtain more information about a particular product, instead of searching the Web or trying to find it on the IBM Web site, simply access the home page directly from IBM Support Assistant. Figure 6-6 shows the Support Links tab.

Figure 6-6 IBM Support Assistant Support Links tab

The tab is completely derived from the product plug-ins that are installed. If there are no product plug-ins, this page is blank. However, because IBM Workplace Managed Client bundles a number of product plug-ins, and they all leverage the extension points provided by IBM Support Assistant, you can get to a number of helpful sites with only a click or two.


6.2.3 IBM Support Assistant Service componentThe Service component of IBM Support Assistant performs three distinct tasks:

� Acts as the preferred data collection mechanism for gathering all logs and information required to do problem determination for a particular issue.

� Provides access directly to the IBM Electronic Service Request (ESR) tool, which enables entitled customers to open or update problem tickets with IBM Support.

� Enables inline transmittal of collected problem data through FTP to IBM Support FTP sites.

Figure 6-7 shows the Service tab.

Figure 6-7 IBM Support Assistant Service tab


IBM Support Assistant data collectorThe IBM Support Assistant data collector is the recommended tool to use to gather all of the client’s problem logs and environment information. The main mechanism for executing the collector is through the UI, as shown in Figure 6-8. The product plug-in provides the installation directory and client workspace, which are required by the collector in order to find the files to gather. The IBM Support Assistant data collector is configured to read a file named wct25.inventory, which is stored in the product plug-in for the IBM Workplace Managed Client, which is $ISA_DIR/eclipse/plugins/com.ibm.esupport.client.WCT_1.0.0.0400/.

The wct25.inventory file contains pseudo-script designed for use with the data collector. The script is fairly flexible, enabling the collector to gather individual files, entire directories, or multiple files using wildcard substitution. It has numerous other features (macro support, system command execution, and so on), but that is beyond the scope of this chapter. Suffice it to say that the inventory file controls what data gets collected. Among these are the entire $WORKSPACE/logs directory, any javacores generated, configuration files, the RCPML document, the collector.log file produced by the collector itself, and a significant amount of OS environment and configuration information. These are all bundled into a JAR file that named collector_<yymmdd>_<hhmm>_<ssMMM>.jar to make sure that each collection is distinguishable from another.

Figure 6-8 IBM Support Assistant data collector interface


After clicking the Invoke collector button, after a moment, it returns a results page that shows the resulting JAR file and the collector’s log file are both in the $WORKSPACE/.metadata directory. See Figure 6-9.

Figure 6-9 IBM Support Assistant results


IBM Support Assistant ESR linkAfter you have a set of data that corresponds to a problem you need to resolve, you might want to either open a new problem record with IBM Support or possibly update an existing one pertaining to the problem. To facilitate this, the IBM Support Assistant Service component has a link to the IBM ESR Web site, which displays in a subframe of the IBM Support Assistant browser, as shown in Figure 6-10.

Figure 6-10 IBM Support Assistant ESR interface

From this page, anyone properly entitled with an IBM Support contract and valid ESR login can manage their problem reports.


IBM Support Assistant FTP interfaceOf course, if you have collected data, and you have a PMR being worked by IBM Support, you most likely want the Support representatives to be able to use your data to troubleshoot the problem. IBM Support Assistant makes it easy to get the files to IBM as part of the workflow of the Service component. After you have a valid PMR number, the IBM Support Assistant Send System Data page enables you to transmit your collector JAR file directly to one of two IBM Support FTP sites. Figure 6-11 shows the FTP interface.

Figure 6-11 IBM Support Assistant FTP interface

If you are in the same IBM Support Assistant session as when the data collector ran, the data collector output file field is populated with the location of the collector JAR file that was created. Enter a valid PMR number, and click the button to send the data.

Tip: The “Primary” server should always be the first server used, because it corresponds to the main IBM Support FTP site at ftp://ftp.emea.ibm.com/. When transferred, the collector output is renamed to be preceded by the PMR number and is placed in the proper directory. When using this mechanism, the FTP site updates the PMR in the IBM Support problem tracking system to indicate that new data has been uploaded.


ftp://ftp.emea.ibm.com/

Running the IBM Support Assistant collector manuallySo far, we discussed running the IBM Support Assistant data collector through the IBM Support Assistant user interface, but what happens when the UI is not available? What if the client is hung for some reason, or you are unable to start it? Then what are your options? Fortunately, it is possible to run the IBM Support Assistant collector manually, as well. There is a script called cl_collect.sh that in $ISA_DIR/eclipse/plugins/com.ibm.esupport.client.WCT_1.0.0.0400/. Run this command and pass it the path where the IBM Workplace Managed Client was installed:

./cl_collect.sh /opt/IBM/Workplace\ Managed\ Client

As of this writing, there is a bug in the script where it checks for a file that does not exist. This is easily corrected, however. Edit the script, and modify this line:

if [ -f “$1/rcp/richclient.sh” ]; then

Remove the .sh from the file it is attempting to find:

if [ -f “$1/rcp/richclient” ]; then

When executed, the script displays some environment information and a message stating that it is working and to be patient. After it completes, it displays a message in the terminal telling the user that the output will be put in the user’s $WORKSPACE.

Troubleshooting IBM Support AssistantAlthough IBM Support Assistant is a self-help and troubleshooting aid, there are not too many software products that run perfectly every time. So what happens when a problem occurs with IBM Support Assistant itself? For problems with an individual execution of the collector, you can use the collector.log file mentioned in the previous section. It contains a list of the operations the collector performed and should give an indication of where a failure might be occurring.

If the problem is with another segment of IBM Support Assistant, the $WORKSPACE/.metadata directory should also contain a file called ibm_esupport_0.log that contains the log of all IBM Support Assistant activity. Similar to the rcp0.log file, the ibm_esupport_0.log file only captures messages of severity INFO or higher, by default.

Important: Note the distinction that running the collector through the UI puts the collected output in $WORKSPACE/.metadata, while running it manually puts it in $WORKSPACE. This can cause confusion when trying to find the JAR file later.


To increase the granularity at which IBM Support Assistant logs, edit the following file:$ISA_DIR/eclipse/plugins/com.ibm.esupport.client.webapp_1.0.0.0400/common/conf/esc-config.xml

There is an entry for <LoggerConfig> that contains the following parameter:

level=“INFO”

Change “INFO” to “FINEST”, restart the entire client, and IBM Support Assistant recognizes the changes.

6.3 Troubleshooting the productivity toolsIBM productivity tools are a bit different when it comes to troubleshooting. The main reason is that the editors are actually C/C++ programs rather than Java code. As such, they do not use the Java-based logging APIs that create the rcp0.log file. The main problem determination data for the productivity tools is produced by the “crash reporter” mechanism. This is a process that acts as a exception handler for the editors so that if they crash, the reporter handles the signal, dump system, and stack information for the process. It also produces a report of the final few user operations that were performed in the editors, including any menu or toolbar activity that occurred. All of this data is dumped into the $WORKSPACE/logs directory, with names that look like this:

sodc_<type>_<platform>_<hostname>_<yyyy_mm_dd>@<hh_mm_ss>.log

Where <type> is crash or event, depending on the type of data it contains. <platform> is the OS type (Linux or Win32®), and the rest should be self-explanatory. The crash files contain system information and the stack leading to the fault. The event files contain the activity history.

There is a small portion of the productivity tools that is Java code. Java is used when IBM Workplace Managed Client launches the embedded version of the editors. Launching the embedded editors logs messages to the rcp0.log file, so there might be some information that can be taken from the main client log file. Some packages that might be useful to set trace on are:

� com.ibm.superodc.internal.core� com.ibm.seditor.common

Note: These files are generally only useful to IBM Support, so if you are experiencing problems with the IBM productivity tools, make sure to run the collector to gather all diagnostic data (including the sodc* files), and contact your IBM Support representatives.


For additional information about the desktop versions of the editors, the following command launches them, which generates FINEST level of information for the client launcher and also produces more verbose output in the user’s terminal window:

$INSTALL_DIR/rcp/richclient -personality com.ibm.seditor.seditorpersonality -debug

6.4 Troubleshooting provisioningAs previously mentioned, provisioning is the mechanism the client uses to install the applications that are available to the user. It is a very complex process, and although it generally works smoothly, when errors do occur, it can be very difficult to determine what went wrong.

If and when problems arise, there are a number of things to check to try to determine what happened.

Confirming the featuresOne of the first things to check is that the RCPML documents were properly retrieved. Checking the date and time stamps on the files that begin with -lwp-myworkplace*.

The files are in the following two directories:

� $WORKSPACE/.metadata/.plugins/com.ibm.rcp.pagebuilder/config� $WORKSPACE/.metadata/.plugins/com.ibm.rcp.pagebuilder/pages

The files should have a consistent date and time they were updated. Open these files and confirm that any application features listed in the files can be found as directories under $WORKSPACE/applications. The features that should be installed can be identified by the XML tags that start like this:

<feature id=”com.ibm.lwp.wct.mymailcommon.feature”

A corresponding directory is in the applications directory, and it should contain the entire subset of Eclipse features and plug-ins that make up that application feature. If there is anything missing or incomplete with either the RCPML documents or the features, check a number of things, such as whether you can access the provisioning server correctly (check the logs) and that the directories both write permission and the available space to store the features.

After confirming that these items seem to be correct with the RCPML documents and features, check the $WORKSPACE/.config/org.eclipse.update/platform.xml file.


This file describes (in XML) the application features installed and each of the subfeatures that are under them. It gets updated whenever the configuration changes, so confirm that the user has write permission to this file and that all of the features listed in the RCPML documents are listed in the file.

If both the RCPML documents and the platform.xml file all appear to be complete, one of the last things to check is that the feature plug-ins resolve correctly at the OSGi layer.

To access the OSGi Service Platform command line, manually launch the IBM Workplace Managed Client in this manner:

1. Open a terminal window.

2. “cd” to the $INSTALL_DIR/rcp directory.

3. Run the following command:

richclient -debug -console -consolelog

This causes the JVM to launch in debug mode (sending its tracing information to the terminal console), and Eclipse starts with the OSGi prompt available in the terminal. After the platform has initialized, and the prompt is ready, type ss to produce a list of all known plug-ins and their status. Investigate any plug-in that does not have a state of RESOLVED or ACTIVE. Figure 6-12 on page 190 shows the results of the ss command.

Note: Eclipse 3.0 incorporated the OSGi Service Platform to offer a more flexible, standardized mechanism for plug-in management. Plug-ins can be installed, activated, deactivated, updated, or uninstalled without requiring a restart of the platform. This provides a much more dynamic mechanism for deploying components than Eclipse offered previously. For more information about the OSGi Alliance and the OSGi Service Platform, go to:

http://www.osgi.org/



Figure 6-12 Results of OSGi ss command

If you find a problem at any of the stages listed earlier, gather more information by setting tracing specific to the provisioning subsystem. This is done in the same fashion as other application tracing, by modifying the $INSTALL_DIR/rcp/plugin_customization.ini file and including the trace settings listed for provisioning in Table 6-1 on page 172.

Rich Client Platform recovery utilityIn some cases, if provisioning is failing and attempts to determine why your current installation is not working is not resolving the problems, it might be best to simply wipe out your current applications and start fresh. This might sound excessive, or even a bit scary at the thought that you might be losing data, but it is a fairly easy process with little risk. With the dual nature of the client’s installation process, you can remove your applications and some configuration files in your current workspace, and then launch the client again. The platform files are never removed, so it is basically a matter of having the client contact the server and pull down new copies of the applications to which you are allowed access.


To make the process even easier, there is a tool you can use to do the cleanup for you. It is bundled with the platform installation under the $INSTALL_DIR/rcp/eclipse/features/com.ibm.rcp.platform.feature_1.3.0.0400/utilities/serviceability/ directory.

This directory contains a JAR file, a readme file, a properties file, and two scripts. Make sure to read the readme.txt before running the rcprecovery utility. Use the reset.sh script for two functions: to collect diagnostic data (including the local data store) and to remove all local application configuration in order to provision to a “clean” environment.

In Release 2.6, the script gets installed without execute permission, so the first thing is to change that:

chmod +x reset.sh

After the execute permission is set, the script must be run with the user’s IBM Workplace Managed Client account name (not the Linux login account):

./reset.sh <WMC login name>

This can have two optional flags:

-reset-databases

When run without the optional arguments, the tool acts only as a problem determination data collection mechanism. It gathers the files that are listed in the resetoptions.properties file and puts them in two files in the user’s $HOME/IBM/RCP/ directory.

The iwctInstallFiles<date>.jar file contains the data files associated with the client platform, and the iwctlogs<date>.jar file contains the data files associated with the user’s applications and $WORKSPACE environment.

If reset.sh is passed the -databases argument, the utility produces the previous two files, and also a third file called iwctdata<date>.jar, which contains the user’s local data store (Cloudscape database). This is useful for cases where there might be a problem with the user’s local document library, for example.

The final argument -reset wipes out the user’s application configuration.

Important: Before running the reset.sh script with the -reset flag, make sure that there are no Workplace Managed Client processes running. This includes any Java or Eclipse processes, and also includes the productivity tools’ preload process. To kill that, you need to kill two processes, preload.sh and SodcPreload. If you simply kill SodcPreload, it will respawn.


When passing the -reset flag, the utility removes the user’s $WORKSPACE/applications and .config directories, and also the contents of $WORKSPACE/.metadata/.plugins/com.ibm.rcp.pagebuilder (the RCPML documents essentially). When the utility completes, you can launch the client again through the desktop icon and go through the initial provisioning process to reinstall the application. The local data store remains the same, so local libraries and the like stay intact.

6.5 Troubleshooting the Notes plug-inWith the introduction of the Notes plug-in for IBM Workplace Managed Client under Linux, we inherit a mature product that has a existing, robust set of problem determination tools and capabilities. So, how do we reconcile the two environments? In this section, we describe how to get the most information possible from the shared environment to troubleshoot problems that occur with the Notes plug-in.

6.5.1 Logging and tracing for the Notes plug-inWhen investigating issues with the Notes plug-in, we need to set trace on both the IBM Workplace Managed Client side (Java logging) and the Notes side (NOTES.INI parameters). The Java tracing provides more information about items such as:

� Launching the Notes client

� Integration of Notes items in the menu system

� Navigating to and from the Notes UI in the client

The NOTES.INI parameters provide information regarding the internal operation of the Notes client with regard to its interaction with the parent platform.

To enable the Notes plug-in trace the IBM Workplace Managed Client, set the following parameters in the $INSTALL_DIR/rcp/plugin_customization.ini file:

com.ibm.workplace.navigator.notes.level=FINESTcom.ibm.workplace.notes.menus.level=FINESTcom.ibm.workplace.noteswc.level=FINEST

Note: When using -reset flag, the Rich Client Platform (RCP) recovery utility first performs the default data collection described previously, and then removes the user’s application files. Therefore, there is no need to run the utility twice.


As with the other IBM Workplace Managed Client trace settings, these log extra information to the $WORKSPACE/logs/rcp0.log file.

In addition to the Java logging, set Notes debug parameters in the $HOME/notes/notes.ini file.

First, ensure that Notes console logging is enabled. Turn this on by setting:

CONSOLE_LOG_ENABLED=1

This writes Notes messages out to the $HOME/notes/data/IBM_TECHNICAL_SUPPORT/console.log file.

In order to set trace for the Notes plug-in, set this debug parameter in the NOTES.INI file:

DEBUGGINGWCTENABLED=1

This produces extra information to the console.log file for the operation of the plug-in under IBM Workplace Managed Client.

6.5.2 Collecting Notes diagnostic dataIn addition to the console logging that Notes writes out, it also produces a number of other log and trace files, including output from semaphore logging that occurs, output from a stack and environment capturing utility called nsd that ships with Notes, and other information. In general, this information is stored in the $HOME/notes/data/IBM_TECHNICAL_SUPPORT/ directory.

Unfortunately, that makes it a bit difficult for users to find and collect all the troubleshooting data required from both Notes and IBM Workplace Managed Client. So, how do we make it easier for the users? Run the IBM Support Assistant data collector. When the nsd utility runs (it runs automatically upon the Notes plug-in crashing or can be run manually), it produces a Notes.inventory file in the IBM Support Assistant plug-in directory that the data collector can use to gather all of the diagnostic files that correspond to the problem. The main wct25.invenory file contains a stanza that looks for the existence of the Notes.inventory file, and if it exists, it gathers whatever it specifies.

Therefore, by simply running the IBM Support Assistant data collector, you can generate one JAR file that contains all of the problem determination data for both IBM Workplace Managed Client and the Notes plug-in.

Important: The Notes plug-in also supports any of the standard debug NOTES.INI parameters with which full Notes client users might be familiar.


6.6 SummaryConsider the following main concepts from this chapter:

� Finding the client log files in the $WORKSPACE/logs directory, particularly rcp0.log and config0.log

� Understanding how to set trace settings, and using the loggername to help identify what packages to trace

� Understanding how IBM Support Assistant can help users solve their own problems

� Using the IBM Support Assistant data collector to gather all problem determination data

Using these concepts, and the other information included here, users and administrators can minimize any impact to productivity that client problems present.

Note: At the time of writing this book, the Notes plug-in was beta code and not complete. In our test environment, we were unable to get nsd to run properly to generate the Notes.inventory file. This should be addressed by the time the Linux Notes plug-in is made generally available with IBM Workplace Managed Client.


Appendix A. Installing IBM Workplace Managed Client on other Linux distributions

Currently, IBM Workplace Managed Client is only officially supported on Red Hat Enterprise Linux 3. Although other Linux distributions are not yet officially supported, we believe it is valuable also to discuss the installation of IBM Workplace Managed Client on additional distributions.

In this appendix, we help the experienced and technically savvy reader to get Workplace Managed Client running on other Linux distributions. Keep in mind, however, that this information might not be complete for each different Linux distribution and that it is not supported by IBM.

Currently, we have tested installations on SUSE Linux 9.3, Debian Testing, and Ubuntu 5.10. In each case, the information contained in this appendix enabled us to successfully install Workplace Managed Client.

A

Note: This appendix is intended to provide additional information that builds on the basic installation methods described in Chapter 3, “Workplace Managed Client 2.6 on Linux installation and configuration” on page 63. Also review the installation process described in that chapter as a foundation before installing any of these other Linux distributions.


Prerequisites for the Linux installationWorkplace Managed Client comes with its own Java runtime environment, so there are no special requirements for that.

Note the following prerequisites:

� A current browser to access both IBM Workplace and IBM WebSphere Portal. Firefox 1.0.x or 1.5 works.

� A Java browser plug-in to start the installer download (see “Configuring the browser for Java” on page 91).

� The most important prerequisite is a Mozilla 1.4.3 installation that matches the Workplace Managed Client API and will be used as embedded browser by Workplace Managed Client.

� A configured /etc/gre.conf file to match the Mozilla 1.4.3 installation.

Getting and compiling Mozilla 1.4.3Download the sources of the Mozilla 1.4.3 release. We downloaded this release from the following mirror site:

ftp://ftp.heanet.ie/mirrors/ftp.mozilla.org/pub/mozilla.org/mozilla/releases/mozilla1.4.3

You can download either mozilla-1.4.3-source.tar.bz2 or mozilla-1.4.3-source.tar.gz. They only differ in the compression method. Save this file into a local directory and start a command line session in this directory.

Unpack the sources, using one of the following commands, depending on the version you just downloaded:

user@workstation:~/downloads> tar xjvf mozilla-1.4.3-source.tar.bz2

Or:

user@workstation:~/downloads> tar xzvf mozilla-1.4.3-source.tar.gz

This creates the “mozilla” directory. Step into this directory:

user@workstation:~/downloads> cd mozillauser@workstation:~/downloads/mozilla>



The next step is the autoconfiguration of the Mozilla code. Because this source code can be compiled on many different systems, including Microsoft Windows, UNIX, Mac OS, and different Linux distributions, the configure script tries to obtain the recommended settings for your installation.

However, the switches we use in the configure command line need to be fixed manually. The gtk2 library and the use of the Xft font engine are very important.

user@workstation:~/downloads/mozilla> ./configure --disable-freetype2 --enable-default-toolkit=gtk2 --enable-xft

This configure command has some verbose output and should end with the lines shown in Example A-1 if no error occurred.

Example: A-1 Configure command output

...creating ./config.statuscreating Makefilecreating config/Makefilecreating config/autoconf.mkcreating ldap/Makefilecreating ldap/build/Makefilecreating ldap/clients/tools/Makefilecreating ldap/include/Makefilecreating ldap/libraries/Makefilecreating ldap/libraries/libldap/Makefilecreating ldap/libraries/libprldap/Makefilecreating ldap/libraries/libldif/Makefilecreating ldap/libraries/liblber/Makefilecreating ldap/libraries/libiutil/Makefilecreating ldap/libraries/libssldap/Makefile

In case of an error, you probably need to install additional development tools or -devel packages that come with your distribution.

Note: To compile software from source, install the development tools that come with your distribution. For compiling Mozilla, you need the compiler for C and C++ (usually gcc and g++), make, autoconf, and some others. You need to also install all available -devel packages that contain information needed to compile the source.

If the next step, the autoconfiguration, fails, it is likely that you have to install additional -devel packages or development tools. Use the output to help determine what is needed.

Appendix A. Installing IBM Workplace Managed Client on other Linux distributions 197

The next step is the build process. After the configure command creates your Makefile, you can start the build:

user@workstation:~/downloads/mozilla> make

This usually takes some time. The make command steps into every subdirectory and calls the compiler to build all objects. Finally, all objects are linked into libraries and executables.

Installation and testsAssuming that the build finally succeeded, you can install the new binaries. Usually, the make install command takes care of this. The default install directory is /usr/local/lib/mozilla-1.4.3. You can change this with the configure command, but we keep it here.

Because the ordinary user account we used to build the binaries does not have any write permissions in the /usr/local file hierarchy, we have to become root before doing the installation:

user@workstation:~/download/mozilla> suPassword:workstation:/home/user/download/mozilla # make install

Now the binaries will be installed to the /usr/local/lib/mozilla-1.4.3 directory. You can now go to this directory and try to start Mozilla. Do not forget to exit the root shell first. Setting the environment variable before starting the process is necessary so that Mozilla can find its own shared libraries:

workstation:/home/user/download/mozilla # exituser@workstation:~/download/mozilla> cd /usr/local/lib/mozilla-1.4.3user@workstation:/usr/local/lib/mozilla-1.4.3> LD_LIBRARY_PATH=$LD_LIBRARY_PATH:. ./mozilla-bin


If the Mozilla Web browser is starting up, you are nearly done. You can check that the embedded Mozilla library is linked against the gtk2-libraries (libgtk-x11-2.0.so.0), which is very important. See Example A-2.

Example: A-2 Check that embedded Mozilla library is linked against gtk2-libraries

user@workstation:/usr/local/lib/mozilla-1.4.3> /usr/local/lib/mozilla-1.4.3> ldd libgtkembedmoz.so linux-gate.so.1 => (0xffffe000)... libgtk-x11-2.0.so.0 => /opt/gnome/lib/libgtk-x11-2.0.so.0 (0x4024b000) libgdk-x11-2.0.so.0 => /opt/gnome/lib/libgdk-x11-2.0.so.0 (0x40513000)... libexpat.so.0 => /usr/lib/libexpat.so.0 (0x40ac9000)

Configuration for Workplace Managed ClientThe last action tells Workplace Managed Client which browser version to use as the embedded Workplace Managed Client browser. This is done in the file /etc/gre.conf (or /etc/gre.d/gre.conf, depending on your distribution).

The content of the /etc/gre.conf file, according to this Mozilla installation, should read:

[1.4.3]GRE_PATH=/usr/local/lib/mozilla-1.4.3

Now, everything should be OK to install Workplace Managed Client on your distribution.

Tip: GRE is an acronym for Gecko Rendering Engine, and the gre.conf file simply tells local programs which different rendering engines are installed on the system and can be embedded into other programs.

Note: With some distributions, when launching the browser within Workplace Managed Client for the first time, the browser did not start successfully. After trying a second time to launch the client, however, the browser did launch successfully and continued to function correctly for each subsequent session. The IBM Redbooks team did not research this issue in depth, but we recommend that you launch the client a second time if you experience this behavior.

Appendix A. Installing IBM Workplace Managed Client on other Linux distributions 199

Appendix B. Ericom PowerTerm WebConnect for IBM Workplace

IBM recently announced the availability of Ericom PowerTerm WebConnect for IBM Workplace (see http://www.ericom.com). This product, developed specifically for IBM Workplace, provides access to applications running on Microsoft Windows Terminal Services, established systems, and Linux host servers from within IBM Workplace environment for both Linux and Windows desktops. In addition to a server component, the product includes a portlet and an IBM Workplace Managed Client plug-in. Both the portlet and the plug-in are supported on Linux and Windows desktops. For customers who are looking for migration options from Windows to Linux desktops, this technology can be a key factor to accelerate the adoption of Linux. Further benefits of using this technology come from centrally managed access and delivery of enterprise applications that lower the administration management requirements and operational costs of desktops systems and applications.

This appendix describes the features and functions of Ericom PowerTerm WebConnect for IBM Workplace. It also describes the integration options with IBM Workplace and the integration results from the end-user perspective. We assume that you have some familiarity with the IBM Workplace family of products (http://www.ibm.com/developerworks/workplace/products/).

B


http://www.ericom.com

http://www.ibm.com/developerworks/workplace/products/

IBM Workplace and Ericom enterprise-wide application access and delivery

IBM Workplace is an integrated family of collaborative capabilities that are based on open standards and delivered to users in a secure work environment. To access the installed capabilities of IBM Workplace, users can use a basic browser or IBM Workplace Managed Client. With these options, users can choose the most convenient access point to available resources, information, business applications, or other people, from anywhere and at any time.

Ericom PowerTerm WebConnect for IBM Workplace extends the number of applications that can be easily accessed from IBM Workplace through the browser and IBM Workplace Managed Client to include Linux, established applications, and Windows Terminal Services. Therefore, the combination of the IBM Workplace and Ericom PowerTerm WebConnect products provides centralized and enterprise-wide access to applications and services.

How Ericom PowerTerm WebConnect integrates with IBM WorkplaceOn the server side, Ericom PowerTerm WebConnect runs on both Windows and Linux, on x86, IBM POWER™ technology platforms (32-bit and 64-bit server platforms), and IBM Eserver zSeries® products. On the client side, it supports both Windows and Linux desktops.

Figure B-1 shows how IBM Workplace and the Ericom PowerTerm WebConnect server work together.

Figure B-1 Ericom PowerTerm WebConnect integration with IBM Workplace

WMC = Workplace Managed Client


Ericom PowerTerm WebConnect provides comprehensive and secure access to enterprise applications running on established systems such as IBM mainframe (zSeries), mid-range systems (iSeries), UNIX (pSeries), and others. In addition, Ericom PowerTerm WebConnect provides access to one or more Windows Terminal Services, which function as Windows application providers. Most Windows applications can be hosted on the terminal servers and made available for remote access. To enable the Ericom PowerTerm WebConnect server to access Windows Terminal Services, the Ericom Terminal Server Agent has to be installed on the Windows Terminal Services.

To integrate the Ericom PowerTerm WebConnect capabilities and make them available through a browser-based workplace, the PowerTerm WebConnect portlet needs to be installed on the IBM Workplace Collaboration Services server. Through the IBM Workplace administration console, this portlet is then made available to users who need access to remote Windows and host applications through the portal interface.

To make the Ericom PowerTerm WebConnect capabilities available through Workplace Managed Client, the PowerTerm WebConnect plug-in needs to be installed on the Workplace Collaboration Services server. Through the IBM Workplace administration console, this plug-in is then made available to users who need access remote Windows and host applications through the Workplace Managed Client interface (see Figure B-2).

Figure B-2 PowerTerm WebConnect Workplace Managed Client plug-in

The PowerTerm WebConnect client software and components are downloaded to the client and activated through a click the corresponding link. The client software itself is transparent to the user.

Appendix B. Ericom PowerTerm WebConnect for IBM Workplace 203

Workplace Managed Client-based PowerTerm WebConnect solutionYou can use the Workplace Managed Client installation running on Windows or Linux to access remote Windows and established applications. When you access your workplace through Workplace Managed Client for the first time after the Workplace Managed Client plug-in is added to the server configuration, the plug-in is provisioned to Workplace Managed Client. After a successful provisioning, a new icon representing to the Ericom PowerTerm WebConnect plug-in is added to the application switcher in Workplace Managed Client.

After successful plug-in provisioning, you are asked to provide your credentials to the PowerTerm WebConnect server. These credentials can then be automatically reused in future sessions.

When the connection to the PowerTerm WebConnect server is established, you are presented a list with all available applications, personalized to your role in the organization. From this list, you can select and launch applications (see Figure B-3).

Figure B-3 Application delivery through Workplace Managed Client

Browser-based Ericom PowerTerm WebConnect solutionIn addition to the Workplace Managed Client plug-in, Ericom PowerTerm WebConnect for IBM Workplace also provides a portlet that can be installed on the Workplace Collaboration Services server and used through a portal. Similar to the Workplace Managed Client plug-in, the PowerTerm WebConnect portlet provides access to the personalized list of connections. After the first successful


login to the PowerTerm WebConnect server, your credentials are stored securely on the IBM Workplace server. When you click a link of the application that you want to access, a separate window opens, providing access to that application (see Figure B-4).

Figure B-4 Application delivery through the browser-based IBM Workplace

Ericom PowerTerm WebConnect for IBM Workplace features

This section describes the key features and benefits of using Ericom PowerTerm WebConnect for IBM Workplace.

Access to established applicationsPowerTerm WebConnect for IBM Workplace enables centrally managed host access that supports a comprehensive range of more than 35 terminal emulation types, thus providing access to applications running on a wide variety of character-based host systems. For enhanced usability, PowerTerm WebConnect for IBM Workplace provides fully functional terminal emulation embedded in a browser, along with tools for enhancing the emulation page by adding graphics, colors, and links to automate various operations. Users benefit from the


simplicity of the Web browser, combined with the powerful capabilities of a complete terminal emulation package. Figure B-5 illustrates several PowerTerm WebConnect for IBM Workplace features.

Figure B-5 PowerTerm WebConnect for IBM Workplace features

PowerTerm WebConnect provides IBM Workplace with a secure access point to a wide range of hosts, including IBM mainframes (zSeries), iSeries, IBM AIX® 5L™ (pSeries), OpenVMS, UNIX, Linux, Tandem, HP-3000, and more. Host access features include:

� Support for more than 35 emulation types

� Multiple language support, including English, German, French, Spanish, Greek, and others

� Advanced security support (SSH and SSL protocols)

� Drag and drop keyboard mapping and advanced scripting functionality

� File transfer (secure FTP, AS/400 DFT, IND$FILE, Kermit, Zmodem, and others)

� Printer sessions, auto-print, host print transform, and more

� Power GUI for rejuvenating established applications with a three-dimensional look


� PowerPad and function bar for easy access to macros

� Graphical color selection and scalable fonts

� Administrative lockdown of any feature to prevent misuse

� Server-stored scripts and configurations

� Emulator High-Level Language Application Programming Interface (EHLLAPI)

Access to Microsoft Windows applications To provide access to Windows applications, the applications have to be deployed on a terminal server. Ericom PowerTerm WebConnect allows access to Windows Terminal Services 2000 and 2003 (32 and full 64 bit). Windows Terminal Services access features include:

� Support for true, seamless windows

� Local and remote printing options

� Improved performance and application load balancing

� Microsoft Active Directory and LDAP integration

� Remote desktop support that simplifies administration tasks

� Enhanced security with secure SSL gateway

� Single sign-on to the terminal server

Centralized administrationEricom PowerTerm WebConnect provides central administration capabilities. Using the browser-based administration console, administrators can easily manage servers, applications, sessions, and access control. Customized reports that detail user operations let you monitor and audit user activities. In addition, logging of all server operations simplifies server administration, maintenance, and support and enables monitoring and verifying server behavior.

To provide remote support to users having problems on their desktops, PowerTerm WebConnect provides remote desktop support and built-in instant messaging capabilities. Remote desktop support enables administrators to remotely view and control the entire user’s desktop. Built-in instant messaging enables users to communicate with support teams, including the ability to send screen captures. Both capabilities significantly simplify the administrator’s ability to resolve help desk and support issues.


Security aspects and single sign-onOn the server side, Ericom enables system administrators to restrict users to specific applications and to deliver applications only to the specific users or groups of users needing them. When accessing the Ericom PowerTerm portlet or the Workplace Managed Client plug-in, users are presented a personalized list of applications to which they are granted access. Users can activate an application by clicking the corresponding link, with no need to re-enter user name and password information. The appropriate client component is then provisioned to the desktop.

Ericom PowerTerm WebConnect leverages existing user repositories, such as LDAP and Active Directory, for authentication and user management. The PowerTerm WebConnect server forwards user credentials to the directory service for authentication. In addition, the PowerTerm WebConnect server can automatically forward user credentials to the terminal server.

Further security features include:

� Built-in SSL gateway provides the ability to tunnel Windows and established applications through secure transport.

� SFTP for secure file transfer enables SSH secured file transfer using the FTP protocol.

� SSH/SSL security can be used for secure terminal emulation sessions.

True, seamless windows Ericom PowerTerm WebConnect capabilities enable users to interact with all the windows within a single desktop, regardless of whether they are local or remote. The local task bar conveniently controls both local and remote applications. Local and remote applications look and behave identically (Figure B-6 on page 209).


Figure B-6 PowerTerm WebConnect windows

With the ability to use all applications in a familiar way, users are able to work more productively and intuitively, reducing user training requirements and support requirements. In addition, enterprises are able to maximize server resource utilization by running several applications over a single RDP connection.

PrintingEricom PowerTerm WebConnect supports the LPD/LPR protocol for managing remote printing from a host. PowerTerm WebConnect supports dynamic IP addresses, so even users who are behind a firewall, use DHCP, or connect through an Internet service provider, can use this printing solution.

Availability, performance, and scalabilityThe Ericom focus on availability, performance, and scalability is assured by the architecture and available features of PowerTerm WebConnect for IBM Workplace. Session reconnect enables interrupted sessions to resume from the exact point of interruption. Therefore, it is guaranteed that data previously entered by the user is not lost. This removes the necessity to log in again and re-enter data.

Ericom PowerTerm WebConnect for IBM Workplace can be configured to support thousands of concurrent sessions. Load balancing capabilities prevent server overloads and downtime. Constant system availability is assured by available fail-over capabilities.


SummaryEricom PowerTerm WebConnect for IBM Workplace extends browser-based and Workplace Managed Client-based IBM Workplace capabilities by providing a comprehensive ability to access Microsoft Windows and established applications. Therefore, this software supports the IBM Workplace strategy to provide a unified access to the applications, tools, and resources that users need to conduct their day-to-day business.

Furthermore, centralized administration aspects of the Ericom PowerTerm WebConnect product support the server-managed aspects that are propagated by the IBM Workplace platform. This combination guarantees the no-touch application deployment and provisioning for all enterprise applications and results in a simplified IT infrastructure management and reduced administration costs.

Ericom PowerTerm WebConnect for IBM Workplace is available for both Windows and Linux desktops, so it supports flexibility of choice regarding the desktop operating system that is provided by the IBM Workplace technology. Enterprises interested in introducing Linux on the desktop can use IBM Workplace in combination with the Ericom solution to allow all types of available applications (and new applications) to be deployed on Linux desktops, thus protecting investments in existing applications. This helps dramatically improve processes related to the migration to Linux desktops.


Appendix C. Additional material

This redbook refers to additional material that can be downloaded from the Internet as described in this appendix.

C


Locating the Web materialThe Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to:


Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks

Select Additional materials and open the directory that corresponds with the redbook form number, SG247208.

Using the Web materialThe additional Web material that accompanies this redbook includes the following file:

File name DescriptionWMCsource.zip Code sample for building sample application





Important: IBM DOES NOT WARRANT OR REPRESENT THAT THE CODE PROVIDED IS COMPLETE OR UP-TO-DATE. IBM DOES NOT WARRANT, REPRESENT OR IMPLY RELIABILITY, SERVICEABILITY OR FUNCTION OF THE CODE. IBM IS UNDER NO OBLIGATION TO UPDATE CONTENT NOR PROVIDE FURTHER SUPPORT.

ALL CODE IS PROVIDED “AS IS,” WITH NO WARRANTIES OR GUARANTEES WHATSOEVER. IBM EXPRESSLY DISCLAIMS TO THE FULLEST EXTENT PERMITTED BY LAW ALL EXPRESS, IMPLIED, STATUTORY AND OTHER WARRANTIES, GUARANTEES, OR REPRESENTATIONS, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF PROPRIETARY AND INTELLECTUAL PROPERTY RIGHTS. YOU UNDERSTAND AND AGREE THAT YOU USE THESE MATERIALS, INFORMATION, PRODUCTS, SOFTWARE, PROGRAMS, AND SERVICES, AT YOUR OWN DISCRETION AND RISK AND THAT YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGES THAT MAY RESULT, INCLUDING LOSS OF DATA OR DAMAGE TO YOUR COMPUTER SYSTEM.

IN NO EVENT WILL IBM BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES OF ANY TYPE WHATSOEVER RELATED TO OR ARISING FROM USE OF THE CODE FOUND HEREIN, WITHOUT LIMITATION, ANY LOST PROFITS, BUSINESS INTERRUPTION, LOST SAVINGS, LOSS OF PROGRAMS OR OTHER DATA, EVEN IF IBM IS EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THIS EXCLUSION AND WAIVER OF LIABILITY APPLIES TO ALL CAUSES OF ACTION, WHETHER BASED ON CONTRACT, WARRANTY, TORT OR ANY OTHER LEGAL THEORIES.

Appendix C. Additional material 213

Related publications

The publications listed in this appendix are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.

IBM RedbooksFor information about ordering these publications, see “How to get IBM Redbooks” on page 217. Note that some of the documents referenced here might be available in softcopy only.

� IBM Workplace Managed Client: ISV Integration Guide, REDP-4119

� IBM Workplace Collaboration Services: Release 2.5 Deployment Guide, SG24-6777

� Linux Client Migration Cookbook A Practical Planning and Implementation Guide for Migrating to Desktop Linux, SG24-6380

� IBM Workplace Client Technology Productivity Tools for IBM Lotus Workplace Documents 2.0.1, REDP-3947

Other publicationsThis publication is also relevant as a further information source:

� Scarpino, M., et al., SWT/JFace in Action: GUI Design with Eclipse 3.0, Manning Publications, 2004, ISBN 1932394273

Online resourcesThese Web sites and URLs are also relevant as further information sources:

� Linux at IBM

http://www.ibm.com/linux

� IBM Workplace products


� IBM Workplace Managed Client API Toolkit Version 2.6 User’s Guide



http://www.ibm.com/linux



� Using the Eclipse GUI outside the Eclipse Workbench, Part 1: Using JFace and SWT in stand-alone mode, IBM developerWorks article


� IBM Cloudscape product page


� More information about IBM Cloudscape


� IBM Cloudscape Information Center


� IBM Support Assistant


� Workplace Collaboration Services 2.6 Information Center


� WebSphere Application Server Information Center


� WebSphere Portal information center


� Eclipse framework


� Open Source Development Lab (OSDL) Desktop Linux

http://www.osdl.org

� Open Source Development Lab (OSDL) Desktop Linux Working Group


� Open Source Development Lab (OSDL) Member Roster page


� OASIS standards and ODF


� JSR 47: Logging API Specification


� java.util.logging API


� OSGi Alliance and the OSGi Service Platform



http://www.osdl.org
















� Mozilla Firefox browser


� Mozilla 1.4.3 release mirror site


� Information about the java.util.logging.Level specification


How to get IBM RedbooksYou can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site:

ibm.com/redbooks

Help from IBMIBM Support and downloads

ibm.com/support

IBM Global Services

ibm.com/services

Related publications 217



http://www.ibm.com/support/

http://www.ibm.com/support/

http://www.ibm.com/services/

http://www.ibm.com/services/





Index

Aaccess setting 65ActionTaskSave class 149Activity Explorer 4, 19, 45, 47, 173

application 47overview 45preference 47stores content 47view 47

Activity Explorer overview 45adding commands to menus and action bars 148adding fonts to IBM Workplace 122advanced office workstation 8Apache Derby 152

in-depth details 152application abstraction layers 14application development

framework 2platform 3tool 16

application support added by Workplace Managed Client 10applications available on Linux 8applications overview 20architectural overview of the Linux desktop solution using Workplace Managed Client 13attention indicators 24

Bbasic office workstation 7, 11benefits of a corporate Linux desktop 6build a sample application 1building a sample application for Workplace Man-aged Client 125Button searchButton 159

Ccalendar 27chat session 26, 154client application 19client installation introduction 90client-side interface 26

© Copyright IBM Corp. 2006. All rights reserved.

Collaborative Learning 60collecting Notes diagnostic data 193communicating selection changes in List View 146configuring a Workplace 2.6 server for Managed Cli-ent support 64configuring access to Managed Client applications 85configuring access to the Managed Client and set-ting policies 83configuring the browser for Java 91configuring the development environment 130confirming the features 188connecting to a Domino server 31connection URI 153contact name 145

label 154contributing to Workplace Managed Client action bars 150contributing to Workplace Managed Client menus 148core platform 15, 90cost saving 11creating a new toolkit project 131creating a runtime configuration 137creating domain objects 139creating the database 152creating the Detail View 144creating the List View 139

Ddate and time stamp 188Debian Testing

installing Workplace Managed Client on Debian Testing 64, 195

default JVM 137deploying the sample application 161desktops system 201

operational costs 201Detail View 139, 144

following code 147property change events 147saving tasks 146

devel package 197

219

DisposeEvent e 161document formats 118document library 3, 23, 43, 84, 113, 127, 170

working 51documents 51download link 13, 83

Managed Client 91

EEclipse framework 16Eclipse update site and installer executable 66Electronic Service Request (ESR) 181e-mail address 154embedded browser 59Emulator High-Level Language Application Pro-gramming Interface (EHLLAPI) 207end-to-end Linux client/server environment 12end-user spam 23Ericom PowerTerm WebConnect 202

capability 203leverage 208product support 210server 203

export data 118extension services layer 17external application 60external applications 60

Ffiner-grained control 85, 90full-featured office desktops 12

Ggeneric contributions layer 16generic UI components 17GridData gd 145GridUtils.make label 145GridUtils.setLayoutData 145

Hhigh-level architectural overview 13home directory 20, 97, 163HTTP server 67

IIBM Cloudscape

database 151

IBM JRE 92IBM productivity tools 3, 51, 113, 187

default format 120detailed discussion 51

IBM productivity tools native format 120IBM Support 165, 170

new problem record 184problem tickets 181

IBM Support Assistant data collector 182IBM Support Assistant ESR link 184IBM Support Assistant FTP interface 185IBM Support Assistant Search component 175IBM Support Assistant Service component 181IBM Support Assistant Support Links component 180IBM Workplace ix, 1–2, 19–20, 67, 113–114, 127, 165, 195, 201

2.6 API Toolkit 21administration 203API Toolkit 27Client Technology platform 152Client Technology Productivity Tool 117Collaboration Service 5, 78, 127Collaboration Services content 72Collaborative Services server 26Collaborative Services system administrator 21Documents 53, 57Documents library service 51environment 201Ericom PowerTerm WebConnect 202Ericom PowerTerm WebConnect server 203family of products 5, 201feature 205functionality 59installed capabilities 202Instant Messaging service 40integration options 201Managed Client 2, 21, 116, 127, 165, 202Managed Client 2.6 55, 122Managed Client account name 191Managed Client application 61Managed Client bundle 180Managed Client document library 43Managed Client documents functionality 51Managed Client help 177Managed Client interface 43Managed Client productivity tool 3Managed Client side 192Managed Client Tool 130


Managed Client trace setting 193platform 210plug-in, Ericom PowerTerm WebConnect 204Portal 196PowerTerm WebConnect 201product 170product family 174product functionality 59product team 169productivity tools editors 54SDK 131server 205software 84software development kit 131strategy 210technology 210user 174

IBM Workplace Managed Client ix, 2, 20, 94, 113, 127, 165IBM Workplace Managed Client and the Linux desk-top 1IBM Workplace Managed Client applications 19ILiveNameListener 157import plugin 150Inbox 22increasing the allowed number of open files 93inline creation 113install an IDE 130install the base platform 94install the IBM Workplace Managed Client Tool 131install the Managed Client 131installation and configuration 1installation and configuration of Workplace Man-aged Client 2.6 on Linux 63installation process 68installing the Managed Client 90instant messaging 26instant messaging (IM) 3, 21, 130, 172introduction to Workplace Managed Client on Linux 1

JJava runtime environment (JRE) 14, 92Java Specification Request (JSR) 166JDBC driver 154

KKDE directory 116

key features of the sample application 129

Llaunching the IBM productivity tools 114linking views 146Linux client

environment 1strategy 1

Linux desktop 5, 8, 91Lotus Notes applications 10use Workplace Managed Client 10

Linux desktop classifications 6Linux distribution 195Linux on the desktop today 5Linux platform 4, 20, 63, 123

complete Notes experience 45font installation process 123

Linux system 5, 123ongoing success story 5

Linux workstation 5, 91different frequent deployment 5different types 6

List View 139communicating selection changes 146plug-in 147register 147

live name support 154live names and instant messaging integration 154log file 77, 166logging 166logging and tracing for the Notes plug-in 192logging and tracing in Workplace Managed Client 2.6 166login server 103Lotus Notes 19

Mmail 22mail threading 23, 25main window 128Managed Client 19, 63, 113, 125

application layer 20particular installation 111preload facility 110

manually remove the files 110messaging applications 21Microsoft Excel 121Microsoft Office

Index 221

data format 8document format 113file format 120file type 115form field 121format 120format document 118license 6template 122user interface 8

Microsoft Office formats 120Microsoft PowerPoint 121

document 121template 121

Microsoft WindowsTerminal Services 201

Microsoft Word 121model view controller (MVC) 143Mozilla 1.4.3

core 59installation 196release 196

NNotes plug-in 30NOTES.INI parameter 192

OOASIS OpenDocument Format 119offline support 2, 23OLE object 121online awareness 25online/offline status 130Open Source Development Lab (OSDL) 5open standard (OS) 6, 113, 202OpenDocument Format (ODF) 3, 54, 113OS resource 161

Ppersistent chat 45–46

multiple members 46persistent chats 50personal information manager (PIM) 9plug-in 30, 92, 139, 170

src folder 142Plug-in Development

Environment 135

Tool 131plug-in start 32png file 56Portal Content Management (PCM) 53portal pages 65portlet 65, 201post-installation tasks 105PowerTerm WebConnect 8, 201

available features 209client software 203plug-in needed 203portlet 203product 202server 202window 209Workplace Managed Client 202

prerequisites 66, 91presence awareness 127private void

contributeToRealActionBars 151createChangeButton 159createChatButton 159createColumns 143createDisposeListener 161createLiveNameLabel 158createLiveNameListener 157makeActions 151refreshLiveNameLabel 160

product plug-in 182productivity tool

small portion 187productivity tools 2, 43, 113, 187

default templates 122main problem determination data 187

project workflow 51many types 51

provision the client. 100public void

createControls 145notifyListeners 147propertyChange 147run 149setUser 160widgetDefaultSelected 159widgetSelected 159

RRCP recovery utility 190


RCPML document 182Redbooks Web site 217

Contact us xiremove the files 110rich client

access 85application 2, 130check box 84technology 2

Rich Client Platform Markup Language (RCPML) 64–65running the IBM Support Assistant collector manual-ly 186

Ssample application 125, 128, 212

public APIs 125saving tasks from Detail View 146saving tasks to the database 151SCI

what is 64SCI setup summary 78SCI uninstaller 79

component selection 80sel.getFirstElement 146SelectionEvent arg0 159server client installer (SCI) 64Session Initiation Protocol (SIP) 26shared file 46, 49shared files 49shared folders 48shared note 49shared object 45

awareness information 46shared snapshot 49shared snapshots 49side effect 155single sign-on (SSO) 127software development kit (SDK) 131SSL certificate 104standard calendaring 27Standard Widget Toolkit (SWT) 14summary 194Sun JRE 92superuser 69, 123supported platforms 91SWT control 154SWT.DEFA ULT 145

SWT.SING LE 144Synchronized Multimedia Integration Language (SMIL) 120system expertise 7

TTask val 147TCP/IP address 31team spaces 10, 19–20, 57technical workstation 7, 11template support 122test the development environment 135toolbar activity 187total cost of ownership (TCO) 5–6tracing 170transactional workstations 7, 11troubleshooting IBM Support Assistant 186troubleshooting IBM Workplace Managed Client 165troubleshooting provisioning 188troubleshooting the Notes plug-in 192troubleshooting the productivity tools 187

UUbuntu 5.10

installing Workplace Managed Client 64, 195UI element 38uninstalling the Managed Client 106uninstalling the SCI 79UNIX purist 69user interface (UI) 174using the Activity Explorer 47using the IBM Support Assistant for self-help and data collection 173using the uninstaller 106

WWeb browser 3, 19, 206, 212Web Conferencing 19, 60–61WebSphere Application Server

administration 83configuration 74platform 67

WebSphere Portal 65configuration dialog box 78content 72Content Publishing store 53

Index 223

Document Manager Web interface 116working with document libraries 51working with documents 54working with the Notes plug-in 35Workplace administrator 81Workplace Collaboration Services 67

2.5 602.6 662.6 server 66server 66, 127, 203

Workplace Collaboration Services 2.6 server 66Workplace Learning 90Workplace Managed Client 1, 19, 63, 125, 151, 195, 201

action bar 150application 151application switcher 204database driver 153first start 32framework 15installation 204interface 203menu 148packaging applications 128platform 125plug-in 208support 63what is 2

Workplace Managed Client framework 15Workplace Managed Client in the desktop segments 11Workplace Managed Client on a Linux desktop

why use 10Workplace Managed Client platform 127

XXML files 173


(0.2”spine)0.17”<

->0.473”

90<->

249 pages

IBM W

orkplace Managed Client 2.6 on Linux

®

SG24-7208-00 ISBN 0738497355

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICALINFORMATION BASED ONPRACTICAL 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


IBM Workplace Managed Client and the Linux desktop

Installation and configuration information

Build a sample application

With IBM Workplace Managed Client Release 2.6 on Linux, IBM offers a strategic end-to-end Linux solution that provides both the benefits of Linux and IBM Workplace Collaboration Services. This IBM Redbook provides a technical overview of IBM Workplace Managed Client and examines why it is a smart, strategic choice. In addition, we provide a detailed description and best practices for deploying, installing and configuring the product.

We focus on the following topics:� Benefits and positioning of a Linux client. Why Workplace

Managed Client on Linux?� Overview of the product features and functionality.� Technical and architectural overview of the client.� Description of how to install the client on Red Hat

Enterprise Linux and other Linux distributions.� Possibilities and benefits for an end-to-end Linux

solution (IBM Workplace server and IBM Workplace Managed Client on Linux).

� Example of a sample application and customization based on the underlying Eclipse framework.

Back cover


