• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
RDB Synchronization, Transcoding and LDAP Directory Services ...
 

RDB Synchronization, Transcoding and LDAP Directory Services ...

on

  • 1,727 views

 

Statistics

Views

Total Views
1,727
Views on SlideShare
1,727
Embed Views
0

Actions

Likes
0
Downloads
10
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    RDB Synchronization, Transcoding and LDAP Directory Services ... RDB Synchronization, Transcoding and LDAP Directory Services ... Document Transcript

    • 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 Solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 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.3 Installing WebSphere Everyplace Access . . . . . . . . . . . . . . . . . . . . . . . . 192 8.4 Sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 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 Solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 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.4 Installing WebSphere Everyplace Access . . . . . . . . . . . . . . . . . . . . . . . . 216 9.5 Sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 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. © Copyright IBM Corp. 2002. All rights reserved. 3
    • 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. 4 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. 6 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 1. Synchronizing with DB2 databases 7
    • 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 8 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 9
    • 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. 10 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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): 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. 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: 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, DB2e_employee. Note: The group name must begin with DB2e (case sensitive). g. Click Create Group. Chapter 1. Synchronizing with DB2 databases 11
    • 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): 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. 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: a. Click Start -> Programs -> IBM Everyplace Synchronization Server -> 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 12 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 13
    • 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. 14 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 15
    • 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. 16 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 17
    • 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. 18 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 19
    • 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. 20 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 21
    • 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. 22 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 23
    • 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. 24 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 25
    • 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. 26 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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”. Chapter 1. Synchronizing with DB2 databases 27
    • 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 28 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 1. Synchronizing with DB2 databases 29
    • 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. 30 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 31
    • 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. 32 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 33
    • 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. 34 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 35
    • 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. 36 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 37
    • 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. 38 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 39
    • • 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 40 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • <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. Chapter 1. Synchronizing with DB2 databases 41
    • 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. 42 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 43
    • 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. 44 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 45
    • 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 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) DPropR subscription DB2 source database SSL (optional) Everyplace Client Secure 127.0.0.1 DB2e Sync 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. 46 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 47
    • 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.... 48 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 49
    • 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. 50 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 1. Synchronizing with DB2 databases 51
    • 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. 52 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 53
    • 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. 54 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 55
    • 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 WebSphere Application Server Subscription set and IBM HTTP Server DB2 Everyplace Subscriptions Mobile Devices m23vnx78.itso.ral.ibm.com Administration Port 80 Center (MDAC) Upload subscription Basic Authentication DB2 source database SSL (optional) Everyplace Client Secure 127.0.0.1 DB2e Sync proxy Port 1080 DB2e database Pocket PC Figure 1-60 Upload subscription - sample scenario 56 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • To create an upload subscription: 1. Open the DB2 Control Center and Mobile Devices Administration Center by clicking Start -> Programs -> IBM Everyplace Synchronization Server -> 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. Chapter 1. Synchronizing with DB2 databases 57
    • 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 58 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 sets pane. You can also click Create... to create a new 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. Chapter 1. Synchronizing with DB2 databases 59
    • 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. 60 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 1. Synchronizing with DB2 databases 61
    • 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. 62 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. © Copyright IBM Corp. 2002. All rights reserved. 63
    • 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 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 Oracle source SSL (optional) database Everyplace Client Secure 127.0.0.1 DB2e Sync 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. 64 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. 66 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 2. Synchronizing with Oracle databases 67
    • 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. 68 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 2. Synchronizing with Oracle databases 69
    • 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. 70 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 2. Synchronizing with Oracle databases 71
    • 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. 72 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 2. Synchronizing with Oracle databases 73
    • 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. 74 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 WebSphere Application Server Subscription set and IBM HTTP Server DB2 Everyplace Subscriptions Mobile Devices m23vnx78.itso.ral.ibm.com Administration Port 80 Center (MDAC) Upload subscription Basic Authentication Oracle source SSL (optional) database Everyplace Client Secure 127.0.0.1 DB2e Sync proxy Port 1080 DB2e database Pocket PC Figure 2-17 Upload subscription - sample scenario You can create an upload subscription by following these steps: 1. Open the DB2 Control Center and Mobile Devices Administration Center by clicking Start -> Programs -> IBM Everyplace Synchronization Server -> 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 Chapter 2. Synchronizing with Oracle databases 75
    • 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 sets pane. You can also click Create... to create a new 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. 76 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 2. Synchronizing with Oracle databases 77
    • 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. 78 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 2. Synchronizing with Oracle databases 79
    • 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. 80 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. © Copyright IBM Corp. 2002. All rights reserved. 81
    • 82 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. © Copyright IBM Corp. 2002. All rights reserved. 83
    • 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. 84 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Transcoding Technologies 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 86 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 3. Transcoding Technologies 87
    • 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. 88 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 3. Transcoding Technologies 89
    • 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. 90 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 3. Transcoding Technologies 91
    • 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. 92 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 3. Transcoding Technologies 93
    • 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. 94 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure 3-6 Enable tracing portlet 2. Scroll down and find TranscodingTraceLogger. Check the box beside it. See Figure 3-7 on page 96. Chapter 3. Transcoding Technologies 95
    • 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 96 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 3. Transcoding Technologies 97
    • Everyplace Wireless Gateway WTE forward proxy WebSphere HTTP HTTP Everyplace Access WAP WAP Proxy and Gateway Transcoding Technologies 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> 98 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • <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. Chapter 3. Transcoding Technologies 99
    • 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. 100 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure 3-10 Choose HelloWorld portlet to modify its parameters 4. Add a parameter named FilterChain, with the value Transcoding. Click Save. Chapter 3. Transcoding Technologies 101
    • 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. 102 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 3. Transcoding Technologies 103
    • 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 104 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 3. Transcoding Technologies 105
    • Figure 3-16 Request Viewer 106 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 © Copyright IBM Corp. 2002. All rights reserved. 107
    • 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 108 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Transcoding Technologies 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. 110 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 4. Using annotation for document clipping 111
    • 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 112 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 4. Using annotation for document clipping 113
    • 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. 114 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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"> <!--METADATA type="Annotation" startspan <?xml version="1.0"?><annot version="1.0"> <replace><text>ITSO News</text></replace></annot>--> <B>The IBM Raleigh ITSO News for 07/20/2002</B> <!--METADATA type="Annotation" endspan--></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. Chapter 4. Using annotation for document clipping 115
    • 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*)”> <replace><text>ITSO News</text></replace></annot>--> <B>The IBM Raleigh ITSO News for 07/20/2002</B> <!--METADATA type="Annotation" endspan--></font></td></tr> 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. 116 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 4. Using annotation for document clipping 117
    • Example 4-3 New annotation condition <annot version="1.0" condition="!(device=*Internet+Explorer*)"> <replace><text>ITSO News</text></replace></annot>--> <B>The IBM Raleigh ITSO News for 07/20/2002</B> <!--METADATA type="Annotation" endspan--></font></td></tr> 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. 118 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 4. Using annotation for document clipping 119
    • 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. 120 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Example 4-5 Redbook02 HTML <html> <HEAD><META name="GENERATOR" content="IBM WebSphere Studio"></HEAD> <Title>The Redbook News</Title> <body bgcolor="#FFFFFF"> <!-- header & logo --> <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"> <td width="28">2</td> <td width="307"><font face="arial,sans-serif,helvetica" size="2"> <b>Building Portals </b></font></td> <TD width="83">SG99-9908</TD> <TD width="57">07/21/02</TD> </tr> <tr align="left"> <td width="28">3</td> <td width="307"><font face="arial,sans-serif,helvetica" size="2"> <b>Easy Application Development </b></font></td> <TD width="83">SG99-9909</TD> <TD width="57">07/21/02</TD> </tr> Chapter 4. Using annotation for document clipping 121
    • <tr align="left"> <td width="28">4</td> <td width="307"><font face="arial,sans-serif,helvetica" size="2"> <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 122 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 4. Using annotation for document clipping 123
    • 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"> <description target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]"> <replace> <text>ITSO Redbook News</text> </replace> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[2]"> <keep/> </description> </annot> 124 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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' ?> Chapter 4. Using annotation for document clipping 125
    • <annot version="2.0"> <description target="/HTML[1]/BODY[1]/CENTER[1]/H3[1]/text()[1]"> <replace> <text>ITSO Redbook News</text> </replace> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/P[2]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[2]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[3]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[1]/TH[4]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[1]"> <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[2]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[3]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[1]/TBODY[1]/TR[2]/TD[4]"> <remove/> </description> --------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]"> <keep/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[2]/TBODY[1]/TR[1]"> 126 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • <remove/> </description> <description take-effect="before" target="/HTML[1]/BODY[1]/CENTER[1]/TABLE[2]/TBODY[1]/TR[2]"> <keep/> </description> </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. Chapter 4. Using annotation for document clipping 127
    • 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. 128 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 © Copyright IBM Corp. 2002. All rights reserved. 129
    • 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. 130 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. 132 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 name="href"> <xsl:value-of select="link"/> </xsl:attribute> <xsl:value-of select="title"/> </a> </xsl:when> <xsl:otherwise> <a> <xsl:attribute name="href"> <xsl:value-of select="link"/> </xsl:attribute> <img border="0"> <xsl:attribute name="src"> <xsl:value-of select="url"/> </xsl:attribute> </img> </a> </xsl:otherwise> Chapter 5. Using XSL stylesheets 133
    • </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. 134 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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"?> <!--Date and Time of export :Thu Jul 25 17:44:46 EDT 2002--> <Resources ServerModel="testOne" Version="magic411srv"> <Stylesheet> Chapter 5. Using XSL stylesheets 135
    • <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> <Enable>true</Enable> </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. 136 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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> Chapter 5. Using XSL stylesheets 137
    • 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. 138 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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> <body bgcolor="#FFFFFF"> <center> <h2>ITSO Breaking News</h2> </center> <xsl:apply-templates/> <!-- footer --> <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> <xsl:value-of select="."/> </i> </xsl:template> <xsl:template match="story/releaseDate"> <b> <xsl:value-of select="."/> </b> </xsl:template> <xsl:template match="story/shortDetail"> <br/> </xsl:template> <xsl:template match="story/fullDetail/paragraph"> <p> <xsl:value-of select="."/> </p> Chapter 5. Using XSL stylesheets 139
    • </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 <?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!-- template for each newsitem --> <xsl:template match="newsitem"> <html> <body bgcolor="#FFFFFF"> <center> <h3>ITSO Breaking News</h3> </center> <br/> <xsl:apply-templates/> </body> 140 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • </html> </xsl:template> <xsl:template match="title"> <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 Chapter 5. Using XSL stylesheets 141
    • Nokia Toolkit The final stylesheet is for a WML device. The stylesheet is shown in Example 5-7. Example 5-7 WML stylesheet <?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!-- template for each newsitem --> <xsl:template match="newsitem"> <wml> <card> <p> <xsl:apply-templates/> </p> </card> </wml> </xsl:template> <xsl:template match="title"> <strong> <b> <xsl:value-of select="."/> </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 142 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. © Copyright IBM Corp. 2002. All rights reserved. 143
    • 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. Transcoding Technologies Portal-level Portlet-level transcoding transcoding Portlet Filter Portal Filter Portlet Aggregator Portal Figure 6-1 Portal-level transcoding in WebSphere Everyplace Access 144 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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.*)) &amp; (Accept=*wml*)) | (User_Agent=*Nokia*) &amp; (!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> <Enable>true</Enable> </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. 146 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 6. Portal-level transcoding 147
    • 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. 148 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • <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 Chapter 6. Portal-level transcoding 149
    • 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. 150 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Transcoding Technologies 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). Chapter 6. Portal-level transcoding 151
    • 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> 152 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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: Proxy /wps/* http://m23x303x/* 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. Chapter 6. Portal-level transcoding 153
    • 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. 154 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 6. Portal-level transcoding 155
    • 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 Transcoding Technologies 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. 156 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 6. Portal-level transcoding 157
    • 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 Transcoding Technologies m23m3041 m23x303x 9.24.106.102 9.24.105.103 Proxy directive: Proxy /wps/* http://m23x303x/* 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 Figure 6-12 on page 157. 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: Proxy /wps/* http://m23x303x/* 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-...... 158 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. . © Copyright IBM Corp. 2002. All rights reserved. 159
    • 160 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. © Copyright IBM Corp. 2002. All rights reserved. 161
    • 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 162 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. 164 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 165
    • 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 ... 166 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 167
    • 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. 168 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 169
    • 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. 170 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 171
    • 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 172 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 173
    • 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). 174 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 175
    • 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. 176 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 177
    • 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. 178 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 179
    • 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 180 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 181
    • 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. 182 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 7. IBM SecureWay Directory services in WebSphere Everyplace Access 183
    • 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. 184 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 8 Chapter 8. iPlanet Directory services in WebSphere Everyplace 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. © Copyright IBM Corp. 2002. All rights reserved. 185
    • 8.1 Solution architecture 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 WebSphere Everyplace iPlanet m23x2501.itso.ral.ibm.com Access V4.1.1 Directory Server Port 388 V5.1 WebSphere Application 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. 186 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Operating System Windows 2000 Server Windows 2000 Server Service Pack 2 Service Pack 2 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. 188 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 8. iPlanet Directory services in WebSphere Everyplace Access 189
    • 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. 190 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 8. iPlanet Directory services in WebSphere Everyplace Access 191
    • 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. 8.3 Installing 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. 192 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 8. iPlanet Directory services in WebSphere Everyplace Access 193
    • 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 ... 194 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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, dc=itso,dc=ral,dc=ibm,dc=com 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, dc=itso,dc=ral,dc=ibm,dc=com 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). Chapter 8. iPlanet Directory services in WebSphere Everyplace Access 195
    • 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. 8.4 Sample applications 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. 8.4.1 Configuring the LDAP Search portlet 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. 196 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 8. iPlanet Directory services in WebSphere Everyplace Access 197
    • 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). 198 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 8. iPlanet Directory services in WebSphere Everyplace Access 199
    • 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: http://docs.sun.com/?q=iplanet&p=/coll/S1_ipDirectoryServer_51 200 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 9 Chapter 9. Active Directory services in WebSphere Everyplace 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. © Copyright IBM Corp. 2002. All rights reserved. 201
    • 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. 9.2 Solution architecture 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 WebSphere Everyplace Active m23x3072.yourco.com Access V4.1.1 Directory Port 389 Server V5.0 WebSphere Application 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 202 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Operating System Windows 2000 Server Windows 2000 Server Service Pack 2 Service Pack 2 Domain yourco.com yourco.com 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. 204 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 9. Active Directory services in WebSphere Everyplace Access 205
    • 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. 206 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 9. Active Directory services in WebSphere Everyplace Access 207
    • 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 208 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 9. Active Directory services in WebSphere Everyplace Access 209
    • 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). 210 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 on page 212). Chapter 9. Active Directory services in WebSphere Everyplace Access 211
    • 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 on page 213). 212 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 9. Active Directory services in WebSphere Everyplace Access 213
    • 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 214 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • The User DN prefix is: cd The User DN suffix is: cn=Users,dc=yourco,dc=com The DN of the wpsadmins group is: cn=wpsadmins,cn=Users,dc=yourco,dc=com The User DN prefix is: cd The User DN suffix is: 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 dSCorePropagationData: 20020912153723.0Z dSCorePropagationData: 16010101000417.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 Chapter 9. Active Directory services in WebSphere Everyplace Access 215
    • 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. 9.4 Installing WebSphere Everyplace Access 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. 216 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 9. Active Directory services in WebSphere Everyplace Access 217
    • 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. 218 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 9. Active Directory services in WebSphere Everyplace Access 219
    • 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. 220 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 9. Active Directory services in WebSphere Everyplace Access 221
    • 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). 222 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure 9-16 Manage users and groups in Portal server 9.5 Sample applications 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). Chapter 9. Active Directory services in WebSphere Everyplace Access 223
    • 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. 224 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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). 2. Select Portal Administration. 3. Click the Users and Groups tab. 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). Chapter 9. Active Directory services in WebSphere Everyplace Access 225
    • 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 on page 227). 226 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 on page 228). Chapter 9. Active Directory services in WebSphere Everyplace Access 227
    • 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). 228 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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). Chapter 9. Active Directory services in WebSphere Everyplace Access 229
    • 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. 230 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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). Chapter 9. Active Directory services in WebSphere Everyplace Access 231
    • 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 (Figure 9-28 on page 233). 3. Click OK to close the window. 4. Click DB2 Everyplace Sync and from the menu, select Tools -> Configure (Figure 9-28 on page 233). 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). 232 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 9. Active Directory services in WebSphere Everyplace Access 233
    • 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. 234 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 9. Active Directory services in WebSphere Everyplace Access 235
    • Figure 9-32 The new record in the DB2 database after synchronization 236 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. © Copyright IBM Corp. 2002. All rights reserved. 237
    • 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. 10.2 Solution architecture 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. 238 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Windows 2000 Server Windows 2000 Server WebSphere Everyplace Domino m23x3074.yourco.com Access V4.1.1 Server V5.08 Port 386 WebSphere Application 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 Operating System Windows 2000 Server Windows 2000 Server Service Pack 2 Service Pack 2 Domain yourco.com yourco.com 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) 240 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 10. Domino Directory services in WebSphere Everyplace Access 241
    • 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. 242 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 on page 244. Chapter 10. Domino Directory services in WebSphere Everyplace Access 243
    • 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. 244 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 10. Domino Directory services in WebSphere Everyplace Access 245
    • 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. 246 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 10. Domino Directory services in WebSphere Everyplace Access 247
    • 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. 248 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 on page 250). Chapter 10. Domino Directory services in WebSphere Everyplace Access 249
    • 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. 250 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 10. Domino Directory services in WebSphere Everyplace Access 251
    • 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). 252 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 on page 254). Chapter 10. Domino Directory services in WebSphere Everyplace Access 253
    • 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. 254 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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). Chapter 10. Domino Directory services in WebSphere Everyplace Access 255
    • 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). 256 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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). Chapter 10. Domino Directory services in WebSphere Everyplace Access 257
    • 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 on page 259). 258 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. 10.4 Installing WebSphere Everyplace Access 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). Chapter 10. Domino Directory services in WebSphere Everyplace Access 259
    • 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. 260 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Chapter 10. Domino Directory services in WebSphere Everyplace Access 261
    • 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 on page 263). 262 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 10. Domino Directory services in WebSphere Everyplace Access 263
    • 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. 264 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure 10-26 Adding permissions to the wpsadmin user 10.5 Sample applications 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. Chapter 10. Domino Directory services in WebSphere Everyplace Access 265
    • 1. Log on to the Portal server as a wpsadmin user. 2. Select Portal Administration. 3. Click the Users and Groups tab. 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. 266 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 10. Domino Directory services in WebSphere Everyplace Access 267
    • 10.5.2 Configuring the LDAP Search portlet 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 268 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Chapter 10. Domino Directory services in WebSphere Everyplace Access 269
    • 270 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 © Copyright IBM Corp. 2002. All rights reserved. 271
    • 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. 272 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. 274 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 275
    • 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. 276 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 277
    • Figure A-11 View Information window 11.Read the license agreement and click Yes. Then click Next. 278 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-12 License agreement 12.Choose the installation type. For this sample, we chose Standard Install. Click Next . Appendix A. WebSphere Everyplace Access sample installation 279
    • 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. 280 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-14 Loading the response file 14.Select the desired components to install. For this sample, we install all the components. Click Next. Appendix A. WebSphere Everyplace Access sample installation 281
    • 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. 282 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 283
    • 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. 284 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 285
    • 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. 286 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 . Appendix A. WebSphere Everyplace Access sample installation 287
    • Figure A-21 Define the suffix and administrator’s user name and password 21.Define the administrator’s user name and password. Click Next. 288 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-22 Administrator’s user name and password for WebSphere Application Server 22.Enter the name of the installation directory. Click Next. Appendix A. WebSphere Everyplace Access sample installation 289
    • 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 . 290 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 291
    • 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 . 292 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 293
    • Figure A-27 LTPA password 27.Enter the relevant information for Portal server. Click Next. 294 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 295
    • 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. 296 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-30 Define LDAP configuration 30.Select Additional Database Configuration to install and enter the database administrator information defined earlier. Click Next. Appendix A. WebSphere Everyplace Access sample installation 297
    • Figure A-31 Additional database configuration 31.Select the portlets to be installed, and click Next. 298 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 299
    • 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. 300 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-34 Select Everyplace Synchronization Adapters 34.Enter WebSphere Application Server and WebSphere Portal server information. Click Next. Appendix A. WebSphere Everyplace Access sample installation 301
    • 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. 302 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-36 Summary 36.Installation starts. The Setup Manager displays the status of the installation process. Appendix A. WebSphere Everyplace Access sample installation 303
    • 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. 304 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 305
    • 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. 306 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-40 Open Security Center e. The Security Center opens. Appendix A. WebSphere Everyplace Access sample installation 307
    • 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. 308 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-42 Security Center h. On the Administrative Role tab, select AdminRole and click Select. The Select User/Group - AdminRole window is shown. Appendix A. WebSphere Everyplace Access sample installation 309
    • 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. 310 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 311
    • 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. 312 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Appendix A. WebSphere Everyplace Access sample installation 313
    • – 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. 314 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix A. WebSphere Everyplace Access sample installation 315
    • 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. 316 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-48 IBM Everyplace Client InstallShield welcome window 2. Answer Yes to the license agreement. Figure A-49 License agreement 3. Choose a folder to install the client. Click Next. Appendix A. WebSphere Everyplace Access sample installation 317
    • 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. 318 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure A-52 Review settings 6. The InstallShield wizard starts copying files. Figure A-53 Copying files 7. Upon completion, click Finish. Appendix A. WebSphere Everyplace Access sample installation 319
    • 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. 320 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Appendix A. WebSphere Everyplace Access sample installation 321
    • 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. 322 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. © Copyright IBM Corp. 2002. All rights reserved. 323
    • 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. 324 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. 326 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure B-5 Select product to install 7. Choose Typical as the installation type. Click Next. Appendix B. Sample Oracle Enterprise Edition installation 327
    • Figure B-6 Choose installation type 8. The installer starts loading installation files. 328 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure B-7 Loading installation files 9. In the next window, enter the Global Database Name and SID. Appendix B. Sample Oracle Enterprise Edition installation 329
    • Figure B-8 Enter Global Database Name and SID 10.A summary of this installation is displayed. Review it and click Install. 330 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure B-9 Summary window 11.The installer starts installing. Appendix B. Sample Oracle Enterprise Edition installation 331
    • 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 . 332 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix B. Sample Oracle Enterprise Edition installation 333
    • Figure B-13 Database Configuration Assistant 3. Select Typical. Click Next. Figure B-14 Database type 4. Select Create new database files. Click Next. 334 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix B. Sample Oracle Enterprise Edition installation 335
    • 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. 336 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix B. Sample Oracle Enterprise Edition installation 337
    • 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. 338 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix B. Sample Oracle Enterprise Edition installation 339
    • 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. 340 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Appendix B. Sample Oracle Enterprise Edition installation 341
    • 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. 342 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 Appendix B. Sample Oracle Enterprise Edition installation 343
    • 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. 344 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • Figure B-33 Check constraints 11.Click Next in the Storage Information window. 12.Choose not to partition this table. Click Next. Appendix B. Sample Oracle Enterprise Edition installation 345
    • Figure B-34 Partitions option 13.All the necessary information has been collected, and a summary is shown. Click Finish. Figure B-35 Summary 346 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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. Appendix B. Sample Oracle Enterprise Edition installation 347
    • 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. 348 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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: http://docs.sun.com/?q=iplanet&p=/coll/S1_ipDirectoryServer_51 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/ © Copyright IBM Corp. 2002. All rights reserved. 349
    • 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 © Copyright IBM Corp. 2002. All rights reserved. 351
    • 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 sample applications 169 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 applications 196 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 352 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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 354 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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
    • 356 RDB Synchronization, Transcoding and LDAP Directory Services in IBM WebSphere Everyplace Access V4.1.1
    • 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