RDB Synchronization, Transcoding and LDAP Directory Services ...

Front cover

RDB Synchronization, Transcoding
and LDAP Directory Services in
IBM WebSphere Everyplace Access
Version 4.1.1
Synchronize DB2 Everyplace data with
back-end DB2 and Oracle databases

Adapt portlet content using
Transcoding Technologies

Integrate WebSphere Portal
with existing LDAP services

Juan R. Rodriguez
Gregory Mebberson
LindaMay Patterson
Gianfranco Rutigliano
Luo Yuan Zhi (Anna)

ibm.com/redbooks

International Technical Support Organization

RDB Synchronization, Transcoding and LDAP
Directory Services in IBM WebSphere Everyplace
Access Version 4.1.1

November 2002

SG24-6856-00

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

First Edition (November 2002)

This edition applies to Version 4, Release 1, Modification 1 of IBM WebSphere Everyplace
Access for Multiplatforms.

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

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Part 1. Database synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Synchronizing with DB2 databases . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Architecture overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1 DB2 Everyplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.2 IBM Everyplace Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.3 Secure Proxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.4 DB2 Everyplace Sync Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 Before you start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.1 Creating users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.2 Creating subscription and subscription set . . . . . . . . . . . . . . . . . . . . 12
1.4 Binding LDAP and MDAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.5 Client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.6 Sample application synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.7 Verify the synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
1.8 Synchronization using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
1.8.1 Enable server security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
1.8.2 Enable client security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
1.9 Synchronization with remote DB2 databases . . . . . . . . . . . . . . . . . . . . . . 43
1.10 Sync modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
1.11 Types of subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
1.11.1 DataPropagator subscription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
1.11.2 Upload subscription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
1.12 Filtering data from data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
1.13 Debug and tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
1.13.1 Enable tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
1.13.2 Trace files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
1.13.3 DB2 Everyplace control database . . . . . . . . . . . . . . . . . . . . . . . . . . 61
1.14 Hints and tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
1.15 About Mobile Application Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

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

Chapter 2. Synchronizing with Oracle databases . . . . . . . . . . . . . . . . . . . 63
2.1 Common grounds with DB2 data source. . . . . . . . . . . . . . . . . . . . . . . . . . 64
2.2 Create a subscription with Oracle data source . . . . . . . . . . . . . . . . . . . . . 65
2.2.1 Add Oracle JDBC driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
2.2.2 Create a JDBC subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
2.2.3 Create an upload subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
2.3 Sample dsysetjavahome.bat file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
2.4 Synchronize with remote Oracle database . . . . . . . . . . . . . . . . . . . . . . . . 79
2.5 Hints and tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Part 2. Transcoding Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 3. Transcoding Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.1 Transcoding Technologies overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
3.1.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.1.2 Preference profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.1.3 XML stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.1.4 Annotators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.1.5 Transcoding plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
3.2 XMLConfig tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.3 Request Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.3.1 How to start Request Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
3.4 Logging and tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
3.4.1 Message files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
3.4.2 Tracing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3.4.3 Gather troubleshooting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3.5 A simple portlet using Transcoding Technologies . . . . . . . . . . . . . . . . . . . 97
3.5.1 Enable transcoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
3.5.2 Use Request Viewer to monitor the process . . . . . . . . . . . . . . . . . . 105

Chapter 4. Using annotation for document clipping . . . . . . . . . . . . . . . . 107
4.1 Annotation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.1.1 Annotation processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.2 Internal annotation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.2.1 Page Designer in WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . 110
4.2.2 Sample application: The Redbook News . . . . . . . . . . . . . . . . . . . . 110
4.3 External annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
4.3.1 The external annotation language. . . . . . . . . . . . . . . . . . . . . . . . . . 119
4.3.2 Sample scenario: RedbookNews02 . . . . . . . . . . . . . . . . . . . . . . . . 120

Chapter 5. Using XSL stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
5.1.1 Configuring stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
5.2 Configure portal for stylesheet processing . . . . . . . . . . . . . . . . . . . . . . . 131

iv RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1

5.3 Sample one: XML Feed. . . . . . . . . . . . . . . . . . ...... ....... ...... . 132
5.3.1 Configuring the XMLFeed portlet . . . . . . ...... ....... ...... . 134
5.3.2 An alternative - Register the stylesheet . ...... ....... ...... . 135
5.4 Sample scenario 2 - ITSO News XML Feed . . ...... ....... ...... . 136
5.4.1 Sample stylesheets . . . . . . . . . . . . . . . . . ...... ....... ...... . 138

Chapter 6. Portal-level transcoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.1.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
6.1.2 Fragmentable elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.1.3 Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.1.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.2 WML fragmentation in Transcoding Technologies . . . . . . . . . . . . . . . . . 150
6.2.1 Scenario 1: Using a WAP reverse proxy . . . . . . . . . . . . . . . . . . . . . 151
6.2.2 Scenario 2: Using a forward proxy . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.2.3 Scenario 3: Using a forward proxy and reverse proxy . . . . . . . . . . 157

Part 3. LDAP Directory services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace
Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
7.1 Solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.1.1 Specifications for the sample scenario . . . . . . . . . . . . . . . . . . . . . . 163
7.2 Installing IBM SecureWay Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.3 Installing WebSphere Everyplace Access . . . . . . . . . . . . . . . . . . . . . . . . 165
7.4 Sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
7.4.1 Configuring the LDAP Search portlet . . . . . . . . . . . . . . . . . . . . . . . 169
7.4.2 Using IBM DB2e with a remote SecureWay Directory server . . . . . 171
7.5 Recommendations, hints and tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Chapter 8. iPlanet Directory services in WebSphere Everyplace Access . .
185
8.1.1 Specifications for the sample scenario . . . . . . . . . . . . . . . . . . . . . . 187
8.2 Installing and configuring iPlanet Directory . . . . . . . . . . . . . . . . . . . . . . . 187
8.2.1 Installing iPlanet Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
8.2.2 Configuring iPlanet for WebSphere Everyplace Access . . . . . . . . . 189
8.4.1 Configuring the LDAP Search portlet . . . . . . . . . . . . . . . . . . . . . . . 196
8.5 Recommendations, hints and tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Chapter 9. Active Directory services in WebSphere Everyplace Access201
9.1 Active Directory overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Contents v

9.2.1 Specifications for the scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
9.3 Installing and configuring Active Directory . . . . . . . . . . . . . . . . . . . . . . . 203
9.3.1 Installing Windows 2000 support and administration tools . . . . . . . 205
9.3.2 Verifying Active Directory server installation . . . . . . . . . . . . . . . . . . 206
9.3.3 Configuring Active Directory for WebSphere Everyplace Access . . 208
9.3.4 Obtaining the LDAP schema for Active Directory . . . . . . . . . . . . . . 213
9.5.1 Creating users and groups in WebSphere Everyplace Access. . . . 223
9.5.2 DB2 Everyplace synchronization using Active Directory. . . . . . . . . 226
9.5.3 Configuring the client on the Pocket PC and synchronizing . . . . . . 232

Chapter 10. Domino Directory services in WebSphere Everyplace Access
237
10.1 Lotus Domino R5 overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
10.2 Solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
10.2.1 Specifications for the scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
10.2.2 Users and groups required in this scenario. . . . . . . . . . . . . . . . . . 240
10.3 Setting up Domino Directory services . . . . . . . . . . . . . . . . . . . . . . . . . . 241
10.3.1 Installing Lotus Domino server . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
10.3.2 Installing and configuring the Domino Administration client . . . . . 248
10.3.3 Configuring LDAP services on Domino . . . . . . . . . . . . . . . . . . . . . 252
10.3.4 Obtaining the LDAP schema for the Domino server . . . . . . . . . . . 258
10.4 Installing WebSphere Everyplace Access . . . . . . . . . . . . . . . . . . . . . . . 259
10.5 Sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
10.5.1 Creating users in WebSphere Everyplace Access . . . . . . . . . . . . 265
10.5.2 Configuring the LDAP Search portlet . . . . . . . . . . . . . . . . . . . . . . 268

Appendix A. WebSphere Everyplace Access sample installation . . . . . 271
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
10.6 Server installation verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
10.7 Client installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
10.8 Hints and tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Appendix B. Sample Oracle Enterprise Edition installation . . . . . . . . . . 323
Oracle installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Create a simple database using wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Create simple table using wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Populate table with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

vi RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1

Other resources . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 349
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 349
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . ...... ....... ...... . 350
IBM Redbooks collections . . . . . . . . . . . . . . . . . ...... ....... ...... . 350

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Contents vii

viii RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1

Notices

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

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

IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

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

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

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

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

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

COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the
sample programs are written. These examples have not been thoroughly tested under all conditions. IBM,
therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to IBM's application
programming interfaces.

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

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

Redbooks(logo)™ Everyplace™ RETAIN®
AIX® IBM® SecureWay®
DataPropagator™ Informix® SP™
DB2® iSeries™ Tivoli®
DB2 Universal Database™ Redbooks™ WebSphere®

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

Lotus® Lotus Notes®
Domino™ Notes®

The following terms are trademarks of other companies:

ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United
States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.

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

C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both.

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

SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure
Electronic Transaction LLC.

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

x RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1

Preface

This redbook will help you plan, install and implement Relational Database
Synchronization (RDB) with back-end databases such as DB2 and Oracle using
the JDBC interface, Transcoding Technologies and LDAP services, using
Lightweight Directory Access Protocol (LDAP) directories such as IBM
SecureWay Directory, iPlanet, Microsoft Active Directory and Domino LDAP
Directory services in IBM WebSphere Everyplace Access Version 4.1.1.

A step-by-step sample installation is also included to show you how to install this
product to support connections using a Pocket PC. Hints and tips are also
included where applicable.

A basic knowledge of Lightweight Directory Access Protocol (LDAP), IBM
SecureWay Directory Server, DB2 Everyplace, DB2 or Oracle databases, IBM
HTTP Server, IBM WebSphere Application Server, IBM WebSphere Portal,
Pocket PC, Windows CE, WAP devices and Transcoding Technologies is
assumed.

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

Juan R. Rodriguez is a Consulting IT professional at the IBM
ITSO Center, Raleigh. He received his Master of Science
degree in Computer Science from Iowa State University. He
writes extensively and teaches IBM classes worldwide on such
topics as networking, Web technologies, and information
security. Before joining the IBM ITSO, he worked at the IBM
laboratory in the Research Triangle Park (North Carolina, USA)
as a designer and developer of networking products.

Gregory Mebberson is a software developer in IBM Global
Services in Sydney, Australia. He has seven years of
experience in developing customer solutions using Lotus Notes
and other applicable technology, and has a Bachelor of Applied
Science from Chisholm Institute of Technology, Melbourne,
Australia. He has co-authored several IBM Redbooks.

© Copyright IBM Corp. 2002. All rights reserved. xi

LindaMay Patterson is an Advisory Software Engineer in the
eServer Custom Technology Center (eCTC) in IBM Rochester,
Minnesota. She has 28 years of experience within IBM working
with various software products to create business application
solutions. She is currently working with the Enterprise Segment
Strategy Team in the Pervasive Computing Division. Her
current focus is on Pervasive Computing, XML, and related
technologies. Prior to joining the eCTC, she worked in Partner
World for Developers - iSeries creating educational material on
various topics and helping ISVs incorporate new technology in their solutions.

Gianfranco Rutigliano holds a degree in Systems
Engineering from the University of Lima (Peru) and is a
member of the Application Management Services (AMS) group
in IBM Global Services working with e-business projects and
related Internet technologies. He has worked with
e-marketplace and home-banking implementation systems
using Java technologies. Currently he is involved in wireless
application solution projects using PDAs.

Luo Yuan Zhi (Anna) is an Advisory IT Specialist from the
Emerging Technology Center in IBM Singapore. She has eight
years of experience in the telecommunications and IT fields.
Her current area of expertise is centered around Web
technologies and Pervasive Computing. She holds a
Bachelor’s degree (with honors) in Control and
Communication Engineering from University of Manchester
Institute of Science and Technology (UMIST), United
Kingdom, and a Master of Science degree in Computer
Engineering from the University of Singapore.

Thanks to the following people for their contributions to this project:

Margaret Ticknor
International Technical Support Organization, Raleigh Center

James Thrasher, Alan Booth, Laurie Bader, Charlene Frazier, Curtis Ebbs
IBM Research Triangle Park, Nort Carolina, USA

Al Chakra, Darren M. Childress, Jim Brancato, Charlene Frazier
IBM Research Triangle Park, North Carolina, USA

Casey Paxton
IBM Austin, Texas, USA

xii RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1

Isaac Cheng, Garner Lee
IBM Santa Teresa, California, USA

May Wone
IBM San Jose, California, USA

Charles Ackeifi
CourtBridge Consulting Group, Connectitut, USA

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

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

Find out more about the residency program, browse the residency index, and
apply online at:
ibm.com/redbooks/residencies.html

Comments welcome
Your comments are important to us!

We want our 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 Internet note to:
redbook@us.ibm.com
Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195

Preface xiii

xiv RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1

Part 1

Part 1 Database
synchronization
DB2 Everyplace is a small-footprint relational database and enterprise
synchronization architecture for mobile and embedded devices that includes the
following:
Supports any JDBC-compliant database
DB2, Oracle, Microsoft SQL, Informix, Sybase
WBXML encoded datastream
SyncML-like interface
Secure Sockets Layer (SSL) capability
On-demand synchronization
Integrated into IBM Everyplace Client
DB2 Everyplace Client-side programming interfaces available
User administration and access controls integrated into WebSphere
Everyplace Access

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

In this part we describe the DB2 Everyplace synchronization function available in
IBM WebSphere Everyplace Access V4.1.1.

2 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1

1

Chapter 1. Synchronizing with DB2
databases
This chapter describes the configuration steps necessary to carry out DB2
Everyplace Synchronization with back-end DB2 databases. The following topics
are covered:
Overview
DB2 Everyplace Synchronization Server configuration
Everyplace Client configuration
Sample application scenario
Synchronize with remote databases
Hints and tips

Note: In this chapter, the root directory that WebSphere is installed to is
referred to as “WebSphere_Install_Dir”. It should be replaced by the actual
directory name in real cases.


1.1 Architecture overview
The diagram shown in Figure 1-1 depicts the relational database synchronization
environment for JDBC subscription types.

Replication
JDBC JDBC
DB2e Sync Server
source database
WebSphere Application Server (DB2)

mirror
database
(DB2) DB2 database
(LDAP data)
DB2e Sync LDAP
JDBC
WebSphere Directory
Server
Portal Services
(servlet) Users and
Groups

WebSphere Application Server Subscription
set and
IBM HTTP Server DB2 Everyplace Subscriptions
Mobile Devices
m23vnx78.itso.ral.ibm.com Administration
Synchronization Port 80
Basic Authentication
Center (MDAC) JDBC subscription
DB2 source database
SSL (optional)

Everyplace Client

Secure 127.0.0.1 DB2e Sync
proxy
Port 1080

DB2e database
Pocket PC

Figure 1-1 DB2 Everyplace synchronization for JDBC subscriptions

The hand-held device sits on the IBM Everyplace Client, which is the unified
client for PIM and relational database synchronization. The unified client has a
component called Secure Proxy, which is transparent to the user. Secure Proxy
handles user authentication and data encryption between the client and the Web
Server.

On the server side, IBM HTTP Server handles incoming HTTP requests, and
passes those destined for WebSphere Application Server via a plug-in.
WebSphere Portal rides on top of the WebSphere Application Server. It provides
administration portlets to manage portlets as well as users and groups. User and
group information is stored within LDAP.


Also on the server, DB2 Everyplace periodically replicates the back-end
databases to mirror databases; this process for JDBC subscription type is also
illustrated in Figure 1-1 on page 4. DB2 Everyplace Mobile Devices
Administration Center or MDAC, together with WebSphere Portal, provide the
complete administration functionalities for DB2 Everyplace Sync Server. MDAC
stores its configuration information in a DB2 database.

When synchronization is initiated at the client, the request is passed to Secure
Proxy on the mobile device. Secure Proxy sends the request to IBM HTTP
Server and, optionally, through SSL. Secure Proxy also takes care of the
authentication required by WebSphere Application Server. The user is
authenticated against the user registry in LDAP. Once the user is authenticated,
DB2 Everyplace Sync Server is invoked and data synchronization is carried out
between the client and the mirror databases.

1.1.1 DB2 Everyplace
DB2 Everyplace consists of two main components:
DB2 Everyplace database
DB2 Everyplace Sync Server

DB2 Everyplace is the database engine installed on the mobile device. DB2
Everyplace Sync Server carries out bi-directional synchronization of data
between the database on the mobile device and the source database on the
server.

For synchronization of the relational database from the server to the mobile
device, the selected data is replicated periodically to a mirror (or mid-tier)
database, which acts as a temporary repository for the data. A subset of the
mirror data is moved to the database on the mobile device. On the other hand,
for synchronization from the mobile device to the server, data is also moved into
the mirror database first, then gets replicated to the server periodically.

DB2 Everyplace synchronization is controlled by DB2 Everyplace Sync Server,
which has been integrated into WebSphere Everyplace Access’ Everyplace
Synchronization Server.

In order to set up synchronization, the following entities must be defined
beforehand:
Group
User
Subscription set
Subscription

Chapter 1. Synchronizing with DB2 databases 5

A user must belong to a group. A subscription must belong to at least one
subscription set. A group subscribes to one or more subscription sets for data
synchronization.

1.1.2 IBM Everyplace Client
IBM Everyplace Client is an unified client application package for Personal
Digital Assistants (PDAs). Everyplace Client provides a common interface that
supports synchronization, security, device management, offline Portal content,
offline Domino applications, and DB2 Everyplace database synchronization.

Note: DB2 Everyplace Sync client is part of the Everyplace unified client.

1.1.3 Secure Proxy
Everyplace Client relies on the Secure Proxy for authentication and encryption.
Stand-alone DB2 Everyplace used MD5 for authentication. In WebSphere
Everyplace Access, MD5 is disabled and the Secure Proxy takes over the
responsibility. Everyplace Client supports SSL for encryption.

Everyplace Client is also capable of storing and sending LTPA tokens.

1.1.4 DB2 Everyplace Sync Server
DB2 Everyplace Sync Server has been integrated into WebSphere Everyplace
Access. It is deployed in WebSphere Application Server as a Web module
containing several servlets.

DB2e Sync Server is HTTP based. Mobile devices can establish either a wireless
or wired connection to synchronize data over the Internet, a wireless network,
intranet, local area network (LAN), or wide area network (WAN).

1.2 Before you start
Before you start configuring and testing relational database synchronization, it is
important to make sure IBM DB2 Everyplace Server and Everyplace
Synchronization Server are running without error. Do the following:
1. Open WebSphere Application Server’s Administrative Console by clicking
Start -> Programs -> IBM WebSphere -> Application Server V4.0 ->
Administrator’s Console.


2. When the console is ready, make sure IBM DB2 Everyplace Server and
Everyplace Synchronization Server are running and there are no error
messages in the Event Message window.
3. To verify the DB2 Everyplace Sync servlet is running, open a browser and
type the following into the address box:
http://hostname/db2e/db2erdb
Enter the login information when prompted. You should see the page shown
in Fig 1-3 which displays information about the sync servlet.

Figure 1-2 DB2 Everyplace sync servlet

If you see this page, you are ready to proceed.
4. If this page is not shown, check the following:
a. Check whether the following file is present:
WebSphere_Install_DirIBMSyncServerdb2eServerlibdsysync.jar
b. In WebSphere Application Server Administrative Console, click IBM DB2
Everyplace Server. In the right pane, click the JVM Settings tab. Check
the classpaths and make sure you have this line in the classpaths:
WebSphere_Install_DirIBMSyncServerdb2eServerproperties


Figure 1-3 Check DB2 Everyplace Server’s classpaths

1.3 Server configuration
For relational database synchronization, the server configuration and
management activities are handled at two places: user and group management
is done in WebSphere Portal, while subscription and subscription sets are
managed by the Mobile Devices Administration Center (MDAC).

1.3.1 Creating users and groups
Everyplace Synchronization Server supports multiple synchronization groups.
Synchronization groups must be created using WebSphere Portal’s
administration portlets. A user must be a member of a synchronization group in
order to synchronize with the DB2 Everyplace Sync Server. When these
synchronization groups are in use, their names are stored in the file
DSYLDAP.properties, located at:

WebSphere_Install_Dir/IBMSyncServer/db2e/Server/properties/com/ibm/mobile
services


Under the key “SYNCGROUP”.

To use the relational database adapter, a special user and group configuration is
required:
Each group must have a prefix of DB2e (case-sensitive), such as
DB2e_myemployees.
DB2e groups should not be members of any synchronization group defined in
the DSYLDAP.properties file.
Relational Database synchronization users must be a member of one of the
synchronization groups defined in the DSYLDAP.properties file.
Relational Database synchronization users must also be a member of one
group that begins with DB2e.
Relational Database synchronization users can belong to only one DB2e
group, but the user may belong to other groups in the Portal environment
including other synchronization groups.

The following steps demonstrate how to create groups and users for relational
database synchronization:
1. To create a synchronization group:
a. Click Start -> Programs -> IBM Everyplace Synchronization Server ->
Administration Portlet.
b. Log in to the WebSphere Portal as an administrator, for example,
wpsadmin.
c. Select the Portal Administration page group.
d. Select the Users and Groups page.
e. Select the Manage User Groups tab.
f. Enter the synchronization group name in the Group Name field, for
example, SyncGroup
g. Click Create Group.


Figure 1-4 Create synchronization group

The group should be created and appear in the User Groups field.
h. Follow similar steps to create more synchronization groups.

Important: The IBM DB2 Everyplace Server uses the group “SyncGroup” by
default. If you choose to use a different name, for example “AllSyncUsers”,
you will need to start up MDAC using your synchronization group, and then
restart the IBM DB2 Everyplace Server.

The group name can be confirmed by looking at the last line of the following
file:

WebSphere_Install_DirIBMSyncServerdb2eServerpropertiescomibmmob
ileservicesDSYLDAP.properties

For example: SYNCGROUP=AllSyncUsers

We recommend having a parent synchronization group that contains all
synchronization users, and to use this group when starting MDAC.


After creating the desired synchronization group(s), users who are expected to
synchronize with the database(s) must be added to the synchronization group(s).
2. To add users to synchronization group(s):
wpsadmin.
f. Search to find the synchronization group.
g. Select the synchronization group.
h. Click Membership.
i. Select Add users to group.
j. Use the Name is field to search for users.
k. Select the user(s) to add from the Search Results field.
l. Click Add to group.

As mentioned earlier, relational database synchronization users must belong to
both synchronization group(s) and DB2e groups (relational database adapter
group).
3. To create a relational database adapter group:
wpsadmin.
f. Enter the synchronization group name in the Group Name field, for
example, DB2e_employee.

Note: The group name must begin with DB2e (case sensitive).

g. Click Create Group.


Tip: After adding or removing users to a DB2e group, we recommend
resetting that user in MDAC.

4. To add users to relational database adapter group(s):
wpsadmin.
f. Search to find the synchronization group.
g. Select the synchronization group.
h. Click Membership.
i. Select Add users to group.
j. Use the Name is field to search for users.
k. Select the user(s) to add from the Search Results field.
l. Click Add to group.

Note: For relational database synchronization to work, user(s) must exist
in both synchronization group(s) and one relational database adapter
group.

1.3.2 Creating subscription and subscription set
Synchronization-related information for a relational database is defined as a
subscription. Subscriptions are grouped into subscription sets that the user
groups can subscribe to. We have our users and groups, so now we must define
the necessary subscriptions and subscription sets to make the synchronization
work.
1. To create a subscription:
Launch MDAC.
The DB2 Control Center will automatically open. As the MDAC retrieves
the users and groups information from LDAP, a WPS LDAP Logon window


pops up and asks for the necessary information to retrieve data from
LDAP (see Figure 1-5).
Enter the LDAP administrator’s user name and password, and specify the
synchronization groups defined through WebSphere Portal. We suggest
having a parent group that contains all synchronization users, However
multiple synchronization groups may be entered, separated by
semicolons. Click OK.

Figure 1-5 WPS LDAP Logon window

The Mobile Devices Administration Center launches.


Figure 1-6 MDAC

b. Click the Groups and Users folders to check that the DB2e group(s) and
user(s) are imported into the MDAC.
c. Right-click Subscription -> Create -> Table Subscription -> JDBC
Subscription....

Note: JDBC Subscription is used in this scenario. Other types of
subscription will be covered in later sections.

The Create JDBC Subscription wizard opens.


Figure 1-7 Create JDBC Subscription wizard

d. Enter the name of the subscription and, optionally, a description. Click the
Source tab.
e. In this tab, the source database information should be provided.
i. In the Database URL field, enter the source database URL, for
example, jdbc:db2:VNURSE. Or you can also use the ... button besides
this field to browse and choose the source database.
ii. In the Driver field, use the down arrow to choose the desired JDBC
driver from the list.
iii. In the User ID field, provide the user ID that can be used to access this
database.
iv. In the Password and Verify Password fields, enter the password.
v. You can click Test Connection to verify the connection to the
database.
vi. When done, click the Mirror tab.


Figure 1-8 Create JDBC Subscription - define source database

f. In this tab, the mirror database information should be provided.
i. In the Database URL field, enter the mirror database URL, for example,
jdbc:db2:M_VNURSE. Or you can also use the ... button besides this
field to browse and choose the source database.
ii. In the User ID field, provide the user ID that can be used to access this
database.
iii. In the Password and Verify Password fields, enter the password.
iv. You can click Test Connection to verify connection to the database.
v. When done, click the Identification tab.


Figure 1-9 Create JDBC Subscription - define mirror database

g. On the Identification tab, click the Define subscription button.
h. The Define Replication Subscription window is shown. Click Add.

Figure 1-10 Create JDBC Subscription - define subscription

i. The Add Table window is displayed.


Figure 1-11 Create JDBC Subscription - define subscription - add table

Select the table to be synchronized. The Target schema and Target table
fields are filled in automatically; accept the default or change it to anything
desirable.
Click the appropriate Access Privileges. Click Add.
If there is more than one table to be synchronized, select more tables to
add; when done, click Close.
The tables have been added to the subscription now.


Figure 1-12 Create JDBC Subscription - define subscription

j. Click the Timing... button to adjust the replication frequency.

Figure 1-13 Adjust replication frequency

Click OK and OK to return to the Create JDBC Subscription wizard.
k. Click the Subscription sets tab.


Figure 1-14 Create JDBC subscription - define subscription set

Choose from the available subscription sets in the left pane and click -> to
put it into the right pane. The subscription sets shown on the right pane will
include this newly created subscription.
You can also choose to create a new subscription set by clicking the
Create... button. The Create Subscription Set wizard will be covered later.
l. Now all the information have been gathered for the subscription. Click OK.
m. The new subscription should appear in the right pane when clicking the
Subscriptions folder. It can always be altered by right-clicking the
subscription and choosing Edit.
2. To create a subscription set:
a. With MDAC open, right-click Subscription sets -> Create -> Table
Subscription -> JDBC Subscription.
The Create Subscription Set wizard opens.


Figure 1-15 Create Subscription Set wizard

b. On the Identification tab, enter the name and description for this
subscription set. Click the Subscriptions tab.
c. Choose from the available subscriptions in the left pane and click -> to
include it in this subscription set, or click ->-> to choose all.

Figure 1-16 Create Subscription Set - select subscription to include

You can also click the Create... button to create a new subscription,
following the steps described in the previous section.


When done, click the Groups tab.
d. Choose from the available groups in the left pane and click -> to subscribe
it to this subscription set, or click ->-> to select all of the groups.

Figure 1-17 Create Subscription Set - select groups

e. Enough information has been collected to create a subscription set. Click
OK.
f. The newly created subscription set should appear in the right pane of
MDAC when clicking the Subscription sets folder. It can be easily
modified or examined by right-clicking the subscription set and choosing
Edit.
g. Now click the Groups folder; in the right pane, for each group, the number
appearing in the Subscription sets column indicates the number of
subscription sets this group is subscribing to.


Figure 1-18 MDAC - groups

The association with the subscription sets can be easily changed by
right-clicking the group and choosing Edit. Select or deselect subscription
sets in the Subscription sets tab.


Figure 1-19 MDAC - groups - change subscription sets

1.4 Binding LDAP and MDAC
As discussed in previous sections, users and groups are created in WebSphere
Portal and maintained in LDAP. The Mobile Devices Administration Center or
MDAC retrieves this information from LDAP and keeps a copy in its control
database DSYCTLDB.

In MDAC, it is possible to refresh this binding if any changes take place in
WebSphere Portal.
For refreshing group information, right-click the Groups folder and select
Refresh WPS LDAP groups.
For refreshing user information, right-click the Users folder and select
Refresh WPS LDAP users.

By doing the refreshing, if new users or groups are added, they will be brought
into the MDAC and its control database.

If any user is removed from the sync group in WebSphere Portal, upon refreshing
the LDAP users, MDAC will warn you of the inconsistency and prompt you to
delete the user from MDAC’s control database.


Figure 1-20 MDAC prompts for inconsistency in user information

Click Yes to delete the user from MDAC.

Figure 1-21 Confirmation for deleting user from MDAC

Click OK to confirm the deletion.

If any DB2e group is removed from WebSphere Portal, upon refreshing WPS
LDAP groups, MDAC will warn you of the inconsistency and prompt you to delete
the group from MDAC’s control database.


Figure 1-22 MDAC prompts for inconsistency in group information

Click Yes to delete the group from MDAC.

Figure 1-23 Confirmation for deleting user from MDAC

Click OK to confirm the deletion.

1.5 Client configuration
IBM Everyplace Client requires a minimal configuration to perform relational
database synchronization. Do the following steps to set up this configuration:
1. On Pocket PC, open IBM Everyplace Client.
2. Click Tools -> User Options.


Figure 1-24 Everyplace Client

3. In the User Options window, specify the host name of the Everyplace
Synchronization Server. Also enter the user ID and password for the user who
is to perform synchronization.
You can set Everyplace Client to run after the system restart by checking
Make a copy in “Startup Folder”.


Figure 1-25 Everyplace Client - User Options

Click OK to close the User Options window.
4. Highlight the item DB2 Everyplace Sync and click Tools -> Configure.

Figure 1-26 Configure DB2 Everyplace Sync


5. The Configuration window is shown. The server address and server port are
those of the secure proxy. Do not attempt to change them unless you know
the exact values.
The user ID and password are automatically filled in from what you specified
in the User Options window.
Enter a device ID, which could be the same as the user ID.

Note: A user is only allowed to be associated with one device ID. Once an
initial synchronization is successful with a device ID, if the same user
attempts to synchronize again with a different device ID, the
synchronization will fail.

Figure 1-27 DB2 Everyplace Sync configuration

6. The Everyplace Client should be ready for synchronization now.

1.6 Sample application synchronization
IBM DB2 Everyplace provides a sample application that is installed
automatically: the Visiting Nurse (VNURSE) application. This application
simulates the scenario where a nurse visits some patients and take their medical
data. The nurse uses the VNURSE application to retrieve a patient’s information,
such as past medical record and contacts. The nurse also uses this application
to record the newly collected medical data, and can synchronize with the


back-end database to upload or download the latest updated information about
the patients.

To get familiar with this sample application, click Programs -> DB2 Everyplace
Samples -> VNURSE.

To work with this sample application, there are also subscription and subscription
sets in the Everyplace Synchronization Server. The subscription is JDBCSUB1
and the subscription set is SUBSCRIPTION_SET1.

Explore the defined subscription and subscription sets in MDAC to get familiar
with them.

To try out the sample application VNURSE synchronization:
1. Create a synchronization group and add a user to it.
2. Create a relational database adapter group (DB2e group) and add the same
user to this group as well.
3. In MDAC, add the DB2e group to subscription set SUBSCRIPTION_SET1.
4. Configure the Everyplace Client on Pocket PC, as described in 1.5, “Client
configuration” on page 26.
5. In Everyplace Client, check the box next to DB2 Everyplace Sync; notice
that the status of it changes to Scheduled.

Figure 1-28 Schedule DB2 Everyplace Sync

6. Click Execute. The synchronization starts.


Figure 1-29 Executing DB2 Everyplace Sync

7. When the synchronization is completed, it returns to the Everyplace Client
window, and the status changes to Completed.

Figure 1-30 DB2 Everyplace Sync completes

8. Now go the Configure window for DB2 Everyplace Sync and click the
Subscription tab. SUBSCRIPTION_SET1 is shown here, and you can
change the Sync Mode to Skip, Synchronize, or Refresh.


Figure 1-31 DB2 Everyplace Sync Configure - Subscription tab

9. If for any reason the synchronization failed, click Tools -> Show log to get
some information about the failure.
10.Try adding a new medical record using the VNURSE application, then
perform the synchronization again.
11.Use DB2 Control Center to view whether the new record appears in
VNMEDICALRECORD table of the VNURSE database.

1.7 Verify the synchronization
After completing the synchronization, you may verify the synchronization results.
On the server side, use the usual ways to query the back-end database to verify
the changes are there. On the client, if you have an application that can retrieve
and display the data from the databases, such as the sample VNURSE
application, use it to verify the results.

Another generic way to verify the results is to use the DB2eCLP tool that comes
with DB2 Everyplace:
1. Click the Programs icon.


Figure 1-32 Pocket PC Programs

2. Click File Explorer. Navigate to My DeviceProgram FilesIsync.

Figure 1-33 Pocket PC File Explorer

3. All the synchronized databases are stored in this directory. For example,
DSY_VNMEDICALRECORD is the table VNMEDICALRECORD used by the
VNURSE application. Verify that the database of interest appears here.
4. Go back to the Programs window. Click the DB2 Everyplace Samples icon.


Figure 1-34 DB2 Everyplace Samples

5. Select DB2eCLP and click OK on the welcome window.

Figure 1-35 DB2eCLP

6. Type in the top pane:
connect to program filesisync
Make sure isync is followed by a backward slash (“”). Otherwise, the
connection will not be established. Then click Execute.


Figure 1-36 Using DB2eCLP

7. Type the SQL statement in the top pane, for example:
select * from vnmedicalrecord where patientid=’900000001’
Click Execute and the query results will be displayed in the bottom pane for
you to verify.

Figure 1-37 Using DB2eCLP

8. Type other necessary SQL commands to verify.


9. When done, make sure to exit the DB2eCLP by clicking the Close button to
release the database connection. Otherwise, other DB2e applications will not
be able to operate.

1.8 Synchronization using SSL
To prevent synchronization data from being exposed to unintended parties, it is
often desirable to turn on security between the server and the client. In the case
of DB2 Everyplace Synchronization, security must be enabled on both the HTTP
server, the application server, and the mobile client. This section describes an
example of enabling SSL security on IBM HTTP Server and WebSphere
Application Server, as well as on IBM Everyplace Client.

1.8.1 Enable server security
In this section, we provide an example of how you will enable SSL in the IBM
HTTP Server.

Enable security on IBM HTTP Server
Execute the following steps:
1. Create a new key database.
A key database is a file that the server uses to store one or more key pairs
and certificates. You can use one key database for all your key pairs and
certificates or create multiple databases. IBM HTTP Server comes with the
IKEYMAN tool, which is a key manager to manage the key databases.
a. Make a directory for the key databases to be stored, for example, c:keys.
b. Start the Key Management utility of IBM HTTP Server (IKEYMAN) by
clicking Start -> Programs -> IBM HTTP Server -> Key Management
Utility.
c. Select Key Database File from the main interface and then select New.


Figure 1-38 IBM HTTP Server Key Management Utility

d. In the New window, enter the desired key database name, the directory to
store the key database, and click OK.

Figure 1-39 Create new key database

e. In the Password Prompt window, enter and re-enter the desired password
for the key database. Check Stash the password to a file? Click OK.


Figure 1-40 Set password for the key database file

2. Create a self-signed key file.
In this example, we use IKEYMAN to create some self-signed certificates to
use. Otherwise, you can use a certificate from a well-known Certificate
Authority (CA).
a. In IKEYMAN, select Key Database File from the main interface, then
select Open.
b. In the Open window, select the key database file just created and click
OK.
c. Enter the correct password when prompted.
d. Select Personal Certificates in the Key Database content frame and click
the New Self-Signed button.


Figure 1-41 Create self-signed key

e. In the Create New Self-Signed Certificate window, enter the following
information:
• Key Label: Enter a descriptive comment that is used to identify the key
and certificate in the database, for example, my first key.
• Key Size: For testing purposes, use the default value. Otherwise,
check with your security administrator for the proper key size in your
installation.
• Common Name: Enter the fully qualified host name of the Web server
as the common name.
• Organization Name: Enter the name of your company, for example,
IBM.
• Organization Unit: This is optional, but you should check with your
security administrator for the proper value in your installation. The
calculated hash value to be used for the digital signature will include
this and other values in the certificate.
• Locality: This is optional.
• State/Province: This is optional.


• Zipcode: This is optional.
• Country: Enter a country code. Specify at least two characters, for
example, US.
• Validity Period: For testing purposes, use the default value. Otherwise,
check with your security administrator for the proper value in your
installation.

Figure 1-42 Create the self-signed key

f. Click OK and exit IKEYMAN.
3. Set up the IBM HTTP Server.
The IBM HTTP Server configuration must be changed to allow for security.
a. Open the IBM HTTP Server configuration file:
Installation_Directoryconfhttpd.conf
b. Add the SSL module:
Locate the following line:
LoadModule ibm_app_server_http_module
After the above line, add the following LoadModule line:
LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll
c. At the end of httpd.conf, add the following lines. The text shown in italics
should be edited for your environment.
Listen 443


<VirtualHost yourServerName.raleigh.ibm.com:443->
SSLEnable
SSLClientAuth none
SSLCipherSpec 34
SSLCipherSpec 35
SSLCipherSpec 3A
SSLCipherSpec 33
SSLCipherSpec 36
SSLCipherSpec 39
SSLCipherSpec 32
SSLCipherSpec 31
SSLCipherSpec 30
ServerName yourServerName.raleigh.ibm.com
DocumentRoot "c:/IBM HTTP Server/htdocs"

<Directory " c:/IBM HTTP Server/htdocs "->Options Indexes
AllowOverride None
order allow,deny
all from all
</Directory->

</VirtualHost->

Keyfile c:/keys/key.kdb
SSLV2Timeout 100
SSLV3Timeout 1000
d. Save and close the httpd.conf configuration file.
e. Restart IBM HTTP Server.
4. Verify that security is enabled on IBM HTTP Server.
a. Open a browser.
b. Type https://yourserver.raleigh.ibm.com in the address bar.
c. If using a self-signed certificate, accept the certificate if prompted.

Note: For security reasons, it is always recommended that you use
certificates signed by a Certificate Authority (CA). Use self-signed certificates
for testing purposes only.

Enable security on WebSphere Application Server
1. Configure WebSphere Application Server.
a. Open the WebSphere Application Server Administrative Console by
selecting Start -> Programs -> IBM WebSphere -> Application Server
V4.0 -> Administrator’s Console.
b. Click Virtual Hosts.


c. Click the Add button.
d. Add *.443 to the Host Aliases list.
e. Click Apply.
f. Expand nodes by clicking the +.
g. Right-click yourServer.
h. Click Regen Webserver Plugin.
i. Right-click yourServer.
j. Click Stop for Restart. You may want to check the Task Manager to verify
that the WebSphere Application Server Java process has stopped. It is a
large Java process (70 MB or greater). There may also be other Java
processes associated with it. The only way to tell if it is a WebSphere
Application Server Java process is that you will see a huge (70 MB or
greater) Java process.
k. Start the WebSphere Application Server Administration Server by
selecting Start -> Programs -> IBM WebSphere -> Application Server
V4.0 -> Start Admin Server.
2. Verify that security is enabled on WebSphere Application Server.
a. Open a browser.
b. Access the Portal home page:
https://yourServer.raleigh.ibm.com/wps/portal
Accept the certificate if prompted.

1.8.2 Enable client security
IBM Everyplace Client uses a Secure Proxy for basic authentication. It is
transparent to the user and requires minimal configuration.

To enable the Everyplace Client to use SSL:
1. Open IBM Everyplace Client.
2. Select Tools -> User Options.
3. Check the box next to User SSL for Synchronization.


Figure 1-43 Turn On SSL on IBM Everyplace Client

4. Click OK.

Now the server and the client can communicate using SSL.

1.9 Synchronization with remote DB2 databases
In an enterprise environment, the databases are often stored on separate
machines from the Everyplace Synchronization Server. This section
demonstrates how to configure a subscription to synchronize with a remote DB2
database.
1. Before you start, make sure to run db2jstrt command on the remote
database machine so that the DB2 server can accept JDBC net connections.
2. Open the Mobile Administration Center.
3. Right-click Subscriptions and choose Create -> Table subscription ->
JDBC subscription.
4. The Create JDBC Subscription wizard opens. Enter a name for the
subscription and, optionally, a description. Click the Source tab.


5. Click the down arrow besides the Driver field and choose IBM DB2 UDB
Remote. The Database URL field will change to a different format
automatically.
Fill in the Database URL field, where the host is the host name or IP address
of the machine where the remote data source resides, and the port number is
6789 by default. Enter the database name.
Specify the user name and password that can access the source database.
Click the Mirror tab.

Figure 1-44 Specify remote data source

6. In the Mirror tab, specify the local mirror database and provide the user name
and password used to access this database. Click the Subscription sets tab.
7. In the Subscription sets tab, specify the subscription sets this subscription
should belong to. Click the Identification tab.
8. On the Identification tab, click the Define subscription button.
9. The Define Replication Subscription window is shown. Click Add.
10.Add the tables to be synchronized and click Close.
11.Modify the replication interval if necessary and click OK and OK.
By now, the subscription to a remote data source is configured.
12.Click the + besides the Logs folder and click Replication. Sometimes it is
necessary to refresh by right-clicking Replication and choosing Refresh.


Make sure the replication for the newly created subscription is carried out
successfully.
You can also use the Control Center to view the contents of the mirror
database to see whether the data has been replicated.
13.If the replication has no problem, this subscription is ready for use.

1.10 Sync modes
In Everyplace Client, for the subscription sets of DB2 Everyplace Sync, there are
three possible Sync modes, namely Skip, Synchronize, and Refresh.
Skip
If the Sync mode is configured to Skip, the subscription set will not participate
in the next synchronization with the source.
Synchronize
With this mode, source and mobile databases are synchronized on their
changes.
Refresh
With Refresh mode, the client drops and recreates all the relevant tables, and
the server sends all the rows for the client for each table.

1.11 Types of subscription
In the previous sections, we use JDBC subscription for data synchronization.
There are three possible types of subscriptions for relational database tables:
DataPropagator subscription
DataPropagator subscription is used only with DB2 back-end data sources.
The DB2 data source is left intact, but separate steps must be taken to enable
replication between source and mirror databases.
JDBC subscription
JDBC subscription provides users with access to data in any source database
with a JDBC interface. Triggers are inserted into the source database.
Upload subscription
Upload subscription only allows the user to directly insert rows into a table on
a source database. The source table may reside on any database that
supports JDBC. There is no mirror database involved.


1.11.1 DataPropagator subscription
With DataProgator subscriptions, DB2 Everyplace Sync Server uses DB2
DataPropagator to replicate data between the source DB2 database and the
mirror DB2 database. Figure 1-45 illustrates this process.

Replication
JDBC DPropR
DB2e Sync Server DPropR
source database
WebSphere Application Server (DB2)

mirror
database
(DB2) DB2 database
(LDAP data)
DB2e Sync LDAP
JDBC WebSphere Directory
Server
Portal Services
(servlet) Users and
Groups

set and
Mobile Devices
Center (MDAC) DPropR subscription
DB2 source database
SSL (optional)

Everyplace Client

proxy
Port 1080

DB2e database
Pocket PC

Figure 1-45 DataPropagator subscription - sample scenario

In the whole synchronization scenario, different subscription types only affect
replications. Client configuration and usage steps remain the same.

Note: DataPropagator subscriptions can only be used with DB2 back-end
databases.

Before creating DataProgator subscriptions, the source database table must be
defined as a replication source in DB2:
1. Open the DB2 Control Center and Mobile Devices Administration Center by
clicking Start -> Programs -> IBM Everyplace Synchronization Server ->
Launch MDAC.


2. In DB2 Control Center, expand the source database (for example, VNURSE)
and select the Tables folder to list the available tables.
3. Locate the synchronization source table, for example,
VNMEDICALRECORD, and right-click it.
4. Select Define as replication source -> DB2 Everyplace Sync Server.

Figure 1-46 Define source database table as replication source

5. Select Run Now.

Figure 1-47 Run Now

6. Click OK.


7. Verify the replication source has been created by clicking the Replication
Sources folder.

Figure 1-48 Table added as replication source

Now we can define the subscription.
8. In Mobile Devices Administration Center, select Subscription -> Create
-> Table Subscription -> DataPropagator subscription....


Figure 1-49 To create DataPropagator subscription in MDAC

9. The Create DataPropagator Subscription wizard opens. In the Identification
tab, type a name for this subscription, for example, MedicalRecord. Optionally,
enter a description for this subscription.


Figure 1-50 Create DataPropagator Subscription wizard

10.Click the ... button next to the Source database field. Choose the source
database from the list, and click OK.

Figure 1-51 Choose source database

11.Click the ... button next to the Mirror database field. Choose the mirror
database from the list, and click OK. If a mirror database was not created
earlier, click Create to launch the Create Database wizard.


Figure 1-52 Set mirror database

12.Click the Authentication tab. Enter the user ID and password information for
both source and mirror databases.

Figure 1-53 Enter authentication information for source and mirror databases


13.Click the Subscription sets tab. Select the subscription set(s) that this
subscription will belong to and click -> or ->-> to bring it to the Selected
subscription sets pane. You can also click Create... to create a new
subscription set.

Figure 1-54 Select subscription set

14.Click the Identification tab again. Click the Define subscription... button.


Figure 1-55 Define subscription

15.The Define Replication Subscription wizard opens.

Figure 1-56 Define Replication Subscription wizard

16.Click the Add button to open the Add window.
17.The previously defined replication sources are displayed. Select the desired
one and enter a name in the Target table field if it is different from the source.
Click Add. Repeat for more replication sources. Click OK when done.


Figure 1-57 Add replication source

18.In the Define Replication Subscription wizard, click the Timing... button to
modify the replication frequency.

Figure 1-58 Define Replication Subscription wizard

19.Click OK and OK; upon successful creation of the subscription, a DB2
message is shown.


Figure 1-59 Subscription creation successful

Now there are some extra steps to take in order to bind the tables and start
capture for the DataPropagator subscription:
1. Exit the DB2 Control Center and Mobile Devices Administration Center.
2. Open a DB2 command window by selecting Start -> Programs -> IBM DB2
-> Command Window.
3. Shut down all connected applications by entering:
db2 force application all
4. In a DB2 command window, change to the bnd directory of the DB2 UDB, for
example:
cd c:program filesSQLLIBbnd
5. Then type:
bindcap db_name db2user db2userpassword
This will change the database configuration parameter LOGRETAIN to
CAPTURE. Replace db_name with the name of the database you would like to
update, such as VNURSE in our example. Please note that db2user must be
a valid DB2 UDB user name and db2userpassword the corresponding
password.
6. The same command must be run for the mirror database as well:
bindcap mirror_db_name db2user db2userpassword
Replace mirror_db_name with the name of the mirror database you would like
to update, such as M_VN2 in our example.
7. Start the capture process by typing in the DB2 command window:
asnccp db_name
Where db_name is the source database, for example VNURSE in our example.
Leave the DB2 command window open. The capture process will run
continuously in the background. If the capture process stops, repeat these
steps.


8. The DataPropagator subscription has been fully configured now; check the
LogsReplication folder in MDAC to make sure replication succeeds.

Once the subscription is set up, IBM Everyplace Client can synchronize with the
source database in exactly the same way with JDBC subscriptions.

For other resources of how to configure DataPropagator subscription, please
refer to the IBM DB2 Everyplace Sync Server Administration Guide 7.2,
SC27-0845 and the IBM Redbook IBM Replication Solutions for Pervasive
Computing with DB2 Everyplace and DB2 Satellite Edition, SG24-6217.

1.11.2 Upload subscription
The upload subscription process, as the name suggests, is one way only. It
allows the client to insert rows into the source database, but not the other way
around. There is no mirror database involved in upload subscription process,
which is illustrated in Figure 1-60. In this sample scenario, a DB2 back-end
database is used as the source database.

No mirror database
No replication required source database
(DB2)

JDBC
DB2 database
(LDAP data)
DB2e Sync LDAP
WebSphere Directory
Server
Portal Services
(servlet) Users and
Groups

set and
Mobile Devices
Port 80 Center (MDAC) Upload subscription
Basic Authentication DB2 source database
SSL (optional)

Everyplace Client

proxy
Port 1080

DB2e database
Pocket PC

Figure 1-60 Upload subscription - sample scenario


To create an upload subscription:
Launch MDAC.
2. In the Mobile Devices Administration Center, select Subscription -> Create
-> Table Subscription -> Upload subscription....

Figure 1-61 Create upload subscription

3. The Create Upload Subscription wizard opens. In the Identification tab, type a
name for this subscription, for example, MedicalRecord. Optionally, enter a
description for this subscription.


Figure 1-62 Name the subscription

4. Click the Source tab. Choose the suitable database driver by clicking the
down arrow next to the Driver field.

Figure 1-63 Setup source database


5. In the same window, enter the user ID and password that can access the
source database.
6. Click the Subscription sets tab. Select the subscription set(s) this
subscription will belong to and click > or >> to bring it to the Selected
subscription set.

Figure 1-64 Select subscription set

7. Click the Identification tab again. Click the Define subscription... button.
The Define Upload Subscription wizard opens.

Figure 1-65 Define Upload Subscription wizard

8. Click the Add button to open the Add window.


9. Select the table into which rows will be inserted from the client. Change the
Target schema and Target table name if they are different from the defaults.
Click Add. Repeat for more tables. Click OK when done.

Figure 1-66 Select table that is to receive data from client

10.Click OK and OK. The Upload Subscription will be created and shown in
MDAC.

Once the subscription is set up, changes made to the DB2 Everyplace databases
on the client will be uploaded into the source database through the use of IBM
Everyplace Client. Changes made to the source database, on the other hand, will
be propagated to the client database. IBM Everyplace Client usage is the same
regardless of the different subscription type.

1.12 Filtering data from data sources
DB2 Everyplace Sync Server includes several filtering options for horizontal,
vertical, and user-based filtering methods. Data filtering is essential to reduce
traffic and optimize mobile device storage.

For details on how to configure these filters, please refer to the IBM DB2
Everyplace Sync Server Administration Guide 7.2, SC27-0845.


1.13 Debug and tracing
In this section, we include some useful information that you may need for
problem determination when synchronizing DB2 Everyplace data.

1.13.1 Enable tracing
To turn on tracing for DB2 Everyplace Sync Server:
1. Open and edit the file:
WebSphere_Install_DirIBMSyncServerdb2eServerpropertiescomibmmo
bileservicesDSYGdflt.properties
2. Modify the key Trace.Level to:
Trace.Level = *
3. Restart Everyplace Synchronization Server in the WebSphere Application
Server Administrative Console.

1.13.2 Trace files
The trace files for DB2 Everyplace synchronization are located in:

WebSphere_Install_DirIBMSyncServerdb2eServerlogsdsy.n.trace

Where n=0,1, 2....n. Depending on the trace file size set in DSYGdflt.properties,
when the first trace file (dsy.0.trace) hits the limit, a new trace file (dsy.1.trace) is
generated, and so on.

There is another trace file in the logs directory, dsyadmin.n.trace, where n=0, 1,
2...n; this is the trace file for MDAC.

1.13.3 DB2 Everyplace control database
All the information configured in MDAC is stored in a control database
(DSYCTLDB) in DB2. If the control database gets corrupted, it can be dropped
and recreated using the batch file:

WebSphere_install_dirIBMSyncServerdb2eServerbindsyctldb.bat

1.14 Hints and tips
It is always a good idea to test your connection when defining subscriptions.


After defining a subscription, check in the MDAC under Logs -> Replication
if there is any replication activity started and ended successfully for the newly
defined mirror database. If there is not, the subscription is probably not
configured properly and you will need to delete it and define it again.
When the database is large, make sure to configure a big enough log file size
for the mirror database, as all the records are processed in a single
transaction Otherwise, replication may fail.
When the database is large and replication takes a much longer time, make
sure to leave enough time between each replication. Otherwise, replication
may fail.
When synchronization fails with no apparent reasons, try resetting the user in
MDAC by right-clicking the particular user and choose Reset.

1.15 About Mobile Application Builder
There is a Mobile Application Builder (MAB) available for DB2e Version 7.2.1.
This version of MAB is primarily for building DB2e applications for Palm devices.
A newer version of MAB will be able to build DB2e applications for the Pocket PC
platform. It is expected that it will be available in a future release of WebSphere
Everyplace Access.


2

Chapter 2. Synchronizing with Oracle
databases
This chapter describes how to configure Oracle database as the synchronization
data source for WebSphere Everyplace Access DB2 Everyplace.


2.1 Common grounds with DB2 data source
The relational database synchronization architecture was discussed in
Chapter 1, “Synchronizing with DB2 databases” on page 3. This information
remains valid in this chapter. The only difference is that the back-end database is
Oracle now. Therefore, what is different here in operation is database replication.
Now the data needs to be replicated into a DB2 mirror database from an Oracle
data source. The process for JDBC subscription types is illustrated in Figure 2-1.

Replication
JDBC JDBC
DB2e Sync Server
source database
WebSphere Application Server (Oracle)

mirror
database
(DB2) DB2 database
(LDAP data)
DB2e Sync LDAP
JDBC
WebSphere
Server Directory
Portal Services
(servlet) Users and
Groups

set and
Mobile Devices
Center (MDAC) JDBC subscription
Oracle source
SSL (optional) database
Everyplace Client

proxy
Port 1080

DB2e database
Pocket PC

Figure 2-1 JDBC subscription synchronization with back-end Oracle database

For group and user creation and client configuration, refer to Chapter 1,
“Synchronizing with DB2 databases” on page 3.

Note: This chapter only covers how to create subscriptions with an Oracle
data source; everything else remains the same as in the DB2 case.


2.2 Create a subscription with Oracle data source
In this section, we include a recommended procedure to install the JDBC driver
to support an Oracle back-end database. Once this driver has been properly
installed, you should be able to add JDBC and Upload synchronization
subscriptions. However, the DataPropagator subscription type is not available
when using a back-end Oracle database.

2.2.1 Add Oracle JDBC driver
In order to create a JDBC subscription with an Oracle database, DB2 Everyplace
Server must be aware of how to load Oracle’s JDBC driver. The following steps
illustrate the changes to be made:
1. Exit the Mobile Devices Administration Center, if it is running.
2. Open WebSphere Application Server’s Administrative Console by clicking
Start -> Programs -> IBM WebSphere -> Application Server V4.0 ->
Administrator’s Console.
3. Stop the application server IBM DB2 Everyplace Server.
4. Locate the dsysetjavahome.bat file in the
WebSphere_install_dirIBMSyncServerdb2eServerbin directory and open it
with a text editor.
5. Add the complete path of the Oracle JDBC driver to the SET_JDBC_DRV_CP
line of the file. For example:
SET JDBC_DRV_CP=c:OracleOra81jdbclibclasses12.zip
6. In the WebSphere Application Server Administrative Console, click IBM DB2
Everyplace Server. In the right pane, click the JVM Settings tab.
Add the complete path of the Oracle JDBC driver into the list of classpaths.

Chapter 2. Synchronizing with Oracle databases 65

Figure 2-2 Add Oracle JDBC driver to DB2 Everyplace Server’s classpath

7. Click Apply.
8. Restart the application server IBM DB2 Everyplace Server. Make sure there
is no error in the Event Message pane.

2.2.2 Create a JDBC subscription
1. Open the Mobile Devices Administration Center by clicking Start ->
Programs -> IBM Everyplace Synchronization Server -> Launch MDAC.
2. If there is not one, create a subscription set following the same steps as
described in 1.3.2, “Creating subscription and subscription set” on page 12.


Figure 2-3 Create a subscription set

3. Right-click the Subscriptions folder and choose Create -> Table
subscription -> JDBC subscription.

Figure 2-4 Choose to create a JDBC subscription


4. On the Identification tab, give the new subscription a name of your choice.

Figure 2-5 Name the subscription

5. Click the Source tab. Click the down arrow besides the Driver box and
choose Oracle from the list. Observe that the format in the Database URL
field changes.


Figure 2-6 Choose Oracle as the driver

6. Enter the database URL for the Oracle data source, for example:
jdbc:oracle:thin:@127.0.0.1:1521:sales
Fill in the user ID and password that can access the database.

Figure 2-7 Fill in the source information


7. Click the Test Connection button to test whether a successful database
connection can be established. If not, modify the information and try again.

Figure 2-8 Test connection

8. Click the Mirror tab. Click the ... button besides the Database URL box to
choose a mirror database. Fill in the user ID and password information
necessary to access the mirror database. Test the connection.

Figure 2-9 Configure mirror database

9. Click the Subscription set tab. Choose the subscription set this subscription
will belong to and move it to the right pane.


Figure 2-10 Choose subscription set

10.Go back to the Identification tab and click Define subscription.
11.Click Add. There is probably a message informing you that there are too
many tables available to choose from. Click Close.

Figure 2-11 Too many tables to display

12.The available tables are shown. If you cannot find the table you want to use to
do the configuration, click the Filter button.


Figure 2-12 Available tables

13.Enter a suitable filter to reduce the scope. “%” is the wildcard character. Click
OK.

Figure 2-13 Filter the number of tables to view

14.Now the number of displayed tables is greatly reduced.


Figure 2-14 Filtered table view

15.Choose the table of interest and modify the Target schema and Target table
name if necessary. click Add.
16.Add more tables if desired. When done, click Close.

Figure 2-15 The table(s) to sync

17.Click Timing and modify the replication interval. For large tables, leave
sufficient time.


18.Click OK and OK again.
19.If the source database is big, it takes a longer time to get the subscription
created. When done, it returns to the MDAC window, with the created
subscription shown in the right pane.

Figure 2-16 Subscription created

20.Right-click the Replication folder under Logs and choose Refresh. Make
sure replication started and ended successfully for the mirror database you
configured.

The subscription is now ready for use.

2.2.3 Create an upload subscription
As explained in 1.11.2, “Upload subscription” on page 56, upload subscription is
for one-way data transfer between client and server databases. With Oracle
source database, the client is able to upload changes in the DB2 Everyplace
database into the Oracle source database. This scenario is illustrated in
Figure 2-17 on page 75.


No mirror database
No replication required source database
(Oracle)

JDBC
DB2 database
(LDAP data)
DB2e Sync LDAP
WebSphere
Server Directory
Portal Services
(servlet) Users and
Groups

set and
Mobile Devices
Port 80 Center (MDAC) Upload subscription
Basic Authentication Oracle source
SSL (optional) database
Everyplace Client

proxy
Port 1080

DB2e database
Pocket PC

Figure 2-17 Upload subscription - sample scenario

You can create an upload subscription by following these steps:
Launch MDAC.
2. In Mobile Devices Administration Center, select Subscription -> Create ->
Table Subscription -> Upload subscription....
3. The Create Upload Subscription wizard opens. In the Identification tab, type a
name for this subscription, for example, SalesHistory. Optionally, enter a
description for this subscription.
4. Click the Source tab. Choose the Oracle database driver by clicking the
down arrow next to the Driver field.
Enter the correct database URL in Database URL field, for example:
jdbc:oracle:thin:@127.0.0.1:1521:sales


Figure 2-18 Define Oracle source database

5. In the same window, enter the user ID and password that can access the
Oracle source database.
6. Click the Test connection button to verify the connection can be established.
7. Click the Subscription sets tab. Select the subscription set(s) this
subscription will belong to and click > or >> to bring it to the Selected
subscription set.
8. Click the Identification tab again. Click the Define subscription... button.
The Define Upload Subscription wizard opens.
9. Click Add. There is probably a message informing you that there are too
many tables available to choose from. Click Close.


Figure 2-19 Too many tables to display

10.The available tables are shown. If you cannot find the table you want to
configure with, click the Filter button.

Figure 2-20 Available tables

11.Enter a suitable filter to reduce the scope. “%” is the wildcard character. Click
OK.


Figure 2-21 Filter the number of tables to view

12.Now the number of displayed tables is greatly reduced.

Figure 2-22 Filtered table view

13.Choose the table of interest and modify the Target schema and Target table
name if necessary. Click Add.
14.Add more tables if desired. When done, click Close.
15.Click OK and OK. The upload subscription is created.


2.3 Sample dsysetjavahome.bat file
Example 2-1 Sample dsysetjavahome.bat file
@echo off
rem -----------------------------------------------------------------------
rem (C) COPYRIGHT International Business Machines Corp. 2000-2002
rem All Rights Reserved
rem
rem US Government Users Restricted Rights - Use, duplication or
rem disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
rem
rem dsysetjavahome.bat: set the java/jre path & classpath
rem -----------------------------------------------------------------------

for %%i in ("%DSYINSTDIR%") do (set DSY_INSTDIR=%%~sfi)
for %%i in ("%DSYSQLLIBINSTDIR%") do (set DSY_SQLLIBINSTDIR=%%~sfi)

SET JAVA_HOME=%WAS_HOME%java
SET JAVA_HOME_MDAC=%DSY_SQLLIBINSTDIR%javajava12jdkjre

rem for jdk 1.2.X and 1.3.X
SET JDK_EXTRA_CP=.

rem for jdk 1.1.X
rem SET
JDK_EXTRA_CP=%DSYSQLLIBINSTDIR%javajrelibi18n.jar;%DSYSQLLIBINSTDIR%javaj
relibrt.jar;%DSYSQLLIBINSTDIR%javaswingall.jar

rem jdbc drivers
SET JDBC_DRV_CP=c:OracleOra81jdbclibclasses12.zip

2.4 Synchronize with remote Oracle database
To create a subscription to synchronize with the Oracle data source that is on a
separate machine, follow the same steps illustrated in 2.2, “Create a subscription
with Oracle data source” on page 65.

2.5 Hints and tips
In addition to the hints and tips given in 1.14, “Hints and tips” on page 61,
consider the following:
If you get an error, DSYD007, MDSS connection pool encountered the
exception: unable to register JDBC driver for ......, please check to


make sure the Oracle JDBC driver is in the classpath of IBM DB2 Everyplace
Server and that this server has been properly restarted with no errors.
If you cannot make a test connection within MDAC to the Oracle database,
check to make sure JDBC_DRV_CP is properly configured in
dsysetjavahome.bat, and IBM DB2 Everyplace Server has been restarted to
take in the change.


Part 2

Part 2 Transcoding
Technologies
In this part of the redbook we describe the function provided by Transcoding
Technologies in the IBM WebSphere Everyplace Access V4.1.1 so that existing
enterprise online portlet applications can be accessed from wireless devices
such as WAP phones and Pocket PCs.

Step-by-step examples show ways to implement text clipping, a process to
manipulate existing HTML portlet pages to meet the characteristics of requesting
devices. Included are scenarios using stylesheets to transform XML portlet
content into other markup languages suitable for handling by client devices.

WML fragmentation, a function of Portal level transcoding, is also described in
different configurations.


3

Chapter 3. Transcoding Technologies
This chapter provides an introduction to the Transcoding Technologies in
WebSphere Everyplace Access. It covers the relevant tools and options
available with Transcoding Technologies for portlet-level transcoding.

Note: For information about portal-level transcoding, see Chapter 6,
“Portal-level transcoding” on page 143.


3.1 Transcoding Technologies overview
Transcoding Technologies included in WebSphere Everyplace Access provide
the ability to tailor Web-based information to the different needs of different
users. For example, Web pages can be made available on handheld and other
pervasive devices economically and efficiently.

With Transcoding Technologies, users receive information tailored to the
capabilities of the devices they are using. For example, users with small-screen
devices access a scaled version of the information, while users of a specialized
markup language access the same information in a format suitable for their
devices. By providing a single dissemination point for multiple renderings of
information, Transcoding Technologies eliminate the expense of re-authoring or
porting data or applications for multiple networks and devices. Transcoding
Technologies extend the reach of information to a new class of users.

Transcoding Technologies transform content based on the information
associated with the request, such as device constraints and organizational
policies. Web content can be transformed differently for different devices.
Transcoding Technologies can support all common types of Web data, including
HTML pages and Extensible Markup Language (XML). Transcoding
Technologies also tailor images to adjust screen size, file size, and numbers of
colors.

Transcoding Technologies offer three ways to transform contents:
XML stylesheets
Annotators
Transcoding plug-ins

They are also referred to as resources in Transcoding Technologies. There is
another type of resource called preference profiles, which is used to represent
the characteristics of devices and users and determine which stylesheet,
annotator, or plug-in to use.

These resources are discussed in more details in the following sections in this
chapter.

Note: In the following sections, the root directory where Transcoding
Technologies is installed is referred to as TT_Root. You should replace this
with your actual directory name, for example, C:Program FilesIBMTrans.


3.1.1 Architecture
Transcoding Technologies in WebSphere Everyplace Access are invoked at two
different levels:
Portlet-level transcoding. This is used for content transformations. For
example, markup language conversions, stylesheets, and annotators are
applied at this level.
Portal page level transcoding. This is used for whole-page modifications, for
example content fragmentation.

Figure 3-1 illustrates the Transcoding Technologies as implemented in IBM
WebSphere Everyplace Access Version 4.1.


11 10 7 6

12 9 8
Portlet
Filter

1 Portal
2 3
Filter

4 Portlet 5

Aggregator
Portal

Figure 3-1 Transcoding Technologies in WebSphere Everyplace Access

The request flow can be explained as follows:
1. The user agent (WAP browser, Pocket PC browser, desktop browser) makes
a request to the portal. In this environment the request is previously received
by the portal filter.
2. The portal filter calls the portal to receive its contents, which calls the
aggregator to aggregate the page.

Chapter 3. Transcoding Technologies 85

3. The aggregator selects portlets based on a combination of values, like user
credentials and whether the portlet supports the current aggregator. If a
portlet is configured to be transcoded and it provides a markup that
Transcoding Technologies can use, it will be selected as well. For example, if
the portlet provides HTML and the client needs WML content, the aggregator
will select the portlet because the portlet content must be transcoded.
Therefore, for a portlet that is configured to use Transcoding Technologies,
the aggregator calls the portlet filter as if it were a proper portlet.
4. The portlet filter calls the portlet to receive its contents.
5. The portlet returns its contents.
6. The portlet filter sends the portlet’s contents to Transcoding Technologies for
processing, associating the portlet’s contents with a default URI, unless
otherwise specified. This step is known as portlet-level transcoding.
Note that the portlet thinks it is communicating directly to the aggregator, so
no special programming style is needed to write a portlet that is filtered.
7. Transcoding Technologies return the processed contents to the portlet filter.
8. The portlet filter returns the processed contents as if it were a proper portlet
returning contents normally.
9. The aggregator, having finished aggregating the page, returns the page.
10.The portal filter sends the portal’s aggregated contents to Transcoding
Technologies for processing. This step is known as portal-level transcoding.
11.Transcoding Technologies return the processed contents.
12.The portal filter returns the processed contents.

3.1.2 Preference profiles
A preference profile can represent a particular type of device, or a particular user
or group of users. Transcoding Technologies use preference profiles to decide
how to treat documents that will be delivered to different devices and different
users. For example, on a device with a small screen, it may be desirable to
convert tables to lists to reduce horizontal scrolling. For a particular user, images
should be eliminated altogether.

When Transcoding Technologies process a document, a device profile and a
user profile are selected to apply to the document.

Device preference profiles are represented by .prop files located in:
<TT_Root>etcpreferencesdevice


User preference profiles are represented by .prop files located in:
<TT_Root>etcpreferencesuser

If the X-IBM-PVC-Device-Type field is present in the HTTP header, Transcoding
Technologies use the device profile whose file name matches the value specified
for that field. The value of the X-IBM-PVC-Device-Type field is set by WebSphere
Portal’s preference aggregation.

For example, if the value of X-IBM-PVC-Device-Type is
Microsoft!Internet+Explorer!6.0, the following device preference profile will be
used:
TT_RootetcpreferencesdeviceMicrosoft!Internet+Explorer!6.0.prop

Figure 3-2 illustrates the properties file for Microsoft Internet Explorer Version 6.

#version = 1.0
#Wed Jul 10 12:55:23 CDT 2002
framesSupported=true
deviceRule=(User_Agent%e*MSIE 6.0*)
javaAppletsSupported=true
portalOrdinal=360
portalMarkupVersion=ie
createCHTML=false
portalClient=true
desiredContentTypes=[text/html]
parent=NT.InternetExplorer
javaScriptSupported=true

Figure 3-2 Microsoft!Internet+Explorer!6.0.prop

If the X-IBM-PVC-Device-Type field is not present in the HTTP header,
Transcoding Technologies use the device profile whose user-agent value
matches the value of the user-agent field in the HTTP header. If no matching
profile is found, Transcoding Technologies use the default device profile.

User resources are not maintained through Transcoding Technologies. However,
other programs can pass information to Transcoding Technologies specifying the
use of a user profile. A user profile is selected for a request in the following way.
If a value is specified for userAndSessionExtractor in etc/localConfig.prop,
Transcoding Technologies try to execute the referenced implementation of the
UserAndSessionExtractor interface to obtain user and session names and select
the user profile that matches the user name.

You can specify a field in the HTTP header to be used to select a user profile by
setting the httpUserIdField value in etc/localConfig.prop. For example, if you


specify httpUserIdField=X-UserField, then Transcoding Technologies would find
the value of the X-UserField keyword in the HTTP header and select the user
profile that matches that value.

If the X-IBM-PVC-User field is present in the HTTP header, Transcoding
Technologies use the user profile that matches the value specified for that field.

If none of these checks identifies a user profile, then Transcoding Technologies
do not use a specific user profile. If one of these methods is used to specify a
user profile and the specified file is not found, Transcoding Technologies do not
try the other methods; it does not use a specific user profile. For example, if you
specify httpUserIdField=myUserField but myUserField is not specified in the
HTTP header, Transcoding Technologies would not look for the
X-IBM-PVC-User field.

If more than one device preference profile matches the incoming request, it is
impossible to predict which of the matching profiles would be selected. For
example, if you create two device profiles with expressions that could match the
same user-agent value, either one could be selected for a request that specifies
that user-agent value. Be sure to specify unique values for any new profiles you
create.

Each profile contains values for the preferences that are important to the device
that the profile represents. If a preference is not important to the device, it can be
omitted so that a value can be chosen from a different profile. For most
preferences, Transcoding Technologies will check profiles for a value in this
order:
1. Specific user
2. Specific device
3. Default user
4. Default device

If a value is not specified for a preference in one profile, Transcoding
Technologies will work down the list until a value is found. The transcoding
plug-ins that will be applied to the document are selected based on the combined
profiles.

Transcoding Technologies provide profiles for several common pervasive
devices. There are default profiles to be used if none of the existing profiles
matches the device being used.

In addition to determining which transcoding plug-ins will be used, a profile can
be used to select a stylesheet or annotator. You can also specify parameters to
be used by stylesheets that accept parameters.


3.1.3 XML stylesheets
When Transcoding Technologies process documents composed in Extensible
Markup Language (XML), it uses XSL stylesheets to convert these documents to
any markup language, such as HTML, WML, or other forms of XML.

Stylesheets can be registered using the XMLConfig tool and be visible to all
portlets. Alternatively, stylesheets can be set for specific portlets using Portal
Administration. For details see Chapter 5, “Using XSL stylesheets” on page 129.

After being registered, each stylesheet is represented by a stylesheet selector,
which is mapped to a .prop file containing conditions for the selection of the
stylesheet for use by Transcoding Technologies.

A stylesheet is selected to process a document based on the values of one or
more fields in the HTTP header, including the URL, and on the name or URL of
the input DTD. A stylesheet can also be selected based on criteria that match a
preference profile.

Some stylesheets accept parameters that affect how they operate on
documents. A stylesheet that accepts parameters can retrieve values for the
parameters from:
The HTTP header of the request
Values specified for the Parameters field in the XMLConfig file
Values specified in a preference profile

3.1.4 Annotators
For pervasive devices with limited screen size, it is often desirable to show only
the key information from a Web page, and get rid of the less critical stuff such as
graphics and other gimmicks. Annotators can be used to specify which portions
of a Web page to include or discard when the page is transcoded.

There are two types of annotators:
Internal annotators
They can be created using the tools available in WebSphere Studio
Application Developer and WebSphere Studio Site Developer. Internal
annotators are special tags embedded in the original Web page. When the
page passes through Transcoding Technologies, these tags are examined
and acted upon. For details about and samples of internal annotators, see
4.2, “Internal annotation” on page 109.


External annotators
These come as separate and independent annotation files that the
Transcoding Technologies use to operate on the original Web page. External
annotators can be created with simple text editors, or with tools supplied in
the Pervasive Toolkit.
External annotators can be registered using the XMLConfig tool and be
visible to all portlets. Alternatively, external annotators can be set for specific
portlets using Portal Administration. For details see Chapter 4, “Using
annotation for document clipping” on page 107.
After being registered, each annotator is represented by an annotator
selector, which contains conditions for the selection of the annotator for use
by Transcoding Technologies.
An annotator is selected based on the values of one or more fields in the
HTTP header, including the URL. An annotator can also be selected based
on criteria that match a preference profile.
For details about and samples of external annotators, see 4.3, “External
annotation” on page 118.

3.1.5 Transcoding plug-ins
A transcoding plug-in is a program written with programming languages that
modifies the content of a document. Transcoding plug-ins are selected to
process a document based on conditions specified by the program when the
transcoding plug-in is created.

Several transcoding plug-ins are provided with Transcoding Technologies in
WebSphere Everyplace Access, and you can obtain or develop others:
The image transcoding plug-in modifies images to better support the display
capability of a device.
The text transcoding plug-in converts textual data, such as HTML or XML,
from one format to another and can perform a number of transformations to
simplify the output.
The fragmentation transcoding plug-in fragments XML documents into
pieces small enough to be managed by the target device.
The HTML DOM generator creates a Document Object Model (DOM)
version of incoming HTML documents.
The annotation transcoding plug-in, also called annotation engine, interprets
the contents of files written with Transcoding Technologies' annotation
language to perform document clipping.


The HTML to WML transcoding plug-in converts HTML documents to WML
for devices with WAP browsers.
The HTML to compact HTML transcoding plug-in converts HTML
documents to Compact HTML documents for devices with CHTML browsers.

These transcoding plug-ins are installed with the product and enabled by default
(with the exception of the HTML DOM generator). To verify whether the
transcoding plug-ins are enabled or to change their status, use the XMLConfig
tool.

3.2 XMLConfig tools
The Transcoding Administrative Console cannot be used in this release.
Therefore, a set of command line tools are provided to effectively perform the
following tasks:
Export resources
Import resources
Disable resources
Enable resources

Note: Resources such as device profiles, stylesheet registrations, and
external annotator registrations can be configured using this tool.

For an example of how to use these commands, see 5.3.2, “An alternative -
Register the stylesheet” on page 135.

3.3 Request Viewer
Request Viewer is a very useful visual tool for monitoring the traffic going through
Transcoding Technologies. You can view the configuration and status
information of the registered transcoding plug-ins within Transcoding
Technologies.

Request Viewer is particularly handy as a debugging tool, because it enables
you to examine the flow of requests and responses through the server and
observe which plug-ins are triggered and when they are triggered. For each
transaction, Request Viewer also displays the header and content information as
they are manipulated by the transcoding plug-ins.

Note: Request Viewer can also be used to monitor traffic on a remote
machine running Transcoding Technologies.


Figure 3-3 shows the Request Viewer’s Server Configuration window. In this
window, all the registered transcoding plug-ins are displayed in the upper-left
pane. The upper-right Details pane shows the configuration and status
information for the transcoding plug-ins.

Figure 3-3 Request Viewer - Server Configuration window

The Request Viewer’s Request Processing pane shows the flow of the requests
and responses captured. The Transaction Header pane displays all the HTTP
headers in the requests and responses, while the Transaction Content pane
shows the body of the requests and responses. For a sample Request
Processing window, see Figure 3-16 on page 106.

3.3.1 How to start Request Viewer
The following procedure can be used to extract and start the Request Viewer
tool:
1. Locate the file wtpscripts.jar in the Transcoding Technologies root directory;
for example, c:Program FilesIBMTrans.
2. Expand this JAR file using an unzip tool such as WinZip.


3. Locate RequestViewer.bat in the expanded JAR file.
4. Extract this file to the Transcoding Technologies root directory; for example,
c:Program FilesIBMTrans.
5. From a command line, run RequestViewer.bat.
6. A window pops up asking information about the machine where Transcoding
Technologies are running. If it is running on the same machine, click Local. If
it is on a remote machine, you will need to supply the necessary information.
Click OK.

Figure 3-4 Starting Request Viewer

Note: The Request Viewer tool uses the RMI protocol when monitoring
remote Transcoding Technologies in WebSphere Everyplace Access. For
local monitoring, RMI is not required.

7. Request Viewer will be started.


Figure 3-5 Request Viewer started

Note: Request Viewer is a monitoring tool; therefore, you cannot change the
configuration or status of the transcoding plug-ins with it.

3.4 Logging and tracing
To turn on tracing for Transcoding Technologies:
1. Log in to WebSphere Portal as an administrator, choose the Portal
Administration page group. Choose the Portal Settings page and the
Enable Tracing portlet.


Figure 3-6 Enable tracing portlet

2. Scroll down and find TranscodingTraceLogger. Check the box beside it. See


Figure 3-7 Enable tracing for Transcoding Technologies

3. Click Save after you have selected the desired trace options.

3.4.1 Message files
Message files are created in the TT_Rootlog directory. The first message file
created is named TranscoderMessages1.log. When the maximum size is
reached, this file will be renamed to TranscoderMessages2.log and a new
TranscoderMessages1.log file created for new messages.
TranscoderMessages1.log is always the newest file. The default message file
size is 512 kilobytes.

When the maximum number of message files have been filled, the oldest file will
be deleted, the suffix number of each remaining file will be increased by one, and
a new TranscoderMessages1.log will be created for new messages. A new file is
begun when Transcoding Technologies are restarted. The default number of
message files is 3.

Message file size and maximum number of message files are defined in the
properties file:
TT_RootetcrasTranscoderRASMessageFileHandler.properties


3.4.2 Tracing files
Tracing records the specific behavior of Transcoding Technologies, recording
information useful in the diagnosis of problems.

Trace files are created in the TT_Rootlog directory. The first trace file created is
named WebSphere Portal Server 4.1_TranscoderTrace1.log. When the
maximum size is reached, this file will be renamed to WebSphere Portal Server
4.1_TranscoderTrace2.log and a new WebSphere Portal Server
4.1_TranscoderTrace1.log file created for new messages. The default trace file
size is 512 kilobytes. WebSphere Portal Server 4.1_TranscoderTrace1.log is
always the newest file.

When the maximum number of trace files has been filled, the oldest file will be
deleted, the suffix number of each remaining file will be increased by one, and a
new WebSphere Portal Server 4.1_TranscoderTrace1.log will be created for new
messages. A new file is begun when Transcoding Technologies are restarted.
The default number of trace files is 3.

Tracing file size and maximum number of tracing files are defined in the
properties file:
TT_RootetcrasTranscoderRASTraceFileHandler.properties

3.4.3 Gather troubleshooting data
When running into problems using Transcoding Technologies, there is a certain
set of information that will be useful in troubleshooting.

There is a program named RASCollect in Transcoding Technologies’s root
directory. Executing RASCollect.bat on Windows or RASCollect.sh on AIX,
Solaris, or Linux will package the necessary files and settings to make it easy to
gather diagnostic information. When it finishes execution, a zip or tar file will be
created in directory TT_Rootlog that you can send to the relevant people for
diagnosis. It will be named RASCollect.zip on Windows NT, Windows 2000, or
Linux, and RASCollect.tar on AIX or Solaris.

3.5 A simple portlet using Transcoding Technologies
In this section we include a sample scenario to show how to enable transcoding
in WebSphere Everyplace Access.

The sample scenario is illustrated in Figure 3-8 on page 98.


Everyplace
Wireless Gateway WTE forward proxy

WebSphere
HTTP HTTP Everyplace Access
WAP
WAP Proxy and
Gateway

WAP/IP

WAP Simulator

Figure 3-8 Transcoding sample scenario

3.5.1 Enable transcoding
To give an example of how to enable Transcoding Technologies for a portlet, a
very simple HelloWorld portlet is used, which does nothing but display a Hello
World message. The portlet descriptor (portlet.xml) for this portlet is shown in
Example 3-1.

Example 3-1 portlet.xml for HelloWorld portlet
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN"
"portlet_1.1.dtd">
<portlet-app-def>
<portlet-app uid="DCE:25400630-8a18-1201-0000-005d15e0e1ac:1"
major-version="1" minor-version="0">
<portlet-app-name>HelloWord application</portlet-app-name>
<portlet id="Portlet_1" href="WEB-INF/web.xml#Servlet_1"
major-version="1" minor-version="0">
<portlet-name>HelloWord portlet</portlet-name>
<cache>
<expires>0</expires>
<shared>NO</shared>
</cache>
<allows>
<maximized/>
<minimized/>
</allows>


<supports>
<markup name="html">
<view/>
</markup>
</supports>
</portlet>
</portlet-app>
<concrete-portlet-app uid="DCE:25400630-8a18-1201-0000-005d15e0e1ac:1.1">
<portlet-app-name>HelloWord application</portlet-app-name>
<concrete-portlet href="#Portlet_1">
<portlet-name>HelloWord portlet</portlet-name>
<default-locale>en</default-locale>
<language locale="en">
<title>HelloWord portlet</title>
<title-short></title-short>
<description></description>
<keywords></keywords>
</language>
</concrete-portlet>
</concrete-portlet-app>
</portlet-app-def>

Install this portlet into WebSphere Portal. To enable this portlet to use
Transcoding Technologies, do the following:
1. Log in to WebSphere Portal as an administrator, for example, wpsadmin.
2. Go to the Portal Administration page group -> Portal Settings -> Global
Settings portlet and check the Enable transcoding of portlet content box.


Figure 3-9 Enable global setting for Transcoding Technologies

3. Go to the Portal Administration page group -> Portlets page -> Manage
Portlets portlet, choose the HelloWorld portlet, and click Modify
parameters.


Figure 3-10 Choose HelloWorld portlet to modify its parameters

4. Add a parameter named FilterChain, with the value Transcoding. Click Save.


Figure 3-11 Add the parameter to enable transcoding

5. Add this portlet to a desired page group and page, for example, the Welcome
page of WebSphere Everyplace Access home page group. View this portlet in
a normal desktop browser.


Figure 3-12 HelloWorld portlet displayed in a desktop browser

6. Use Nokia Mobile Internet Toolkit to view the portlet with a WAP browser.
Start Nokia Mobile Internet Toolkit by clicking Start -> Programs -> Nokia
Mobile Internet Toolkit -> Mobile Internet Toolkit.
7. Next, you will configure the WAP Simulator to access the portlet. In the Nokia
WAP Simulator, a connection profile is required and this profile can be for a
direct HTTP connection to your Application Server or a WAP/IP connection if
you plan to connect using a WAP Gateway.
Figure 3-13 on page 104 shows a sample HTTP connection profile and a
sample WAP/IP profile. Click Settings -> Toolkit Preferences to get to this
window.


Figure 3-13 Nokia Mobile Internet Toolkit preferences

8. In the Go field, type the portal page URL and press Enter.

Figure 3-14 Type portal page URL


9. The Welcome page is shown on the simulator. Scroll down to the HelloWorld
portlet and select it. The transcoded portlet is shown in the WAP browser.

Figure 3-15 Welcome page and HelloWorld portlet displayed in WAP browser

3.5.2 Use Request Viewer to monitor the process
Request Viewer can be used to observe and monitor when the portlet and portal
page are transcoded.

Open Request Viewer and use the WAP browser to access the HelloWorld
portlet. When the HelloWorld portlet is opened on the WAP browser, Request
Viewer has captured some activities in its Request Processing window.

In this sample scenario, there are three entries. The first one is for building the
Welcome portal page, the second one transcodes the HelloWorld portlet into
WML, while the third one is for building the portal page with the HelloWorld
portlet opened.

As illustrated in Figure 3-16 on page 106, you can expand each transcoder that
the request goes through and examine the content changes in MEG Input and
MEG Output.


Figure 3-16 Request Viewer


4

Chapter 4. Using annotation for
document clipping
In this chapter, document clipping using the Transcoding Technologies within
WebSphere Everyplace Access (Everyplace Access) is introduced. Clipping is
an approach used to manipulate an HTML document to suit the characteristics of
the requesting device.

By using the annotation language, the developer can instruct Transcoding
Technologies on how to modify and clip an incoming HTML document and
generate the customized output. The developer has the ability to specify when
particular annotation files or individual annotation instructions are executed
against an HTML document. This is based on information contained in the HTTP
header or the device profile.

This chapter contains the following:
An overview of annotations for Transcoding Technologies
An example of internal annotation using WebSphere Studio
An example of using external annotation for different devices


4.1 Annotation overview
Document clipping allows an enterprise to deploy existing Web content to mobile
devices without having to create new versions of the existing content. This ability
allows the enterprise to expand the reach of their existing Web applications and
allows their mobile workers greater access to information and data.

Annotation, a clipping technique, allows you to specify the document content to
be affected and the action to be performed on that content. Annotation, an XML
dialect, consists of various instructions that are used by the Transcoding
Technologies to perform the customization. Annotation instructions can be
associated with the HTML document in two ways:
1. External annotations: The annotation instructions are located in a separate
file (.ann file). These instructions consist of two parts:
– The location: The XPath of the element within the HTML document where
the action is to be applied.
– The action: The particular activity that is to occur against a particular
portion of the HTML document (as specified by the XPath). The action
may be applied to a particular HTML tag, a group of HTML tags, or to
specific content.
2. Internal annotations: The annotations reside within the HTML document.
They are represented as comments within the HTML file. Internal annotations
consist of the actions and are located immediately before the associated
HTML tag, group of associated HTML tags, or content.

Both external annotations and internal annotations are processed by the
Transcoding Technologies within Everyplace Access. Transcoding Technologies
contain an annotation editor that processes the annotation instructions and
creates a clipped version of the document as output. The overall set of
annotation instructions available are:
remove Removes associated HTML tag(s) and content
keep Keeps associated HTML tag(s) and content
table Affects overall table (in particular, the heading)
column Removes a complete table column
row Removes a complete table row
field Modifies fields within a form
option Used to specify a selectable option
insertattribute Allows insertion of an attribute into an HTML tag
inserthtml Allows insertion of HTML


replace Replaces the specified content within the HTML
document with the content specified
replacewithhtml Replaces the associated HTML tag with the new HTML
tag specified within the instruction
setpreference Sets a preference that the Transcoding Technologies will
use with transcoding the HTML document
splitpoint Identifies your preferred fragmentation point to the

4.1.1 Annotation processing
The input to annotation is a Document Object Model (DOM) containing the
source HTML document. You can think of the DOM as a tree representation of
the source document. If you are using external annotations, the annotation
instructions are inserted into the DOM according to the XPath and before/after
attribute of the annotation instruction.

Next the DOM is processed by traversing the tree. The annotation instructions
are processed as they are encountered within the DOM. The keep or remove
state is maintained according to the annotation instructions that are encountered.
The result of the annotation process is a DOM with the modified structure and
content. This DOM is input to the rest of the transcoding process with the final
result in the markup language needed for the target device.

4.2 Internal annotation
As stated earlier, for internal annotation, the annotation instructions are
embedded directly into the HTML document. The new WebSphere Studio
products provide the capability to create HTML documents and JSPs. The
WebSphere Studio products support annotation of HTML documents.

The sample scenarios in this chapter have been developed using WebSphere
Studio Site Developer Advanced, which is included with Everyplace Access. The
Everyplace Toolkit (a WebSphere Studio plug-in provided by Everyplace Access)
has also been installed. The Everyplace Toolkit provides the tools to create and
manage portlets.

Note: In all subsequent references to WebSphere Studio Site Developer
Advanced in this chapter, the term WebSphere Studio is used.

Chapter 4. Using annotation for document clipping 109

4.2.1 Page Designer in WebSphere Studio
The portlet perspective within WebSphere Studio is used to create a sample
portlet, as well as the JSP and HTML content emitted by the JSP. The
WebSphere Studio Page Designer is a visual tool that allows you to create JSP
statements and HTML content. The Page Designer has three views, which are:
1. Design: A WYSIWYG editor that allows you to visually construct the page.
This editor is also used to specify your internal annotations
2. Source: An editor that allows you to view and edit the JSP and HTML source
3. Preview: A viewer that allows you to see the HTML as it would appear within
a browser

The WebSphere Studio Page Designer is used to create the HTML content the
JSP will generate. Next the Page Designer is used to annotate the HTML
content. With Page Designer, you can identify the HTML content that is to be
annotated and specify the type of annotation that is to occur. Page Designer
provides the following annotation instructions:
Remove or keep HTML tags or content: Either individual tags or groups of
tags.
Replace text: Replace tags and their content with text. Note that using replace
text removes the HTML tags so any styling provided by the HTML tag(s) is
lost.
Remove table rows or columns: Selected rows or columns can be deleted
from the associated table. Multiple rows or columns can be removed in any
combination.
Propagate tables headings: Allows column headings to be propagated as
labels with the row content when rendering the tables as lists.

For a good overview on Page Designer in relation to creating internal
annotations, refer to Section 5.4 in IBM WebSphere Everyplace Server Service
Provider and Enable Offerings: Enterprise Wireless Applications, SG24-6519.

4.2.2 Sample application: The Redbook News
The Redbook News application is a simple application that consists of a basic
portlet named TheRedbookNews.java and a JSP named TheRedbookNews.jsp
that emits the HTML. This simple example is intended to show you various
annotation capabilities within Page Designer. For example, in this scenario a
table and various text areas are included to show various annotation instructions.
Figure 4-1 on page 111 shows the HTML content in Page Designer’s Design
view.


Figure 4-1 TheRedbookNews.jsp in Page Designer - Design view

Using the Design view within WebSphere Studio Page Designer, internal
annotation instructions are created. The annotation default state is set to keep.
However, if you are going to remove more content than you are going to keep,
you may want to change the annotation default state, which could minimize the
number of instructions you would need to create.

Text replacement
Because many mobile devices have very small screens it is important be very
selective about the content sent to that target device. The Text Replacement
function provides the ability to replace the associated text with your text
replacement. This may be a shorter version of the original text. One draw back to
this function is that the associated HTML tags are removed and you are not
allowed to enter HTML tags in the text. So any HTML tags used for positioning
and improved presentation of the information are lost.

The steps to do text replacement are as follows:
1. In the Design view click the area that you want to replace; in this case it is
The IBM Raleigh ITSO News for 07/20/2002.


2. Right-click and a drop-down list will appear.
3. Click Annotation -> Set Text Replacement, as shown in Figure 4-2, and a
text box will appear, as shown in Figure 4-3.
4. Enter your new (replacement) text into the text entry box, as shown in
Figure 4-3, and click OK.

Figure 4-2 Selecting Text Replacement

Figure 4-3 Enter replacement text


Tip: If you prefer to work from the menu bar rather than using the right mouse
button to get to the annotation option, you can click Edit (on the menu bar)
and move your mouse to the Annotate entry in the drop-down list. While the
mouse is on the Annotate entry, the available annotation options with appear
in the another drop-down list. You can select the appropriate action. The rest
of the steps are the same as when using the right mouse button.

Remove or keep elements
To remove or keep an area with the Design view, perform the following steps:
1. Highlight the area you wish to remove or keep. For example, select multiple
HTML tags and content to remove. You can select large regions with multiple
HTML tags or select each HTML instance individually, whichever approach
you prefer.
2. Right-click the area and, as before, the options list will appear.
3. Click Annotation -> Set Remove Region. When this operation is complete
the specified area will have hash marks through it, as shown in Figure 4-4.

Figure 4-4 Results of remove annotation

Removing columns or rows from a table
Tables are a very nice way to represent information in a Web page; however,
some mobile devices do not have the space to display a large table. Page
Designer has annotation instructions that allow you to simplify a table. You can
remove rows and columns from a table or remove the column headings. In this
instance, columns from the table will be removed. For example, you can use the
following steps to remove a column or row from a table:
1. Select an entry in the table (column or row) you want to clip.
2. Go to the menu bar and click Edit -> Attributes. The Attributes window
appears, as shown in Figure 4-5 on page 114. Switch to the Table tag, if not
already displayed.


3. Click the Annotation tab.
4. Select either Remove this column or Remove this row, as shown in
Figure 4-5. In this case, for example, you will click Remove this column and
then click OK. When the operation is processed, the column appears with
hash marks through it (within the Design view).

Figure 4-5 Remove column from table

Instead of using the propagate table headings annotation instruction, the
headings from the table will be removed by selecting the heading and using the
remove rows option.

All the annotations
The complete set of annotations (represented in the Design view) is shown in
Figure 4-6 on page 115. These are the unique annotations performed for this
sample scenario. To get the desired results, you will use similar actions on
various parts of the document. Figure 4-6 on page 115 shows the hash marks in
the different areas where content will be removed.


Figure 4-6 Design view with all the annotations

An example of an internal annotation for text replacement is shown in
Example 4-1.

Example 4-1 Internal annotations
<tr><td><font face="arial,sans-serif,helvetica" size="3">

<B>The IBM Raleigh ITSO News for 07/20/2002</B>
</font></td></tr>

The internal annotation (in Example 4-1) shows replacing the text The IBM
Raleigh ITSO News for 07/20/2002 with ITSO News. Please note that the
complete annotation instruction appears before the HTML tag and content that it
is to effect. Also note that the internal annotation instruction is represented as a
comment.

The results of internal annotation
After the portlet is installed and configured on the WebSphere Everyplace
Access home page, you must make sure the portlet is available to transcoding by
adding the parameter FilterChain = Transcoding to the portlet. To set the
parameter, execute the following steps within Portal Administration:
1. Click Manage Portlet to see the portlets.

2. Highlight the TheRedbookNews portlet and click Modify Parameters.
3. On the Configure parameters and titles window, specify FilterChain as the
parameter and Transcoding as the value.
4. Finally, click Add and then click Save.

A new portal session is started using Internet Explorer to view the updated
WebSphere Everyplace Access home page. You will notice that the new portlet
(displayed within Internet Explorer) contains the annotations intended for the
WML browser only. In this situation, you have two options:
1. Disable transcoding for Internet Explorer (IE). This is done by disabling
transcoding within the device resource for the Internet Explorer device
profile(s). To do this set the <Enable> element value to false in the device
profile and execute the ImportResources command against the file with the
device profile.
2. Modify the internal annotations to include a condition statement that blocked
the annotations from being processed for IE.

In this sample scenario, the internal annotations that affect each annotation
instruction within the HTML document are modified. To do this you will edit the
annotation instructions within the Page Designer Source view. For example, a
modified annotation instruction with the condition (which is highlighted) is shown
in Example 4-2.

Example 4-2 Annotation instruction with condition
<tr><td><font face="arial,sans-serif,helvetica" size="3">
<!--METADATA type="Annotation" startspan
<?xml version="1.0"?>
<annot version="1.0" condition=”!(user-agent=*IE*)”>

Next, the portal with the modified version of TheRedbookNews portlet is updated
and another Internet Explorer portal session is started. The results should show
that no annotation takes place for Internet Explorer. The Internet Explorer view of
the portlet is shown in Figure 4-7 on page 117.

Figure 4-7 Internal annotation results in Web browser

Next the Nokia Mobile Internet toolkit is started and the portal URL is entered.
The Redbook News portlet is selected and the annotated WML document
appears. The complete dialogue is shown in Figure 4-8.

Figure 4-8 Internal annotation results in Nokia browser

Internal annotations for Pocket PC
The condition instructions within the internal annotation file will be changed
before running with the Pocket PC. For example, the new condition is
!device=*Internet+Explorer. An annotation statement with the new condition is
shown in Example 4-3 on page 118.


Example 4-3 New annotation condition
<annot version="1.0" condition="!(device=*Internet+Explorer*)">

The results in the IE browser and the WML browser are the same. The results
with the Pocket PC are shown in Figure 4-9.

Figure 4-9 Internal annotation in Pocket PC

4.3 External annotation
External annotation allows you to store your annotation instructions in a separate
file away from the target HTML source. This approach is appropriate when the
developer does not have control over the source HTML or has different
annotation instructions for different situations and does not want to use the
internal annotation condition statements.


There are two key parts to an annotation instruction, which are:
1. Annotation markup action: The particular action to be taken against the
HTML element(s)
2. XPath location: The exact location of the element(s) within the HTML source
to take the action against

For internal annotations the XPath was not necessary because the annotation
instruction was located in relationship to the HTML tag(s); they were intended to
effect. However, the external annotations are in a separate file, so the XPath
provides the location of the element(s) to be effected.

XPath is a Worldwide Web Consortium (W3C) specification that provides the
syntax used to identify the location of all the elements and content within an
HTML or XML document.

4.3.1 The external annotation language
Because the external annotation language is an XML dialect, the first entry within
the file is the XML version statement, represented as <?xml version='1.0' ?>.
Next is the root element for the annotation language represented as <annot
version=2.0>.

Each annotation instruction is represented in a <description> element, which can
consist of:
condition = text Defines the condition that must be true for the
annotation action to be applied. This is an
optional attribute.
take-effect = before or after Identifies when the annotation is to occur,
either before or after the target node.
target = XPath Identifies the target node (as defined by the
XPath to a given element).
<action> element A child element that states the action to be
taken. There are several actions (some of the
most important ones are included), which are;
<inserthtml>, <insertmarkup>, <keep>,
<remove>, <replace>, <replacewithhtml>,
<setpreferences>, <splitpoint>, <table>.

Example 4-4 on page 120 shows an annotation instruction. This particular
annotation shows replacing the text at location
target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]" with the text ITSO
Redbook News.


Example 4-4 External annotation description element
<description target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]">
<replace><text>ITSO Redbook News</text> </replace>
</description>

4.3.2 Sample scenario: RedbookNews02
In this sample scenario, the RedbookNews02 application is used to show
external annotations. This sample is a variation of the Redbook News application
(used for internal annotations). The RedbookNews02 application consists of the
RedbookNews02.java portlet and the RedbookNews02.jsp, which emits the
HTML. The HTML consists of headings, text, and tables allowing us to show
various annotation instructions. The RedbookNews02 application, without any
annotations applied, is shown in Figure 4-10.

Figure 4-10 RedbookNews02 without annotations

The HTML document itself is seen in Example 4-5 on page 121.


Example 4-5 Redbook02 HTML
<html>
<HEAD><META name="GENERATOR" content="IBM WebSphere Studio"></HEAD>
<Title>The Redbook News</Title>
<body bgcolor="#FFFFFF">


<center>
<h3>The IBM Raleigh ITSO News for 07/23/2002</h3>
<P>
<FONT face="Arial" size="2" color="#0000cc">
<B>Thanks for stopping by.</B></FONT>
</P>
<P><FONT face="arial,sans-serif,helvetica" size="2">
<B><I>We have Four (4) New Books Available TODAY! </I></B></FONT>
</P>

<table border="2">
<TR align="left">
<TH width="28">No.</TH>
<TH width="307">
<CENTER><FONT face="arial,sans-serif,helvetica" size="2">
<B>Book Title </B></FONT></CENTER>
</TH>
<TH width="83">IBM Form#</TH>
<TH width="57">Published</TH>
</TR>
<tr align="left">
<td width="28">1</td>
<td width="307"><font face="arial,sans-serif,helvetica" size="2">
<B>The Wireless Enterprise </B></font></td>
<TD width="83">SG99-9907</TD>
<TD width="57">07/20/02</TD>
</tr>
<tr align="left">
<b>Building Portals </b></font></td>
<TD width="83">SG99-9908</TD>
<TD width="57">07/21/02</TD>
</tr>
<tr align="left">
<b>Easy Application Development </b></font></td>
<TD width="83">SG99-9909</TD>
<TD width="57">07/21/02</TD>
</tr>

<tr align="left">
<b>Annotations For Fun</b></font></td>
<TD width="83">SG99-9910</TD>
<TD width="57">07/22/02</TD>
</tr>
</table>
<P><font face="arial,sans-serif,helvetica" size="2" ><B><I> For details on
these books and our vast selection of books - visit our
website!!!</I></B></font></P>

<table border="0">
<tr align="center"><td><FONT face="arial,sans-serif,helvetica" size="2"
color="#FF0000"><B>IBM International Technical Support
Organization</B></FONT></td></tr>
<tr align="center"><td><font face="arial,sans-serif,helvetica" size="2"><a
href="http://www.redbooks.ibm.com">http://www.redbooks.ibm.com</a></font></td><
/tr>
</table>
</center>
</body>
</html>

For this application there are three target devices:
Internet Explorer
Pocket PC - Compaq Ipaq
Wap Browser - Represented by the Nokia Toolkit

An external annotation file is created for each of these client devices.

Portlet parameters
After the portlet is installed and configured on the WebSphere Everyplace
Access home page, you will need to modify the portlet parameters using the
Manage Portlet’s Modify Parameters option. Listed in Table 4-1 are the
parameters and their values.

Table 4-1 tPortlet parameters
Parameter Value

FilterChain Transcoding

URI http://m23x303x.itso.ral.ibm.com/RedbookNews02.jsp


The new parameter is the URI. This parameter will be used by the Transcoding
Technologies to associate the annotation resources to this JSP. This will be
discussed further later in this chapter.

Registering annotation files
Because in this sample scenario three different annotation files (one for each
target device) are created, the annotation files will be registered with the
transcoding server. In order to do this you will need to create <Annotator>
element resources and use the ImportResources command to register them.
Also, the transcoding server needs a way to determine, which annotation file to
process for a particular target device.

In addition, the <keys> element will be used within the annotation resources to
identify each annotation file to the associated target device. Within the
<Annotator> element for each annotation file, you will need to include a <key>
element. Each key element has a Name attribute which you will need to assign a
valid key name and value.

By looking at the device profiles in the WTPConfig.xml file you should find the
valid keys for each device. For example, the device profiles for the Internet
Explorer and the Pocket PC do not contain <keys> elements; so before you
register the <Annotator> elements you will need to create <keys> elements for
these devices. For example, copy the two device profiles from the
WTPConfig.xml file to a new file along with the <XML> element and
<Resources> element. Then add a <keys> element to each device profile. The
<keys> element created for the Pocket PC is shown in Example 4-6 and the
<keys> element for the Internet Explorer is shown in Example 4-7. The rest of the
device description is left unchanged.

Example 4-6 Keys for Pocket PC
<Keys>
<Key Name="deviceType">PocketPC</Key>
</Keys>

Example 4-7 Keys for Internet Explorer
<Keys>
<Key Name="deviceType">Internet+Explorer</Key>
</Keys>

The ImportResources command is used to register the updated device profiles.
After all the changes to the device profiles are performed, you will be ready to
register the annotation files (using the ImportResources command). Example 4-8
on page 124 shows the annotation entry created for the WML device.


Example 4-8 Annotator for WML browser
<Annotator>
<Folder>ibm/itsotest</Folder>
<SelectorName>RedbookNews02WML02</SelectorName>
<Name>RedbookNews02WML02</Name>
<Description>This ann file is for the Redbook News 02 </Description>
<URL>http://m23x303x.itso.ral.ibm.com/RedbookNews02.jsp</URL>
<Location>C:/Stylesheets/Redbook02WML.ann</Location>
<Keys><Key Name="deviceType">WML Device</Key>
</Keys>
<Enable>true</Enable>
</Annotator>

Please take note that the annotator’s <URL> element contains the same
information as the portlet’s URI parameter. These must match in order for the
transcoding server to match the JSP with the annotation file.

Internet Explorer - External annotation
Even though you do not need to annotate the HTML document for Internet
Explorer, it is a good way to show a simple annotation file. Internet Explorer’s
annotation file contains these annotations:
Replace text.
Remove the first paragraph.
Keep the rest of the document. Notice that this entry is not necessary
because the default state is keep but it was included anyway.

The annotation file for Internet Explorer is shown in Example 4-9.

Example 4-9 External annotation for Internet Explorer
<?xml version='1.0' ?>
<annot version="2.0">

<replace> <text>ITSO Redbook News</text> </replace>
</description>

<description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[1]">
<remove/> </description>

<keep/> </description>
</annot>


The results of the external annotation processing are shown in Figure 4-11 on
page 125.

Figure 4-11 Results - Internet Explorer

Pocket PC - External annotation
More text and two columns from the table (column one and column four) will be
removed for the Pocket PC. In Example 4-10, the following annotation
instructions are shown:
Replace text.
Remove content.
Modify the book table (table 1) by removing row 1 and row 4 (this includes
removing the associated heading).

Unlike with internal annotations, you can create annotation statements only for
rows and not for columns, which caused us to create annotation instructions for
each row in order to remove the first and last column of the table.

Example 4-10 Pocket PC external annotation file
<?xml version='1.0' ?>


<annot version="2.0">
<replace> <text>ITSO Redbook News</text> </replace>
</description>
<description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]">
<description take-effect="before"
target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]">
target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[1]">
target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[1]">
--------repeat these instructions for Table Row 3, 4 & 5 -------
<description
target="/HTML[1]/BODY[1]/CENTER[1]/P[3]/FONT[1]/B[1]/I[1]/text()[1]">
<replace> <text>Details at our website:</text> </replace>
</description>
<description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[2]">


</annot>

The results of the Pocket PC external annotations are shownin Figure 4-12.

Figure 4-12 Results - Pocket PC external annotation

WML browser - External annotation
The external annotations for the WML browser (Nokia Toolkit) are similar to the
external annotation instructions for the Pocket PC, except that you keep columns
1 and 2 (the number and the book title) of the Book table. The results displayed
on the Nokia Toolkit are shown in Figure 4-13.


Figure 4-13 Results - WML browser external annotation

Tip: To run each annotation file and verify that you agree with the way the
results look, set the portlet AnnotationFile parameter with a value of the
location of each annotation file and use Internet Explorer as the test device.
The AnnotationFile parameter’s value would be in the following format:

file:c:/stylesheets/Redbook02IE.ann.

Also, remember to delete the AnnotationFile parameter when you are done
because this parameter overrides the annotator resources.


5

Chapter 5. Using XSL stylesheets
In this chapter, Transcoding Technologies within WebSphere Everyplace Access
(Everyplace Access) are used to transform eXtensible Markup Language (XML)
documents to various markup languages required by mobile devices or Web
browsers. It is natural to extend existing applications that generate XML
documents to the Web and to mobile devices. This approach provides the
enterprise with the opportunity to share XML documents with their various users
(mobile and on site) while retaining one original representation of that data as
XML documents.

The combination of eXtensible Stylesheet Language (XSL) stylesheets and
Transcoding Technologies allows the transformation of XML documents for
display on various mobile devices and Web browsers. Stylesheets are frequently
used to convert XML documents of a particular document type to other XML
dialects, HTML, and device markup languages (such as WML). Stylesheets
consist of rules that specify the XML document content (elements, attributes, and
element content) to be processed and how that content is to be processed in
order to generate the expected markup language.

The following topics are discussed in this chapter:
How to configure the portal for stylesheet processing
How to configure a portlet for stylesheet processing
How to use stylesheets with sample applications
How to use multiple stylesheets against a particular XML document type


5.1 Overview
XML has become the standard for representing information when that data is
outside a conventional database system. By its very nature XML provides the
means (through the use of elements and attributes) to express data in a
descriptive and meaningful way. XML documents consist of both the data
description (via elements and attributes) and the content (data) housed together
within the same file.

Representing data in XML documents makes processing and understanding that
data very easy and natural for humans and appropriately equipped applications.
However, browsers understand their own markup languages. In order to display
XML documents in a pleasing and readable fashion on the various browsers, the
XML document must be converted to the target browser’s markup language.

Stylesheets are used to convert XML documents to the desired browser markup
language. The Transcoding Technologies (TT) within Everyplace Access provide
the mechanism to accept both the stylesheet and the XML document as input
and generate the desired markup as is specified by the stylesheet rules.

Transcoding Technologies provide you with a means to use stylesheets with your
XML documents and dynamically convert the XML document to the right markup
needed by the specific device.

5.1.1 Configuring stylesheets
The transcoding server must know about the stylesheet(s) in order to perform the
XML document conversion. Transcoding Technologies provide you with these
methods of registering your stylesheets with the transcoding server. These are:
Register the stylesheet with the transcoding server by adding the stylesheet
resources to the configuration.
Configure the portlet to use a stylesheet. This approach is an alternative to
registering the stylesheet. There are multiple ways to configure the portlet.
They are:
– If the stylesheet is part of the to the portlet WAR file, a <config-param>
element with the stylesheet specifics is added to the <concrete-portlet>
element within the portlet’s portlet.xml file.
– If the stylesheet is not within the portlet WAR file, you can specify the
StylesheetFile parameter with the installed portlet.


Specify the stylesheets within the XML document using the wtp-condition.
This approach supports multiple stylesheets for a document. This approach
supports situations where the portlet emits more than one XML document
type, each of which has its own stylesheet(s).

5.2 Configure portal for stylesheet processing
Prior to configuring the specific application portlet(s), you must configure the
portal for processing XML documents. This is accomplished by updating the
PortletFilterService.properties file and adding XML in the portal markup
languages supported by the portal. To do this, the following steps should be
performed:
1. Open the PortletFilterService.properties file with a text editor. The file is
located within the application server directory at
<ApplicationServer>/lib/app/config/services/.
2. After the existing entries within the filtername = Transcoding, add the
following entries:
Transcoding.transcodeMarkup.4 = xml->hmtl
Transcoding.transcodeMarkup.5 = xml->wml
3. Save and close the file.

The results of editing the PortletFilterServices.properties file are shown in
Example 5-1.

Example 5-1 Modified PortletFilterService.properties
filtername1 = Transcoding
Transcoding.classname =
com.ibm.transform.wps.portletfilter.TranscodingPortletFilter
Transcoding.transcodeMarkup.1 = html->wml
Transcoding.transcodeMarkup.2 = html->chtml
Transcoding.transcodeMarkup.3 = html->vxml
Transcoding.transcodeMarkup.4 = xml->html
Transcoding.transcodeMarkup.5 = xml->wml

To include XML in the markup languages supported by the portal, access the
Portal Administration and execute the following steps:
1. Click Portal Administration -> Portal Settings -> Manage Markups. This
gets you to the Manage Markups page.
2. Click Add new markup.

Chapter 5. Using XSL stylesheets 131

3. Enter these three values:
– Markup name: xml
– MIME type: text/xml
– Default character set: UTF-8
4. Click OK.

The results of this activity are shown in Figure 5-1. The new entry for XML is the
last entry in the list.

Figure 5-1 Results of adding new markup

5.3 Sample one: XML Feed
The XMLFeed application accesses a syndicated news feed, in this case, the
Wired News Web site at
http://www.wired.com/news_drop/netcenter/netcenter.rdf. The Wired News
Web site is a technology and business-oriented news service. The data
(generated by Wired News) is in RSS format, which is an XML dialect for
syndicated news feeds, Web logs, and other dynamic Web information.

The XMLFeed application consists of a portlet (XMLFeed), which invokes a JSP
(rss.jsp), which links to the Web site, gets the data stream, and sends that
stream to the portlet for display.

Obviously, the portal does not display XML, so you will need to convert this XML
data stream for display. To accomplish this, you will create a stylesheet to convert
the RSS data stream to HTML. The sample stylesheet is shown in Example 5-2
on page 133.


Example 5-2 RSS stylesheet
<?xml version='1.0'?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:param name="textLinksPreferredToImages" select="'true'"/>
<xsl:output method="html"/>
<xsl:template match="/">
<html>
<body>
<xsl:apply-templates select="/rss/channel/image"/>
<ul>
<xsl:for-each select="/rss/channel/item">
<li><a>
<xsl:attribute name="href">
<xsl:value-of select="link"/>
</xsl:attribute>
<xsl:value-of select="title"/>
</a></li>
</xsl:for-each>
</ul>
<p><em>
<xsl:value-of select="/rss/channel/copyright"/>
</em></p>
</body>
</html>
</xsl:template>

<xsl:template match="/rss/channel/image">
<xsl:choose>
<xsl:when test="$textLinksPreferredToImages='1'">
<a>
</xsl:attribute>
<xsl:value-of select="title"/>
</a>
</xsl:when>
<xsl:otherwise>
<a>
</xsl:attribute>
<img border="0">
<xsl:attribute name="src">
<xsl:value-of select="url"/>
</xsl:attribute>
</img>
</a>
</xsl:otherwise>


</xsl:choose>
</xsl:template>
</xsl:stylesheet>

5.3.1 Configuring the XMLFeed portlet
With the stylesheet created and the portlet already installed you will need to set
the portlet parameters, which is done using Portal Administration. In this sample
scenario, the portlet is configured with the stylesheet information.

Select Manage Portlet (within Portal Administration), select XMLFeed portlet
from the list, and then click Modify parameters. On the Configure parameters
and titles page, enter the parameters and values, as shown in Table 5-1.

Table 5-1 XMLFeed portlet parameters
Parameter Value Meaning

FilterChain Transcoding Allow transcoding for the portlet.

url /xml/rss.jsp Use this JSP, which accesses the Web
site.

StylesheetFile file:c:/Stylesheets/rss2 Use this XSL stylesheet.
html.xsl

Finally, click Save and then click Close.

The StylesheetFile parameter works fine in this instance because only one
stylesheet needs to be configured for this portlet.

Tip: The JSP used in this example will be stored in the directory
<PortalServer>/app/wps.ear/wps.war/xml.

The results of running the XMLFeed portlet
The XMLFeed portlet results are shown in Figure 5-2 on page 135.


Figure 5-2 XMLFeed portlet results using StylesheetFile parameter

5.3.2 An alternative - Register the stylesheet
An alternative to creating the portlet parameter StylesheetFile =
file:c:/Stylesheets/rss2html.xsl is to register the stylesheet with the transcoding
server. This is accomplished using Transcoding Technologies commands and
creating a resource.xml file with the stylesheet information. To register the
stylesheet with the transcoding server, you will need to perform the following
steps:
1. Start a DOS prompt and change to the IBMTrans directory (in this scenario,
C:Program FilesIBMTrans).
2. Run the ExportResources command. This action produces the
WTPResources.xml file.
3. Open the WTPResource.xml file in a text editor and save the file as MyRSS
Resources.xml. Now edit the new file and delete all the content except for the
xml version element and the resource element and save this new file.
4. Within the MyRSSResources.xml file create the <Stylesheet> element with
the appropriate information. The stylesheet element and information is shown
in Example 5-3. Save the file changes.
5. Run the ImportResources -File c:stylesheetsMyRSSResources.xml
command. This action registers the stylesheet with the transcoding server.
6. Restart the Portal server to ensure the updated resources are in effect.

Example 5-3 Stylesheet configuration file - MyRSSResource.xml
<?xml version="1.0" encoding="UTF-8"?>

<Resources ServerModel="testOne" Version="magic411srv">
<Stylesheet>

<Folder>ibm/samples</Folder>
<SelectorName>rss2html</SelectorName>
<Name>rss2html</Name>
<Description>stylesheet for RSS content</Description>
<OutputMimeType Enable="true" order="1">text/html</OutputMimeType>
<Location>file://C:/Stylesheets/rss2html.xsl</Location>
<InputDTD>http://www.wired.com/news_drop/rss-0_91.dtd</InputDTD>
</Stylesheet>
</Resources>

With the changes in effect, the results shown in Figure 5-3 are obtained.

Figure 5-3 XMLFeed portlet results using MyRSSResource.xml file

The Wired News has its own Document Type Definition (DTD) for the RSS XML
dialect, which is located at http://www.wired.com/news_drop/rss-0_91.dtd.
This is the DTD included in the stylesheet resource file shown in Example 5-3 on
page 135. There are other Web sites that generate RSS documents; two
examples are:
http://www.cnn.com/cnn.rss
http://www.linuxtoday.com/backend/biglt.rss

To access these Web sites, the JSP must be changed to link to these sites.
These sites use the DTD
http://my.netscape.com/publish/formats/rss-0.91.dtd, so remember to
reference that DTD in your stylesheet resource.

5.4 Sample scenario 2 - ITSO News XML Feed
The ITSO News XMLFeed portlet is similar to the XML Feed in that the JSP
accesses an XML document and sends the XML document to the portlet. The
ITSO News XMLFeed application consists of a portlet (ITSONewsXMLFeed) that
invokes a JSP (itsoNewsXML.jsp), which reads the latest NewsBrief.xml file.


To display XML document content on various devices, you will need to create
stylesheets to generate the markup language required for each of the target
devices. Within the XML document, wtp-condition statements are included and
they specify the condition(s) and the location and name of the stylesheet to be
used. The NewsBrief. xml file is shown in Example 5-4. The wtp-condition
statements are located at the beginning of the XML document after the XML
version statement.

Example 5-4 NewsBrief.XML file
<?xml version="1.0" encoding="ISO-8859-1"?>
<?wtp-condition stylesheet="http://localhost/ITSONews2HTML.xsl"
condition="(device=*Internet+Explorer*)"?>
<?wtp-condition stylesheet="http://localhost/ITSONews2PcktPC.xsl"
condition="(device=*Pocket+PC*)" ?>
<?wtp-condition stylesheet="http://localhost/ITSONews2Wap.xsl"
condition="(device=*Nokia*)" ?>
<newsitem>
<title>"It's alive! DB2 goes autonomic"</title>
<story>
<location>NEW YORK </location>
<releaseDate>July 22,2002</releaseDate>
<shortDetail>IBM offering a new version of DB2 that boasts autonomic
computing and Web services technology to help customers manage
and extract value from the vast amounts of data used run an advanced
enterprise.
</shortDetail>
<fullDetail>
<paragraph>IBM has raised the competitive threshold in databases, offering a
new version of DB2 that boasts autonomic computing and Web services technology
to help customers manage and extract value from the vast, complex and growing
amounts of data it takes to run an advanced enterprise. DB2 V8 incorporates new
autonomic technology to help companies simplify and automate many of the tasks
associated with maintaining databases, plus it delivers broad support for open
standards, so customers can manage, integrate and analyze information from a
wide variety of sources.
</paragraph>

<paragraph>DB2 V8 opens a new phase in the three-way database struggle between
IBM, Oracle and Microsoft. As companies struggle to contain data management
costs and tame complexity, we're offering new tools to simplify administration,
access information no matter where it resides and uncover vital patterns and
connections in scattered data pools that they can use to improve customer
service, increase revenue and gain a competitive advantage.
</paragraph>
</fullDetail>
</story>


As you can see from the example, the wtp-conditions each apply to a different
device and each have an associated stylesheet. The wtp-conditions and
associated stylesheets are shown in Table 5-2.

Table 5-2 Sample conditions (wtp-conditions)
wtp-condition Associated stylesheet

device=*Internet+Explorer* http://localhost/ITSONews2HTML.xsl

device=*Pocket+PC* http://localhost/ITSONews2PcktPC.xsl

device=*Nokia* http://localhost/ITSONews2Wap.xsl

The Transcoding Technologies can use the information from the HTTP header or
the device profile to determine which stylesheet to apply. Using the wtp-condition
makes it very easy to manage a set of stylesheets that need to be applied to an
XML document under specific conditions, or in the case of specific devices.

Tip: In order to use the HTTP URL, the stylesheets will be located in the <IBM
HTTP Server>/httpdocs directory.

5.4.1 Sample stylesheets
The goal is to have the Transcoding Technologies select the stylesheet
appropriate to the device making the request. The wtp-condition gives you the
ability to specify it in the XML document by using the specific conditions
applicable in each instance. For example, review the sample stylesheets used in
this scenario and view the results.

Internet Explorer stylesheet
First, let us look at the stylesheet for an Internet Explorer browser, which is
shown in Example 5-5 on page 139. If you remember, the XML document (shown
in Example 5-4 on page 137) contains two types of story content: A
<shortDetail> element and a <fullDetail> element. The <shortDetail> was a very
brief key statement from the story; this content was intended for mobile devices.
The <fullDetail> contains the complete story and is intended for Web browsers.

Note: Since there is space within the portal page, the full story will be
displayed.

The stylesheet is shown in Example 5-5 on page 139.


Example 5-5 Stylesheet for IE browser
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns="http://www.w3.org/1999/xhtml"
version="1.0">

<xsl:template match="newsitem">
<html>
<center> <h2>ITSO Breaking News</h2> </center>
<xsl:apply-templates/>

<center>
<table border="0">
<tr align="center"><td><b>
IBM International Technical Support Organization</b></td></tr>
<tr align="center"><td><a
href="www.redbooks.ibm.com">http://www.redbooks.ibm.com</a></td></tr>
</table>
</center>
</body>
</html>
</xsl:template>

<xsl:template match="title">
<h3>
<xsl:value-of select="."/>
</h3>
</xsl:template>

<xsl:template match="story/location">
<i>
</i>
</xsl:template>

<xsl:template match="story/releaseDate">
<b>
</b>
</xsl:template>
<xsl:template match="story/shortDetail">
<br/>
</xsl:template>
<xsl:template match="story/fullDetail/paragraph">
<p>
</p>

</xsl:template>
</xsl:stylesheet>

The results are shown in Figure 5-4.

Figure 5-4 NewsBrief.xml - Results in IE browser

Pocket PC stylesheet
Next you will look at the stylesheet for the Pocket PC and the results of applying
the stylesheet to the XML document. The sample stylesheet is shown in
Example 5-6.

Example 5-6 Pocket PC stylesheet
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">


<html>
<center> <h3>ITSO Breaking News</h3> </center>
<br/>
</body>

</html>
</xsl:template>

<h4> <xsl:value-of select="."/> </h4>
<br/>
</xsl:template>

<xsl:template match="story">
<p> <xsl:value-of select="shortDetail"/> </p>
</xsl:template>
</xsl:stylesheet>

As you can see from the stylesheet, the rule with match=”story” contains value-of
select = shortDetail. This rule causes the shortDetail element content to be put in
the output stream. The results displayed on the Pocket PC are shown in
Figure 5-5.

Figure 5-5 NewsBrief.xml - Results in Pocket PC


Nokia Toolkit
The final stylesheet is for a WML device. The stylesheet is shown in
Example 5-7.

Example 5-7 WML stylesheet
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<wml>
<card>
<p>
</p>
</card>
</wml>
</xsl:template>
<strong>
<b>
</b>
</strong>
<br/>
</xsl:template>
<xsl:template match="story">
<xsl:value-of select="shortDetail"/>
</xsl:template>
</xsl:stylesheet>

As in the Pocket PC example, the shortDetail element is selected as the story
body. The results are shown in Example 5-6.

Figure 5-6 NewsBrief.xml - Results in WML

6

Chapter 6. Portal-level transcoding
The main function of portal-level transcoding implemented in IBM WebSphere
Everyplace Access is to provide services to transform portlet content into a
series of dynamically linked information (called decks), suitable for handling by
client devices using markup languages such as WML for WAP devices and
compact HTML (cHTML) for i-mode devices.

In this chapter, we describe the fragmentation function provided by Transcoding
Technologies and how this support is integrated in a WebSphere Everyplace
Access environment for proper portlet access.

Sample scenarios using WAP client devices are included to show how to
configure a WAP Gateway and its associated WAP proxy. In these scenarios, the
Web Traffic Express (WTE) proxy is used as a WAP proxy when deploying
portlet applications using IBM WebSphere Everyplace Access to generate WML
portlet content.

Note: The Web Traffic Express proxy can also be used for binary WML
caching. The WAP Gateway in Everyplace Wireless Gateway provides a
plug-in for WTE to support this function.


6.1 Overview
Many phones have limited storage capacity (for example, 2880 bytes). However,
many Web pages exceed these limits. Therefore, converting an HTML page to
i-mode (cHTML) or WML is very likely to result in a deck and/or page that
exceeds the maximum storage capacity of a phone. The same problem may be
encountered with native wireless content if the content generator is unaware of
the specific limits of the phone being used. Exceeding the storage capacity of the
phone means that the page cannot be viewed on that phone.

The fragmentation function provided by Transcoding Technologies makes it
possible to view these over-large pages on the limited storage phones.
Fragmentation solves this problem by splitting a single oversized deck and/or
page into multiple smaller decks/pages, each one smaller than the maximum
size limitation.

Note: The main function provided by portal-level transcoding is deck
fragmentation.

Figure 6-1 illustrates portal-level transcoding as implemented in WebSphere
Everyplace Access.

Portal-level Portlet-level
transcoding transcoding

Portlet
Filter

Portal
Filter

Portlet

Aggregator
Portal

Figure 6-1 Portal-level transcoding in WebSphere Everyplace Access


Fragmentation is performed by the fragmentation transcoder. This transcoder is
registered and enabled by default.

Note: Transcoding Technologies in IBM WebSphere Everyplace Access
support fragmentation for WML and i-mode (cHTML).

6.1.1 How it works
The fragmentation transcoder traverses the Document Object Model (DOM) tree
representing the over-large card/page. The DOM is generated internally and
automatically when HTML is transcoded to WML or i-mode (cHTML). Therefore,
you do not need to enable the HTML Document Object Model Generator
transcoder.

If elements will fit on the new page, they are added to it and removed from the
original. If elements do not fit, there are two ways to handle them:
They can be fragmented: Recursively traverse the element's subtree.
They cannot be fragmented: Finish fragmenting the new page; the original
may still be too large.

The maximum size for a fragment is a property of the device. The fragmentor
determines the size value from the information, as follows:
For WML there is a parameter that specifies the maximum size value in the
device preference profile. The key parameter (WMLMaximumDeckSize) is a
configurable property and is shown in Example 6-1.

Example 6-1 WML device preference profile
<Device><SelectorName>WML-Device</SelectorName>
<UserAgent>(User_Agent=*WAP*) | (User_Agent=*Wap*) | (User_Agent=*MOT-CB*) |
(((User_Agent=*UP.Browser/3.1*) | (User_Agent=*UP.Browser/4.*) | (User_Agent=*
UP/4.*)) & (Accept=*wml*)) | (User_Agent=*Nokia*) &
(!User_Agent=*Rover*)</UserAgent>
<TranscodeImages>true</TranscodeImages>
<DesiredMimeType order="0">text/vnd.wap.wml</DesiredMimeType>
<SupportsColor>false</SupportsColor>
<Keys><Key Name="disposeImages">false</Key>
<Key Name="ConfigurableProperties">transcodeImages{bool} disposeImages{bool}
fixedImageScale{bool} imageScaleFactor{itext} textLinksPreferredToImages{bool}
desiredContentTypes{text} propagateFirstTableRowData{bool}
convertTablesToUnorderedLists{bool} WMLMaximumDeckSize{itext}</Key>
<Key Name="imageScaleFactor">0.5</Key>
<Key Name="NonConfigurableProperties">screenCapability{text}
supportedImages{text} colorSupported{bool}</Key>
<Key Name="propagateFirstTableRowData">false</Key>

Chapter 6. Portal-level transcoding 145

<Key Name="deviceType">WML Device</Key>
<Key Name="convertTablesToUnorderedLists">false</Key>
<Key Name="fixedImageScale">true</Key>
<Key Name="textLinksPreferredToImages">true</Key>
<Key Name="WMLMaximumDeckSize">2880</Key>
<Key Name="screenCapability">low</Key>
<Key Name="supportedImages">[wbmp]</Key>
</Keys>
</Device>

i-mode (cHTML): The maximum size value is 2048 bytes by default. There is
no parameter as with WML. i-mode phones can also have different cache
sizes. The size is specified in the User-Agent field in the HTTP header. For
example, User-Agent DoCoMo/1.0/N502/c8 specifies an 8 KB cache. In this
case, the fragmentor adjusts fragmentation size based on this cache size. If
the cache size is c8 (8 KB), the fragmentor sets the maximum size to 3000
bytes. If the cache size is c10 (10 KB), the fragmentor sets the maximum size
to 4000 bytes.

In addition to splitting up the deck/page into smaller chunks, the fragmentor adds
links to each of the generated pieces to allow navigation from one piece to the
next and the previous one. The Continue link allows you to move to the next
fragment and the Return link moves you to the previous one. The first fragment
has no Return link and the last no Continue link.

Figure 6-2 on page 147 shows an example of WML fragmentation. A single
oversized WML deck is fragmented into two smaller pieces. The Continue and
Return links are inserted into the fragments to allow for navigation between the
fragments. Also, any intra-deck links in the original deck are fixed to point to the
target in whatever deck/card in which they are placed.


Deck1

Card1
FragDeck1

FragCard1
Target
Target

Continue FragDeck2

FragCard2

Link

Link Return

Figure 6-2 Fragmented WML deck

After fragmentation is performed, the first fragment is sent to the client as an
HTTP response. The fragmentation engine stores non-first fragments in a
general-purpose resource repository. Making the resource repository general
purpose will allow for reuse by other components needing a similar service in the
future. But for now, only the fragmentation engine uses the resource repository.
Because the fragmentor needs the resource repository to save fragments for
later retrieval, the resource repository should not be disabled if fragmentation is
being used. If the fragmentor is disabled, the resource repository should also be
disabled; this will improve performance.

All fragments are named so that a request for any fragment will be routed back to
the transcoder. This means including the Web server host name and required
fields so that the transcoder is invoked to handle the fragment request.

For example:
http://m23x303x/wps/TranscodingUtilities/ifrag-4739I34/m23x303x...

Where m23x303x is the portal host name.

Note: Fragments are kept until the original document expires. If a request for
a discarded fragment is received, a Fragment expired message is sent.


6.1.2 Fragmentable elements
Fragmentable elements are:
Nodes (tags) with children
Nodes (tags) that can be safely cloned with child nodes distributed among the
clones (safely means that the resulting markup is valid and the content's
meaning and/or presentation is essentially unchanged)

Note that elements with no children (for example, break elements) are not listed
below as fragmentable, but a card/page may be split at one of these elements.
WML fragmentable elements are:
<wml>, <card>, <p>, <em>, <strong>, <i>, <b>, <u>, <big>, <small>, <table>
i-mode fragmentable elements are:
<html>, <body>, <p>, <blockquote>, <blink>, <center>, <dir>, <div>, <font>,
<plaintext>, <pre>, <ul>

6.1.3 Common problems
Invalid input (invalid content) will cause a request to be rejected
(FragmentRejectedException). Sometimes, content cannot be fragmented into
small enough pieces. This is likely to happen with the following elements:
Fragmentable elements provided as a reference
Long paragraphs with no breaks
Large forms

6.1.4 Example
Figure 6-3 on page 149 is a simple example of WML deck fragmentation. The
fragmentor traverses the tree depth-first. At each node (tag), the fragmentor
calculates the size of the page represented by the nodes visited so far, plus any
descendants of the current node. If this amount exceeds the maximum size, then
either the tree is fragmented before the current node, or the subtree(s) of the
current node is recursively considered for fragmentation.

The double line in Figure 6-3 on page 149 indicates where the fragmentor
determines that this tree must be fragmented.


<wml>

<card> <card>

......
<p> <p>

text <br> text

Figure 6-3 Fragmentation example

Figure 6-4 illustrates the first fragment resulting from fragmenting the WML deck,
as indicated in Figure 6-3.

<wml>

<card>

<p>

text <br>

Figure 6-4 First fragment


Figure 6-5 is the second fragment. Notice that the <wml>, <card>, and <p>
elements from the original card were duplicated, with children distributed or
duplicated as necessary between the new and old elements. This remaining
fragment may still be too large for the target device, so the fragmentor begins
again at the top of this DOM to see if it needs to be fragmented.

<wml>

<card> <card>

......
<p> <p>

text

Figure 6-5 Next fragment

6.2 WML fragmentation in Transcoding Technologies
WML fragmentation algorithms in Transcoding Technologies include URLs and,
therefore, some special considerations are required when running in a
WebSphere Everyplace Access environment.

In this section we include three sample scenarios to illustrate how you will
configure a WAP Gateway and a WAP proxy using WML fragmentation in a
WebSphere Everyplace Access environment.

Note: A reverse proxy must be properly configured when running portlet
applications using WML fragmentation.


6.2.1 Scenario 1: Using a WAP reverse proxy
In this section we describe a sample scenario for WML fragmentation in a
WebSphere Everyplace Access environment where a WAP proxy is configured
as a reverse proxy. The WAP client device can be connected to this domain in the
following ways:
Using HTTP to the WAP proxy (reverse proxy) using a WAP Simulator. This is
commonly done for application development.
Using a WAP/IP connection to the Everyplace Wireless Gateway (EWG).
Using other WAP connections such as using PPP protocol or LAN.

In this scenario we show you how to configure the WAP Gateway and the WAP
reverse proxy. The sample scenario is illustrated in Figure 6-6.

Everyplace
Wireless Gateway

WebSphere
HTTP HTTP Everyplace Access
WAP
Reverse Proxy and
Gateway

rs615003 m23m3041 m23x303x
9.24.105.119 9.24.106.102 9.24.105.103

WAP/IP Proxy directive:
Proxy /wps/* http://m23x303x/*

WAP Simulator

Figure 6-6 Sample scenario using a reverse proxy

For WAP connections, the Everyplace Wireless Gateway must be configured to
connect to a reverse proxy. The WAP Gateway configuration is shown in
Figure 6-7 on page 152; this option is not available during installation and you will
need to use the Wireless Gateway Administrative Console (Gatekeeper).


Figure 6-7 WAP Gateway configuration to connect to a WAP reverse proxy

When using the WAP Gateway connected to a reverse proxy, the values you
configured in the WAP Gateway are used. This means that any computer name
and port values can be used in the application since they will be replaced. For
example:
<a href="http://xxxx:yy/wps/portal">WEA Portal</a>


Where xxxx is any host name or IP address and yy is the port number. These
values will be replaced with the configured values (9.24.106.102:80 in this
scenario).

Of course, this is not true if you are connected directly to the WAP reverse proxy
using the HTTP protocol. In this case, the application values will be used.

The WAP device in this scenario is not directly connected to WebSphere
Everyplace Access. Therefore, the WAP reverse proxy must be configured to
provide the connectivity to the WebSphere Everyplace Access machine.

For this scenario the WAP reverse proxy is assumed to be configured to listen on
port 80, which is the default port. If using a different port, you will need to
configure the listening port in the port directive in the ibmproxy.conf file. For
example:
Port 80

In addition, you will need to specify the protocols that this proxy server will
forward. For example, to forward all HTTP requests with the string wps in the
link, you configure the proxy directive as follows:

Where m23x303x is the host name (you can also use the IP address) of the
WebSphere Everyplace Access machine and listening port 80.

In this sample scenario, the resulting link to access the portal will be:
http://m23x303x/wps/portal

Therefore, it will reach the target WebSphere Everyplace Access machine.

The same is true for WML fragment links. For example, Figure 6-8 on page 154
shows a WML deck where you can see that, as expected, all references in the
links point to the WAP reverse proxy port 80.

You can also notice that links for WML fragments, when using portal-level
transcoding, have the following format:
http://<computer-name>/wps/TranscodingUtilities/ifrag-......

Because of the configured proxy directive in this sample scenario, the effective
link to access the fragment will result in something similar to the following:
http://m23x303x/wps/TranscodingUtilities/ifrag-......

Therefore, Transcoding Technologies will effectively retrieve the proper
fragment.


Figure 6-8 WML deck in WAP Simulator showing a link for a fragment

Figure 6-9 on page 155 illustrates the option to request a fragment.


Figure 6-9 Requesting a fragment

The WML fragment link can also be monitored when using the Request Viewer
tool. See Figure 6-10.

Figure 6-10 Monitoring fragmentation with Request Viewer tool


6.2.2 Scenario 2: Using a forward proxy
In this section we show a scenario using a forward proxy (see Figure 6-11).

Everyplace
Wireless Gateway

WAP HTTP HTTP
Gateway
Forward Proxy Internet

rs60002 m23m1807
9.24.105.64 9.24.105.225

WAP/IP

WebSphere
HTTP Everyplace Access
WAP Simulator and

m23x303x
9.24.105.103

Figure 6-11 Intranet and Internet access using a forward proxy

The forward proxy in this scenario will give you access to Web sites on the
Internet. However, in this scenario portal-level WML fragmentation takes place
for portlet content in WebSphere Everyplace Access only.

This is a very simple scenario, since no extra configuration is required other than
the WAP Gateway, which needs to be configured to use the WAP forward proxy.
Figure 6-12 on page 157 illustrates the WAP Gateway configuration for this
scenario.


Figure 6-12 WAP Gateway configuration using a forward proxy

Note: In this scenario, URLs and links must include the WebSphere
Everyplace Access computer name and listening port.

6.2.3 Scenario 3: Using a forward proxy and reverse proxy
In this section, we describe a sample scenario for portal-level WML
fragmentation in a WebSphere Everyplace Access environment where a forward
proxy is configured in the WAP Gateway to provide general access to Internet
sites. In addition, a reverse proxy is used to access WebSphere Everyplace
Access portlet content. The scenario is illustrated in Figure 6-13 on page 158.


Everyplace
Wireless Gateway

WAP HTTP HTTP
Gateway
Forward Proxy Internet

rs60002 m23m1807
9.24.105.64 9.24.105.225

WAP/IP

WebSphere
HTTP Everyplace Access
WAP Simulator
Reverse Proxy and

m23m3041 m23x303x
9.24.106.102 9.24.105.103
Proxy directive:

Figure 6-13 Sample scenario using a forward proxy for Internet access

In this scenario, consider the following:
1. The WAP Gateway is configured to use a WAP forward proxy. See
2. Computer names in URLs and links must point to the reverse proxy.
3. The reverse proxy must be configured to forward requests to the WebSphere
Everyplace Access machine. For example, to forward all HTTP requests with
the string wps in the link, you configure the proxy directive as follows:
Where m23x303x is the host name (you can also use the IP address) of the
WebSphere Everyplace Access machine and listening port 80.
4. All fragment requests will be forwarded to portal-level transcoding for
retrieval. The fragment request has the following format:
http://m23x303x/wps/TranscodingUtilities/ifrag-......


Part 3

Part 3 LDAP Directory
services
In this part of the redbook, we provide useful information to support leading
LDAP directories. Guidelines are included to help you install, tailor, and configure
the new IBM WebSphere Everyplace Access product using Lightweight Directory
Access Protocol (LDAP) directories such as IBM SecureWay Directory, iPlanet,
Microsoft Active Directory, and Domino LDAP Directory.

.


7

Chapter 7. IBM SecureWay Directory
services in WebSphere
Everyplace Access
WebSphere Everyplace Access provides the flexibility of supporting various
Lightweight Directory Access Protocol (LDAP) directories. The default LDAP
directory is IBM SecureWay Directory. A typical installation of WebSphere
Everyplace Access could incorporate a local SecureWay LDAP directory.
However, support exists for accessing a remote, pre-existing LDAP directory.

In this chapter, we will discuss how to install and configure WebSphere
Everyplace Access using such a remote IBM SecureWay Directory server. An
installation may be required to use a remote LDAP directory if the customer
wishes to utilize an established LDAP directory in order to keep directory
information in a single repository.

This chapter highlights the differences encountered when using a remote
directory server. For a complete installation of WebSphere Everyplace Access
with a local IBM SecureWay Directory server, see Appendix A, “WebSphere
Everyplace Access sample installation” on page 271.


7.1 Solution architecture
The sample scenario shown in this chapter documents an installation of
WebSphere Everyplace Access using a remote IBM SecureWay Directory.

Windows 2000 Server
Windows 2000 Server

WebSphere Everyplace
LDAP m23x3072.yourco.com Access V4.1.1
SecureWay Port 387
Directory V3.2.2

WebSphere Application
Server V4.0.1

DB2 IBM HTTP Server

m23vnx78.yourco.com

HTTP

Pocket PC
Everyplace client
V8.1
Desktop browser

Figure 7-1 Typical scenario layout using a remote IBM SecureWay LDAP Directory


7.1.1 Specifications for the sample scenario
Specifications for the sample scenario included in this chapter are shown in
Table 7-1.

Table 7-1 Sample scenario specifications
Role WebSphere Everyplace SecureWay Directory
Access Application Server
Server

Machine DNS Name m23vnx78.yourco.com m23x3072.yourco.com

Operating System Windows 2000 Server Windows 2000 Server
Service Pack 2 Service Pack 2

Domain yourco.com yourco.com

Additional Software IBM WebSphere IBM SecureWay Directory
Everyplace Access V4.1.1 Server V3.2.2
eFix 3.2.2-SWD-002

7.2 Installing IBM SecureWay Directory
To set up the environment, you will first need to install and configure IBM
SecureWay Directory. It is important to create the required users and groups in
the LDAP directory before installing WebSphere Everyplace Access.

To install IBM SecureWay Directory, you will use the installation disk for IBM
WebSphere Everyplace Access for Windows, Version 4.1.1 and select only
SecureWay Directory Server. The SecureWay Directory Server also requires the
IBM HTTP Server and DB2 Universal Database Server, and these are
automatically installed.

During the installation process, you are prompted for the directory suffix
information. For this sample scenario environment, you will enter the information
as shown below (see Figure 7-2 on page 164).

Note: In this sample scenario, the SecureWay Directory Server will be installed
listening on port 387, but it is recommended that you use the default port of 389.

Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 163

Figure 7-2 Configuring SecureWay Directory

Once the directory server is running, you will import the LDIF file that created the
desired schema. Itis important to note that the required administrator users and
groups were created; creating some users for testing is also important.

The required users and groups are:
wpsadmin Portal administration user.
wpsbind Used to access the LDAP directory.
wpsadmins The portal administrators group.

Important: The SecureWay Directory Management Tool configuration file,
dmt.conf, needs to be modified if running LDAP on another port, or if
accessing a remote directory.

Tip: To check that the directory server is running, and also to confirm the
schema, you can use the ldapsearch command. See Example 7-1 on
page 166 for the results of a query on our directory server.


7.3 Installing WebSphere Everyplace Access
Installing WebSphere Everyplace Access with a remote directory server requires
the following to be done during the standard install process.

First, when choosing components, ensure that the SecureWay Directory Server
is not selected (Figure 7-3).

Figure 7-3 Select only the required WebSphere components

Later in the installation, when selecting the LDAP server type, choose
SecureWay Directory, and enter the name of the directory server, in our case,
m23x3072.yourco.com. Since our SecureWay Directory Server is listening on
port 387, you also need to change the LDAP port number from the default value
of 389.


Figure 7-4 Selecting SecureWay Directory as the LDAP server

Next, you need to supply the Distinguished Names for the LDAP users, groups
and administrators. If required, the ldapsearch command can be used to confirm
schema details, as shown in Example 7-1.

Example 7-1 Using ldapsearch to confirm LDAP schema.
C:>ldapsearch -h m23x3072 -p 387 -D cn=wpsadmin -w wpsadmin -b
dc=yourco,dc=com cn=* dn

cn=users, dc=yourco, dc=com
cn=groups,dc=yourco,dc=com
uid=wpsadmin,cn=users,dc=yourco,dc=com
uid=wpsbind,cn=users,dc=yourco,dc=com
cn=wpsadmins,cn=groups,dc=yourco,dc=com
uid=Kelly,cn=users,dc=yourco,dc=com
uid=Greg,cn=users,dc=yourco,dc=com
...


Selecting one of the user records returned, you can determine the User DN
prefix, as well as the User DN suffix. For example, given the following record:
uid=wpsadmin,cn=users, dc=yourco,dc=com

you can see the User DN prefix is uid , and the User DN suffix is cn=users,
dc=yourco,dc=com

Similarly, looking at a group entry:
cn=wpsadmins,cn=groups, dc=yourco,dc=com

the Group DN prefix is cn, and the Group DN suffix is cn=groups,
dc=yourco,dc=com

Using the results from the example above, you can then confirm the details in the
LDAP Configuration window.

Figure 7-5 Confirming LDAP configuration details


After clicking Next, you will be required to enter the directory in which the
SecureWay Directory client will be installed. Following this, continue with the
installation process. You will be prompted to configure the administration role for
the WebSphere Application Server. For details, see Appendix A, “WebSphere
Everyplace Access sample installation” on page 271.

In the Security Center of the Administrative Console, confirm the details on the
Authentication tab (Figure 7-6). The LDAP Settings field entries should
correspond to the remote Directory server, in our case, m23x3072.yourco.com,
port 387.

Figure 7-6 Confirming the LDAP settings in the Administrative Console

Selecting the Administrative Role tab, assign users and groups to the
AdminRole, as shown in Figure 7-7 on page 169.


Figure 7-7 Assigning users and groups to the AdminRole

7.4 Sample applications
Included with IBM WebSphere Everyplace Access are two applications that you
can use to illustrate how WebSphere Everyplace Access and IBM SecureWay
Directory are easily integrated.

First, you will configure the LDAP Search portlet and search the directory for a
specific user, and secondly, you will use the DB2 Everyplace sample application,
Visiting Nurse, to show a more complex scenario involving IBM SecureWay
Directory.

7.4.1 Configuring the LDAP Search portlet
As part of the default WebSphere Everyplace Access installation, an LDAP
search portlet is provided. This allows portal users to search the LDAP directory,
returning such information as department, telephone number and e-mail
address.

Initially, the portlet contains no LDAP directory server information, and needs to
be configured. To access and configure the portlet:
1. Select the Productivity page from WebSphere Everyplace Access Home.
2. Click the Edit button in the title bar to display the settings for the LDAP
search.


3. Enter the LDAP server name.
If your LDAP is not installed on the default port of 389, you will also need to
specify the port number.
In our case, this is m23x3072.yourco.com:387
4. Enter the Directory Name. This matches your LDAP schema, for example
dc=yourco,dc=com

If desired, you can also change some of the search parameters.

Figure 7-8 Entering required directory information for the LDAP Search portlet

5. Click Save to complete the configuration.

With the portlet configured, you can now search the LDAP, with a typical result
shown in Figure 7-9 on page 171.


Figure 7-9 Typical LDAP search results

7.4.2 Using IBM DB2e with a remote SecureWay Directory server
In this example, you will use IBM DB2 Everyplace with a remote IBM SecureWay
Directory server.

Note: The application used in this sample scenario, Visiting Nurse, is supplied
with DB2 Everyplace.

This example shows how to configure the server and Pocket PC for this
application; a more in-depth look at DB2 Everyplace can be found in Chapter 1,
“Synchronizing with DB2 databases” on page 3.

First, you will need to create a synchronization group. The members of this group
are all users who need to synchronize with the DB2 Everyplace Sync Server.

In this sample scenario, the default synchronization group name SyncGroup is
used. For example:
1. Create a user group called SyncGroup.
a. From Portal Administration, select the Users and Groups page and click
the Manage User Groups tab.
b. In the Group name field, type SyncGroup and click Create Group.


2. Add all your users to the group who will be using DB2 Everyplace.
a. With SyncGroup highlighted in the User Groups pane, click Membership.
b. Search for either the users or groups you wish to add, then highlight the
entries in the Search Results pane, and click Add to Group.
The names and groups should now appear in the Members Belonging to
Group -- SyncGroup pane (Figure 7-10). Figure 7-11 on page 173 shows
the same group, as displayed via the SecureWay Directory Management
Tool (DMT).
c. When all required users and groups are added, click OK to save the
group.

Figure 7-10 All the required users are added to the SyncGroup via the portal


Figure 7-11 The same SyncGroup as viewed via the SecureWay DMT

The next element required for synchronization is the DB2e group. Since you are
using the sample application Visiting Nurse, you will choose to create a group as
described here. The naming convention requires the group to start with DB2e.
3. Create a DB2e group called DB2e_Nurse.
Following a similar sequence as in step 1 above, create a group called
DB2e_Nurse.
4. Populate the group with the users and groups who will be using your DB2e
application.
Follow the steps for populating a group as shown above in step 2. When
completed, it will look similar to Figure 7-12 on page 174.


Figure 7-12 DB2e_Nurse membership

With the synchronization and DB2e groups populated, you will need to create the
subscriptions using the Mobile Devices Administration Center (MDAC).

Tip: When starting MDAC, ensure that you are logged in with sufficient DB2
access rights.

5. Click Start -> Programs -> IBM Everyplace Synchronization Server ->
Launch MDAC.
Log in specifying your WebSphere Portal server LDAP logon, wpsadmin, and
your Everyplace Synchronization group that you created in step 1 on
page 171, SyncGroup. This will then connect via a SOAP RPC to the
SecureWay Directory server for authentication (Figure 7-13 on page 175).


Figure 7-13 Connecting to MDAC specifying the SyncGroup

Once MDAC has loaded, verify the DB2e groups and users have been imported.
To do this:
6. Click Groups.
The DB2e_Nurse group should be present, as shown below in Figure 7-14.

Figure 7-14 Verifying the required groups are available in MDAC


7. Click Users.
All the users who are members of SyncGroup will appear in this folder. After
you have created a subscription, and the users have connected, this view will
also show their device type and device ID. See Figure 7-20 on page 180 to
see where this is configured.

Figure 7-15 Verifying the users are imported into MDAC

Next, you will need to create a subscription which will enable our users to
connect to the database tables you specify. The Visiting Nurse sample
application provides a suitable JDBC subscription; all you need to do is link it to
the DB2e group.

At this time, you can confirm the details of the supplied subscription:
a. Click the Subscriptions folder.
b. Right-click JDBCSUB1 and select Edit....
c. On the Identification tab, click Define subscription...; you can see what
tables will be synchronized (Figure 7-16 on page 177).
d. Click Cancel to close the pop-up window.


Figure 7-16 Determining the tables that are synchronized

e. Select the Source tab; in the Database URL field, it shows the VNURSE
database is the source database for this subscription.

Figure 7-17 Confirming the source database

f. On the Subscription sets tab, confirm that the subscription set
SUBCRIPTION_SET1 is in the right-hand pane.


Figure 7-18 Assigning a subscription set to a subscription

g. Click Cancel to close the subscription. If you made any changes you wish
to keep, click OK.

Next, you will need to assign the DB2e group to the subscription set assigned to
the Visiting Nurse database.
8. Click the Subscription sets folder.
9. Right-click SUBSCRIPTION_SET1 and select Edit...
10.On the Groups tab, from the Available Groups pane, highlight DB2e_Nurse
and click > to move it into the Selected Groups pane, as shown in Figure 7-19
on page 179.


Figure 7-19 Assigning our DB2e group to the subscription set

11.Click OK to close the subscription set window.
Now that you have completed the subscription, you will need to configure the
client on the Pocket PC.
12.Start the Everyplace Client, and the User Options window will be displayed.
If the user options are not displayed, you can view the user options by clicking
Tools -> User Options.
13.Enter the WebSphere Everyplace Access information.
You will need to enter a user ID that exists in the SyncGroup, as created in
step 2 on page 172.
14.Click OK to close the window.
Next, you will need to confirm the DB2 Everyplace Sync information. This is
automatically populated with the User Options entered previously.
15.Highlight DB2 Everyplace Sync and from the menu, select Tools ->
Configure.
On this window, you can configure the User ID and password, as well as the
Device ID. The supplied values are acceptable, and the User ID specified
here must belong to a DB2e group. Our user is a member of the DB2e_Nurse
group, as created earlier in step 4 on page 173.
16.Click the Subscription List tab.
This list is empty since you have not yet completed a synchronization.
17.Click OK to close the DB2 Everyplace Sync window.


Figure 7-20 Steps to configure the Everyplace Client on the Pocket PC

18.To initiate a synchronization, click the Execute button.

Once the synchronization is completed, the status is updated, as shown in
Figure 7-21.

Figure 7-21 Completion of a successful synchronization


Now you can check the Subscription List tab, and confirm that the
SUBCRIPTION_SET1 is shown.
19.Click Tools -> Configure, and select the Subscription List tab.
You can see that SUBSCRIPTION_SET1 was correctly added to the list.

Figure 7-22 Confirming the synchronization picked up the subscription

This successful synchronization will also have updated our Users view in MDAC
with the device type, device ID and the version of Everyplace Sync client.
20.If required, restart the MDAC application as shown in step 5 on page 174.
21.Click the Users folder in MDAC.
You can see that the details for our user Kelly have been updated.

Figure 7-23 User details in MDAC showing a user that has connected


Now that the Pocket PC device is synchronizing, you can use the Visiting Nurse
sample application to confirm that data entered on the Pocket PC is getting
synchronized with the DB2 database.
22.Start the Visiting Nurse application on the Pocket PC.
a. Click Start, and select Programs.
b. Open the DB2 Everyplace Samples folder and click VNurse.
23.Select a patient, and create a new medical record. An example is shown in
Figure 7-24. To do this:
a. Highlight a patient’s name and click the Info button.
b. On the Personal Information page, click the Records button.
c. Add a new medical record by clicking Add.
d. Once you have filled out the record, click Save.

Figure 7-24 Creating a record in the Visiting Nurse application

24.Close the Visiting Nurse application.


25.Start the Everyplace Client and initiate a synchronization.
a. Click Start and select Everyplace Client from the menu.
b. Click the Execute button.

Upon successful completion of the synchronization, the records will be replicated
to the source database as defined in the JDBC subscription. One method to
confirm that the new record was added to the DB2 database is to sample the
table contents using the IBM DB2 Control Center as shown in Figure 7-25.

Figure 7-25 The new record in the DB2 database after synchronization

Observation: IBM Directory Server provides a powerful LDAP infrastructure
that is using the reliable IBM DB2 Universal Database engine, which provides
scalability to tens of millions of entries, as well as groups of hundreds of
thousands of members.


7.5 Recommendations, hints and tips
A critical element when installing WebSphere Everyplace Access is
understanding the LDAP directory schema. You need to know both the User DN
prefix and suffix, as well as the Group DN prefix and suffix.

You also need to confirm that the User DN and password used when selecting
the LDAP server type are correct. This can be checked using the ldapsearch
command (Example 7-1 on page 166).

More information on IBM SecureWay Directory is available with the
documentation provided with the software. The Getting Started guide, as well as
a server and client readme file, can be viewed by clicking Start -> Programs ->
IBM SecureWay Directory.

The Getting Started guide also provides further links to product documentation.


8

Chapter 8. iPlanet Directory services in
Access
In this chapter, we discuss how WebSphere Everyplace Access can be
integrated with an existing iPlanet Directory Server using the Lightweight
Directory Access Protocol (LDAP).

The incorporation of LDAP support in IBM WebSphere Everyplace Access allows
both user and group information to remain in a pre-existing iPlanet Directory
Server, while still keeping the same interface and functionality in WebSphere
Everyplace Access.

We cover a typical scenario, stepping through how the iPlanet Directory is
configured and how WebSphere Everyplace Access is installed to access this
LDAP directory.

We also cover how to configure the LDAP Search portlet, which is installed by
default with WebSphere Everyplace Access.

This chapter covers areas where information specific to supporting iPlanet is
applicable. Once the servers are set up and configured, user and group
management is unaffected by the underlying LDAP directory server, and thus is
not covered.


The sample scenario shown in this chapter documents an installation of
WebSphere Everyplace Access using an iPlanet Directory for the management
of the portal’s users and groups. As illustrated in Figure 8-1, the iPlanet Directory
Server is hosted on a separate server from WebSphere Everyplace Access.

Windows 2000 Server
Windows 2000 Server

iPlanet m23x2501.itso.ral.ibm.com Access V4.1.1
Directory Server Port 388
V5.1

Server V4.0.1

LDBM IBM HTTP Server

m23vnx78.itso.ral.ibm.com

HTTP

Pocket PC
Everyplace client
V8.1
Desktop browser

Figure 8-1 iPlanet Directory Server solution architecture

Since iPlanet Directory Server provides global directory services, it can be used
by many applications that implement LDAP, and can be used as a single
repository for directory information.

An iPlanet Directory Server installation includes the directory, the LDAP server
side software, and a user interface that allows for the management and search of
entries in the directory.


8.1.1 Specifications for the sample scenario
Specifications for the sample scenario included in this chapter are shown in
Table 8-1.

Table 8-1 Sample scenario specifications
Role WebSphere Everyplace iPlanet Directory Server
Access Application Server

Machine DNS Name m23vnx78.itso.ral.ibm.com m23x2501.itso.ral.ibm.com


Domain itso.ral.ibm.com itso.ral.ibm.com

Additional Software IBM WebSphere Everyplace iPlanet Directory Server
Access V4.1.1 V5.1

8.2 Installing and configuring iPlanet Directory
In this section, a sample iPlanet installation and configuration are included.

8.2.1 Installing iPlanet Directory
A typical iPlanet server install is shown in this section. The iPlanet product is
installed using most of the default settings and directories. Following are the
installation steps, and where appropriate, windows showing information specific
to this environment.

Note: The iPlanet Directory Server is installed here listening on port 388 to
avoid conflicts with other LDAP servers. However, a typical installation would
probably use the default port 389.

1. Log in to the server as a user with administrator privileges.
2. Run the setup program, and after viewing the Welcome window, click Next to
continue.
3. When prompted, select iPlanet Server installation.
4. Next, choose a Typical installation.
5. Accept the default directory for the installation, and continue.
6. Select the required components and continue.
Note: In this sample installation, all components are selected.

Chapter 8. iPlanet Directory services in WebSphere Everyplace Access 187

7. For the configuration directory, select This instance will be the
configuration directory server.
If this directory server is not the configuration directory server, select the
configuration directory at this point. The configuration server must be running
for the installation to continue.
8. Choose the default entry Store data in this directory server.
The option for storing data in another directory server is used if this instance
is a configuration server only.
9. Next, you will need to enter the server settings (see Figure 8-2).
For Server Identifier, choose the default. Is this case it is our machine
hostname, m23x2501.
The server port, normally the default of 389, is suitable, but in this sample
installation, port 388 is used.
The suffix should correspond to your Internet DNS name. In this case, it is
dc=itso,dc=ral,dc=ibm,dc=com
Click Next to continue.

Figure 8-2 Server settings for our iPlanet Directory server

10.For the Configuration Directory Administrator ID and password, enter the user
name and password you will use when logging in to the iPlanet Console.
11.For the Administration domain, you will accept the default value, in this case,
itso.ral.ibm.com (Figure 8-3 on page 189). Since you only have one instance
of the iPlanet server, you do not need to be concerned with establishing other
administrative domains.


Figure 8-3 Setting the Administration domain

12.For the Directory Manager DN, accept the suggested value, cn=Directory
Manager, and enter a suitable password.
13.For the Administrative port selection, again the default value is accepted.
14.Following this, the summary is displayed. Click Install when you are ready to
begin the product installation.

At the completion of the installation, the product has built a basic directory tree
that contains server-related data. In order to use the iPlanet directory server with
WebSphere Everyplace Access, you will need to configure iPlanet as described
in 8.2.2, “Configuring iPlanet for WebSphere Everyplace Access” on page 189.

More information about the deployment and installation of iPlanet Directory
Server V5.1 can be found at the Sun Product Documentation Library at:
http://docs.sun.com/?q=iplanet&p=/coll/S1_ipDirectoryServer_51

8.2.2 Configuring iPlanet for WebSphere Everyplace Access
Once the iPlanet directory service is running, you will need to create some
entries for administrators and user groups. These must be created before
installing WebSphere Everyplace Access.
1. Start the iPlanet Console
a. Click Start -> Programs -> iPlanet Server Products -> iPlanet Console
5.1
b. Log in using the Configuration Directory Administrator ID as defined during
installation step 10 on page 188.


2. Create a user record for wpsadmin.
a. Click the Users and Groups tab.
b. From the menu, select User -> Create -> User....
c. From the Select Organizational Unit window, highlight People and click
OK.
When selecting the organizational unit to create the user, a useful feature
is a pop-up showing the DN for the type of unit highlighted. The window
shown in Figure 8-4 confirms the structure when adding a user to the
directory. Alternatively, clicking Show DNs will display each organizational
unit as its Distinguished Name.

Figure 8-4 Schema pop-up confirming directory structure

d. In the Create User window, enter the details for the wpsadmin user. This is
the user you will use for portal administration (Figure 8-5 on page 191).

Tip: Make sure the user ID is wpsadmin. When generating the user ID, iPlanet
will combine the first letter of the first name with the last name. In this
example, it would create wwpsadmin. You will need to correct the default user
ID generated.


Figure 8-5 Creating the wpsadmin user in iPlanet

3. Create a user record for wpsbind.
Follow the same steps as you did when creating the wpsadmin user above.
4. Create an administrators group, wpsadmins, and add wpsadmin and wpsbind
as members.
a. Click the Users and Groups tab.
b. From the menu, select User > Create > Group....
c. From the Select Organizational Unit window, highlight Groups and click
OK.
d. In the Create Group window, enter wpsadmins as the group name, as well
as a suitable description.
e. In the left-hand pane, click Members.
f. Click Add; this will bring up a window for searching users and groups.
g. Click Search; when complete, select wpsadmin and wpsbind and click
OK.
h. With both users added (Figure 8-6 on page 192) click OK to finish creating
the group.


Figure 8-6 Adding the wpsadmin and wpsbind users to the portal administrators group

With these users and groups in the LDAP directory, you can now begin the
installation of WebSphere Everyplace Access.

Installing WebSphere Everyplace Access with a remote iPlanet Directory Server
requires only minimal changes from the typical installation (see Appendix A,
“WebSphere Everyplace Access sample installation” on page 271).
1. When selecting which components to install, ensure that SecureWay
Directory Server is not selected (Figure 8-7 on page 193). The installation of
the local LDAP is not required, since in this case the LDAP directory is
provided by the iPlanet Directory Server.


Figure 8-7 Select only the required WebSphere components

2. Later in the installation, you are prompted for the LDAP server type
(Figure 8-8 on page 194). Select iPlanet and enter the details of your server,
as shown below:
a. LDAP Server
The address of your iPlanet Directory Server. For example:
m23x2501.itso.ral.ibm.com
b. User DN
This corresponds to the administrator details selected when configuring
the iPlanet Directory Server (see installation step 10 on page 188). For
example:
uid=administrator,ou=administrators,ou=TopologyManagement,o=NetscapeRoot
c. User password
Enter and confirm the password for the user specified above.
d. Suffix
The suffix for your iPlanet Directory Server. This was specified during the
iPlanet Directory Server installation, step 9 on page 188. In this example, it
is dc=itso,dc=ral,dc=ibm,dc=com.


e. LDAP port
The port the LDAP server is using. This is the port value entered during
the iPlanet Directory Server installation (see step 9 on page 188), for
example port 388.

Figure 8-8 Selecting iPlanet as the LDAP server

3. In the next window, you will be prompted for the LDAP configuration
information (Figure 8-9 on page 195). This must match your LDAP directory
schema. You can confirm this information by executing the ldapsearch
command, as shown below:

Example 8-1 Using ldapsearch to confirm LDAP schema
c:>ldapsearch -h m23x2501 -p 388 -D
uid=administrator,ou=administrators,ou=TopologyManagement,o=NetscapeRoot -w
password -b dc=itso,dc=ral,dc=ibm,dc=com cn=* dn

uid=wpsadmin,ou=People, dc=itso,dc=ral,dc=ibm,dc=com
uid=wpsbind,ou=People, dc=itso,dc=ral,dc=ibm,dc=com
cn=wpsadmins,ou=Groups, dc=itso,dc=ral,dc=ibm,dc=com
uid=Kelly,ou=People, dc=itso,dc=ral,dc=ibm,dc=com
uid=Greg,ou=People, dc=itso,dc=ral,dc=ibm,dc=com
...


Selecting one of the user records returned, you can determine the User DN
prefix, as well as the User DN suffix. For example, given the following record:
uid=wpsadmin,ou=People, dc=itso,dc=ral,dc=ibm,dc=com
we can see the User DN prefix is uid, and the User DN suffix is ou=People,
Similarly, looking at a group entry:
cn=wpsadmins,ou=Groups, dc=itso,dc=ral,dc=ibm,dc=com
the Group DN prefix is cn, and the Group DN suffix is ou=Groups,
Using results similar to those shown in the example, the LDAP configuration
information can be confirmed, and the installation can continue by clicking
Next.

Figure 8-9 Confirming LDAP configuration details

During the installation, you will be prompted to configure the administration role
for the WebSphere Application Server. This is completed as per the standard
installation, and checking the Authentication tab in the Security Center, you
should see the correct details in the LDAP Settings fields (Figure 8-10 on
page 196).


Figure 8-10 Confirming the LDAP settings in the Administrative Console

Once the installation process is complete, WebSphere Everyplace Access will be
running, and will be using the iPlanet Directory server for user authentication and
for managing user and group information.

As an example of how you might configure a portlet to query an iPlanet directory
server, an example of how to configure the LDAP search portlet is included in this
section.

Provided with the standard WebSphere Everyplace Access installation is an
LDAP Search portlet that allows portal users to search the LDAP directory. The
search can be performed using various attributes and will return selected user
information such as name, department, telephone number and e-mail address.


The portlet will need to be configured for a specific LDAP directory, and this can
be done either by an individual user who has the proper access rights, or by the
Portal server administrator. Configuration performed by the administrator, via
Work with Pages, will make the portlet configured by default for users. In this
example, you will configure the portlet as the administrator, keeping in mind that
the same configuration information is applicable to the individual user who has
the access rights to edit the portlet.
1. Log in to the WebSphere Everyplace Access server with administration rights.
2. Select Work with Pages.
3. Select WebSphere Everyplace Access Home from the Place drop-down
menu.
4. Select Productivity from the Page drop-down menu.
5. Click the Edit portlet icon for the LDAP Search portlet (Figure 8-11).

Figure 8-11 Editing the LDAP Search portlet


6. This will bring up the properties for the portlet (Figure 8-12) where the LDAP
details are entered. The required information is the server name and the
directory name.

Figure 8-12 Entering in the LDAP server properties in the portlet

a. Optional Display Name
This will appear in the portlet’s title bar. Enter something descriptive or
leave it blank.
b. Server Name
The address of the LDAP directory server. In this case, you want to search
the iPlanet Directory Server. Since you are not using the default LDAP port
of 389, you will need to specify the port, for example:
m23x2501.itso.ral.ibm.com:388
c. Directory Name
This corresponds to the suffix for your iPlanet Directory server, for
example dc=itso,dc=ral,dc=ibm,dc=com.
The remaining parameters are used to set up the default search criteria. You
may choose to make Last Name the default field to search on, for example.
7. Click Save to save and close the properties box.

The portlet is now configured, and users can perform searches on the LDAP
directory (Figure 8-13 on page 199).


Figure 8-13 Results of doing a wildcard search on the LDAP directory

Observations: Using IBM WebSphere Everyplace Access with an iPlanet
Directory Server provides a transparent solution for user authentication and
user management.

The implementation of LDAP allows WebSphere Everyplace Access to have a
common look and feel regardless of the underlying LDAP directory.


8.5 Recommendations, hints and tips
The most critical element when installing WebSphere Everyplace Access is an
understanding of the LDAP directory schema. You need to know both the user
DN prefix and suffix, as well as the group DN prefix and suffix.

You also need to confirm that the user DN and password used when selecting
the LDAP server type is correct. This can be checked by the use of the
ldapsearch command (Example 8-1 on page 194).

For more information and product documentation on iPlanet Directory Server
V5.1, see the Sun Documentation Library at:


9

Chapter 9. Active Directory services in
Access
In this chapter, we discuss the interoperability between WebSphere Everyplace
Access and an external Active Directory server using the Lightweight Directory
Access Protocol (LDAP).

We explain how to install and configure the Active Directory server and how to
install the WebSphere Everyplace Access to access this LDAP directory. We
also include sample applications in order to verify this installation.


9.1 Active Directory overview
Active Directory is the directory service provided by Windows 2000 Server that
allows you to store information of objects in the network (including users, files,
printers, servers, domains, etc.) and to make this information available to other
authorized users, therefore simplifying the access and management of these
network resources.

Active Directory requires a Domain Name System (DNS) to allow clients to locate
the Active Directory server and resources, by resolving domain names to IP
addresses. It uses the Lightweight Directory Access Protocol (LDAP) to allow
access to data stored in this directory. In addition, it must reside on a domain
controller server.

The scenario described here consists of an Active Directory server configured
with the necessary options to allow it to be an external directory service of a
WebSphere Everyplace Access server. The sample scenario is illustrated in
Figure 9-1.

Windows 2000 Server
Windows 2000 Server

Active m23x3072.yourco.com Access V4.1.1
Directory Port 389
Server V5.0

Server V4.0.1 DB2

IBM HTTP Server

m23x2676.yourco.com

HTTP

Pocket PC

Everyplace client
V8.1
Desktop browser

Figure 9-1 WebSphere Everyplace Access with Active Directory - sample scenario


The sample scenario described in this chapter includes the installation and
configuration of the Active Directory server and additional steps required to
properly install WebSphere Everyplace Access server with an external Active
Directory server.

9.2.1 Specifications for the scenario
The configuration values for this sample scenario are shown in Table 9-1.

Table 9-1 .Configuration values
Role Application Server Active Directory Server

Machine DNS Name m23x2676.yourco.com m23x2672.yourco.com

IP address 198.168.10.11 198.168.10.5



Domain Role Member Server Domain Controller
Domain Name System (DNS)

Additional Software IBM WebSphere Everyplace
Access V4.1.1

Additional Windows 2000 Active Directory
Components Windows 2000 Support Tools
Windows 2000 Administrative Tools

9.3 Installing and configuring Active Directory
The following is a typical Active Directory installation with the required options to
fulfill the specifications described above. It is necessary to be logged on with
administration privileges in the server to start the installation.
1. Run the dcpromo command to launch the Active Directory Installation wizard
and click Next to continue.
Start > Run > dcpromo
2. As the Active Directory installation become the server in a Domain controller,
you need to specify an existing domain or create a new one. In this scenario,
you do not have a domain created, and therefore you must select to become
a server in a Domain controller for a new domain.
3. Select Create a new domain tree.

Chapter 9. Active Directory services in WebSphere Everyplace Access 203

4. Select Create a new forest of domain trees.
5. Enter the Full DNS name for new domain, in this case, yourco.com.
6. Leave the default value for the Domain NetBIOS name (YOURCO for this
installation).
7. Accept the default values for Active Directory database and log locations, in
some cases you will need to consider changing these values if required.
8. Accept the default folder location to be shared as the system volume or
choose a new location.
9. Active Directory needs a DNS server to work correctly but actually our
scenario does not have one. A warning message will appear stating that the
Active Directory wizard cannot contact the DNS server that handles the
selected domain name. Click OK and choose the option to install a DNS
server on the computer.
Note: You can always configure a DNS at a later time, but for purpose of this
scenario the Windows 2000 DNS server installation option is selected during
the Active Directory installation.
10.For the user and group objects permissions, select the default option,
Permissions compatible with pre-Windows 2000 servers. In this scenario it is
valid to select Permissions compatible only with Windows 2000 servers.
11.Enter an Administrator password.
12.Review the installation summary, and click Next when you are ready to begin
the installation.


Figure 9-2 Installation summary for Active Directory

13.When the installation is completed, click Finish to close the Active Directory
Installation wizard.
14.Restart your computer.

9.3.1 Installing Windows 2000 support and administration tools
This section contains installation instructions for the Windows 2000 tools used in
the scenarios described in this chapter.

Windows 2000 support tools
The Windows 2000 Support Tools contain the ADSI Edit MMC snap-in tools, that
will be used in this chapter.

Note: The ADSI Edit MMC snap-in is a tool that allows you to add, delete, edit or
move objects (such as users and groups) of the Active Directory.


You will need to follow these steps to install these support tools. However, it is
necessary that you are logged on the server with administration privileges to
begin the installation.
1. Run the following command from your Windows 2000 CD-ROM:
<CD drive>:SUPPORTTOOLSSETUP.EXE
2. Supply the user information (name and organization name).
3. Select Typical as the installation type.
4. Click Next to begin the installation.
5. Click Finish to close the Installation wizard at the end of the Support Tools
installation.

Windows 2000 administration tools
The Windows 2000 administration tools includes the Active Directory Users and
Computers management console, required in this chapter.

Note: The Active Directory Users and Computers is a management console
used to administer data in the directory server.

Follow these steps to install the administration tools:
1. Run the following command:
C:WINNTSystem32adminpak.msi
2. Select Install all of the Administrative Tools.
3. When the installation ends, click Finish to close the wizard.

Before you can use the ADSI Edit MMC snap-in tool, you will also have to
register the schmmgmt.dll. To register the DLL file, run the following command:
regsvr32 schmmgmt.dll

9.3.2 Verifying Active Directory server installation
It is recommended that you verify that Active Directory and DNS are working
correctly before continue with the WebSphere Everyplace Access installation.

As Active Directory needs the support of a DNS, you should ensure that there
are no problems with the DNS service in your server. One of the steps you must
do to verify this in a Windows 2000 DNS server is confirm that the DNS service
location records for the new domain controller have been created. For example:
1. Start the DNS Administrator Console. Click Start > Programs >
Administrative Tools > DNS.


2. Expand your server name folder (m23x2672 in this case), expand the
Forward Lookup Zones folder and expand your domain name folder
(yourco.com for this scenario).
3. The following folders must be present: _msdcs, _sites, _tcp, and _udp. These
folders and the service location records they contain are critical to Active
Directory operations.

Note: This is not the only procedure to ensure Windows 2000 DNS server is
working correctly. There are many additional steps to verify the correct
working of the DNS server, and the steps may be different depending on the
DNS server model you are using. Refer to the documentation of your DNS
server for more details about procedures to verify your DNS is correctly
configure.

A quick way (not necessarily the only way) to verify if your Active Directory is
working correctly is by adding a new machine to the domain. In this sample
scenario you will need to add the WebSphere Everyplace Access server
machine to the new domain created for this scenario (yourco.com). If the
WebSphere Everyplace Access machine appears in your Active Directory Users
and Computers management console in the Computers folder, and you can log
in the domain from the WebSphere Everyplace Access machine, the Active
Directory could probably be working correctly.


Figure 9-3 Active Directory Users and Computers management console

9.3.3 Configuring Active Directory for WebSphere Everyplace Access
It is necessary to create some users and groups in the Active Directory before
beginning the WebSphere Everyplace Access installation. These are the
WebSphere Everyplace Access administrator users and groups that must be in
the LDAP server so that WebSphere Everyplace Access can validate them when
required.

Table 9-2 and Table 9-3 on page 209 summarize the groups and users, used
during WebSphere Everyplace Access installation, that must be configured in
Active Directory.

Table 9-2 Groups needed for WebSphere Everyplace Access installation
Group name Description Member of

wpsadmins WebSphere Everyplace Administrators group
Access administrative
group


Table 9-3 Users needed for WebSphere Everyplace Access installation
User name Description Member of

wpsadmin WebSphere Everyplace wpsadmins group
Access administrator user

wpsbind User for WebSphere wpsadmins group
Everyplace Access
security purposes. (to bind
between WebSphere
Everyplace Access and
LDAP)

For example, follow these suggested steps to create groups and users:
1. Start the Active Directory Users and Computers tool.
a. Log in to the server as a user with administrator privileges.
b. Click Start -> Programs -> Administrative Tools -> Active Directory
Users and Computers.
c. Expand the contents of the domain name you created (yourco.com in this
case) in the left-pane tree view as shown in Figure 9-4.

Figure 9-4 Active Directory Users and Computers tool


2. Create the administrator group wpsadmins.
a. Right-click the Users folder, select New, and then click Group.
b. In the New Object-Group window, enter the details for the wpsadmins
group (Figure 9-5).

Figure 9-5 Creating the wpsadmins group in Active Directory

c. Click OK to create the group.
d. Right-click the wpsadmins group recently created and select Properties.
e. Select Member Of tab and click Add.
f. Select the Administrators group in your domain, click Add and click OK
(Figure 9-6 on page 211).


Figure 9-6 Including wpsadmins in Administrators group

g. Click OK.
3. Create the administrator user wpsadmin.
a. Right-click the Users folder, select New, and then click User.
b. In the New Object-User window, enter the details for the wpsadmin user


Figure 9-7 Creating wpsadmin user in Active Directory

c. Type the password for this user and click Next.
d. Review the summary for the new user and click Finish.
e. Right-click the webadmin user recently created and select Properties.
f. Select the Member Of tab and click Add.
g. Select the wpsadmins group in your domain, click Add and click OK


Figure 9-8 Including wpsadmin user in wpsadmins group

h. Click OK.
4. Create the administrator user wpsbind.
Follow the same steps as you did when creating the wpsadmin user above.

9.3.4 Obtaining the LDAP schema for Active Directory
One way to obtain the LDAP directory schema for your Active Directory server is
to use the ADSI Edit MMC snap-in. This tool show objects of the Active Directory
in a hierarchical tree, allowing you to manipulate them.

For example, to obtain the Distinguished Name (DN) prefix and suffix of the user
wpsadmin created previously in the Active Directory, you could do the following:
1. Open the ADSI Edit MMC snap-in tool by clicking Start -> Programs ->
Windows 2000 Support Tools -> Tools -> ADSI Edit.
2. Find the wpsadmin user in the left-hand tree pane.
a. Expand the Domain NC container.
b. Expand the Domain DN where the user was created, in this case
DC=yourco,DC=com


c. Expand CN=Users; the CN=wpsadmin object must be below it.

Figure 9-9 ADSI Edit MMC snap-in

3. Obtain the Distinguished Name (DN).
The Distinguished Name of the wpsadmin user can be obtained by joining in
reverse order the objects to which the wpsadmin user belongs.
In this case, the DN of wpsadmin is:
cn=wpsadmin,cn=Users,dc=yourco,dc=com
The User DN prefix is: cd
The User DN suffix is: cn=Users,dc=yourco,dc=com

In the example below, it is fairly simple to obtain the DN of the administrator user
and wpsadmins group. For example:
The DN of the Administrator user is:
cn=Administrator,cn=Users,dc=yourco,dc=com


The DN of the wpsadmins group is:
cn=wpsadmins,cn=Users,dc=yourco,dc=com

Another way to obtain the LDAP directory schema for your Active Directory
server is to use the ldifde command, as shown in Figure 9-10.

Figure 9-10 Executing ldifde command

This command returns a LDIF file that contains all the users in the Active
Directory. If you open this file (output.ldf in this case), you will be able to obtain
the Distinguished Name of the users. For example:
dn: CN=Users,DC=yourco,DC=com
changetype: add
cn: Users
description: Default container for upgraded user accounts
distinguishedName: CN=Users,DC=yourco,DC=com
dSCorePropagationData: 20020912153740.0Z
instanceType: 4
name: Users
objectCategory: CN=Container,CN=Schema,CN=Configuration,DC=yourco,DC=com
objectClass: container
showInAdvancedViewOnly: FALSE
systemFlags: -1946157056
uSNChanged: 3218
uSNCreated: 1314
whenChanged: 20020912153740.0Z
whenCreated: 20020906143204.0Z


dn: CN=wpsadmin,CN=Users,DC=yourco,DC=com
changetype: add
accountExpires: 9223372036854775807
adminCount: 1
cn: wpsadmin
codePage: 0
countryCode: 0
displayName: wpsadmin
distinguishedName: CN=wpsadmin,CN=Users,DC=yourco,DC=com
instanceType: 4
name: wpsadmin
objectCategory: CN=Person,CN=Schema,CN=Configuration,DC=yourco,DC=com
objectClass: user
sAMAccountName: wpsadmin
sn: wpsadmin
userAccountControl: 66048
userPrincipalName: wpsadmin@yourco.com
uSNChanged: 2810
uSNCreated: 2787
whenChanged: 20020906145631.0Z
whenCreated: 20020906145534.0Z
....

If you select wpsadmin, the DN for this user is the row named “dn:”. In this case,
the created value is CN=wpsadmin,CN=Users,DC=yourco,DC=com

Note: During the WebSphere Everyplace Access installation, you will need
information about your LDAP schema.

The WebSphere Access installation using a remote Active Directory server is
similar to a typical installation using IBM SecureWay LDAP services. However,
there are considerations you must be aware of:
1. When you have to select the desired WebSphere Everyplace Access
components and subcomponents to install, do not select SecureWay
Directory Server.
Note: The SecureWay Directory is the default LDAP server provided by
WebSphere Everyplace Access and can be installed locally or on a remote
server.
In this sample scenario, Active Directory has already been installed as a
remote LDAP server, and therefore you do not need to install SecureWay
Directory. Figure 9-11 on page 217 illustrates this option.


Figure 9-11 Selecting WebSphere Everyplace Access install components

2. In the LTPA password window, you will be prompted to enter the LTPA
password. You must enter the password of the bind user you previously
created; this is wpsbind.
3. Later in the installation, in the LDAP server type selection window, enter the
following configuration values (Figure 9-12 on page 218):
a. Select Microsoft Active Directory.
b. LDAP Server: the address or full computer name of the Active Directory
Server (in this case, m23x2672.yourco.com)
c. User DN: the LDAP schema for the Active Directory administrator user.
You can refer to 9.3.4, “Obtaining the LDAP schema for Active Directory”
on page 213 for more details.
In this scenario, the User DN is:
cn=Administrator,cn=users,dc=yourco,dc=com
d. User password and Confirm password: enter the password for the
administrator user specified above.
e. Suffix: the suffix for the server has been configured. In this case:
dc=yourco,dc=com


f. LDAP port number: the port the Active Directory Server uses. By default,
this is 389.

Figure 9-12 Selecting Active Directory as the LDAP server

4. In the next window, you must provide information about the Active Directory
configuration (Figure 9-13 on page 219). You can refer to 9.3.4, “Obtaining
the LDAP schema for Active Directory” on page 213 for information about the
Distinguished Name of users and groups in your Active Directory.


Figure 9-13 LDAP Configuration details

5. Fill in the fields and click Next to continue the WebSphere Everyplace Access
installation.
6. As a part of the WebSphere Everyplace Access installation, you must
configure the Security Center of the WebSphere Application Server. These
configuration values are related to LDAP settings and the administration role
for the WebSphere Application Server.
When you open the Security Center during the standard WebSphere
Everyplace Access installation, click the Authentication tab to check the
details for the LDAP settings. The window is shown in Figure 9-14 on
page 220.


Figure 9-14 Authentication tab in WebSphere Application Server Security Center

The LDAP settings for the sample scenario in this chapter are:
– Security Server ID: the DN of the user created for security purposes. In
this case, cn=wpsbind,cn=users,cn=yourco,cn=com
– Security Server Password: the password for the user above.
– Host: the IP address or fully qualified DNS name of the Active Directory
server. In this case, m23x2672.yourco.com
– Directory Type: Active Directory.
– Port: port for Active Directory Server. We are using the 389 default port.
– Base Distinguished Name: the DN of the domain the Active Directory
administrator’s user belongs to. In this case, the user Administrator
belongs to cn=yourco,cn=com.
– Bind Distinguished Name: the full DN of the administrator user. In this
case, cn=Administrator,cn=users,cn=yourco,cn=com.
– Bind Password: the password for the administrator user.


7. Complete the configuration of the Administration Role and the rest of the
standard WebSphere Everyplace Access installation. For details, see
Appendix A, “WebSphere Everyplace Access sample installation” on
page 271.
8. Important: Before you begin working with the WebSphere Everyplace
Access server, it is required that you provide the WebSphere Everyplace
Access administrator user (wpsadmin in this case) full manage authority over
the users and groups in the WebSphere Everyplace Access. This will allow
the WebSphere Everyplace Access administrator to search for and manage
users and groups in WebSphere Everyplace Access. For example:
a. Log on to the WebSphere Everyplace Access server as user wpsadmin (or
another user with administration rights).
b. Select Portal Administration.
c. Click the Security tab.
d. Click Get Users and Groups.
e. Click Search for users.
f. Type an asterisk (*) in the Name is field and click Go.
g. From the search results list, select the wpsadmin user, click Add to list
and click OK.
h. From the Select the objects for permissions drop-down menu, select User
groups and click Go.
i. From the table list, check the Select all option in the Manage column.
j. Click Save.
Figure 9-15 on page 222 illustrates the new permissions for the wpsadmin
user.


Figure 9-15 Adding permissions tor the wpsadmin user in Portal server

You can now see both the users and groups you previously created in Active
Directory when you perform a search on users and groups (Figure 9-16 on
page 223).


Figure 9-16 Manage users and groups in Portal server

In this section, sample applications are executed using the configured
WebSphere Everyplace Access with Active Directory LDAP services.

9.5.1 Creating users and groups in WebSphere Everyplace Access
Creating users and groups is a simple way to verify the interoperability of
WebSphere Everyplace Access and Active Directory.

Note: In this environment, you can add users and groups directly from the Active
Directory or using the WebSphere Everyplace Access interface.

If you want to add users and groups directly in Active Directory, see the
suggested steps to create the wpsadmins group and wpsadmin and wpsbind
users (see 9.3.3, “Configuring Active Directory for WebSphere Everyplace
Access” on page 208).


There are two ways to create users using WebSphere Everyplace Access: by
using the sign-up option (self-enrollment) or by using an administrator user.

User self-enrollment
To create a user using the self-enrollment option, you must enter the Portal
server and click the Sign up button. Fill out the registration form (Figure 9-17)
and submit the request.

Figure 9-17 Self-enrollment user registration

User enrollment by an administrator
To create users in WebSphere Everyplace Access through an administrator user,
follow these steps:
1. Log on to the Portal server using the wpsadmin user (or an administrator
user).
2. Select Portal Administration.
3. Click the Users and Groups tab.


4. Click Create new user.
5. Enter the information for the new user and click OK (Figure 9-18).

Figure 9-18 Creating a new user

Group creation by an administrator
To create groups in WebSphere Everyplace Access through an administrator
user, follow these steps:
1. Log on to the Portal server using the wpsadmin user (or an administrator
user).
4. Click the Manage User Groups tab.
5. Enter the name of the new group in the Group Name field and click Create
group (Figure 9-19 on page 226).


Figure 9-19 Creating a new group in WebSphere Everyplace Access

9.5.2 DB2 Everyplace synchronization using Active Directory
In this sample scenario, a sample application supplied by DB2 Everyplace, called
Visiting Nurse, is used. This scenario illustrates DB2 Everyplace synchronization
when using a remote Active Directory server for LDAP services.

In this section, we briefly explain how to configure WebSphere Everyplace
Access server and a Pocket PC for this application. For more details, see
Chapter 1, “Synchronizing with DB2 databases” on page 3.

Creating the synchronization and DB2e groups
First, you will need to create a synchronization group in WebSphere Everyplace
Access. This group will have all the users who need to synchronize with the DB2
Everyplace Sync Server. In this sample scenario, the default name SyncGroup is
used for this group.

Once the SyncGroup group is created, you will be required to add all users for
which you want to allow DB2 Everyplace synchronization capabilities


Figure 9-20 Setting the SyncGroup group

Since this is the Visiting Nurse application, the new DB2e group will be called
DB2e_Nurse, and you will add the users that need to work with this application


Figure 9-21 Setting up the DB2e_Nurse group

Creating a subscription and subscription set
To create a subscription and a subscription set, we must use the Mobile Devices
Administration Center (MDAC).
1. Click Start -> Programs -> IBM Everyplace Synchronization Server - >
Launch MDAC, and log in with wpsadmin user and SyncGroup as the
synchronization group.
2. Verify that the DB2e group (DB2e_Nurse group in this case) is available in the
Groups folder (Figure 9-22 on page 229).


Figure 9-22 MDAC Groups folder

3. Verify that all the users who are members of SyncGroup appear in the Users
folder (Figure 9-23).

Figure 9-23 MDAC Users folder

4. In this scenario, a JDBC subscription is used. For example:
a. Click the Subscriptions folder.
b. Right-click JDBCSUB1 and select Edit (Figure 9-24 on page 230).


Figure 9-24 Edit JDBCSUB1 Subscription

c. On the Identification tab, click Define subscription... to see the tables
that will be synchronized (Figure 9-25).

Figure 9-25 Define Replication Subscription

d. Select the Source tab; the VNURSE database must appear in the
Database URL field.


e. On the Subscription sets tab, the subscription set SUBSCRIPTION_SET1
must be in the right-hand pane (Figure 9-26).

Figure 9-26 Subscription sets

f. Close the subscription window.
5. You will need to assign the DB2e group to the subscription set assigned to the
Visiting Nurse database.
a. Click the Subscription sets folder.
b. Right-click SUBSCRIPTION_SET1 and select Edit.
c. On the Groups tab, select DB2e_Nurse from the Available Groups list and
move it to the Select Groups list (Figure 9-27 on page 232).


Figure 9-27 Editing Subscription Set

d. Close the subscription set window.

9.5.3 Configuring the client on the Pocket PC and synchronizing
The following procedure can be used to configure the client in the Pocket PC:
1. Start the Everyplace Client and go to the User Options window (Tools ->
User Options).
2. Fill out the WebSphere Everyplace Access information. You will need to
provide a user ID that belongs to the SyncGroup created previously
3. Click OK to close the window.
4. Click DB2 Everyplace Sync and from the menu, select Tools -> Configure
5. In the Configure window, you must provide a value for User ID and Device ID.
Leave the default values shown (Figure 9-28 on page 233).
6. To initiate the synchronization, click Execute. Once the synchronization is
completed, the status is updated (Figure 9-28 on page 233).


Figure 9-28 Steps to configure the Everyplace Client on the Pocket PC

7. Click the Subscription List tab and confirm that SUBSCRIPTION_SET1 is
available (Figure 9-29).

Figure 9-29 Verifying that the synchronization process selected the subscription


8. Notice that in the MDAC application, the user executing the synchronization
process has been updated with the device type, device ID, and the version of
Everyplace Sync client (Figure 9-30).

Figure 9-30 MADC Users details

Verifying the synchronization
Now that the Pocket PC device is synchronizing, you can use the Visiting Nurse
sample application to confirm that in fact data entered on the Pocket PC is
getting synchronized with the DB2 database. For example:
1. Start the Visiting Nurse application on the Pocket PC.
a. Click Start and select Programs.
b. Open the DB2 Everyplace Samples folder and click VNurse.
2. Select a patient and create a new medical record. An example is shown in
Figure 9-31 on page 235. To do this:
a. Highlight a patient’s name and click the Info button.
b. On the Personal Information page, click the Records button.
c. Add a new medical record by clicking Add.
d. Once you have filled out the record, click Save.


Figure 9-31 Creating a record in the Visiting Nurse application

3. Close the Visiting Nurse application.
4. Start the Everyplace Client and initiate a synchronization.
a. Click Start and select Everyplace Client from the menu.
b. Click the Execute button.

Upon successful completion of the synchronization, the records will be replicated
to the source database as defined in the JDBC subscription. One method to
confirm that new records are added to the DB2 database is to view the table
contents using the IBM DB2 Control Center, as shown in Figure 9-32 on
page 236.


Figure 9-32 The new record in the DB2 database after synchronization


10

Chapter 10. Domino Directory services
in WebSphere Everyplace
Access
In this chapter, we discuss the interoperability between WebSphere Everyplace
Access and an external Lotus Domino server using the Lightweight Directory
Access Protocol (LDAP).

We explain how to install and configure the Lotus Domino server and LDAP
services and how to install WebSphere Everyplace Access to access this LDAP
directory. We also include sample scenarios to verify the installation.


10.1 Lotus Domino R5 overview
Lotus Domino R5 is an integrated server platform for messaging, groupware, and
Web applications, delivering secure communication, collaboration and business
applications. It includes the following servers:
Domino Mail Server, used for messaging purposes.
Domino Application Server, a secure platform to deliver Web applications. It
provides an integrated messaging and Web application software platform.
Domino Enterprise Server, which extends the functionality of Domino Mail
and Domino Application Servers with high availability services.

The Domino Directory services are a way to refer the directory architecture in
Domino R5, whose central component is the Domino Directory, a store for
directory information about users, servers, groups, and other objects, used by
the Domino servers and by clients within a Domino domain. The other
components of the Domino Directory services are:
Directory Catalog, a specialized database with information about one or more
Domino directories.
Directory Assistance, which provides a redirect mechanism to access
directory information from secondary directories, with the information residing
in its original directory.
Domino LDAP server task, which provides LDAP Version 3-compliant access
to Domino and third-party directories from clients and applications.

A Domino server is required to have Domino Directory services running and
available. For this reason, you will need to set up and configure LDAP services in
the Domino server. In addition, you can also set up and configure Directory
Assistance and Directory Catalogs when required.

For more information about Domino Directory services, refer to the redbook
Getting the Most From Your Domino Directory, SG24-5986.

The scenario presented in this chapter includes a Lotus Domino Application
server with LDAP services configured with the required options to allow it to be
an external directory service of a WebSphere Everyplace Access server. The
sample scenario described in this chapter is illustrated in Figure 10-1 on
page 239.


Windows 2000 Server
Windows 2000 Server

Domino m23x3074.yourco.com Access V4.1.1
Server V5.08 Port 386

Server V4.0.1 DB2
Notes IBM HTTP Server

m23x2501.yourco.com

HTTP

Pocket PC
Everyplace client
V8.1
Desktop browser

Figure 10-1 WebSphere Everyplace Access and Domino LDAP Services

The description of this scenario includes the installation and configuration of a
Lotus Domino Application server, and the configuration of the LDAP services.

Note: In this sample scenario, it may not be necessary to configure Directory
Assistance and Directory Catalogs in the Domino server. However, this could be
a requirement in other situations.

Chapter 10. Domino Directory services in WebSphere Everyplace Access 239

10.2.1 Specifications for the scenario
Table 10-1 illustrates the configuration values used in this sample scenario.

Table 10-1 Configuration
Role Application Server Domino R5 Server

Machine DNS Name m23x2501.yourco.com m23x2674.yourco.com

IP address 198.168.10.12 198.168.10.6



Additional Software IBM WebSphere Everyplace Domino R5.08 Server (Domino
Access V 4.1.1 Application Server)

10.2.2 Users and groups required in this scenario
It will be required that you create users and groups in the Domino server before
starting the WebSphere Everyplace Access installation. These are the
WebSphere Everyplace Access administrator users and groups that must be
available in the LDAP server so that WebSphere Everyplace Access can validate
them when required.

Table 10-2 and Table 10-3 on page 240 summarize the groups and users used
during WebSphere Everyplace Access installation that must be configured in the
LDAP Directory.

Table 10-2 Groups needed for WebSphere Everyplace Access installation
Group name Description Member of

wpsadmins WebSphere Everyplace Access Administrators group
administrative group

Table 10-3 Users needed for WebSphere Everyplace Access installation
User name Description Member of

wpsadmin WebSphere Everyplace Access wpsadmins group
administrator user

wpsbind User for WebSphere Everyplace wpsadmins group
Access security purposes. (to bind
between WebSphere Everyplace
Access and LDAP)


10.3 Setting up Domino Directory services
You will need to install a Domino server to have Domino Directory services. For
this scenario, a Domino Application Server is installed as Domino server. You will
also need to install the Lotus Domino Administrator client to administer the
Domino server, and configure LDAP to run in this server.

10.3.1 Installing Lotus Domino server
This is a typical Lotus Domino server installation; in this sample scenario, most of
the default settings and directories are used. The required options are selected
to fulfill the specifications of the scenario described in Table 10-2 on page 240
and Table 10-3. For example:
1. Log in to the server as a user with administrator privileges.
2. Run the setup program to open the Installation wizard. Click Next in the
Welcome window.
3. Read the License Agreement and click Yes.
4. Supply the company information (user and company name) and click Next.
5. Accept the default product and data folders locations or change them if you
desire.
6. Choose to install a Domino Application Server and click Next (Figure 10-2 on
page 242). For the purpose of this scenario, it is not necessary to customize
the installation.


Figure 10-2 Select the type of Domino server

7. Accept the default Program Folder and click Next to start the Domino server
installation.
8. At the end of the installation, click Finish to close the Installation wizard and
finish the Domino server installation.
9. Open the Lotus Domino server to start the server setup, including the LDAP
services, by clicking Start -> Programs -> Lotus Applications -> Lotus
Domino Server.
10.In the Step 1 window, select the option First Domino Server and click the
right-pointing arrow on the top right-hand side as illustrated in Figure 10-3 on
page 243.


Figure 10-3 Step 1 - Creating a new Domino server

11.In the Step 2 window, select Advanced Configuration to customize the
server configuration parameters. Click the right-pointing arrow as shown in


Figure 10-4 Step 2 - Select a setup method

In the Step 3 window, enter the advanced configuration parameters. You must
select LDAP as Internet Directory Services to set the LDAP server to
automatically run on server startup. You must also activate the HTTP and IIOP
options in the Web Browsers section. The rest of the options are optional. Click
the right-pointing arrow as illustrated in Figure 10-5 on page 245.


Figure 10-5 Step 3 - Domino advanced configuration

12.In the Step 4 window, enter the administration settings information
(Figure 10-6 on page 246). Enter the password for the certified ID (password
in this case), and the administrator user and password for the Domino server
(in this sample scenario, wpsadmin). See 10.2.2, “Users and groups required
in this scenario” on page 240 to obtain information about users and groups
required for this scenario.

Important: Be sure to enter wpsadmin as the administrator’s last name and
leave blank the first and middle name in the Administrator’s Identity section.
Domino server generates the user ID combining the first letter of the first name
with the last name.


Figure 10-6 Step 4 - Domino administrative settings

13.Click Finish to complete the Domino server setup. A summary of the Domino
configuration will appear; review the options (Figure 10-7 on page 247).

Important: Be sure to remember the location and password for the Certifier ID
and Administrator ID created during the Domino server setup and shown in
the summary configuration window. You will need this information for
configuring and for administration tasks.

As we need to create the wpsadmins administrator group, click the Set
Access Control List Entry button.


Figure 10-7 Domino configuration summary

14.In the Set Default Database Access window, select the Add a group option
and type wpsadmins as the name of the group. Click OK (Figure 10-8).

Figure 10-8 Creating the wpsadmins group

15.Click the Exit Configuration button in the Domino summary configuration
window.


16.Start the Domino server by clicking Start -> Programs -> Lotus
Applications -> Lotus Domino Server.
17.Wait until the Domino server finishes loading (Figure 10-9).

Figure 10-9 Starting Domino server

10.3.2 Installing and configuring the Domino Administration client
You will need to install the Domino Administration client to be able to administer
the Domino server.

Important: The Lotus Domino server must be available and running before
you start the Domino Administration client installation.

For example, follow this procedure:
1. Run the setup program to open the Installation wizard. Click Next at the
Welcome window.
2. Read the License Agreement and click Yes.
3. Supply the company information (user and company name) and click Next.
4. Accept the default product and data folders locations or change them if you
desire. Click Next.
5. Select the Domino Administrator option and click Next (Figure 10-10). For
the purposes of this scenario, it is not necessary to customize the Domino
Administrator installation.


Figure 10-10 Installing Domino Administration

6. Accept the default Program Folder and click Next to begin the Domino
Administration installation.
7. At the end of the installation, click Finish to close the Installation wizard and
finish the installation.
8. Open the Lotus Domino Administration client by clicking Start ->
Programs -> Lotus Applications -> Lotus Domino Administrator.
This will start the administrator configuration process.
9. Click Next in the Setting Up Connections window.
10.Select I want to connect to a Domino server and click Next.
11.Select Set up a connection to a local area network (LAN) and click Next.
12.Enter the Domino server name, in this case m23x2674/yourco, and click Next


Figure 10-11 Entering the Domino server name

13.Select the Use my name as identification option and enter the administrator
user name for the Domino server. In this case, wpsadmin is the administrator
during the Domino server installation.


Figure 10-12 Enter the Domino administrator user

14.Click Next in the Connecting to a Domino Server over a LAN window.
15.For this scenario, select I don’t want to create an Internet mail account
and click Next.
16.For this scenario, select I don’t want to connect to a news server and click
Next.
17.For this scenario, select I don’t want to connect to another directory
server and click Next.
18.Choose whether you will use a proxy to connect to the Internet and click Next .
In this sample scenario, a proxy is not used.
19.Select how you will connect to the Internet. For example, in this scenario
select the Connect over local area network (or cable modem) option and
click Next.
20.Click Finish to complete the Domino Administration client configuration. You
will be prompted to enter a password to start the Administration client. Enter
the password for the administrator user (the user is wpsadmin in this case)
and click OK.


10.3.3 Configuring LDAP services on Domino
It is necessary to create an additional user (wpsbind, as shown in 10.2.2, “Users
and groups required in this scenario” on page 240) and set some LDAP
parameters in Domino before beginning the WebSphere Everyplace Access
installation.

Creating users in Domino
Follow these steps to create a user:
1. Start Domino Administration client if it is not opened by clicking Start ->
Programs -> Lotus Applications -> Lotus Domino Administrator.
2. Go to the Administration page and select the People & Groups tab
(Figure 10-13).

Figure 10-13 Domino Administration client

3. Right-click People and select Register Person.
4. When you are prompted to choose the certifier ID, select the cert.id file from
your Domino server data directory (by default, it is located in
c:LotusDominoData). Click Open.
5. Enter the password for the certifier ID selected earlier and click OK.

Tip: The certifier ID is created during the Domino server setup, in the
administrative settings form (Step 4 window). For more information, see
10.3.1, “Installing Lotus Domino server” on page 241).


6. Click the Basics button on the left-hand side, and enter the information for
the new user wpsbind (Figure 10-14).
7. Select the Advanced option to configure an Internet password.

Tip: You will be required to set an Internet password for all users because
LDAP uses this as a means to authenticate users.

Figure 10-14 Registering user wpsbind

8. Click the Groups button, select wpsadmins and click the Add button


Figure 10-15 Adding wpsbin to the wpsadmins group

9. Click the Add person button. If you want, you can create more users at this
time, or you can do so later.
10.Click the Register All button, and when the registration process finishes,
click Done to close the Register Person form.

Configuring LDAP in Domino
To configure LDAP services on your Domino server, you will need to create a
server configuration document.
1. In the Domino Administration client, select the Configuration tab and expand
the Server section, then click the Configurations icon. Now click the Add
Configuration action button to create a new configuration document.
2. Select the Use these settings as the default settings for all servers
checkbox (Figure 10-16 on page 255).

Note: Note that only one configuration document can be designated as such.


Figure 10-16 Creating a new server configuration document

3. Once you have selected this option, the LDAP tab appears. Click it to move to
that section.
4. Click the button Choose fields that anonymous users can query via
LDAP; an LDAP Field List window will appear with a list of queriable fields.
Accept this list or add more fields if you want, then click OK (Figure 10-17).

Figure 10-17 LDAP field list

5. In the LDAP Configuration form, select Yes in the Allow LDAP users write
access option. Leave the other fields with their default values (Figure 10-18
on page 256).


Figure 10-18 LDAP Configuration settings

6. Click the Save and Close button; a new configuration document will be
created (Figure 10-19 on page 257).


Figure 10-19 Configuration document for all the servers

7. In the Configuration tab, in the Server section, click the Current Server
Document icon and the Edit Server button.
8. Select the Ports tab; inside the Port section, click the Internet Ports tab and
select the Directory tab. You will see some configurations about LDAP. In this
sample scenario, LDAP services uses port 386, but you can always use the
default port 389 if you wish (Figure 10-20 on page 258).


Figure 10-20 LDAP settings

9. Click the Save and Close button to save the changes you made.

10.3.4 Obtaining the LDAP schema for the Domino server
To obtain the LDAP directory schema for your Domino server, you can execute
the ldapsearch command located in the Lotus Notes program directory (by
default, c:LotusNotes).

For example, at the command prompt window, enter the following command:
ldapsearch -h m23x2674 -p 386 -d cn=wpsadmin,o=yourco -w wpsadmin -b
o=yourco cn=* dn

You will see a list of the Distinguished Names of the users in your Domino server


Figure 10-21 LDAP schema for Domino server

By selecting one of the returned records, you can determine the User DN prefix
and suffix. For example, given the following record:
CN=wpsadmin,O=Yourco

the User DN prefix for the wpsadmin user is CN, and the User DN suffix is
O=Yourco.

Note: During the WebSphere Everyplace Access installation, you will need
information about your Domino server LDAP schema.

The WebSphere Access installation using remote Domino Directory services
requires some special considerations compared to the typical installation using
IBM SecureWay Directory services. For example:
1. When you have to select the desired WebSphere Everyplace Access
components and subcomponents to install, do not select SecureWay
Directory Server.
Note: The SecureWay Directory is the default LDAP server provided with
WebSphere Everyplace Access and can be installed locally or as a remote
server.
In this sample scenario, it is assumed that Domino Directory services have
already been installed as a remote LDAP server, and therefore you do not
need to install SecureWay Directory (Figure 10-22 on page 260).


Figure 10-22 Selecting WebSphere Everyplace Access install components

2. In the LTPA Password window, you will be prompted to enter the LTPA
password. You must enter the password of the bind user wpsbind created
previously.
3. Later in the installation, in the LDAP server type selection window, enter the
following details (Figure 10-23 on page 261):
a. Select Lotus Domino Application Server.
b. LDAP Server: the address or full computer name of the Domino server (in
this case, m23x2674.yourco.com).
c. User DN: the LDAP schema for the Domino server administrator user.
Refer to 10.3.4, “Obtaining the LDAP schema for the Domino server” on
page 258 for more details.
In this scenario, the User DN is cn=wpsadmin,o=yourco
d. User password and Confirm password: enter the password for the
administrator user specified above.
e. Suffix: the suffix for the server that has been configured. In this case, it is
o=yourco.


f. LDAP port number: the port the LDAP uses. In this scenario, we are using
port 386.

Figure 10-23 Selecting Domino server as the LDAP server

4. In the next window, you must provide information about the Domino server
configuration (Figure 10-24 on page 262). Review 10.3.4, “Obtaining the
LDAP schema for the Domino server” on page 258 to obtain information
about Distinguished Names of users and groups in your Domino server.


Figure 10-24 LDAP configuration details

Fill in the fields and click Next to continue the WebSphere Everyplace Access
installation.
5. As part of the WebSphere Everyplace Access installation, you must perform
some configurations in the Security Center of the WebSphere Application
Server. These configurations are related to LDAP settings and the
administration role for the WebSphere Application Server.
When you have to open the Security Center during the standard WebSphere
Everyplace Access installation, execute the following additional step:
– Click the Authentication tab and check the details for LDAP settings


Figure 10-25 Authentication tab at the WebSphere Application Server Security Center

The LDAP Settings for this sample scenario are:
Security Server ID: the DN of the user created for security purposes. In this
case, cn=wpsbind,o=yourco
Security Server Password: password for the user above.
Host: the IP address or full DNS name of the Domino server. In this case,
m23x2674.yourco.com
Directory Type: Domino 5.0
Port: the LDAP port. Port 386 is used in this scenario.
Base Distinguished Name: the DN of the domain the Domino server
administrator’s user belongs to. In this case, the user wpsadmin belongs to
o=yourco.
Bind Distinguished Name: the full DN of the administrator user. In this case,
cn=wpsadmin,o=yourco.
Bind Password: the password for the administrator user.
6. Complete the configuration of the administration role and the rest of the
standard WebSphere Everyplace Access installation. For details, see


Appendix A, “WebSphere Everyplace Access sample installation” on
page 271.
7. After the installation and before you start any work, you will be required to
provide full manage authority of the users and groups to the WebSphere
Everyplace Access administrator user (wpsadmin in this case). This will allow
the WebSphere Everyplace Access administrator to search for and manage
users and groups. Follow this procedure:
a. Log on to the WebSphere Everyplace Access server using the wpsadmin
user (or another user with administration rights).
b. Select Portal Administration.
c. Click the Security tab.
d. Click Get Users and Groups.
e. Click Search for users.
f. Type an asterisk (*) in the Name is field and click Go.
g. From the search results list, select the wpsadmin user, click Add to list,
and click OK.
h. From the Select the objects for permissions drop-down menu, select User
groups and click Go.
i. From the table list, check the Select all option in the Manage column.
j. Click Save.
Figure 10-26 on page 265 illustrate the new permissions for the wpsadmin
user.


Figure 10-26 Adding permissions to the wpsadmin user

In this section, two different tasks are described to show the interoperability of
IBM WebSphere Everyplace Access and Domino Directory services.

10.5.1 Creating users in WebSphere Everyplace Access
You can add users directly from the Lotus Administration client or by using the
WebSphere Everyplace Access administration interface. The latter option is
shown here to verify that WebSphere Everyplace Access and the Domino server
are working correctly.


1. Log on to the Portal server as a wpsadmin user.
4. Click the Manage Users tab.
5. Click Create new user.
6. Enter the information for the new user and click OK (Figure 10-27).

Figure 10-27 Creating a new user

7. A message confirming the creation of the new user will appear.
8. You can validate the creation of the new user by searching for all Domino
Directory users (Figure 10-28 on page 267). Type an asterisk (*) in the Name
is field and click Get users. You will see the users in Domino server, including
the new user created, test1.


Figure 10-28 Searching users from WebSphere Everyplace Access

9. You can also view the Domino Administrator client to verify that the new user
has been created in the Domino server (Figure 10-29).

Figure 10-29 Viewing users in the Domino Administrator client


The LDAP Search portlet allows you to search LDAP directories and obtain
information about users. This portlet is provided by the standard installation of
the WebSphere Everyplace Access.
1. Log on to the WebSphere Everyplace Access server as the wpsadmin
administrator user or as a user with administration rights.
2. Select the Productivity tab.
3. Click the Edit icon in LDAP Search portlet.
4. Enter the LDAP Search properties (Figure 10-30):
– Optional Display Name: a name that describe the portlet.
– Server name: the full DNS name of the LDAP server, including the LDAP
port. In this case, this is ldap://m23x2674.yourco.com:386
– Directory name: the DN suffix of the LDAP server.
– The criteria for the initial search.

Figure 10-30 Configuring the LDAP Search portlet


5. Click Save.

The LDAP Search portlet is configured and ready to perform a search in the
Domino server (Figure 10-31).

Figure 10-31 LDAP Search portlet results


A

Appendix A. WebSphere Everyplace
Access sample installation
This appendix provides guidelines for installing WebSphere Everyplace Access.
A sample installation is included to show the installation steps required to support
the scenarios described in this redbook.

This appendix also includes:
Details about IBM WebSphere Everyplace Access installation
Illustrations of connectivity using a Pocket PC
Installation hints and tips


Installation
Operating system requirements
Windows 2000 Server with Service Pack 2.
Windows 2000 Advanced Server with Service Pack 2.

Hardware requirements
The following are recommended hardware requirements:
Windows processor:
– An Intel Pentium III 1 GHz processor or better
Memory (in addition to operating system requirements):
– 1 GB is recommended.
Hard drive:
– 1 GB or more for application installation. More may be needed as the
application operates.
– 1 GB or more for application data storage. Storage space depends on the
amount of data you have.
CD-ROM drive on network mouse or pointing device and keyboard.
Support for a communications adapter.
Network Software: TCP/IP network software installed.
SVGA or better display resolution.

Disk space requirements
Each component may require a different amount of disk space. The amount of
disk space required is dependent on the amount of user and application data that
you anticipate having on your system.

Server installation
The following information describes how to install IBM WebSphere Everyplace
Access on a machine using Windows 2000 Server.


Important: You must log on to the machine as a user with administrative
rights to perform the installation; Otherwise the installation will fail.

Make sure you have given your machine a domain suffix (see Figure A-1).

Close all applications that are running.

Figure A-1 Setting a DNS suffix on Windows 2000 Server

1. Insert CD 1 into the CD-ROM drive; if Java Runtime Environment is not
already installed on the machine, IBM JRE Version 1.3.0 is installed
automatically.

Figure A-2 Installing Java Runtime Environment (JRE) 1.3.0

Appendix A. WebSphere Everyplace Access sample installation 273

2. The Setup Manager will automatically launch. Select a language for the
installation.

Figure A-3 Select language for installation

3. The welcome window of the Setup Manager will appear. Click Next.

Figure A-4 Setup Manager welcome window

4. To agree to the license agreement, click Yes.


Figure A-5 License agreement

5. Choose the destination folder to install Java Runtime Environment (JRE).

Figure A-6 Choose installation folder for JRE

6. Select desired components to install.


Figure A-7 Choose components to install

7. Answer Yes if this JRE is to be used as the system Java Virtual Machine
(JVM).

Figure A-8 Set this JRE to be the system JVM

8. The summary window is shown before copying of files begins.


Figure A-9 Summary window

9. Upon completion, click Finish.

Figure A-10 JRE setup complete

10.The WebSphere Everyplace Access Setup Manager will automatically
launch. View the prerequisites if you are not sure of what they are. Click Next.


Figure A-11 View Information window

11.Read the license agreement and click Yes. Then click Next.



12.Choose the installation type. For this sample, we chose Standard Install.
Click Next .


Figure A-13 Choose installation type

13.In this sample installation, we are not installing from a response file, so leave
the field blank. Click Next.

Tip: You may also use a response file for silent installs.


Figure A-14 Loading the response file

14.Select the desired components to install. For this sample, we install all the
components. Click Next.


Figure A-15 Select components to install

15.The Setup Manager now collects the information required to install the IBM
HTTP Server. Enter the directory where you wish the HTTP Server to be
installed. Click Next.


Figure A-16 Define the directory where IBM HTTP Server will be installed

16.Enter the name and password of the user who can administer the IBM HTTP
Server. If the user does not exist on the machine, it will be created. Click
Next.


Figure A-17 Enter administrator’s user name and password

17.The Setup Manager now collects the information required to install DB2.
Enter the directory to install DB2 Universal Database. Click Next.


Figure A-18 Enter directory to install DB2

18.Enter the administrator’s user name and password that can be used to log on
to the Control Center. Click Next.


Figure A-19 Enter administrator’s user name and password for DB2

19.Now, the Setup Manager proceeds to collect information needed to install
LDAP. Enter the installation directory for LDAP. Click Next.


Figure A-20 Enter installation directory for LDAP

20.Define the desired suffix used in LDAP as well as the administrator’s user
name and password. The suffix determines how users are stored in LDAP.
Click Next .


Figure A-21 Define the suffix and administrator’s user name and password

21.Define the administrator’s user name and password. Click Next.


Figure A-22 Administrator’s user name and password for WebSphere Application Server

22.Enter the name of the installation directory. Click Next.


Figure A-23 Installation directory for WebSphere Application Server

23.WebSphere Application Server needs a database (DB2 in this case) to store
its configuration data; enter the user name and password to access DB2.
Click Next .


Figure A-24 User ID and password used by WebSphere Application Server to access
DB2

24.Enter the relevant database information used by WebSphere Application
Server. Click Next.


Figure A-25 Database information for WebSphere Application Server

25.The Setup Manager now collects information required to install WebSphere
Portal server. Read the information provided in the window and configure
security. For this sample installation, we chose Now. Click Next .


Figure A-26 Configure security

26.Enter the LTPA password. Click Next.

Note: The Lightweight Third Party Authentication (LPTA) mechanism
employed here allows WebSphere Everyplace Access to enable single
sign-on if other servers in the environment supports LPTA cookies.


Figure A-27 LTPA password

27.Enter the relevant information for Portal server. Click Next.


Figure A-28 Relevant install information for Portal server

28.Portal server relies on LDAP to store its users’ credentials. In this window,
select the LDAP server type and provide its settings. Click Next.


Figure A-29 Define the LDAP server used by Portal server

29.Define the LDAP configuration. Click Next.

Note: You may have to use a different user name and password depending on
the directory solution you employ.


Figure A-30 Define LDAP configuration

30.Select Additional Database Configuration to install and enter the database
administrator information defined earlier. Click Next.


Figure A-31 Additional database configuration

31.Select the portlets to be installed, and click Next.


Figure A-32 Selecting the portlets to be installed

32.The next step is to provide information for installing Everyplace
Synchronization Server. Enter the database connection information for
creating the local Everyplace Synchronization Server databases. Click Next.


Figure A-33 Configure database server for ESS

33.Choose the Everyplace Synchronization Adapters that you need. For this
sample installation, we chose the database adapter only. Click Next.


Figure A-34 Select Everyplace Synchronization Adapters

34.Enter WebSphere Application Server and WebSphere Portal server
information. Click Next.


Figure A-35 Enter WebSphere Application Server and Portal server information

35.By now, the Setup Manager has collected enough information to perform the
installation. This window shows a summary of what you entered along the
way. Review this and click Next.


Figure A-36 Summary

36.Installation starts. The Setup Manager displays the status of the installation
process.


Figure A-37 Installation status

37.During the installation process, you will be asked to change the disk and
reboot the machine; do so according to the instructions.
38.As part of the Portal server installation, the Setup Manager displays a
Configuring for Admin Role message.


Figure A-38 Configuring for Admin Role window

Tip: Do not click OK until you have gone through step p on page 310.

The next two steps must be performed to configure the admin roles before
you click OK.
39.Use the Services window to stop and start the IBM HTTP Server. This is
required for the WebSphere Application Server to pick up the plug-in changes
for the Portal server.


Figure A-39 Services window

40.As part of the Portal server installation, Portal makes some configuration
changes to the WebSphere Application Server. To complete this
configuration, at the minimum the default Portal user, wpsadmin, must have
administrative authority. The following steps explain how to give the default
Portal user, wpsadmin, administrative authority. These steps must be
completed before clicking OK in the Configuring for Admin Role window.
a. Use the Services window to start the WebSphere Application Server if not
already started.
Look for IBM WS AdminServer 4.0.
b. Open the Administrative Console for WebSphere Application Server by
clicking Start -> Programs -> IBM WebSphere -> Application Server
V4.0 -> Administrator’s Console.
c. You may be required to log in. Enter the administrator’s user name and
password as defined earlier in the Setup Manager, then click OK .
d. On the menu bar, click Console -> Security Center.


Figure A-40 Open Security Center

e. The Security Center opens.


Figure A-41 WebSphere Application Server Security Center

f. On the General tab, verify that Enable Security is selected.
g. Click the Administrative Role tab.


Figure A-42 Security Center

h. On the Administrative Role tab, select AdminRole and click Select. The
Select User/Group - AdminRole window is shown.


Figure A-43 Security Center

i. Select Select users/groups and type * in the search field, then click
Search to display a list of users and groups.
j. Add the wpsadmin user to AdminRole.
In the Available Users/Groups list, under Users, select
cn=wpsadmin,cn=users,dc=yourco,dc=com(wpsadmin) and click
Add >> to add this user.
k. Add the wpsadmins group to AdminRole.
In the Available Users/Groups list, under Groups, select
cn=wpsadmins,cn=groups,dc=yourco,dc=com(wpsadmins) and click
Add >> to add this group.
l. Click OK to close the Select Users/Groups - AdminRole window.
m. Click OK to close the Security Center.
n. Exit the Administrative Console.
o. Use the Services window to stop and restart the IBM WS AdminServer4.0.
p. Open the Administrative Console again to verify that the application server
named WebSphere Portal has been started.
q. Exit the Administrative Console when done and click OK to close the
installation message for Configuring for Admin Role.

Tip: Note that this operation may take over an hour to complete.


41.When installation is complete, we recommend that you review the logs and
reboot the machine as instructed.

10.6 Server installation verification
The following is a checklist to verify whether your WebSphere Everyplace
Access installation is working properly.

Tip: Check Services to make sure IBM WebSphere AdminServer and IBM
Secureway Directory are running. Also, the host name for your URL should be
the fully qualified host name of your server.

1. Go to the following URL:
http://<hostname>/wps/portal
2. Log in to WebSphere Everyplace Access as administrator, for example
<wpsadmin>.
3. Select Portal Administration from the drop-down menu.
4. Select the Users and Groups page.
5. Select the Manage Users portlet.


Figure A-44 WebSphere Portal Manage User Page

6. Create a new WebSphere Everyplace Access user. Search for the user in the
admin portlet or check in LDAP to see whether the user has indeed been
created.
7. Log out of WebSphere Everyplace Access.
8. Log in to WebSphere Everyplace Access using the new user.
9. Log out of WebSphere Everyplace Access.
10.Log in to WebSphere Everyplace Access as administrator.
11.Select the Portal Administration Page group.
12.Select the Users and Groups page.
13.Select the Manage User Groups portlet.
14.Create a group and verify that it has indeed been created.
15.Check the WebSphere Everyplace Access HOME page group.


16.Check each of WebSphere Everyplace Access pages: Welcome, Offline,
Configure, Administration, Productivity, Notes, and Exchange.

Figure A-45 WebSphere Everyplace Access Welcome page

17.Check WebSphere Everyplace Access portlets present on WebSphere
Everyplace Access pages:
– Internal Mail Box
– Reminder
– World Clock
– QuickLinks
– Image Viewer
– Offline Browsing Configuration
– Offline Browsing Administration


– Banner Ad
– News
– LDAP Search
You may need to add configuration information in order to search. The
LDAP Directory is your suffix, that is: dc=ibm,dc=com
– Lotus Notes (mail, contacts, notebook, calendar, to-do list)
– Microsoft Exchange (mail, contacts, notes, calendar, tasks)
18.Check that ESS page group and pages are installed.
19.Check ESS pages (Manage Servers, Server Setttings, User Management,
Domino Adapter, Exchange Adapter).
20.Check that ESS portlets are present on ESS pages.

Figure A-46 ESS page group and pages

21.Check the WebSphere Application Server Administrative Console for
application servers and enterprise applications.


22.Check application servers (WebSphere Portal, Everyplace Synchronization
Server).
23.Check Enterprise Applications (WebSphere Portal Enterprise Application,
etc.).
24.Check the file system to see if the following CDS files exist:
– C:WebSphereAppServerlibappcds-server.jar
– C:WebSphereAppServerlibappcds-server-sync.jar
– C:WebSphereAppServerlibappcomibmpvcentcds
CommonDataService.properties
25.Check the file system to see if the following directories exist:
– C:WebSpherePortalServerappwps.earwps.warskinshtmlppcie
– C:WebSpherePortalServerappwps.earwps.warscreenshtmlppcie
– C:WebSpherePortalServerappwps.earwps.warthemeshtmlppcie
– C:WebSpherePortalServerappwps.earwps.warthemeshtmlWEAppcie
26.Click WebSphere Everyplace Access, Portal Administration -> Portal
Settings -> Manage Clients to see if it contains Windows CE.


Figure A-47 WebSphere Portal Manage Clients page

10.7 Client installation

Important: Make sure Microsoft ActiveSync has been installed before you
continue with the client installation.

1. Insert CD 5 into the CD-ROM drive. The InstallShield wizard will automatically
launch. Click Next.


Figure A-48 IBM Everyplace Client InstallShield welcome window

2. Answer Yes to the license agreement.


3. Choose a folder to install the client. Click Next.


Figure A-50 Choose install folder

4. Select the components to install. Click Next.

Figure A-51 Select components

5. Review the settings. Click Next if you are satisfied.


Figure A-52 Review settings

6. The InstallShield wizard starts copying files.

Figure A-53 Copying files

7. Upon completion, click Finish.


Figure A-54 Completion

8. Connect your Pocket PC to your machine using ActiveSync. Upon successful
connection, the installation of applications starts automatically. Select Yes.

Figure A-55 Install on Pocket PC

9. The installation starts for Sync Client.

Figure A-56 Installing Sync Client

10.Upon completion, the Sync Client should be present on your Pocket PC.


Figure A-57 Installation complete

Figure A-58 Pocket PC

10.8 Hints and tips
1. If, for any reason, the WebSphere Application Server control database is not
properly created, and WebSphere Application Server cannot start as a result,
do the following:
a. Drop the control database named WASDBL in the DB2 Control Center if
necessary.
b. Recreate the database in the DB2 Control Center using the wizard.
Alternatively, in a DB2 command window, you can use the following
command:
db2 create database WASDBL
c. Open the file admin.config in WebSphere_Install_DirAppServerbin.
d. In this file, set the value of com.ibm.ejs.sm.adminServer.createTables to
true:
com.ibm.ejs.sm.adminServer.createTables=true


e. Save and close admin.config.
f. Restart WebSphere Application Server.
2. When stopping WebSphere Application Server in the Services window, the
Services window may report that it has been stopped, but that the Java
processes may not have been fully ended. Open up the Windows Task
Manager and check that the java.exe processes have been completely
terminated. Then try to restart the server. Otherwise, you may get an error
message stating that WebSphere Application Server cannot be started.


B

Appendix B. Sample Oracle Enterprise
Edition installation
This appendix describes a sample installation of Oracle. It also gives an example
of how to create a simple database using wizards. This appendix is meant for
those who have no experience with Oracle databases.


Oracle installation
In this sample installation, Oracle8i Enterprise Edition, Release 2 (8.1.6) for
Microsoft Windows 2000 and Windows NT is used.
1. Insert the CD titled Oracle8i Enterprise Edition into the CD-ROM drive.
2. The CD will run automatically and displays a selection window.

Figure B-1 Selection window

3. Click the Install/Deinstall Products button.The Welcome window is
displayed.


Figure B-2 Welcome window

Click Next .
4. In the File Locations window, accept the defaults or enter file location
information. Click Next.

Appendix B. Sample Oracle Enterprise Edition installation 325

Figure B-3 Specify file locations

5. The installer starts loading the product list.

Figure B-4 Loading product list

6. When the files are loaded, a list of available products are displayed. Select
Oracle Enterprise Edition 8.1.6.0.0 and click Next.


Figure B-5 Select product to install

7. Choose Typical as the installation type. Click Next.


Figure B-6 Choose installation type

8. The installer starts loading installation files.


Figure B-7 Loading installation files

9. In the next window, enter the Global Database Name and SID.


Figure B-8 Enter Global Database Name and SID

10.A summary of this installation is displayed. Review it and click Install.


Figure B-9 Summary window

11.The installer starts installing.


Figure B-10 Installing

12.During the installation, an Oracle Database Configuration Assistant Alert
message is displayed. Note down the information and click OK.

Figure B-11 Oracle Database Configuration Assistant Alert

13.At the end of the installation, a message of success is shown. Click Exit .


Figure B-12 Installation is successful

The Oracle database has been successfully installed.

Create a simple database using wizards
To create a simple sample database called SALES, do the following:
1. Click Start -> Programs -> Oracle - OraHome81 -> Database
Administration -> Database Configuration Assistant.
2. Select Create a database. Click Next.


Figure B-13 Database Configuration Assistant

3. Select Typical. Click Next.

Figure B-14 Database type

4. Select Create new database files. Click Next.


Figure B-15 Create new database

5. Select Multipurpose. Click Next.

Figure B-16 Multipurpose database

6. For the number of concurrent users, accept the default of 15. Click Next.


Figure B-17 Set number of concurrent users

7. Check the options you want to configure for use in your database. Click Next.

Figure B-18 Choose desired options

8. Specify the name and SID of the database to be created, for example SALES
and SALES. Click Next.


Figure B-19 Set database identification

9. Choose Create database now. Click Finish.

Figure B-20 Create database now

10.Click Yes to start creating the database.


Figure B-21 Confirmation message

11.The database creation process starts. Depending on the options selected
earlier, this may take quite some time.

Figure B-22 Creating database

12.When database is created, a message is shown. Note down the information.
Click OK to dismiss it.


Figure B-23 Database created

The simple database has been created successfully.

Create simple table using wizards
To create a table called HISTORY in our simple sample database SALES, do the
following:
1. To start the DBA Studio, click Start -> Programs -> Oracle - OraHome81 ->
Database Administration -> DBA Studio.
2. Select Launch DBA Studio standalone. Click OK.

Figure B-24 Create table using wizard

3. Enter the administrator’s user name and password. Click OK.


Figure B-25 Enter administrator’s user name and password

4. In the Studio, expand Schema object for database SALES. Right-click Tables
-> Create Using Wizard.

Figure B-26 Create table using wizard

5. Give a name of the new table to be created, for example HISTORY.


Figure B-27 Specify table name

6. Specify all the columns in the table. Click Add for each column to bring it to
the Columns defined list.

Figure B-28 Add columns


The sample columns’ characteristics are shown in Figure B-29.

Figure B-29 Sample columns

When done, click Next.
7. Define primary key(s) by clicking in the Order column.


Figure B-30 Define primary key(s)

8. Specify for each column whether it is nullable and whether it must have
unique values.

Figure B-31 Null and unique constraints


In our example, all columns are not nullable and they do not have to have
unique values.
9. Specify for each column whether it is a foreign key. In our example, they are
not.

Figure B-32 Foreign constraint

10.Specify for each column whether it has check conditions. In our example, they
do not.


Figure B-33 Check constraints

11.Click Next in the Storage Information window.
12.Choose not to partition this table. Click Next.


Figure B-34 Partitions option

13.All the necessary information has been collected, and a summary is shown.
Click Finish.

Figure B-35 Summary


14.The table is created. A success message is shown. Click OK to dismiss it.

Figure B-36 Table created successfully

15.The newly created table should appear in DBA Studio now.

Figure B-37 Newly created table shown in DBA Studio

Populate table with data
There are various ways to populate the newly created table with data. A simple
Java program such as the following is one of the choices. It inserts some rows of
dummy data into the table.


Before running this program, make sure your Java environment is properly set up
and Oracle JDBC driver files (for example
C:OracleOra81jdbclibclasses12.zip) are in the system classpath.

Example: B-1 InsertHistoryDBOracle.java
import java.sql.*;

public class InsertHistoryDBOracle {

public static void main(String[] args) {

try {
Class.forName("oracle.jdbc.driver.OracleDriver");
} catch (ClassNotFoundException e) {
System.out.println (e.toString());
}

try {
Connection conn= DriverManager.getConnection("jdbc:oracle:oci8:@SALES",
"system", "manager");

PreparedStatement ps = conn.prepareStatement("INSERT INTO SYSTEM.HISTORY
(REP, ONE, DT, TWO, INT1, INT2) VALUES ('E01', ?, to_date('Jan 23, 1982
12:00:00AM','MON DD, YYYY HH12:MI:SS PM'), ?, 1, 1)");

for (int i=0; i<=11000; i++)
{
ps.setString(1, Integer.toString(i));
ps.setString(2, Integer.toString(i));
ps.executeUpdate();
}
}
catch (SQLException e) {
System.out.println (e.toString());
}
}

Compile this program in a command window:
javac InsertHistoryDBOracle.java

Run it in the command window:
java InsertHistoryDBOracle

When the program returns, the table is populated.


Related publications

The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.

IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks”
on page 350.
IBM Redbook IBM Replication Solutions for Pervasive Computing with DB2
Everyplace and DB2 Satellite Edition, SG24-6217
IBM WebSphere Everyplace Server Service Provider and Enable Offerings:
Enterprise Wireless Applications, SG24-6519
Getting the Most From Your Domino Directory, SG24-5986

Other resources
This publication is also relevant as a further information sources:
IBM DB2 Everyplace Sync Server Administration Guide 7.2, SC27-0845

Referenced Web sites
These Web sites are also relevant as further information sources:
iPlanet Directory Server V5.1, found in the Sun Product Documentation
Library:
WebSphere Portal:
http://www.ibm.com/software/websphere/portal
WebSphere Application Server:
http://www.ibm.com/software/webservers/appserv
Lightweight Directory Access Protocol standard:
http://www.ietf.org/rfc/rfc1777.txt
WebSphere Studio:
http://www.ibm.com/software/websphere/studio/


WebSphere Transcoding Publisher:
http://www.ibm.com/software/webservers/transcoding
Lotus product information:
http://www.lotus.com/home.nsf/welcome/products
WebSphere Everyplace Server:
http://www.ibm.com/pvc/products/wes_provider/index.shtml
Java Community Process, JSR 168:
http://jcp.org/jsr/detail/168.jsp

How to get IBM Redbooks
You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks

You can also download additional materials (code samples or diskette/CD-ROM
images) from that site.

IBM Redbooks collections
Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.

350 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access

Index
annotation processing 109
A annotations 114, 124
access controls 1
internal annotations 119
Access Privileges 18
application installation 272
Active Directory 159, 206
administration tools 205
ADSI Edit MMC snap-in 205 C
architecture 202 Client installation 316
configuring 203 communications adapter 272
dcpromo command 203 components 275
DNS 202, 204 Control Center 285
Domain Name System 202 Create DataPropagator Subscription wizard 49
external directory service 202 Create JDBC subscription 19
Group creation 225 Create JDBC Subscription wizard 14
installation 204 Create Subscription Set wizard 21
Installation wizard 205 Create Upload Subscription wizard 57, 75
LDAP 201–202
LDAP schema 213
management console 206
D
database URL 69
operations 207 DB2 1, 284
overview 202 DB2 Control Center 12
Permissions 204 DB2 data source 64
remote Active Directory 216 DB2 Everyplace 1, 5, 63
sample applications 201 DB2 Everyplace Sync Server 5
sample scenario 207 DB2 Everyplace Synchronization 3
scenario 203 Everyplace Client 3
self-enrollment 224 JDBC subscription 4
users and groups 208 MD5 6
Windows 2000 DNS 206 MDAC 5
Windows 2000 Server 202 Mobile Devices Administration Center 5
Active Directory Installation wizard 203 overview 4
Add to group 11 relational database synchronization 4
Add users to group 11 remote databases 3
Administration client 248 Secure Proxy 4, 6
administration tools 206 DBA Studio 347
administrative rights 273 Define Replication Subscription wizard 53
Administrator’s Console 310 define subscription set 20
administrator’s user name 288 Define Upload Subscription wizard 59, 76
AdminRole 309 destination folder 275
annotation DNS 206
instructions 118 Document Object Model 109, 145
annotation file 123 DOM 109
annotation instructions 125 domain suffix 273
annotation language 119 Domino 248


Application Server 238 HTTP Server 282
Enterprise Server 238
Mail Server 238
Domino Directory services 238
I
IBM Everyplace Client 1, 6
administration interface 265
IBM HTTP Server 283
architecture 238
IBM SecureWay Directory 159, 161
configuring 248
architecture 162
Directory Assistance 238
Directory Management Tool 164
Directory Catalog 238
install 163
Domino LDAP server task 238
LDAP search portlet 169
install 241
ldapsearch command 166
LDAP 252
remote SecureWay Directory server 171
sample applications 265
users and groups 240
sample scenario 163
Domino LDAP Directory 159
SyncGroup 171
DSYLDAP.properties 8
i-mode 146
dsysetjavahome.bat file 79
i-mode device 143
ImportResources command 116, 123
E installation 303
Everyplace Access 108 installation directory 286, 289
Everyplace Access installation 271 InstallShield wizard 316
Everyplace Toolkit 109 internal annotation 109, 115–116
Everyplace unified client 6 Internet Explorer 116
eXtensible Markup Language 129 iPlanet 159
iPlanet Directory 187
iPlanet Directory Server
F architecture 186
Fragmentation
configuration 187
common problems 148
hints and tips 200
example 148
installation 187
fragmentation transcoder 145
iPlanet Console 189
how it works 145
LDAP 185
i-mode (cHTML) 146
LDAP search portlet 196
WML 145
recommendations 200
fragmentor 145
sample scenario 187
G users and groups 186
Global Database Name 329
Group 5
J
Java Runtime Environment 273, 275
H Java Virtual Machine 276
Hints and tips 3, 321 JDBC interface xi, 360
HOME page group 312 JDBC Subscription 14, 19
HTML JRE 275
Document Object Model 145 JRE Version 1.3.0 273
HTML document 116 JVM 276
HTML portlet pages 81
HTTP 6


K mirror database 70
keep elements 113 Mobile Devices Administration Center 65
keyboard 272 one-way data transfer 74
replication interval 73
source database 74
L subscription 74
LDAP 159, 161, 237, 286–287
tables 72, 78
LDAP configuration 296
test connection 80
LDAP server 295
upload changes 74
LDAP services 237–238
Upload synchronization 65
ldapsearch 200
Oracle data source 64
license agreement 274
Oracle database
Lightweight Directory Access Protocol see LDAP
Hints and tips 79
log 285
JDBC driver 65
Lotus Domino server 237, 241
JDBC subscription 66
LTPA tokens 6
subscription 65
Test Connection 70
M upload subscription 74
Manage User Groups 9 Oracle Database Configuration Assistant 332
Manage Users Groups 312 Oracle Enterprise Edition 323
markup language 137 Oracle8i Enterprise Edition 324
MD5 6 Order column 342
MDAC 8, 22
MDAC screen 74
Membership 11
P
Page Designer 110, 116
mirror database 5, 70
parent synchronization group 10
mobile devices 5, 129
password 284–285, 296
Mobile Devices Administration Center 8, 13
PDAs 6
Pocket PC xi, 81, 117, 360
N pointing device 272
network software 272 Portal Administration 9
Nokia Mobile Internet toolkit 117 Portal Administration Page 312
Portal level transcoding 81
portal session 116
O portlet 116, 136, 298
offline Domino applications 6
Portlet parameters 122
offline Portal content 6
portlet WAR file 130
On-demand synchronization 1
portlet-level transcoding 83
Oracle 1
primary key 342
back-end database 65
data source 69
Database URL 68 R
DataPropagator subscription 65 Redbooks Web site 350
Event Message 66 Contact us xiii
filter 72, 77 Registering annotation files 123
hints and tips 79 relational database adapter 11
IBM DB2 Everyplace Server 80 relational database synchronization 12
JDBC 65 remote Oracle database 79
JDBC driver 65 removing columns 113

Index 353

replication frequency 19 subscription 12, 67, 75, 228
Replication Subscriptio 53 subscription set 5, 12, 70, 76
Request Viewer 91 subscription wizard 19
response file 280 sync servlet 7
RSS documents 136 synchronization 2, 5
RSS format 132 synchronization function 2
synchronization group 12
Synchronization Server 7, 299
S
sample database 339
sample installation 280 T
sample scenarios 109 tags 110
Sample stylesheets 138 target devices 137
schema 18 TCP/IP 272
Schema object 340 text clipping
Search Results 12 a clipping technique 108
Secure Proxy 5 annotation 107
Secure Sockets Layer (SSL) 1 annotation editor 108
SecureWay Directory Server 165 annotation instructions 108
Security Center 310 annotation language 119
Setup Manager 274, 277, 282, 284, 286, 302 annotation process 109
silent installs 280 condition 119
simple database 333, 339 DOM 109
SQL 1 external annotations 108
SSL 5 HTML document 107
Standard Install 279 HTTP header 107
stylesheet processing 129, 131 internal annotations 108
stylesheets markup action 119
configure a portlet 129 modified annotation 116
Configuring 130 Page Designer 110
Document Type Definition 136 Pocket PC 117
DTD 136 sample scenario 116, 120
Internet Explorer stylesheet 138 target node 119
ITSO News XML Feed 136 text replacement 111
multiple stylesheets 131 transcoding 116
overview 130 Transcoding Technologies 81, 83, 107
portlet parameters 134 a simple portlet 97
PortletFilterService.properties file 131 aggregator 86
registering 130, 135 annotation transcoding plug-in 90
resource 136 annotations 107
RSS data stream 132 annotators 84–85, 89
sample 138 architecture 85
sample scenario 136 column 108
wtp-condition statements 137 device 88
XML documents 129 Disable resources 91
XML Feed 132 document clipping 107
XMLFeed application 132 Document Object Model (DOM) 90
XMLFeed portlet 134, 136 Enable resources 91
Subscription 5 enable transcoding 98


Export resources 91 U
Extensible Markup Language 84 Universal Database 284
External annotation 90 upload subscription 75
external annotation 107–108 User 5
field 108 user name 284–285, 296
fragmentation transcoding plug-in 90 users and groups 12, 312
HTML pages 84 Users and Groups page 9
HTTP header 89 using stylesheets 81
image transcoding plug-in 90
Import resources 91
insertattribute 108 W
WAP browser 103
inserthtml 108
WAP devices xi, 360
Internal annotation 89
WAP phones 81
internal annotation 107–108
WAP/IP connection 151
keep 108
Web page 113
logging 94
WebSphere Application Server 5
Manage Portlets 100
WebSphere Everyplace Access
markup language conversions 85
administrator group 210
message files 96
disk space requirements 272
monitor the process 105
hardware requirements 272
option 108
hints and tips 271
overview 84
installation 208
plug-in 90
installation verification 311
Portal Administration 100
LDAP schema 216
Portal page level transcoding 85
operating system requirements 272
portlet filter 86
Pocket PC 271
Portlet-level transcoding 85
remote LDAP server 216
Portlets 100
sample installation 271
preference profiles 84, 86
SecureWay Directory 216
profile 88
server installation 272
remove 108
wpsadmins 210
replace 109
WebSphere Portal 8
replacewithhtml 109
WebSphere Studio Page Designer 111
Request Viewer 91
WebSphere Studio plug-in 109
row 108
welcome screen 274
sample application 110
Windows CE xi, 360
setpreference 109
wizards, using to create simple databases 333
splitpoint 109
wizards, using to create simple tables 339
stylesheets 85
WML browser 116, 118
text transcoding plug-in 90
WML document 117
tracing 94
WML fragmentation 81
tracing records 97
transcoding plug-in 84, 90
troubleshooting data 97 X
user 88 XML dialect 129, 132
user agent 85
XML config tools 91
XML stylesheets 84, 89

Index 355

RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access Version 4.1.1
(0.5” spine)
0.475”<->0.875”
250 <-> 459 pages

Back cover ®

RDB Synchronization, Transcoding
and LDAP Directory Services in
IBM WebSphere Everyplace
Access Version 4.1.1
Synchronize DB2 This IBM Redbook will help you plan, install and implement
Everyplace data with Relational Database Synchronization (RDB) with back-end
INTERNATIONAL
back-end DB2 and databases such as DB2 and Oracle using the JDBC interface, TECHNICAL
Oracle databases Transcoding Technologies and LDAP services, using SUPPORT
Lightweight Directory Access Protocol (LDAP) directories such ORGANIZATION
as IBM SecureWay Directory, iPlanet, Microsoft Active
Adapt portlet content
Directory and Domino LDAP Directory services in IBM
using Transcoding
WebSphere Everyplace Access Version 4.1.1.
Technologies BUILDING TECHNICAL
A step-by-step sample installation is also included to show INFORMATION BASED ON
Integrate WebSphere PRACTICAL EXPERIENCE
you how to install this product to support connections using a
Portal with existing Pocket PC. Hints and tips are also included where applicable.
LDAP services A basic knowledge of Lightweight Directory Access Protocol IBM Redbooks are developed by
(LDAP), IBM SecureWay Directory Server, DB2 Everyplace, the IBM International Technical
DB2 or Oracle databases, IBM HTTP Server, IBM WebSphere Support Organization. Experts
from IBM, Customers and
Application Server, IBM WebSphere Portal, Pocket PC,
Partners from around the world
Windows CE, WAP devices and Transcoding Technologies is create timely technical
assumed. 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

SG24-6856-00 ISBN 0738426636

RDB Synchronization, Transcoding and LDAP Directory Services ...

More Related Content

What's hot

Viewers also liked

Similar to RDB Synchronization, Transcoding and LDAP Directory Services ...

More from Videoguy

RDB Synchronization, Transcoding and LDAP Directory Services ...