Red

Note: Before using this information and the product it supports, read the information in “Notices” on page vii.
First Edition (February 2007)
This edition applies to IBM WebSphere Portal V5.1 and IBM WebSphere Portal V6.
© Copyright International Business Machines Corporation 2007. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
The team that wrote this IBM Redpaper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6. . . . . . . . . . . 1
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Understanding WebSphere Portal migration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2 Migration versus upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.3 Reasons for migrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 High-level overview of WebSphere Portal migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.1 Premigration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.2 Core migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.3 Document Manager and Personalization components . . . . . . . . . . . . . . . . . . . . . . 5
1.2.4 Workplace Web Content Management components. . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4.1 WebSphere Portal V6 environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4.2 Custom portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.4.3 External components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.4 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.5 Noncustom portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.6 Administration portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.7 Search indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.8 Virtual portals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.9 Themes and skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.10 Uniform Resource Locator mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.11 WebSphere Application Server artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.12 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5 Migration checklist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5.1 Steps to prepare your WebSphere Portal V6 environment for migration . . . . . . . 12
1.5.2 Steps to prepare your WebSphere Portal V5.1 environment for migration . . . . . . 13
Chapter 2. Considerations for migrating enterprise environments . . . . . . . . . . . . . . . 15
2.1 Migration approach between clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.1 The WebSphere Portal V5.1 server environment . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.2 The WebSphere Portal V6 server environment . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.3 Environment considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2 Maintaining customizations during migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2.1 Core WebSphere Portal customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2.2 Content changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 3. Migration of core components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.1 Collecting data from the WebSphere Portal V5.1 environment. . . . . . . . . . . . . . . . . . . 24
3.1.1 The Property Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.1.2 Installing the Property Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
© Copyright IBM Corp. 2007. All rights reserved.
iii

3.1.3 Running the Property Collector on WebSphere Portal V5.1 . . . . . . . . . . . . . . . . . 25
3.2 Copying data to WebSphere Portal V6 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.2.1 Copying the Property Collector output file to WebSphere Portal V6 server . . . . . 26
3.2.2 Collecting Web archive files for custom portlets and copying to WebSphere Portal V6 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.3 Migrating your portal using the WPmigrate command-line tool. . . . . . . . . . . . . . . . . . . 26
3.3.1 Extracting the data from the Property Collector output file . . . . . . . . . . . . . . . . . . 27
3.3.2 Exporting the configuration from WebSphere Portal V5.1 server . . . . . . . . . . . . . 28
3.3.3 Importing the configuration into WebSphere Portal V6 server . . . . . . . . . . . . . . . 33
3.4 Postmigration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.4.1 Restarting the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.4.2 Migrating WebSphere Member Manager database tables . . . . . . . . . . . . . . . . . . 38
3.4.3 Adjusting the page hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.4.4 Migrating the search collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4.5 Migrating the Search and Browse Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4.6 Migrating the credential vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.4.7 Administration portlets and pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.4.8 The Web Clipper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.4.9 Migrating the hidden pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.4.10 Migrating the WebSphere Application Server artifacts-Enterprise JavaBeans . . 48
3.4.11 Migrating the global portal settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.4.12 Migrating the portal service configuration properties . . . . . . . . . . . . . . . . . . . . . 49
3.4.13 Migrating the performance settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.4.14 Migrating the struts portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.4.15 Migrating the Click-to-Action portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.4.16 Migrating the business processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.4.17 Migrating the FileServer portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.5 Validating the portal and fixing any remaining issues . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Chapter 4. Migration of Document Manager and Personalization . . . . . . . . . . . . . . . . 51
4.1 The Document Transfer Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.1.1 Installing the Document Transfer Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.1.2 Validating the Document Transfer Tool installation. . . . . . . . . . . . . . . . . . . . . . . . 56
4.2 Migrating the Document Manager documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.2.1 Preparing a checklist for Document Manager validation. . . . . . . . . . . . . . . . . . . . 58
4.3 Synchronizing Document Manager global access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4.3.1 Modifying the Document Manager properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
4.3.2 Creating directories for Document Manager migration . . . . . . . . . . . . . . . . . . . . . 61
4.3.3 Running the export task for Document Manager . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.3.4 Copying files to the WebSphere Portal V6 server. . . . . . . . . . . . . . . . . . . . . . . . . 64
4.3.5 Running the transform task for Document Manager . . . . . . . . . . . . . . . . . . . . . . . 64
4.3.6 Running the import task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
4.3.7 Validating the Document Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.3.8 Postmigration task for Document Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.4 Migrating Personalization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.4.1 Preparing a checklist for Personalization validation . . . . . . . . . . . . . . . . . . . . . . . 68
4.4.2 Custom resource collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
4.4.3 Modifying Personalization properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
4.4.4 Creating directories for Personalization migration . . . . . . . . . . . . . . . . . . . . . . . . 70
4.4.5 Running the export task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
4.4.6 Copying files to WebSphere Portal V6 server. . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.4.7 Running the transform task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4.4.8 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
iv Best Practices for Migrating to IBM WebSphere Portal V6

4.4.9 Migrating the Personalization cache configuration . . . . . . . . . . . . . . . . . . . . . . . . 75
4.4.10 Running the import task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.4.11 Validating your Personalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
4.5 Postmigration tasks for Document Manager and Personalization. . . . . . . . . . . . . . . . . 76
4.5.1 Removing passwords from the Document Manager and Personalization property files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
4.5.2 Uninstalling the Document Tracking Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web
Content Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.1 Migration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.2 Workplace Web Content Management migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.3 Premigration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.3.1 Copying folders from WebSphere Portal V5.1 server to
WebSphere Portal V6 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.3.2 Preparing a checklist for Workplace Web Content Management validation . . . . . 87
5.3.3 Installing the Workplace Web Content Management migration tool . . . . . . . . . . . 88
5.3.4 Installing the authoring portlet to the Web Content Management page . . . . . . . . 94
5.3.5 Migrating the Workplace Web Content Management user data . . . . . . . . . . . . . . 95
5.3.6 Migrating the Workplace Web Content Management rendering portlets . . . . . . . 97
5.3.7 Postmigration tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Appendix A. Troubleshooting and other tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Business portlets not migrated during portal migration . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Temporarily halting user customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Delayed clean-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Changing the delayed clean-up property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Forcing immediate clean-up with xmlaccess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
List of admin portlets in WebSphere Portal V5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
List of admin portlets in WebSphere Portal V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Migrating the search collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Appendix B. Extending the WebSphere Portal migration framework . . . . . . . . . . . . 119
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Framework extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Core migration extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Plugging into the framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Migration filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Creating the River Bend migration sample plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Contents v

vi Best Practices for Migrating to IBM WebSphere Portal V6

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 illustrate 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. vii © Copyright IBM Corp. 2007. All rights reserved.

The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:
BetaWorks™
Cloudscape™
DB2®
Domino® i5/OS®
IBM®
Lotus®
Lotus Notes®
Notes®
Rational®
Redbooks™
Redbooks (logo)
Sametime®
Tivoli®
™
WebSphere®
Workplace™
Workplace Web Content
Management™ z/OS®
The following terms are trademarks of other companies:
Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates.
Enterprise JavaBeans, EJB, Java, JavaBeans, JavaScript, JavaServer, JavaServer Pages, JDBC, JSP, JVM,
J2EE, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Internet Explorer, Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, or service names may be trademarks or service marks of others. viii Best Practices for Migrating to IBM WebSphere Portal V6

This IBM® Redpaper provides detailed information about migrating from IBM WebSphere®
Portal V5.1 to IBM WebSphere Portal V6. This IBM Redpaper introduces the key considerations and the overall decision process before providing step-by-step instructions. It also provides a troubleshooting guide. This IBM Redpaper covers all the key concepts, from stand-alone core portal environments to comprehensive enterprise deployments with clustering, IBM WebSphere Portal components such as Document Manager, Personalization,
IBM Workplace™ Web Content Management, and others.
Whether you are a Line-of-Business Manager looking for overall information about migration, an IT Architect planning a migration, or an Administrator who has to perform the actual migration, this IBM Redpaper is for you.
This IBM Redpaper was produced by a team of specialists from around the world working at the International Technical Support Organization (ITSO), Cambridge MA Center.
Philip Monson is a Project Leader at the ITSO Lotus® Center in Cambridge MA. Phil has been with Lotus/IBM for 16 years, joining the company when the early versions of Lotus
Notes® were rolled out for internal use. He has served in management, technical, and consulting roles in the IT, Sales, and Development organizations.
Brian Cheng is a Portal Content Evangelist working in the WebSphere Portal Development
Organization. He uses a combination of applied knowledge gained from working with Sales,
Services, and Support, and comprehensive product knowledge gained from working on the development team, to effectively architect enterprise solutions. His primary focus is to advise and educate customers, sales and services teams, and development teams with his deep technical skills. His areas of expertise are Portal, Content Management, and Personalization.
Frederic Delos is the Technical Project Lead for IBM Early Deployment Center (EDC)
Workplace, Portal, and Composite Application Projects. He has over five years of experience in designing and deploying Next Generation Lotus Software environments for the EDC. He has developed and executed technical plans for internal Workplace and WebSphere Portal clustered production environments, and prepares technical enablement for the internal IBM systems team. He currently acts as the primary technical and change management liaison for executive-level IBM internal projects running within the Technology Adoption Program (TAP).
Dominic Glennie works as a WebSphere Portal Server consultant for the enterprise architecture division of Open Logic, an IBM premier Business Partner based in the UK
( http://www.openlogic.co.uk/) . He worked in J2EE™ and WebSphere Portal Server development, before switching to a WebSphere Portal Server infrastructure and administration role in 2005. He has worked on large WebSphere Portal engagements throughout the U.K.
Rob Holt is currently the Development Lead for the WebSphere Portal V6 migration team. He has over ten years of experience in software design and development. He has worked in various divisions of IBM, including the System and Technology Group, IBM Global Services, and the Software Group. He has worked as an IBM i5/OS® Software Developer, an IT specialist deploying WebSphere solutions, and an Installation Developer for the WebSphere
Portal and Workplace Collaboration Services products. He holds a Bachelor’s Degree in
© Copyright IBM Corp. 2007. All rights reserved.
ix

Electrical Engineering from North Carolina A&T State University in Greensboro, NC, and a
Master’s Degree in Electrical/Computer Engineering from the Old Dominion University in
Norfolk, Virginia.
Misao Ishikawa is an IT Architect with IBM BetaWorks™, leading WebSphere
Portal-managed beta programs for the last five years in Asia Pacific. He focuses on not only managing beta projects, but also on enablement programs for IBM Technical Salespersons and IBM Business Partners. He also leads beta programs for IBM Tivoli® Security products.
Previous experience includes customer projects that required integration architectures, such as Multi Vendor Solution, Nagano Olympics, and Enterprise Mail/CRM/Portal Solutions, among others.
Simon McNab works for IBM Software Support in the U.K. He provides voice and e-mail support for defects, and simple "how to" questions for the WebSphere Portal Server and the
Lotus product suite. Prior to joining Support, Simon worked in a number of service delivery roles, most recently as a WebSphere Application Server Administrator. He has been with IBM for 10 years and has a degree in Computer Sciences from the Pembroke College,
Cambridge. He has worked on two earlier IBM Redbooks™ on IBM WebSphere Application
Server on z/OS®.
William Trotman is a Software Engineer for the WebSphere Portal Server Level 2 support organization, North America. He has four years of experience working with the WebSphere
Portal Server. He holds a degree in Computer Science from North Carolina State University.
His areas of expertise include WebSphere Portal application programming interfaces (APIs) and migration.
Thanks to the following people for their contributions to this project:
Lee Berry
IBM WCM Software Engineer, IBM Software Group, Lotus
Scott Roehrig
PDM Software Engineer, IBM Software Group, Lotus
Lori Small
PDM Software Engineer, IBM Software Group, Lotus
Monica S. Harris
Software Engineer, IBM Software Group, Lotus
Join us for a two-week 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 will have the opportunity to team with IBM technical professionals,
Business Partners, and Clients.
Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you will 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
x Best Practices for Migrating to IBM WebSphere Portal V6

Your comments are important to us!
We want our papers to be as helpful as possible. Send us your comments about this IBM
Redpaper or other IBM Redbooks in one of the following ways:
򐂰 Use the online Contact us review IBM Redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an e-mail to: redbooks@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400
Preface xi

xii Best Practices for Migrating to IBM WebSphere Portal V6

1
Chapter 1.
This chapter provides an overview of migrating a WebSphere Portal V5.1 environment to
WebSphere Portal V6, and the considerations that go into planning a successful move. (The detailed steps are provided in the subsequent chapters.)
This chapter covers the following topics:
򐂰
1.1, “Introduction” on page 2
򐂰
1.2, “High-level overview of WebSphere Portal migration” on page 4
򐂰
1.3, “Planning” on page 6
򐂰
1.4, “Considerations” on page 6
򐂰
1.5, “Migration checklist” on page 12
© Copyright IBM Corp. 2007. All rights reserved.
1

This IBM Redpaper describes the steps and best practices for migrating an existing
WebSphere Portal V5.1 environment to WebSphere Portal V6. To help illustrate the steps involved in this process, the migration of the fictitious River Bend Coffee and Tea Company’s
(Figure 1-1) portal is described.
Figure 1-1 River Bend Coffee and Tea Company home page
This portal contains pages, custom portlets, and a variety of content, including Document
Manager, Personalization, and IBM Workplace Web Content Management™.
During this migration, migration steps that use the command-line interface are described. In the Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, a mention is made of a migration wizard that provides a graphical user interface (GUI) for migration: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
The best practice is to use the command line. It provides more flexibility and allows for additional verification after each migration task.
In this IBM Redpaper, the environment that is being migrated is configured to an IBM DB2® database and is secured with an IBM Tivoli Directory Server LDAP, all running on a
Windows® server. WebSphere Portal server migration is performed between two single server instances. Both these instances can reside in managed cells, but the target
WebSphere Portal V6 server must not
be clustered at the time of migration. After the migration is completed and verified, the WebSphere Portal V6 server can be clustered.
Additional considerations for production clustered systems are covered in Chapter 2,
“Considerations for migrating enterprise environments” on page 15.
In this case, migration is the process of reconstructing an existing IBM WebSphere Portal
V5.1 environment on to an IBM WebSphere Portal V6 environment so that the latter is identical to the former.
Following are the artifacts that are migrated in the process:
򐂰 Themes and Skins
򐂰 Pages
򐂰 Screens
򐂰 Portlet applications
򐂰 Access control
򐂰 User customization
򐂰 Virtual portals
򐂰 Markups
򐂰 Global settings
2 Best Practices for Migrating to IBM WebSphere Portal V6

򐂰 Portal resources
򐂰 Workplace Web Content Manager content and components
򐂰 Document Manager content
򐂰 Personalization rules
򐂰 Credential vault slots
WebSphere Portal migration does not upgrade the WebSphere Portal V5.1, but rather, is a set of steps to recreate the environment on a newly installed WebSphere Portal V6. This installation of WebSphere Portal V6 can be on the same machine or on a different one. The process moves the applications and configurations from the WebSphere Portal V5.1 to
WebSphere Portal V6. There is no process for upgrading a WebSphere Portal V5.1 to
WebSphere Portal V6.
Similarly, the migration process does not upgrade the themes, portlets, custom code, and components to use the new features of WebSphere Portal V6. If migration is successful, the portal must look and behave the same way it did on the WebSphere Portal V5.1 environment.
Taking advantage of new features such as drag-and-drop themes is a separate task that must be undertaken after a successful migration.
WebSphere Portal V6 is an enterprise portal solution for organizations that want to improve the effectiveness of their operations. WebSphere Portal is the industry's leading portal platform because it delivers a complete set of portal platform services with the reliability and scalability demanded by top global companies. The portal platform allows you to quickly deploy powerful portal applications that can be quickly customized to meet changing business requirements.
WebSphere Portal V6 currently consists of three offerings:
򐂰 IBM WebSphere Portal server
򐂰 IBM WebSphere Portal Enable
򐂰 IBM WebSphere Portal Extend
Following are the new key features:
򐂰 Portal interface includes new themes, drag-and-drop customizations, and fly-out menus
򐂰 IBM WebSphere Portlet Factory Designer allows you to quickly build composite applications from enterprise back-end systems
򐂰 Portal applications can be saved as templates for easy customization and deployment
򐂰 Searchability improved by external search engines
򐂰 Inline editing of portal content that feeds into a review, approval, and deployment workflow
򐂰 Portal users can edit electronic forms as part of a business process and store them in the portal document repository
򐂰 Microsoft® Internet Explorer® and Microsoft Office integration with Document Manager is included for easy file sharing and storage
򐂰 Policy-based administration and additional configuration options are available
򐂰 Performance enhancements to support an increased number of portal pages
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6 3

Following are the key benefits:
򐂰 Improves operational efficiency and productivity by linking the right people, processes, and information so that transactions are executed quickly and accurately
򐂰 Accelerates application and content deployment through new tools and the innovative use of service-oriented architecture (SOA)
򐂰 Lowers the overall cost of portal deployment with faster performance and easier administration
򐂰 Delivers responsiveness and reliability from a leader in the enterprise portal market
The migration process consists of a series of steps (some automated and some manual) that move the elements of your WebSphere Portal V5.1 environment to a newly installed
WebSphere Portal V6. Not all the steps will be required for every migration because not every
environment contains all the artifacts that can be migrated (refer to Figure 1-2 for more
details).
WebSphere Portal
Core Migration
Chapter 3
Do you have
PDM?
YES
Portal Document
Manager
Chapter 4
NO
Do you have
PZN?
YES
WebSphere Portal
Personalization
Chapter 4
NO
Do you have
WCM?
YES
WebSphere Content
Manager
Chapter 5
NO
Validate Server
Content
Figure 1-2 Migration overview
4 Best Practices for Migrating to IBM WebSphere Portal V6

This IBM Redpaper follows the migration of a portal containing many different components.
What follows is a brief explanation of each step involved in migrating to WebSphere Portal
V6.
The first step of the migration process is to install the WebSphere Portal V6 and configure the security to a user registry with the same users as the WebSphere Portal V5.1. If the user repositories are physically different (two separate installations), they are required to be the same brand of software and have exactly the same users with fully qualified distinguished names (DN).
At this stage, if the portal is to use an enterprise-level database, this must also be configured before beginning the migration. It is a requirement that the WebSphere Portal V6 server not be clustered during migration.
The server can be federated, although this is only recommended if the WebSphere Portal server is using the WebSphere process server. (This is discussed in greater detail in
Chapter 2, “Considerations for migrating enterprise environments” on page 15.)
The first step of core migration is to collect all the data that is required for the migration tasks, from the WebSphere Portal V5.1 environment. At this stage, the custom applications are manually copied across and a configuration task is run on WebSphere Portal V5.1 server, which assembles all the other required files together, such as the wpconfig.properties file and the themes and skins.
Using the properties gathered during the data collection, the remaining migration tasks have enough information to access the WebSphere Portal V5.1 server through xmlaccess.
The migration tasks then export all the portal configuration into an xml file.
This file is then filtered and transformed, before being imported into the WebSphere Portal V6 environment.
For portal environments that use the Document Manager and Personalization components, a tool is installed on the WebSphere Portal V5.1 server. This tool is used by migration tasks to export the components. The exported components are then transformed and imported into the new WebSphere Portal V6 server.
This stage of the migration process involves migrating the Workplace Web Content
Management components. This step moves the Workplace Web Content Management content to the new WebSphere Portal V6 environment and modifies the Workplace Web
Content Management viewer portlets to the new location of the content.
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6 5

For complex WebSphere Portal environments, migration can be a potentially lengthy process.
This section provides some key considerations that can help control this:
򐂰 Gathering skills and filling gaps
The migration process must be driven by a WebSphere Portal administrator, although additional skill sets may have to be made available during the process. Depending on the components used, aim to have development, database administrator, LDAP administrator,
WebSphere Process server, WebSphere Application Server, and Workplace Content
Management skills available.
򐂰 Hardware considerations
Portal migration can be run, with both WebSphere Portal V5.1 and WebSphere Portal V6 residing on the same machine or on different machines. (The scenarios performed to write this IBM Redpaper were run with the WebSphere Portal V5.1 and WebSphere Portal V6 running on different machines.)
򐂰 Topology assessment and application architecture
It is recommended that all the enterprise customers have a staging environment that matches the production. If possible, the staging environment must be used as the source for the migration. If migration is performed from a production-clustered environment, one of the nodes must be isolated from external traffic and used as the source server. This isolated node will still use the same portal configuration database and user repository.
This can cause some performance impact on the production system. These issues are
described in detail in Chapter 2, “Considerations for migrating enterprise environments” on page 15.
򐂰 Vendor applications
Check the topic “Supported hardware and software for WebSphere Portal Version 6.0” in the IBM WebSphere Portal Version 6.0 Information Center to confirm whether the versions of any third-party components are supported for WebSphere Portal V6: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/inst_req60.html
This section explains some elements of the WebSphere Portal environment that must be reviewed before starting the migration.
The WebSphere Portal V6 installation must reside on the same operating system (OS) as the
WebSphere Portal V5.1 environment. The WebSphere Portal V6 can be on a newer version of the same OS as long as it figures in the list of supported software in the IBM WebSphere
Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wpf/inst_req60.html
6 Best Practices for Migrating to IBM WebSphere Portal V6

Most of the portlets that worked in WebSphere Portal V5.1 require little or no change to run on WebSphere Portal V6. Having said that, there are several considerations that must be taken into account. Below is a list of commonly used frameworks and APIs in the development of custom portlets. It is recommended that you test your portlets on a
WebSphere Portal V6 test environment before migration. Any updates to the portlets must not be included until after the migration, when the WebSphere Portal administrator can update the application modules.
򐂰 IBM Rational® Application Developer V6 Portlet
Rational Application Developer V6 was released before WebSphere Portal V6. There are some cases where portlets developed using Rational Application Developer V6 will not work correctly. Rational Application Developer V7 will, however, support WebSphere
Portal V6. The following link provides information about some of the issues these portlets will face when migrated to WebSphere Portal V6: http://www-1.ibm.com/support/docview.wss?uid=swg27008730&aid=1
򐂰 IBM Portlet application programming interface
IBM Portlet API is deprecated in WebSphere Portal V6. However, it is still supported, and portlets written using the IBM API must work as before. It is recommended that you migrate the portlets as they are and then re-factor them using the Java™ Specification
Request (JSR) 168 Portlet API when convenient.
򐂰 Private APIs and Agreement for Exchange of Confidential Information
If you have an Agreement for Exchange of Confidential Information (AECI) in place to allow the use of private WebSphere Portal V5.1 APIs, these may have changed in
WebSphere Portal V6. It is likely that you will have to contact your IBM representative to get the updated APIs if they exist.
򐂰 Business processes
If you have business process applications developed for WebSphere Portal V5.1, changes will be required in both the business processes and the portlets in order to enable them to work on WebSphere Portal V6. The following Web site explains the changes required in your Business Process Execution Language (BPEL) applications: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wps/bpi_mig.html
򐂰 Click-to-Action and Cooperative Portlet
For Click-to-Action (C2A)/Cooperative Portlets, the pbportlet.jar must be updated. Refer to the following Web site for more details: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/mig_coop_portlet.html
򐂰 Struts Portlet
The steps for migration depend on the Struts Portlet Framework version that is being used by the application. Applications that package more recent versions of the Struts Portlet
Framework may require no changes at all when migrating to the current version of
WebSphere Portal. The following Web site provides additional information about migrating
Struts Portlets: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/mig_struts.html
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6 7

򐂰 Java Server Faces Portlet
Portlets developed by using the IBM API that use the Java Server Faces (JSF) framework will not work with WebSphere Portal V6 if they were developed using Rational Application
Developer V6. The following Web site provides additional information about portlets developed using Rational Application Developer V6.
http://www-1.ibm.com/support/docview.wss?uid=swg27008730&aid=1
򐂰 Predeployed enterprise archive file
Predeployed enterprise archive (EAR) files require the installation of fix PK32308.
Download this fix and check the fix’s readme file for any additional steps that may have to be followed.
򐂰 Collaborative Portlet
WebSphere Portal V5.1 of the IBM Domino® Application Portlet does not work on
WebSphere Portal V6. At the time of writing this IBM Redpaper, V6 of the Domino
Application Portlet was being written. The following Web site provides the most recent information about this portlet: http://www-1.ibm.com/support/docview.wss?rs=899&uid=swg21245417
The other Collaborative Portlets can migrate without any issue.
When moving custom applications from the WebSphere Portal V5.1 environment, external components must be taken into account before the WebSphere Portal migration. Following is a list of these external components:
򐂰 Web Services for Remote Portlets
Ensure that WebSphere Portal V6 is able to access the server that is providing the Web
Services for Remote Portlets (WSRP) that the server is attempting to consume.
򐂰 Custom-shared libraries
Ensure that any custom-shared library Java archive (JAR) files are copied across from both the <app_server_root>/lib and the <portal_server_root>/shared/lib on the
WebSphere Portal V5.1 environment to the WebSphere Portal V6 environment.
򐂰 Enterprise JavaBeans™
If your portlets are using Enterprise JavaBeans (EJB™) that must be installed on a new server, install and test these before the WebSphere Portal migration so that the portlet can be tested directly after the migration.
򐂰 Web services
Ensure that the Web services that your WebSphere Portal portlets access are accessible to the new server.
򐂰 Data sources
Take note of any data sources that exist on your WebSphere Portal V5.1 environment.
Re-create these data sources and test them before migration.
8 Best Practices for Migrating to IBM WebSphere Portal V6

For the WebSphere Portal migration to fully move your portal configuration, you must set up security on your WebSphere Portal V6 environment in exactly the same way it is on
WebSphere Portal V5.1. Ideally, this must be the same user registry, but might be a different physical server so long as it is the same schema and has exactly the same portal users.
򐂰 Implicit (private) pages
Pages that were created by users might cause problems during the migration if that user does not exist in the user registry. In the base WebSphere Portal V6 installation, if the owner of the page does not exist in the registry, the migration will stop. There is a fix available in development that filters the pages out of the migration if the owner of a page does not exist in the user registry. Refer to the following Web site for information about
WebSphere Portal migration fixes in order to see if PK33978 is available for download: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927
򐂰 Custom user login
If the WebSphere Portal V5.1 environment contains a custom LoginUserAuth class to add additional functionality during the logging process, these changes must be manually moved to WebSphere Portal V6. Because of changes in the API, code changes might be required before the class works with WebSphere Portal V6. This must be tested before migration.
򐂰 Custom User Registry
If the current WebSphere Portal V5.1 installation is using a Custom User Registry, and the plan is to continue using this registry, it must be configured and tested for WebSphere
Portal V6 before migration.
򐂰 WebSphere Member Manager (lookaside) database
The lookaside database is used to hold additional user attributes that are not held in the main user registry. Some organizations use WebSphere Member Manager to store additional user attributes that are used by the Personalization engine, Web Content
Management, or custom portlets. In such instances, the WebSphere Member Manager lookaside database must be migrated. Even if Web Content Management is configured, if it is not using categories and keywords, there might not be any information to be migrated from the database.
If it is determined that the lookaside database must be migrated, refer to the corresponding instructions in the chapter “Migrating the Member Manager database using the command line” under the topic “Migrating the remaining access control configuration” in the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/sec_mig_roles.html
The instructions provided in the information center are specific for DB2. If you are using a database other than DB2, contact your database administrator to help determine the proper commands for your environment.
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6 9

򐂰 Credential vault
The best method for migrating credential vault data is to use the Extensible Markup
Language (XML) Configuration Interface, which requires the installation of an interim fix
(PK28148) on both WebSphere Portal V5.1 and WebSphere Portal V6 environments.
Alternatively, you can migrate your credential vault data using Structured Query Language
(SQL) and direct database operations. The chapter “Migrating credential vault data” under the topic “Migrating the remaining access control configuration” in the IBM WebSphere
Portal Version 6.0 Information Center provides the necessary information: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/sec_mig_roles.html
Check the following migration fix download page for information about future fixes for credential vault migration: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927
Many of the portlets in your WebSphere Portal environment may have been installed by default, downloaded from the IBM portlet catalog, or provided by a third party. Following is a list of some considerations pertaining to these portlets:
򐂰 IBM Business Portlets
Business Portlets are portlets that IBM provides with WebSphere Portal by default or those that are downloaded from the IBM portlet catalog. Some business portlets will not
be moved to WebSphere Portal V6 by migration. Refer to Appendix A, “Troubleshooting and other tips” on page 103 for details.
Following is a list of a few common portlets that are used in WebSphere Portal V5.1:
– Web Clipping Portlet
There are no specific changes to the Web Clipping Portlet with regard to migration.
However, WebSphere Portal V6 ships with the latest version of the Web Clipping
Portlet. Therefore, you might notice some differences if you migrate from a system using an earlier version of the Web Clipping Portlet.
– Web Page Portlet
The Web Page Portlet is deprecated. All the functionalities of the Web Page Portlet are included in the Web Clipping Portlet. As a best practice, after migration, the Web
Clipping Portlet must be used instead of the Web Page Portlet.
– IBM Application Portlet Builder
The Application Portlet Builder portlets are being replaced by the WebSphere Portlet
Factory in WebSphere Portal V6. The Application Portlet Builder portlets are not supported on WebSphere Portal V6 and will not be migrated.
򐂰 Catalog portlets
For portlets that are downloaded from the IBM portlet catalog, the support level and agreement can be verified online under the portlet’s catalog entry. For portlets that are not supported by IBM, contact the software vendor for new releases and support.
򐂰 Portlets from vendors
Check with the vendors whether any of the portlets that they have provided are certified for WebSphere Portal V6, and follow the specific migration steps, if any.
10 Best Practices for Migrating to IBM WebSphere Portal V6

The WebSphere Portal V5.1 administration pages will not
be migrated to WebSphere Portal
V6. Any customizations made to the layout of the pages under administration will not be migrated and must be re-created. Pages outside the administration page that have administration portlets, must be manually checked to make sure that they are in the correct place and are working as expected.
WebSphere Portal migration does not
include the migration of the WebSphere Portal search
indexes. For more information about this, refer to 3.4.4, “Migrating the search collections” on page 41.
Virtual portals are migrated separately. Before migrating a virtual portal, create it in
WebSphere Portal V6. The virtual portals must be migrated one at a time after the migration of the default portal.
Migration tasks copy the WebSphere Portal themes and skins as is and install them on the new WebSphere Portal V6 environment. These WebSphere Portal V5.1 themes work on
WebSphere Portal V6 unmodified. Utilizing the new theme functionality in WebSphere Portal
V6 requires some modifications, and must not be performed until after the migration.
Any custom JavaServer™ Pages™ (JSP™) tag libraries and Tag Library Descriptor (TLD) files used by WebSphere Portal V5.1 themes must be manually moved from WebSphere
Portal V5.1 to WebSphere Portal V6.
Uniform Resource Locator (URL) mappings to pages that are filtered out during the migration must be re-created after the migration.
The portal configuration properties that were held under the
<portal_server_root>/shared/ext/config directory of each node in WebSphere Portal V5.1 are managed by the WebSphere Application Server admin console in WebSphere Portal V6.
They can be configured through the deployment manager in a cluster or the WebSphere
Application Server admin console in the case of a stand-alone node. Properties files do exist in WebSphere Portal V6, although these will only update the portal configuration after a configuration task is run.
Important: Do not use the WebSphere Application Server migration tasks. These are not required and will cause failures.
If you have made any changes to these configuration files in WebSphere Portal V5.1, you must verify whether the migration process has moved these across, and whether the values are applicable for the new WebSphere Portal V6 environment.
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6 11

Following is a list of additional settings:
򐂰 Additional WebSphere Application Server settings
Review any WebSphere Application Server settings that might have been made to your
WebSphere Portal V5.1 and check the WebSphere Application Server Information Center to see how to make these settings in the version of WebSphere Application Server that is used by your WebSphere Portal V6 environment.
򐂰 Java virtual machine settings
The Java virtual machine (JVM™) heap size requirements have changed between
WebSphere Portal V5.1 and WebSphere Portal V6. If the memory is available, the heap size must be increased on the WebSphere Portal V6 after the initial installation. After migration, the heap size must be tuned as part of performance testing.
If your system has had performance problems in the past, it is recommended that you review the WebSphere Portal V6 Tuning Guide. http://www-1.ibm.com/support/docview.wss?uid=swg27008511&aid=1
As a best practice, perform a dry run of your migration and use it to test your application for performance issues before performing production migration.
Before starting the migration, several tasks must be performed to prepare the WebSphere
Portal V5.1 and WebSphere Portal V6 environments.
Attention: Before starting the WebSphere Portal migration, review the WebSphere Portal
V5.1 wpconfig.properties file and ensure that the information in the file matches the current server settings as it is possible for them to get out of sync.
Perform the following tasks to prepare the WebSphere Portal V6 environment:
1. Install WebSphere Portal V6.
2. Disable the WebSphere Portal V6 default security and enable it in the same way as the
WebSphere Portal V5.1 environment (refer to 1.4.4, “Security” on page 9).
3. Transfer the WebSphere Portal V6 configuration to use the same database type as your
WebSphere Portal V5.1.
4. Verify that you can stop and start WebSphere Portal and log in to the default WebSphere
Portal V6 welcome page.
5. Before starting, create the virtual portals that exist in your WebSphere Portal V5.1 environment prior to the migration.
6. Download the latest WebSphere Portal Update Installer for the WebSphere Portal V6 you are using, from the following Web site: http://www-1.ibm.com/support/docview.wss?rs=688&uid=swg24006942
12 Best Practices for Migrating to IBM WebSphere Portal V6

7. Install all the required fixes before migration. Not all the migration fixes listed in the following Web site are required because some may be dependent on the additional components you expect to migrate: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927
Perform the following tasks:
1. Prepare validation criteria, including the test scripts .
2. Ensure that the wpconfig.properties file is up-to-date with the current values on the
WebSphere Portal V5.1 server.
3. Restart the source WebSphere Portal server before starting the migration.
4. Ensure that the previous environment is stable and working as expected.
5. Download the latest WebSphere Portal Update Installer for the WebSphere Portal V5.1 server you are using, from the following Web site: http://www-1.ibm.com/support/docview.wss?rs=688&uid=swg24006942
6. Install all the required fixes before the migration. The WebSphere Portal V6 installation media contains the current required fixes for each of the supported versions of
WebSphere Portal V5.0 and WebSphere Portal V5.1. These fixes are in the
<portal_server_root>\migration\fixes directory of the WebSphere Portal V6 server. Find the directory for the version of WebSphere Portal server that matches the source environment and install these fixes. It is also recommended that you check the following
Web site for any additional migration fixes that are required for the WebSphere Portal server version: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927
7. Run the validate database connection task on your previous environment to verify that the proper values are specified in the wpconfig.properties file because these values are required when running the migration tasks.
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6 13

14 Best Practices for Migrating to IBM WebSphere Portal V6

Chapter 2.
Typically, a WebSphere Portal migration will not simply take place between two static, stand-alone servers. Although the process for migrating more complex production environments is fundamentally the same, there are some additional considerations.
This chapter discusses the following topics specific to live cluster environments:
򐂰
2.1, “Migration approach between clusters” on page 16
򐂰
2.2, “Maintaining customizations during migration” on page 18
2
© Copyright IBM Corp. 2007. All rights reserved.
15

The migration tasks always operate between one source server and one target server. This section discusses how this must be achieved when the source is a part of a cluster, and the target server is intended to be clustered.
A WebSphere Portal V5.1 server clustered environment has multiple, identical servers residing on one or more nodes. Each server shares the same portal configuration database.
The migration tasks only have to interact with one of these servers, which in turn will be the source of all the migrated artifacts. To minimize interference with the rest of the cluster, the node containing this source server must be isolated. This can be achieved by shutting down the server’s node agent and halting user traffic with a method appropriate to your environment. This may, for instance, involve editing out the source node from the Hypertext
Transfer Protocol (HTTP) Server plug-in configuration file.
Attention: Applying fixes to the isolated node may alter the shared portal configuration database. This can cause the other servers to be in an inconsistent state. The fixes mentioned in this IBM Redpaper must not cause a problem, although care must be taken if any additional fixes are applied. Ensure that any fixes that are applied to the isolated node are either applied to the rest of the cluster members or are removed before restarting the node agent.
Tip: All the WebSphere Portal servers within the cluster share the same portal configuration database. Even after being isolated from the deployment manager and user traffic, the source server has the potential to put a load on this database. Therefore, consideration must be given to when migration tasks are run so that the performance impact on the production environment is minimized.
The migration process configures a server on the primary node for the new environment. The
WebSphere Portal V6 cluster must not
be built until after the migration of the WebSphere
Portal V5.1 artifacts. Migrating to a cluster is not
supported and adds unnecessary complexity to the migration process.
The target primary node must be either a stand-alone WebSphere Portal V6 server node or a managed node that is part of a deployment manager cell. In either case, the remaining tasks involved in creating the cluster must be applied after the migration process is completed.
To provide the WebSphere Portal V6 environment, the WebSphere Process server is not used. It is recommended that the source server for the migration be on an unmanaged node.
Create the cluster after the migration is completed by following the steps documented in the
IBM WebSphere Portal Version 6.0 Information Center, which is available on the Web at: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wpf/welcome.html
16 Best Practices for Migrating to IBM WebSphere Portal V6

Also refer the IBM Redbook WebSphere Portal 6 - Best Practices for Enterprise Scale
Deployment, which is available in draft form on the Web at: http://www.redbooks.ibm.com/redpieces/abstracts/sg247387.html?Open
Important: The standard installation process provides the choice of installing WebSphere
Portal V6 with or without the WebSphere Process Server. If the node is to eventually become a part of a cluster, the installation must take place without
the WebSphere
Process Server. Otherwise, it will not be possible to create a cluster from it.
Migrating to an unmanaged node allows the potentially complex task of clustering to be treated separately from the migration process. It also means the configuration of the primary node is kept if the node is ever removed from the cell.
Tip: Because the WebSphere Portal V6 environment is built, take frequent backups of the files and the databases. Always take a backup just before federating the primary node into a cluster because errors often occur during this process.
If the target for the migration is a managed node, the configuration of the migrated server exists only in the cell. If the node is removed from the cell, the configuration will be restored to the state it was in prior to running the addNode command, and the migrated portal configuration will be lost.
Important: For WebSphere Portal server clusters with WebSphere Process Server, the portal component must be installed on a managed WebSphere Application Server node. It is not possible to create a WebSphere Process Server cluster from a standard installation of WebSphere Portal. Therefore, if the intended environment is to include WebSphere
Process Server and be clustered, the migration must be to a managed node.
This section provides information about the various environment considerations.
As a best practice, the migration tasks must be run against the transport ports of the
WebSphere Portal server instead of the HTTP Server. For more details, refer to Chapter 3,
“Migration of core components” on page 23.
It is recommended that transferring the portal configuration database from IBM Cloudscape™ to an enterprise-level database be completed before you start the migration. The performance benefits of an enterprise-level database can speed up the migration tasks considerably. This is particularly evident for Workplace Web Content Management content.
On the rough tests that we ran, the Workplace Web Content Management tasks were over ten times quicker when DB2 over Cloudscape was used.
Migration between WebSphere Portal V5.1 and WebSphere Portal V6 installations located on the same physical server is supported. This is undesirable if the source environment is in production. However, for migrations between the staging or test environments, this might help save resources.
Chapter 2. Considerations for migrating enterprise environments 17

In many cases, there will not be enough resources to comfortably run both WebSphere Portal
V5.1 server and WebSphere Portal V6 server at the same time. Doing so might cause resource contention issues, which in turn is likely to cause failures. The migration tasks do not require both the servers to be running. During the export tasks, only WebSphere Portal V5.1 server must be up. During the import tasks, only WebSphere Portal V6 server is used. As a result, the servers can share the same ports so long as they are not started at the same time.
After migration, the WebSphere Portal V6 server environment must undergo performance testing and tuning. Alterations made to WebSphere Portal V5.1 server for tuning purposes may not be applicable in WebSphere Portal V6 server. As a best practice, a performance baseline of the environment must be taken before the migration in order to be used for comparison. For more details, refer to IBM WebSphere Portal V6 Tuning Guide on the Web at: http://www.ibm.com/support/docview.wss?rs=688&uid=swg27008511
WebSphere Portal production environments are often dynamic, allowing users to customize pages and portlets and to add Workplace Web Content Management and Document
Manager content. This section discusses how these ongoing changes to live environments may be persisted during migration.
Many WebSphere Portal environments allow users to customize the pages and portlets they have access to. When a user customizes a page by modifying a portlet parameter, for instance, WebSphere Portal server creates an implicit private page in the portal configuration database. These additions to the portal configuration will only exist in the production environment. To maintain these configurations, the live environment must be used as the source for migration.
Tip: If it is possible to update the WebSphere Portal V5.1 server staging environment with the latest user customizations from production, this staging environment can be used as the source for the migration.
If user customizations are not allowed in production, the staging environment must have exactly the same configuration in the WebSphere Portal server database as in production. In this case, one of the servers within the staging environment must be used as the source for the core migration tasks. This eliminates unnecessary load on the live environment and produces the same result as using a production server.
Any user customization that occurs between running the export portal content task and switching the new WebSphere Portal V6 server environment into production, is lost. There are four basic approaches to dealing with this:
򐂰 Migrate during downtime in the production environment.
򐂰 Accept losses in user customizations.
򐂰 Turn off customization in production for the duration of the migration process.
򐂰 Migrate the environment and export the pages that may have been customized from production, and import these into WebSphere Portal V6.0 server after migration.
18 Best Practices for Migrating to IBM WebSphere Portal V6

These approaches are not mutually exclusive, and must be combined in a manner that is suitable to your environment. For complex environments, it is usually not possible to migrate an entire system and switch it into production during downtime. This section describes how these methods can be used.
Note: WebSphere Portal V6 server allows user customizations to be stored in a separate database domain that can be shared between clusters. This functionality is likely to be utilized to ease the migration process between V6 and the next major WebSphere Portal release, by allowing the source servers and the target servers to share the same customization database.
If access rights that allow users to customize pages and portlets are removed, this guarantees that the WebSphere Portal server configuration will not change during migration.
These access rights can be changed through xmlaccess or the WebSphere Portal server admin console. With either method, the effect of changing these access rights must be tested in the staging environment before applying to production.
In Appendix A, “Troubleshooting and other tips” on page 103, under the topic “Temporarily halting user customization” on page 105, one method for achieving this by using xmlaccess is
described. Note that where possible, this must be performed after exporting the WebSphere
Portal V5.1 server portal configuration so that the access control rights do not have to be reapplied to the WebSphere Portal V6 server environment postmigration.
In some WebSphere Portal environments, user customizations may be integral to the daily running of the applications. Therefore, it might not always be possible to utilize this approach.
It is possible to reapply the core migration tasks after initially migrating. This moves across the additional user customization that has taken place in the WebSphere Portal V5.1 server environment into WebSphere Portal V6 server. However, this overwrites any changes that have been made in the WebSphere Portal V6 server environment postmigration, including those made by the Workplace Web Content Management configuration tasks. It might also fail completely if pages have been deleted or if portlets have been updated.
As a best practice, it is recommended that for any customizations that cannot be halted in production, the specific WebSphere Portal server artifacts be moved across using xmlaccess as a final migration task.
The xmlaccess configuration tool is compatible with later versions. Therefore, it is possible to export a page along with all its associated implicit pages, and then reimport them into
WebSphere Portal V6 server.
Tip: When exporting pages using xmlaccess, it is a best practice to use custom-unique names. Set these up before migrating to WebSphere Portal V6 server so that the environments match.
Chapter 2. Considerations for migrating enterprise environments 19

In the River Bend environment, after migration, additional implicit pages were created by logging in as users and editing the parameters of a portlet. The page and its child-implicit
pages with the unique name wps.test1 were exported using the script shown in Example 2-1.
Example 2-1 Sample xmlaccess script for reimporting a page and all the child-implicit pages
<?xml version="1.0" encoding="UTF-8"?>
<request
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PortalConfig_1.3.xsd"
type="export">
<!-- sample for exporting a page -->
<portal action="locate">
<content-node action="export" uniquename="wps.test1" export-descendants="true"/>
</portal>
</request>
Tip: For the implicit private pages to be exported, the export-descendents parameter of the content node in the xmlaccess request must be set to true .
Document Manager and Workplace Web Content Management content may change in production, between exporting the content and moving the new WebSphere Portal server environment into production. As with customizations to pages in production, migrating these artifacts may require you to halt the creation of the content or to reimport the content.
Within the River Bend environment, it was possible to rerun the Document Manager migration tasks. Any changes or additions to the documents in the WebSphere Portal V5.1 environment was successfully updated in WebSphere Portal V6.0. Follow the steps described in
Chapter 4, “Migration of Document Manager and Personalization” on page 51 for running the
Document Manager migration tasks.
Attention: Before running the Document Manager and Personalization migration tasks, ensure that the directories specified in the pdm_conf.xml and pzn_conf.xml are empty.
Otherwise, the tasks will fail.
If Personalization rules have changed in the production environment during migration, all the migrated Personalization artifacts on the WebSphere Portal V6 server environment must be removed before the migration tasks can be run again. Otherwise, the tasks will fail. Any additional rules created for WebSphere Portal V6 can remain, so long as the names are unique.
The Web Content Management migration import task will not succeed if a Workplace Web
Content Management library exists with the same name. Two options are available for reimporting the content:
򐂰 Changing the name of the imported library and rerunning the migration tasks
򐂰 Deleting the library and rerunning the migration tasks
20 Best Practices for Migrating to IBM WebSphere Portal V6

Attention: At the time of writing this IBM Redpaper, Workplace Web Content Management libraries could not be deleted from our example River Bend environment on WebSphere
Portal V6. Check with IBM support for a fix.
Refer to Chapter 5, “Migration from WebSphere Portal V5.1 for deployments with Workplace
Web Content Management” on page 77, for details about running the Workplace Web
Content Management migration tasks.
Chapter 2. Considerations for migrating enterprise environments 21

22 Best Practices for Migrating to IBM WebSphere Portal V6

3
Chapter 3.
This chapter describes the process involved in migrating the core components of WebSphere
Portal V5.1 to WebSphere Portal V6, using the command-line tools. These tools are the familiar
WPSconfig
, and the new command-line tool
WPmigrate
. The process is independent of the operating system, database, and security configuration.
Important: Migration requires careful planning and preparation. Make sure that you have read and taken the necessary action pertaining to all the relevant requirements described
in Chapter 1, “Getting started: WebSphere Portal migration from V5.1 to V6” on page 1 and
Chapter 2, “Considerations for migrating enterprise environments” on page 15, before
attempting a migration.
Following is the process involved in migrating the core components:
1. Collecting data from the WebSphere Portal V5.1 environment
2. Copying this data to the WebSphere Portal V6 environment
3. Migrating your portal using the WPmigrate command-line tool: a. Extracting the data from the Property Collector output file a. Exporting the configuration from WebSphere Portal V5.1
a. Importing the configuration into WebSphere Portal V6
4. Performing the postmigration tasks
5. Validating your portal and fixing any remaining issues
Throughout this IBM Redpaper, the installation location for the portal server component of
WebSphere Portal is referred to as <portal_server_root>.
We assume that the WebSphere Portal V6 and WebSphere Portal V5.1 environments are on different physical servers because this is the most common migration scenario.
To test the example River Bend environment, we used Windows servers. Therefore, the syntax of commands and the directory structures in this chapter are specific to a Windows environment. It is recommended that you verify the correct syntax for your operating system.
© Copyright IBM Corp. 2007. All rights reserved.
23

The first step is to collect data from the WebSphere Portal V5.1 environment. This will be used during the later stages of the migration process.
The Property Collector is a WPSconfig task that is run against the WebSphere Portal V5.1 to collect configuration properties from the file system and the database. It creates a compressed file, which must then be manually copied to WebSphere Portal V6. This file is used to supply configuration information, which is used in the later stages of the migration process. It also contains the themes and skins from the WebSphere Portal V5.1. There are no special considerations if you are using virtual portals.
Some of the WPmigrate commands that will be used later make connections to the
WebSphere Portal servers. The host name and the port number for these connections are obtained from the wpconfig.properties files on each machine. The recommended best practice is to connect directly to the Hypertext Transfer Protocol (HTTP) Listener in the
WebSphere_Portal application server instead of through an HTTP Server. This reduces the chances of failure due to network issues and timeouts.
Among other things, the Property Collector collects wpconfig.properties from the WebSphere
Portal V5.1 server. This Collector output file is manually copied to WebSphere Portal V6 and is then used by WPmigrate. Therefore, ensure that wpconfig.properties on the WebSphere
Portal V5.1 server specifies the host name and the port name of the HTTP Listener in the
WebSphere_Portal application server before progressing.
Attention: Ensure that WpsHostName in wpconfig.properties on the WebSphere Portal
V5.1 server is correctly set to a fully qualified host name, and not localhost.
The Collector output file is written to
<portal_server_root>\config\includes\propcollectorOutput.zip.
Like all WPSconfig tasks, this logs to <portal_server_root>\log\ConfigTrace.log.
The Property Collector is supplied with the WebSphere Portal V6 installation. Two files have to be manually copied from your WebSphere Portal V6 server into your WebSphere Portal
V5.1 server. Copy both
these files from WebSphere Portal V6 server to WebSphere Portal
V5.1 server:
򐂰 <portal_server_root>\migration\propcollector.jar
򐂰 <portal_server_root>\migration\propcollector.xml
Copy these to <portal_server_root>\config\includes on your WebSphere Portal V5.1 server.
24 Best Practices for Migrating to IBM WebSphere Portal V6

This section describes how to run the Property Collector on WebSphere Portal V5.1.
Tip: If you are migrating from a cluster, the Property Collector can be run on any cluster member.
Neither WebSphere Portal V5.1 nor WebSphere Portal V6 is required to be running at this time.
Restriction: If you are exporting from Cloudscape, WebSphere Portal V5.1 server must
be shut down. Otherwise, an exception occurs and the Collector fails. This is because
Cloudscape is a single Java virtual machine (JVM) database and the Property Collector cannot access the database when the WebSphere Portal server is running.
To run the Property Collector, type the following commands one after the other from a command prompt on your WebSphere Portal V5.1 server:
򐂰 cd <portal_server_root>\config
򐂰 WPSConfig.bat prop-collector -DDbPassword=wpsdb_password
Tips:
򐂰 -DDbPassword=wpsdb_password is not required if the value is already defined in the wpconfig.properties file.
򐂰 The location of the Collector output file can be overridden by using
-Dcollector.output.file=<fully_qualified_file_name>, for example, WPSconfig.bat prop-collector -Dcollector.output.file=C:\tmp\collector.zip.
򐂰 All the directories in the path must exist.
The WPSconfig command must report the following message:
BUILD SUCCESSFUL
To further verify successful completion, check if the Collector output file is successfully written and whether it can be opened using a zip reader of your choice. The exact contents of the
Collector output file is undocumented and subject to change. However, you must be able to read the individual files inside.
If the Collector does not run successfully, check the output from the command and the
ConfigTrace.log.
The Property Collector can be rerun at any time. Although it will overwrite any existing output file without warning, it is a good idea to delete the existing Property Collector output file first.
Chapter 3. Migration of core components 25

This section shows you how to make the Collector output file and the custom or the third-party Web archive (WAR) files available to WebSphere Portal V6 server.
Copy the Collector output file created in “Running the Property Collector on WebSphere
Portal V5.1” on page 25 to <portal_server_root>\migration\propcollectorOutput.zip on your
WebSphere Portal V6 server.
Tip: It is worth ensuring that the Collector output file on the WebSphere Portal V6 server is readable after being copied.
The WAR files are not migrated automatically. They must be in the
<portal_server_root>\installableApps directory on WebSphere Portal V6 server prior to running the import that will redeploy them.
The migration task will fail and halt if any of the required WAR files have not been copied to
WebSphere Portal V6 server.
Important:
򐂰
If you have any portlets in predeployed enterprise archive (EAR) files, refer to 1.4.2,
“Custom portlets” on page 7.
򐂰 Copy only the customized WAR files. Do not copy the entire directory because this overwrites the new WebSphere Portal V6 server portlets.
The remaining tasks involved in the migration process must be run from WebSphere Portal
V6 server. Use the new command-line tool WPmigrate. This migrates the WebSphere Portal
V5.1 server configuration to WebSphere Portal V6 server. Some tasks must be performed
manually after this migration. These are detailed in 3.4, “Postmigration tasks” on page 38.
The WPmigrate tool is used for the following:
򐂰 Extracting the data from the Property Collector output file
򐂰 Exporting the configuration from WebSphere Portal V5.1
򐂰 Importing the configuration into WebSphere Portal V6
The WPmigrate command is entered from the <portal_server_root>\migration directory on
WebSphere Portal V6 server. It writes a log file to
<portal_server_root>\log\MigrationTrace.log.
26 Best Practices for Migrating to IBM WebSphere Portal V6

Important: Like WPSconfig, WPmigrate appends to its log file on each execution.
However, WPmigrate overwrites any other files that it creates. Therefore, it is recommended that you make copies of these files before rerunning the command.
Tip: If there is a syntax error, for example, “WPmigrate.bat collector-extarct” instead of
“WPmigrate.bat collector-extract”, you will see the following message:
BUILD FAILED
Target ‘collector-extarct' does not exist in this project.
The export and import stages run xmlaccess. As mentioned in “Running the Property
Collector on WebSphere Portal V5.1” on page 25, it is recommended that you run xmlaccess
directly against the HTTP Listener in the WebSphere_Portal Application Server, instead of through an HTTP Server. Because the host name and the port name cannot be entered through the command line, verify that WpsHostname, WpsHostPort, XmlAccessHost, and
XmlAccessPort are set appropriately. Note that XmlAccessHost and XmlAccessPort are new parameters in WebSphere Portal V6 and do not therefore apply to WebSphere Portal V5.1.
XmlAccessHost is set to localhost by default and does not have to be changed.
For the WebSphere Portal V6 server, these parameters are set in wpconfig.properties in
<portal_server_root>\config. For the WebSphere Portal V5.1 server, they are set in wpconfig.properties, which has already been collected by the Property Collector.
This WPmigrate task is run on the WebSphere Portal V6 server. It extracts the contents of the
Collector output file transferred earlier into <portal_server_root>\migration\work\collector. The directories are created if they do not already exist. There are no additional considerations if you are using virtual portals.
This task extracts data from the Collector output file. There is no interaction with either the
WebSphere Portal V5.1 server or the WebSphere Portal V6 server.
Enter the following command:
<portal_server_root>\migration WPmigrate.bat collector-extract
No user ID or password is required to run this task. You only require read and write access to
<portal_server_root>\migration.
Tip: If you prefer to, you can copy the Collector output file to a different location and use the following command instead:
WPmigrate.bat collector-extract -DCollectorOutputFile=<fully qualified name of collector output file>
No actions are required for virtual portals at this time.
Chapter 3. Migration of core components 27

Successful completion is indicated by the following message:
BUILD SUCCESSFUL
You can also inspect the contents of <portal_server_root>\migration\work\collector to ensure that the contents are readable.
If you do not get a BUILD SUCCESSFUL message, examine the messages that are created and review <portal_server_root>\log\MigrationTrace.log to find out the cause.
This can be rerun at any time. Note that it will overwrite its output files without warning.
This WPmigrate task uses the properties collected by the Property Collector to extract the configuration from WebSphere Portal V5.1 server. It executes on the WebSphere Portal V6 server and runs xmlaccess remotely against WebSphere Portal V5.1 server.
If you have any virtual portals defined in your WebSphere Portal V5.1 environment, the configuration for each one must be exported in turn after exporting the default portal configuration. The sequence of exports is not important.
This task writes a number of files that will be used later by the import process. For the default portal, these are written to <portal_server_root>\migration\work\default. Directories are created if they do not already exist. For each virtual portal, they are created in
<portal_server_root>\migration\work\vp-<URL context>, where <URL context> is the URL
context of the virtual portal, which is defined in “Virtual portals” on page 29.
Table 3-1 lists the most important files.
Table 3-1 Output files from the export portal configuration
File name Purpose allout.xml
testexport.xml
xmlaccess export
Result of a command to test connectivity. If the test fails, there will be messages here to help diagnose the issue.
This task runs xmlaccess against WebSphere Portal V5.1. Therefore, WebSphere Portal
V5.1 must be running. There is no interaction with WebSphere Portal V6.
Ensure HTTP connectivity from WebSphere Portal V6 to WebSphere Portal V5.1.
Important: Check whether wmm.xml on the WebSphere Portal V5.1 server environment has the maximumSearchResults parameter set to a number that is greater than the number of portal users. Otherwise, the command will fail.
Also ensure that searchTimeOut is set to a large number, for example, 20,000,000, in order to avoid user repository searches timing out.
28 Best Practices for Migrating to IBM WebSphere Portal V6

Enter the following command:
<portal_server_root>\migration\WPmigrate.bat export-portal-content
-DPrevPortalAdminId=portaladminid -DPrevPortalAdminPwd=password
In this command:
򐂰 PrevPortalAdminId is a portaladminid for the WebSphere Portal V5.1
򐂰 PrevPortalAdminPwd is the password for this portaladminid
Tip: -DPrevPortalAdminId and -DPrevPortalAdminPwd are not required if the values have already been defined in the wpconfig.properties file collected from WebSphere Portal V5.1 server. If you prefer, you can edit the wpconfig.properties file directly on WebSphere Portal
V6 server to set these values. The wpconfig.properties file can be found in
<portal_server_root>\migration\work\collector\wpconfig.properties.
If you use virtual portals, enter the command shown in Example 3-1 for each virtual portal in
turn, after the export of the default portal is completed.
Example 3-1 Command for virtual portals
<portal_server_root>\migration WPmigrate.bat export-portal-content
-DPrevPortalAdminId=portaladminid -DPrevPortalAdminPwd=password
-DVirtualPortal=URL context
In this command,
򐂰 PrevPortalAdminId is a portaladminid for WebSphere Portal V5.1
򐂰 PrevPortalAdminPwd is the password for this portaladminid
򐂰 Uniform Resource Locator (URL) context is the context extension for the virtual portal URL
Important: The context extension is displayed in the column URL Context in the Virtual
Portal Manager, as highlighted in Figure 3-1.
Figure 3-1 Virtual Portal Manager showing URL context
Chapter 3. Migration of core components 29

WPmigrate does not show a progress bar. To ensure that the task is running successfully, monitor the size of the log and the output files. On UNIX® systems, use the tail command.
You can also use your operating system (OS) tools to see what processes are running and the resources they are using.
Successful completion is indicated by the following message:
BUILD SUCCESSFUL.
Tip: It is recommended that you browse allout.xml because this might indicate issues that must be addressed despite the BUILD SUCCESSFUL message. In our River Bend example, there were issues that had to be investigated.
If the export process does not report a BUILD SUCCESSFUL message, the following resources are available to diagnose the problem:
򐂰 Output from the command
򐂰 MigrationTrace.log
򐂰 testexport.xml
򐂰 allout.xml
򐂰 WebSphere Portal V5.1 logs
The cause might be immediately obvious from the command output. If there are connectivity issues between the WebSphere Portal V6 server and the WebSphere Portal V5.1 server, you
will see messages such as the ones displayed in Example 3-2.
Example 3-2 Output from WPmigrate, when unable to contact WebSphere Portal V5.1 server for export
[xmlaccess] EJPXB0009E: Could not connect to portal.
[xmlaccess] java.net.ConnectException: Connection refused: connect
[xmlaccess] EJPXB0016E: An error occurred on the client: Connection refused: connect
BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xml:
161: EJPXB0016E: An error occurred on the client: Connection refused: connect
If the answer is not immediately obvious from the command output, investigate further. The command output tells you where to look next. The entire command output is logged to
MigrationTrace.log. You can thus check MigrationTrace.log if you have lost the command output.
Example 3-3, which is a failed WPmigrate export-portal-content, shows that
C:\WebSphere\PortalServer\migration\work\default\testexport.xml must be indicated. The
“Server response indicates an error” message indicates that xmlaccess was able to contact the WebSphere Portal V5.1 server before something went wrong.
Example 3-3 WPmigrate export portal content failed
[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testexport.xml.
[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testexport.xml.
30 Best Practices for Migrating to IBM WebSphere Portal V6

BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm
l:161: EJPXB0019E: Server response indicates an error. For status and details of
the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\defau lt\testexport.xml.
Total time: 3 seconds
In our example, we opened testexport.xml, as shown in Example 3-4.
Example 3-4 testexport.xml
<failure> com.ibm.wps.command.xml.XmlCommandServlet$AuthenticationException: EJPXA0005E:
Authorization for user wpsadmin failed.
</failure>
In our case, the cause was an incorrect password. We retyped the command with the correct password and it ran to completion.
As mentioned in “Validation” on page 25, it is common to see export portal content complete
successfully, but issue warnings. In our example, on successful export, the output shown in
Example 3-5 was displayed.
Example 3-5 Output from successful WPmigrate export portal content
[xmlaccess] EJPXB0022W: The request was processed successfully on the server, but warnings were enountered during processing. For details of the XmlAccess warnings look at file C:\WebSphere\PortalServer\migration\work\default\allout.xml.
[xmlaccess] EJPXB0020I: The request was processed successfully on the server.
BUILD SUCCESSFUL
Total time: 41 seconds
We checked C:\WebSphere\PortalServer\migration\work\default\allout.xml and searched for
<status. We found the messages shown in Example 3-6.
Example 3-6 Messages from allout.xml for successful export portal content
<status element="[web-app _1_004CSO68OD0EIGCQ_6O uid=pzn.author.1001]" result="warning">
<message id="EJPXA0185W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0185W:
The URL file://localhost/$server_root$/installableApps/pznauthorportlet.war does not point to a directory as required by predeployed portlets. You will need to adjust the URL. [web-app _1_004CSO68OD0EIGCQ_6O uid=pzn.author.1001]</message>
</status>
<status element="[web-app _1_004CSO68OD0EIGCQ_6P uid=pzn.ruleportlet.1001]" result="warning">
<message id="EJPXA0185W">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0185W: The URL file://localhost/$server_root$/installableApps/pznruleportlet.war does not point to a directory as required by predeployed portlets. You will need to adjust the
URL. [web-app _1_004CSO68OD0EIGCQ_6P uid=pzn.ruleportlet.1001]</message>
</status>
<status element="[web-app _1_004CSO68OD0EIGCQ_IP uid=com.ibm.wps.portlets.Calculator.Calculator]" result="warning">
Chapter 3. Migration of core components 31

<message id="EJPXA0186W">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0186W: The URL file://localhost/$server_root$/installableApps/Calculator.war does not point to a file. You will need to adjust the URL. [web-app
_1_004CSO68OD0EIGCQ_IP uid=com.ibm.wps.portlets.Calculator.Calculator]</message>
</status>
These messages refer to missing WAR files. Xmlaccess expects that the WAR files for the exported portlets will exist in <portal_server_root>\installableApps on the server, identified by localhost, which is the WebSphere Portal V5.1 server at this point.
The messages regarding pznauthorportlet.war and pznruleportlet.war messages are normal.
These portlets are part of Personalization and are supplied in predeployed EARs rather than portlet WAR files in both WebSphere Portal V5.1 and V6. Because the migration process handles this automatically, these messages can be ignored.
The message referring to Calculator.war is worth noting. In our example, we installed the
Calculator portlet on WebSphere Portal V5.1 server from the portlet catalog. This was installed using the portal admin graphical user interface (GUI), which picked up the WAR file from the local hard drive of the workstation used for the installation. Therefore, there was no copy of the WAR file in the <portal_server_root>\installableApps directory on WebSphere
Portal V5.1 server. This message does not indicate an error at this point. However, it serves as a reminder to ensure that the WAR file is made available on the WebSphere Portal V6 server before proceeding.
Important: Any references to localhost in allout.xml refer to the WebSphere Portal V5.1 server, rather than the WebSphere Portal V6 server.
Tip: If you have to investigate allout.xml for purposes of troubleshooting, search for
<status to quickly find the warning or error messages.
If necessary, search for references to the message codes identified by “message id” in the
Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, which is available on the Web at: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
Tip: If the output file referenced in the command output does not provide enough information to resolve the cause of a failed export, it is worth checking the logs for the
WebSphere Portal V5.1 server to see if they indicate any issues.
This task can be rerun at any time. It will, however, overwrite its output files without warning.
If this task has to be rerun, it must be run in its entirety. There is no facility to resume the export if it has failed midway.
32 Best Practices for Migrating to IBM WebSphere Portal V6

Attention: The server process called by xmlaccess runs for a short time after an xmlaccess failure. If this process is still running when the export is rerun, you might see the the following message in testexport.xml:
“com.ibm.wps.command.CommandFailedException: EJPXA0166E: The XML Configuration
Interface is currently busy with another request. Please try again later.”
If this happens, wait for a short period and then retry the command.
Tip: It is recommended that you make a copy of the output files before rerunning the import portal content task so that you can compare the outcome of the reruns.
This WPMigrate task uses the allout.xml (the creation of which was described in 3.3.2,
“Exporting the configuration from WebSphere Portal V5.1 server” on page 28), modifies it as
required for V6, and then imports the resulting configuration to the WebSphere Portal V6 server environment using xmlaccess.
If you have any virtual portals defined in your WebSphere Portal V5.1 server, import the default portal first because virtual portals are dependent on resources in the default portal.
After this, restart the WebSphere Portal V6 server, manually recreate the virtual portals in
WebSphere Portal V6 server, and then import each one of them in turn. The sequence of imports is not
important.
Tip: When defining the virtual portals in the WebSphere Portal V6 server, the only parameter that must
match the definition in V5.1 is URL Context. However, it is recommended that you keep all the parameters the same.
This task writes a number of files when executing. For the default portal, they are written to
<portal_server_root>\migration\work\default. The directories will be created if they do not already exist. For each virtual portal, they are created in
<portal_server_root>\migration\work\vp-<URL context>.
Table 3-2 describes the most important files:
Table 3-2 Files created by the import portal content task
File name Purpose importAll.xml
importAllResults.xml
The final Extensible Markup Language (XML) file used for the xmlaccess import
An XML file with the results from the import process testimport.xml
An XML file with the results from a connectivity test made prior to the main xmlaccess import
Attention: The WPMigrate task is potentially very long running. The exact duration depends on your configuration.
Chapter 3. Migration of core components 33

The WPmigrate task uses the configuration values stored in wpconfig.properties on
WebSphere Portal V6 server. This must be validated before progressing further.
The WPmigrate task runs xmlaccess against WebSphere Portal V6 server. Therefore,
WebSphere Portal V6 server must be running. There is no direct interaction with WebSphere
Portal V5.1 server. If there are any shared resources, for example, the database server, there might be a performance impact on the WebSphere Portal V5.1 server environment because of a high level of activity on these resources caused by the import.
Enter the following command:
<portal_server_root>\migration\WPmigrate.bat import-portal-content
-DPortalAdminId=portaladminid -DPortalAdminPwd=password
In this command:
򐂰 PortalAdminId is a portaladminid from the WebSphere Portal V6 server environment
򐂰 PortalAdminPwd is the password for this portaladminid
Tip: -DPortalAdminId and -DPortalAdminPwd are not required if the values are already defined in the wpconfig.properties file for the WebSphere Portal V6 server.
Important: You must specify the WasUserid and WasPassword in the wpconfig.properties file. They cannot
be entered on the command line.
After recreating the virtual portals in the WebSphere Portal V6 server, run the command
shown in Example 3-7 for each one, restarting the WebSphere Portal V6 server after each
import.
Example 3-7 Virtual portals command
<portal_server_root>\migration WPmigrate import-portal-content
-DPortalAdminId=portaladminid -DPortalAdminPwd=password -DVirtualPortal=URL context
In this command:
򐂰 PortalAdminId is a portaladminid from the WebSphere Portal V6 server
򐂰 PortalAdminPwd is the password for this portaladminid
򐂰 URL context is the context extension for the virtual portal URL
Important: You must specify the WasUserid and WasPassword in the wpconfig.properties file. They cannot be entered on the command line.
WPmigrate does not show a progress bar. To ensure that the task is running successfully, monitor the size of the log and the output files. On UNIX systems, it is useful to use the tail command to monitor importAllResults.xml. You can also use your OS tools to see what processes are running and the resources they are using.
Successful completion is indicated by the following message:
BUILD SUCCESSFUL.
34 Best Practices for Migrating to IBM WebSphere Portal V6

Tip: Browse importAllResults.xml even if you see the “ BUILD SUCCESSFUL ” message. There may still be issues that must be investigated before proceeding. Our results and the
corresponding explanation are documented in Example 3-12.
If the import process does not display the BUILD SUCCESSFUL message, the following resources help diagnose the problem:
򐂰 Output from the command
򐂰 migrationTrace.log
򐂰 testimport.xml
򐂰 importAllResults.xml
򐂰 WebSphere Portal V6 logs
The cause might be immediately obvious from the command output. If there are connectivity issues with the WebSphere Portal V6 server, for example, if it has not been started,
messages such as the one shown in Example 3-8 are displayed.
Example 3-8 WPmigrate import portal content task output with the WebSphere Portal V6 server down
BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xml:
275: EJPXB0016E: An error occurred on the client: Connection refused: connect
If you run WPmigrate import without making all the WAR files available in
<portal_server_root>\installableApps, an output such as the one shown in Example 3-9 is
displayed.
Example 3-9 WPmigrate output for missing WAR file
[warFileFilter] INFO: War files are missing from the <wp_root>/installableApps d irectory. Some portlet applications may not be deployed.
[warFileFilter] C:\WebSphere\PortalServer\installableApps\Calculator.war not fou nd.
BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm
l:524: Missing war files have been detected. Verify the missing war files have been copied to the <wp_root>/installableApps directory.
Total time: 3 minutes 34 seconds
If the answer is not immediately obvious from the command output, investigate further. The command output tells you where to look next. Because the entire command output is logged to MigrationTrace.log, check MigrationTrace.log if you have lost the command output.
Example 3-10, which is a failed WPmigrate import portal content task, shows that
C:\WebSphere\PortalServer\migration\work\default\testimport.xml must be indicated. The
“Server response indicates an error” message indicates that xmlaccess was able to contact the WebSphere Portal V6 server before something went wrong.
Example 3-10 WPmigrate import portal content task failed
[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testimport.xml.
Chapter 3. Migration of core components 35

[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testimport.xml.
BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm
l:275: EJPXB0019E: Server response indicates an error. For status and details of
the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\defau lt\testimport.xml.
Total time: 3 seconds
In our example, we opened testimport.xml, as shown in Example 3-11.
Example 3-11 testimport.xml
<failure> com.ibm.wps.command.xml.XmlCommandServlet$AuthenticationException: EJPXA0011E:
Authentication for user wpsadmin failed.
</failure>
In our case, the cause was an incorrect password. We retyped the command with the correct password, and it ran to completion.
As mentioned in “Validation” on page 28, it is common to see the import portal content task
complete successfully, but issue warnings. In our example, on successful import, the output
shown in Example 3-12 was displayed.
Example 3-12 Output from successful import portal content task
[xmlaccess] EJPXB0022W: The request was processed successfully on the server, bu t warnings were enountered during processing. For details of the XmlAccess warni ngs look at file C:\WebSphere\PortalServer\migration\work\default\importAllResul ts.xml.
[miglogger] Oct 24, 2006 8:33:11 PM com.ibm.wps.migration.framework.logging.Migr
ationLogger execute
[miglogger] INFO: EJPMA5200I: Successfully imported XmlAccess script, import res ult in file C:\WebSphere\PortalServer\migration/work/default/importAllResults.xm
l.
post-import:
BUILD SUCCESSFUL
Total time: 13 minutes 1 second
We looked at importAllResults.xml, searched for the <status tag, and found the result shown
in Example 3-13.
Example 3-13 Status from importAllResults.xml
<status element="[credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment]" result="warning">
<message id="EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment]</message>
36 Best Practices for Migrating to IBM WebSphere Portal V6

</status>
<status element="[credential-segment _E_004CSO68OD0EIGCQ_36 name=DefaultAdminSegment]" result="warning">
<message id="EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_36 name=DefaultAdminSegment]</message>
</status>
The messages pertaining to credential segments are normal. This is because the migration process cannot migrate the credential vault. Our River Bend example had a Web Clipping
Portlet that accesses a Web site requiring authentication. This uses the credential vault.
Action is required as described in 3.4.6, “Migrating the credential vault” on page 45.
Tip: If you have to investigate importAllResults.xml for troubleshooting purposes, search for <status in order to quickly find the warning or error messages.
If necessary, search for references to the message codes identified by “message id” in the
Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, which is available on the Web at: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
Tip: If the output file referenced in the command output does not provide enough information to resolve the cause of a failed export, it is worth checking the logs for the
WebSphere Portal V6 server to see if they indicate any issues.
This task can be rerun at any time, even if it has failed midway, for example, due to a time-out. However, it overwrites its output files without warning. The WebSphere Portal V6 server must be restarted before rerunning.
Attention: The server process called by xmlaccess runs for a short time after an xmlaccess failure. If this process is still running when the import is rerun, you might see the following message in testimport.xml:
“com.ibm.wps.command.CommandFailedException: EJPXA0166E: The XML Configuration
Interface is currently busy with another request. Please try again later.”
If this happens, wait a while and try again.
Tip: Take a copy of the output files before rerunning the import portal content task so that you can compare the outcome of any reruns.
Chapter 3. Migration of core components 37

Important: If you decide to rerun the import for a virtual portal, you do not have to delete and recreate the virtual portal first. If you delete and recreate the virtual portal, you might face problems if delayed cleanup is enabled (as it is by default). In our case, we saw the import fail under these conditions with the following message:
“com.ibm.websphere.ce.cm.DuplicateKeyException: The statement was aborted because it would have caused a duplicate key value in a unique or primary key constraint defined on 'PAGE_INST(OID).”
We resolved this by forcing an immediate run of the cleanup service through xmlaccess as
discussed in “Forcing immediate clean-up with xmlaccess” on page 107.
On successful completion of the WPmigrate tasks, you must complete a number of tasks manually. However, not all these steps apply to your configuration.
Attention: If you have themes that use Personalization, you might encounter problems if, as recommended, you have not yet migrated Personalization. If this is the case, there is a
URL mapping labelled Administration, which can be used in the WebSphere Portal V6 server to access the admin page. From here, you can reset the default themes on individual pages to one of the IBM defaults until you migrate Personalization. The resulting
URL is: http://<hostname>:10038/wps/myportal/Administration
The WebSphere Portal V6 server must be restarted after the WPmigrate tasks are completed.
If you are using WebSphere Member Manager, you must migrate the WebSphere Member
Manager database tables using your database tools. The IBM WebSphere Portal Version 6.0
Information Center has instructions for Cloudscape and DB2 under the topic “Migrating the
Member Manager database using the command line”: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wpf/sec_mig_roles.html
For other databases, consult your database administrator (DBA).
Your custom pages may not initially be displayed when you point your browser to
<hostname>/wps/portal. This is because the WebSphere Portal V6 server already has a welcome page, which may be higher in the content node hierarchy. This can be addressed by making a change using the portal admin GUI. If you use virtual portals, you must use the portal admin GUI for each virtual portal, and repeat this step.
38 Best Practices for Migrating to IBM WebSphere Portal V6

In our case, when we started our migrated River Bend portal server for the first time and accessed http://m51g.cam.itso.ibm.com:10038/wps/portal from a browser, we saw the default
WebSphere Portal V6 server welcome (Figure 3-2) page instead of the expected River Bend
welcome page.
Figure 3-2 Welcome page immediately after migration
We addressed this by adjusting the page hierarchy from Portal User Interface
→
Manage
Pages. We clicked Content Root and saw the page hierarchy, as displayed in Figure 3-3. We
clicked the Up Arrow button next to My Portal.
Figure 3-3 Page hierarchy immediately after migration
Chapter 3. Migration of core components 39

This moved My Portal to the top of the list, as shown in Figure 3-4.
Figure 3-4 Fixing the page hierarchy
When we pointed our browser to http://m51g.cam.itso.ibm.com:10038/wps/portal after
making this change, we saw the River Bend welcome page (Figure 3-5).
Figure 3-5 The welcome page displays as expected
40 Best Practices for Migrating to IBM WebSphere Portal V6

Search collections are not
migrated by WPmigrate. They must be exported from the
WebSphere Portal V5.1 server, redefined in WebSphere Portal V6 server, and then imported into the new server. The new search and browse portlet must also be updated because of a
change in its configuration parameters. This is described in 3.4.5, “Migrating the Search and
Browse Portlet” on page 41. The search collection export and import process migrates the
configuration information for the collections, including the URLs of the content, and then builds the indexes in the WebSphere Portal V6 server. The indexes are not copied.
If you are using remote search, follow the same process to export and import the collections.
The only difference is that the XML file is located on the remote machine for both import and export.
In our case, we followed the process described in “Migrating the search collections” on page 109.
Tip: When importing search collections from WebSphere Portal V5.1 server, ensure that your WebSphere Portal V6 server has connectivity to the Web sites being searched.
The Search and Browse Portlet requires a manual configuration change after migration due to a change in configuration parameters.
Immediately after migration, a page with a Search and Browse Portlet shows an error, as
shown in Figure 3-6.
Figure 3-6 Search and Browse Portlet, postmigration
Chapter 3. Migration of core components 41

In WebSphere Portal V5.1 server, the portlet locates its search index through the
configuration parameter called IndexName, as shown in Figure 3-7.
Figure 3-7 Configuring the Search and Browse Portlet in V5.1
42 Best Practices for Migrating to IBM WebSphere Portal V6

In WebSphere Portal V6, this is now called CollectionLocation. To fix this, we reconfigured
the Search and Browse Portlet in question. Note that the IndexName parameter in Figure 3-8
has been preserved by the migration process, but is not used. The required parameter
(CollectionLocation) is not listed on any page.
Figure 3-8 Search and Browse Portlet properties
Important: The problem is that the new parameter (CollectionLocation) is missing. If you have put your search collection in a location that is different from your WebSphere Portal
V5.1 server and updated IndexName to match this new location, this issue continues to occur.
Chapter 3. Migration of core components 43

In our case, we added the missing parameter by typing CollectionLocation in the New
Parameter box and the name of the directory that houses the collection (in our case,
c:\collections\itsoco) in the New Value box, as shown in Figure 3-9, and clicked Add, and then
OK. We then restarted the portal server.
It is recommended that you delete the redundant IndexName parameter at this point.
Figure 3-9 Fixing a Search and Browse Portlet
Attention: There is no requirement to change the location directory between versions.
This is just an example. The fix is required even if you do not change the location.
Important: You must log out and log back in to pick up this change.
44 Best Practices for Migrating to IBM WebSphere Portal V6

This section describes the process involved in migrating the credential vault.
Attention: If you use third-party vault implementation, for example, IBM Tivoli Access
Manager, no additional steps are required. The existing credential secrets can be used in the WebSphere Portal V6 server.
The credential vault slots are migrated as shown in Figure 3-10.
Figure 3-10 Credential vault exists after migration
However, any secret information they contained is not
migrated, as can be seen from our
example, which is shown in Figure 3-11.
Figure 3-11 Credential vault is empty after migration
The secret information can be migrated using your database tools or some new functionality in xmlaccess that is introduced by PK28148, which must be installed on the WebSphere
Portal V5.1 server and the WebSphere Portal V6 server. Both the methods are documented in the WebSphere Portal V6 Information Center under the topic “Migrating credential vault data”: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wpf/sec_mig_roles.html
Using the new xmlaccess functionality is recommended.
Chapter 3. Migration of core components 45

Tip: In our test of PK28148, the following message was displayed, although the import was successful:
"EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment in <portal_server_root>\bin\resultsCVresults.xml.”
At the time of writing this IBM Redpaper, this was being addressed by Development.
Depending on the version of the previous system, some secrets and shared credential slots that are obsolete in the current version are migrated. These slots must be removed using the
Credential Vault administrative portlet under Administration
→
Access
→
Credential Vault.
Select Manage system vault slots and delete the following slots, if applicable:
򐂰 deployment.user
򐂰 wmm.system.id.user
򐂰 deployment.truststore
򐂰 deployment.keystore
As described in 1.4.6, “Administration portlets” on page 11, the administration portlets and
pages have been replaced as part of the migration. Therefore, all the customizations must be reworked, including the following:
򐂰 Portlets added to admin pages
򐂰 Authorization changes to admin portlets
򐂰 Admin portlets added to custom pages
򐂰 URL mapping to admin page
A complete list of the admin portlets in WebSphere Portal V5.1 and WebSphere Portal V6 can
be found in “List of admin portlets in WebSphere Portal V5.1” on page 107 and “List of admin portlets in WebSphere Portal V6” on page 108.
Attention: If you are using the clones of these portlets, authorization information for the clones is preserved. Configuration information is preserved where possible. If the V6 portlet has new configuration parameters that are not present in V5.1, they will be set to default values. If the V6 portlet no longer uses parameters that are present in V5.1, they may be deleted. Therefore, the clones of admin portlets might not function as intended and must be verified and reconfigured if necessary.
Our example River Bend company required two Web Clippers, one for clipping the River
Bend Web site and the other for clipping the itsoco Web site, as mentioned in “Migrating the search collections” on page 109.
There are no issues directly relating to migration. However, WebSphere Portal V6 ships with a more recent version of the Web Clipping portlet than originally shipped with WebSphere
Portal V5.1. You might encounter some issues if you have not updated this portlet in your
WebSphere Portal V5.1 server.
46 Best Practices for Migrating to IBM WebSphere Portal V6

If, for example, the Web site being clipped uses JavaScript™, you might see a warning
message, as shown in Figure 3-12. This issue will also be observed on the WebSphere Portal
V5.1 server if the most recent Web Clipping portlet is installed there.
.
Figure 3-12 Warning message in Clipper, postmigration
To address this, in our example, we edited the Web Clipping Portlet, as shown in Figure 3-13.
Figure 3-13 Editing the Web Clipper portlet
We then selected the Advanced Options, followed by the Modify Security Options. We
selected the box against Remove JavaScript from clipped content, as shown in Figure 3-14,
and clicked OK.
Figure 3-14 Modifying the security options
Chapter 3. Migration of core components 47

We then clicked Next, and then Finish. The message was no longer displayed, as shown in
Figure 3-15.
Figure 3-15 Web Clipper warning has been removed
The clipper for the itsoco Web site showed different issues after migration. Immediately after
the migration, the portlet displayed nothing, as shown in Figure 3-16.
Figure 3-16 itsoco clipper, postmigration
Clicking on Edit showed the cause to be missing credential vault data, as shown in
Figure 3-17. This is because the Web Clipper uses the credential vault to store authentication
data. The credential vault secret does not migrate automatically. Refer to 3.4.6, “Migrating the credential vault” on page 45 for instructions about how to correct this.
Figure 3-17 itsoco clipper with the missing credential vault data
In the standard WebSphere Portal V5.1, the pages held directly under the content root are hidden. In WebSphere Portal V6, they become viewable in the Launch dropdown menu. This can be addressed in WebSphere Portal V6 by using xmlaccess. This is described in the IBM
WebSphere Portal Version V6 Information Center under the topic “Marking pages as hidden under the content root”:
“ http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.e
nt.doc/wps/adxmlref.html
As mentioned in 1.4.3, “External components” on page 8, these are not migrated
automatically. You must migrate them manually.
48 Best Practices for Migrating to IBM WebSphere Portal V6

These portal configuration settings are configured using the WebSphere Portal server admin
GUI. They are set on a per server basis. Therefore, this must be checked for every member in a cluster. They affect the default portal server and all the virtual portals simultaneously.
Because they are not migrated, a manual check is required.
There are changes to the way that portal services are configured in WebSphere Portal V6. In
WebSphere Portal V5.1, these are configured by setting values in properties files under
<portal_server_root>\shared\app\config\services. In WebSphere Portal V6, these configuration settings are managed by Resource Environment Providers in the WebSphere
Application Server.
In WebSphere Portal V6, the settings must be changed either by a direct update by using the
WebSphere Application Server admin console or by updating the corresponding value in the relevant file in <portal_server_root>\config\properties, and then running WPSconfig update-properties. This WPSconfig task reads the properties files and then makes the corresponding updates to the Resource Environment Providers in the WebSphere
Application Server. In a cluster, you must force a replication to ensure that these values are the same for all the cluster members. After changing a portal service configuration property, restart the portal server.
Portal service configuration properties are not
automatically migrated. If you have changed any property from its default value in WebSphere Portal V5.1, refer to the IBM WebSphere
Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wps/srvcfgref.html
Important: Changes made to the properties files in <portal_server_root>\config\properties have no effect until WPSconfig update-properties has been run.
For information about this, refer to the IBM WebSphere Portal Version 6 Tuning Guide: http://www-1.ibm.com/support/docview.wss?uid=swg27008511&aid=1
This is discussed in 1.4.2, “Custom portlets” on page 7.
This is discussed in 1.4.2, “Custom portlets” on page 7.
This is discussed in 1.4.2, “Custom portlets” on page 7.
Chapter 3. Migration of core components 49

If you cloned the FileServer portlet in WebSphere Portal V5.1 and supplied Hypertext Markup
Language (HTML) files in the
<portal_server_root>\root\installedApps\FileServer.war\FileServerPortlet\html directory, copy those files to the <portal_server_root>\installedApps\FileServer.war\FileServerPortlet\html directory on the WebSphere Portal V6 server after running the import task, and then restart the server in order to make the files accessible in the current version.
After the core portal components are migrated, test your portal and confirm that it is working as expected. This process varies from customer to customer, and is dependent on individual configurations.
Do not forget that the additional components (Personalization, Document Manager, and
Workplace Web Content Management) have not been migrated yet. Therefore, any tests of these components will fail at this time. Migration of these components is covered in
Chapter 4, “Migration of Document Manager and Personalization” on page 51 and Chapter 5,
“Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content
Management” on page 77.
Use your own test scripts and validation criteria as recommended in 1.5.2, “Steps to prepare your WebSphere Portal V5.1 environment for migration” on page 13.
If performance is of importance to you, it is recommended that you rerun your performance
tests and compare to the baseline recorded, as described in 1.5.2, “Steps to prepare your
WebSphere Portal V5.1 environment for migration” on page 13. Performance settings have
been mentioned earlier in 3.4.13, “Migrating the performance settings” on page 49.
Tip: Some issues can produce messages in logs without any obvious visibility to the users.
Therefore, carefully check the WebSphere Portal server logs.
Attention: Some WebSphere Portal server features make use of pop-ups. Therefore, do not block pop-ups during testing.
The IBM WebSphere Portal Version 6.0 Information Center provides some general advice for migration verifcation: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wpf/mig_verify.html
The IBM WebSphere Portal Version 6.0 Information Center also provides some migration troubleshooting tips: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wpf/mig_tbl.html
50 Best Practices for Migrating to IBM WebSphere Portal V6

4
Chapter 4.
This chapter describes the process involved in migrating the additional components of
Document Manager and Personalization from WebSphere Portal V5.1 to WebSphere Portal
V6 using the command-line tools.
If your additional component is only Document Manager, skip 4.4, “Migrating Personalization
data” on page 67, as shown in Figure 4-1.
If your Personalization data has some relation to the Document Manager documents, migrate the Document Manager first.
Figure 4-1 shows a Document Manager and Personalization overview.
4.1 Document
Transfer Tool
(DTT)
Migrate
PDM?
NO
YES
4.2 Migrate PDM documents
Migrate
PZN?
NO
YES
4.3 Migrate PZN data
End of Chapter 4
Figure 4-1 Document Manager and Personalization migration overview
© Copyright IBM Corp. 2007. All rights reserved.
51

Document Manager migration and Personalization migration involve the flow shown in
Figure 4-2. Each migration involves the same sequence of tasks (export
→
transform
→ import). However, the commands for the migration tasks are slightly different between
Document Manager and Personalization.
Following is the sequence of the tasks:
1. Performing the premigration tasks
2. Running the export task
3. Copying the exported files to the V6 server
4. Running the transform task
5. Running the import task
6. Performing validation
Migration Start
Prepare Premigration tasks
Export
Copy
Run the export task
Copy exported files to the 6.0 system
Transform Run the transform task
Import Run the import task
Validate Validate migration
Migration End
Figure 4-2 Flow of migration for Document Manager and Personalization
Although the process is independent of database and security configuration, it is required to use the same brand of software for the operating system (OS), database, and user
repository, as described in 1.4.1, “WebSphere Portal V6 environment” on page 6.
Following are the prerequisite conditions for this chapter:
򐂰 Installing the necessary fixes, including PK18903, PK30219, and PK30439 described in
1.5, “Migration checklist” on page 12
򐂰
Completing all the steps described in Chapter 3, “Migration of core components” on page 23
52 Best Practices for Migrating to IBM WebSphere Portal V6

Following is a list of the topics described in this chapter:
򐂰
4.1, “The Document Transfer Tool” on page 54
򐂰
4.2, “Migrating the Document Manager documents” on page 57
򐂰
4.4, “Migrating Personalization data” on page 67
PK18903 includes the Document Transfer Tool (DTT), which must be installed through the
WebSphere Application Server Admin Console.
PK30219 (on the WebSphere Portal V5.1 server) and PK30439 (on WebSphere Portal V6 server) are fixes to deal with long user Distinguished Names (DN) in the Document Manager and Personalization property files. Without applying these fixes, migration for Document
Manager and Personalization fails with an IllegalArgumentException.
Important: At the time of writing this IBM Redpaper, we discovered that if the Workplace
Web Content Management fix PK30516 is required, PK30439 must be installed afterwards.
Ensure that you have completed the steps described in Chapter 3, “Migration of core components” on page 23 before continuing with the Document Manager migration process.
Migrating the Document Manager data without performing this task is not supported.
Throughout this IBM Redpaper, the install location for IBM WebSphere Portal server is
<portal_server_root>.
We assume that the current and the earlier systems are on different physical servers because this is the most common migration scenario.
If your earlier system configured into a cluster environment, we assume that one of the
WebSphere Portal servers in your cluster is dedicated for the migration (for more details
about the cluster environment, refer to Chapter 2, “Considerations for migrating enterprise environments” on page 15).
In our case, we used Windows servers for the River Bend scenario. We tested two cases, one with a Cloudscape database without the Lightweight Directory Access Protocol (LDAP) and another with the DB2 and IBM Tivoli Directory Server LDAP security enabled (refer to
1.5.1, “Steps to prepare your WebSphere Portal V6 environment for migration” on page 12 for
more details).
Chapter 4. Migration of Document Manager and Personalization 53

This tool is invoked by the migration commands, and enables the transfer of Document
Manager documents and Personalization data from one WebSphere Portal server to another.
Install this tool on your WebSphere Portal V5.1 server environment before running the migration tasks for Document Manager and Personalization.
The Document Transfer Tool is included in the PK18903 fix. Therefore, ensure that you have already installed PK18903 on your WebSphere Portal V5.1 server environment. This is only required for Personalization and Document Manager migration.
DTT(icmjcr.ear) is an enterprise application that must be installed using the WebSphere
Application Server admin console. This enterprise archive (EAR) file is located in
<portal_server_root>/jcr/installableApps.
Install the Document Transfer Tool on WebSphere Portal V5.1 server by installing the EAR file through the WebSphere Application Server admin console on to the WebSphere Portal server:
1. Open your browser to the WebSphere Application Server admin console and log in (with the WebSphere Application Server admin user ID if security is enabled).
2. Select Applications
→
Install New Application.
3. Select Local Path: and specify <portal_server_root>/jcr/installableApps/icmjcr.ear
(Figure 4-3).
Click Next four times, leaving the default values intact, to go to the “Step 3: Map modules to application servers” window.
Figure 4-3 Installing new application: icmjcr.ear
54 Best Practices for Migrating to IBM WebSphere Portal V6

4. In the “Step 3: Map modules to application servers” window (Figure 4-4) select
WebSphere_Portal as the module for the installation and check jcrpublishwar as the module to be installed, and click Apply.
Click Next two times, leaving the default values intact, to go to the “Step 5: Summary” window.
Figure 4-4 Mapping modules to application servers
5. In the “Step 5: Summary” window (Figure 4-5), click Finish to complete the task.
Figure 4-5 Summary
6. In the page that opens, click the hyperlink Save to Master Configuration (the third line from the bottom), and then click the hyperlink Save in the Messages window to apply the changes to the master configuration.
Chapter 4. Migration of Document Manager and Personalization 55

7. Restart WebSphere_Portal.
You must now restart the WebSphere Portal V5.1 server. You may want to do this by issuing the following command in your command-line interface (assuming yours is a
Windows environment): cd <portal_server_root>\config
WPSconfig.bat stop-portal-server start-portal-server
Perform the following tasks:
1. Check the admin console running on server1 to see if the icmjcr is installed (Figure 4-6).
However, it will not show a status because the application is installed on the
WebSphere_Portal, unless the WebSphere Portal server is managed by a Document
Manager cell.
Figure 4-6 WebSphere Application Server admin console: icmjcrear is inactive
56 Best Practices for Migrating to IBM WebSphere Portal V6

2. Now check WebSphere_Portal SystemOut.log located in <portal_server_root>\log
(Figure 4-7). Look for icmjcrear. It must tell you that the application is started.
Figure 4-7 SystemOut.log: icmjcrear is started
This section describes how to run the migration tasks for Document Manager. WebSphere
Portal V6 provides you a command-line interface (WPmigrate) to migrate your Document
Manager documents to the WebSphere Portal V6 server.
Running the “migrate-pdm-51x” task for WPmigrate requires a mapped drive because it runs several Ant tasks in sequence (export
→
transform
→
import). It does not transfer the data, but relies on being able to access a directory on the WebSphere Portal V5.1 server through the WebSphere Portal V6 server.
Because operational or security considerations may exclude drive mapping in many cases, this IBM Redpaper shows you how to migrate your Document Manager data without mapping a drive, by running the series of tasks one by one.
However, you must prepare a method, for instance, SSH, writable CD/DVD, to transfer the data from the WebSphere Portal V5.1 server to the WebSphere Portal V6 server.
Following are the topics described in this section:
1. 4.2.1, “Preparing a checklist for Document Manager validation” on page 58
2. 4.3, “Synchronizing Document Manager global access” on page 58
3. 4.3.1, “Modifying the Document Manager properties” on page 60
4. 4.3.2, “Creating directories for Document Manager migration” on page 61
5. 4.3.3, “Running the export task for Document Manager” on page 62
6. 4.3.4, “Copying files to the WebSphere Portal V6 server” on page 64
7. 4.3.5, “Running the transform task for Document Manager” on page 64
8. 4.3.6, “Running the import task” on page 66
9. 4.3.7, “Validating the Document Manager” on page 67
Chapter 4. Migration of Document Manager and Personalization 57

It is recommended that you prepare a validation checklist before Document Manager migration. In many cases there are a large number of documents in the Document Manager libraries. Therefore, perform a spot check in each Document Library. You might want to check if Document Manager functionalities such as Folder access control, Lock, Version, and
Workflow are functioning properly before and after Document Manager migration. Table 4-4
provides a sample checklist.
Table 4-1 Checklist for Document Manager validation
Source
OK
Target Library
Document
Library
Folder (AC) Name
\ (AC:Default) Migration
Presentation
Lock
No
Version
No
Workflow
No
Before migrating, synchronize the Document Manager global access settings. Global access settings for document library inheritance might be different between the WebSphere Portal
V5.1 server and the WebSphere Portal V6 server. Because the scope of migrated settings does not include global settings, synchronize the settings between the WebSphere Portal
V5.1 server and the WebSphere Portal V6 server so that access control for document libraries remains the same after migration. For WebSphere Portal V5.1 server migration, any access roles on the ICM_CONTENT_REPOSITORY virtual resource on the V5.1 source server must also be set on the WebSphere Portal V6 server, using the Set Access on Root button of the Document Libraries administration portlet.
Check your Document Manager global access on your WebSphere Portal V5.1 server by performing these tasks:
1. Open your browser to log in to your WebSphere Portal V5.1 server (Figure 4-8).
– Select Administration
→
Access
→
Resource Permissions.
– Select Virtual Resources as the Resource Type.
58 Best Practices for Migrating to IBM WebSphere Portal V6

– Click the Assign Access icon of ICM_CONTENT_REPOSITORY.
– Check the access control for each role (Figure 4-8).
Figure 4-8 Document Manager global access in WebSphere Portal V5.1 server
2. Use the checklist shown in Table 4-2 to set the same access control on WebSphere Portal
V6 server.
Table 4-2 Checklist for Document Manager global access
Role Propagation Inheritance
Administrator On On
Groups/Users wpsContentAdministrators wpsadmins
Security Administrator On
Delegator
Manager
Editor
Privileged User
User
On
Chapter 4. Migration of Document Manager and Personalization 59

After you have checked the Document Manager global access on your WebSphere Portal
V5.1 server, you are ready to set up your WebSphere Portal V6 server. Perform the following tasks:
1. Open your browser to log in to your WebSphere Portal V6 server and select Launch
→
Administration
→
Portal Content
→
Document Libraries.
2. Click Set Access on Root (Figure 4-9).
Figure 4-9 Selecting Set Access on Root
3. Check and set all the access control list (ACLs) for each role. They must be the same as the ones on your WebSphere Portal V5.1 server that you checked, as described in
“Checking the WebSphere Portal V5.1 server environment” on page 58.
The Document Manager properties file is located in
<portal_server_root>l\jcr\migration\conf\pdm_conf.xml. Change the properties shown in
Table 4-3 to meet your environment’s requirements.
Table 4-3 Document Manager properties you must change
Property name Description
MigDirSource The migration directory on the source (V5.1) server. This directory will be used for export from V5.1. Ensure that this directory is empty.
MigDirSourceShared
MigDirTarget
SourceServerPort
TargetServerPort
DocLib
The directory on the target (V6) server. The tasks that take place after the export task are required to access the exported data from the target (V6) server. Because mapping environment is not used, the exported data must be copied to the target server’s local directory. This property is the local directory where the exported data is stored.
The migration directory on the target (V6) server. This directory will be used for import to V6. Ensure that this directory is empty and is different from the
MigDirSourceShared.
The fully qualified host name and port for the V5.1 server. By default, the port for the V5.1 server is 9081. WPmigrate command communicates with the V5.1 server through this port.
The fully qualified host name and port for the V6 server. By default, the port for the V6 server is 10038. WPmigrate command communicates with the V6 server through this port.
The list of Document Libraries to migrate, separated by commas, for example, Document Manager or Document Manager, and MyLib
60 Best Practices for Migrating to IBM WebSphere Portal V6

Property name
ExportUserId
ExportPassword
ImportUserId
ImportPassword
IncludeWorkflow
IncludeVersion
Description
Set this value to the V5.1 portal administrator user ID that you specified as
PortalAdminId in wpconfig.properties. This must be a fully qualified DN.
Set this value to the V5.1 portal administrator password.
Set this value to the V6 portal administrator user ID that you specified as
PortalAdminiId in wpconfig.properties. Short name can be used even if
LDAP security is enabled.
Set this value to the V6 portal administrator password.
Change to true to migrate the workflow information, including submitted drafts.
Change to true to migrate the document versions.
Important: The best practice is to use fully qualified host names, “/” instead of “\”, and include the entire path in properties.
Also, do not forget to take a backup of the original file.
Important: ExportUserId in the properties file must be in full DN format unless the short name is unique. ImportUserId can also be short name.
Tip: For clarity, change the file names to include the reference to the system they are on.
Create three directories for Document Manager migration, one on WebSphere Portal V5.1 server, and the other two on WebSphere Portal V6 server.
Create an empty export directory on WebSphere Portal V5.1 server, for example, c:\WebSphere\PortalServer\migration\pdm\export51\. This export directory will be used for the
MigDirSource
property described in Table 4-3.
Create an empty export directory on the WebSphere Portal V6 server also, for example, c:\WebSphere\PortalServer\migration\pdm\export60\. This export directory will be used for the
MigDirSourceShared
property described in Table 4-3.
Chapter 4. Migration of Document Manager and Personalization 61

Important: As described in the WebSphere Portal Information Center, you can share the
MigDirSource directory with the V6 server (sharing can be implemented with net use or
Network File System (NFS) mount, and so on) as the MigDirSourceShared directory.
However, it is recommended that you create another directory on the V6 server because file sharing is not allowed in many production environments. This IBM Redpaper assumes that file sharing will not
be used.
The IBM WebSphere Portal Version 6.0 Information Center is available on the Web at: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/mig_tbl.html
Create an empty work directory for import on the WebSphere Portal V6 server, for example, c:\WebSphere\PortalServer\migration\pdm\import60\. This work directory will be used for the
MigDirTarget
property described in Table 4-3. Ensure that this is
not
the same as the
MigDirSourceShared
property.
Your Document Manager property file is now ready to be used for the migration tasks. The export task calls the Document Transfer Tool application on the WebSphere Portal V5.1 server, which creates exported files on WebSphere Portal V5.1 server. These must be copied to WebSphere Portal V6 server.
Ensure that your WebSphere Portal V5.1 server is running, with the Document Transfer Tool application available. There is no interaction with WebSphere Portal V6 server.
Watch out for firewalls because the export task must communicate with your WebSphere
Portal V5.1 server through the
SourceServerPort
specified according to the information
provided in Table 4-3.
Run the export task for Document Manager by typing the following in the
<portal_server_root>\migration directory in the command-line interface on the WebSphere
Portal V6 server (Figure 4-10):
WPmigrate.bat migrate-pdm-export-51x
Figure 4-10 Export task for Document Manager
Tip: Type WPmigrate.bat
(or .sh
for UNIX) on its own in order to list the available commands.
62 Best Practices for Migrating to IBM WebSphere Portal V6

The WPmigrate command must report a BUILD SUCCESSFUL
message (Figure 4-11). Check
the MigrationTrace.log file located in the <portal_server_root>\log directory carefully to confirm.
Figure 4-11 Export task for Document Manager: BUILD SUCCESSFUL message
The export task creates files under the MigDirSource directory that you specified as per the
directions provided in 4.3.1, “Modifying the Document Manager properties” on page 60. You
can find the rootworkspace directory (and more, depending on your environment) there, and you can see that there are subdirectories whose names are associated with your Document
Manager documents (Figure 4-12).
Figure 4-12 Export task for Document Manager: Successful creation of files
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, and eliminate the issues.
Run the WPmigrate command again.
You can also check the WebSphere Portal V5.1 server logs.
This task requires you to clean up the MigDirSource directory before you rerun this task. If you forget to clean up the directory, you receive a BUILD FAILED message with Error 500:
“Please make sure that the export directory is empty and restart export”.
Chapter 4. Migration of Document Manager and Personalization 63

After the export task is successfully completed, the export files are created into new directories (“rootworkspace” and more, depending on your environment) in the MigDirSource directory on the WebSphere Portal V5.1 server.
Copy all the directories in the MigDirSource directory to the MigDirSourceShared directory on
WebSphere Portal V6 server before running the transform task for Document Manager.
There are several methods in which to copy these directories from WebSphere Portal V5.1 server to WebSphere Portal V6 server. Select the most convenient method that allows you to
complete this task (Figure 4-13).
WebSphere Portal V5.1 server
WebSphere Portal V6 server
Figure 4-13 Copying all the directories from V5.1 to V6 for Document Manager
After copying all the directories under the MigDirSource directory, validate a couple of files in the MigDirSourceShared directory by opening in a text reader.
The transform task transforms all the files that are exported by the export task and writes the transformed files to the MigDirTarget directory in the format required by the import task.
There is no interaction with either the WebSphere Portal V5.1 server or WebSphere Portal V6 server.
64 Best Practices for Migrating to IBM WebSphere Portal V6

Run the export task for Document Manager by typing the following in the
<portal_server_root>\migration directory in the command-line interface on WebSphere Portal
V6 server (Figure 4-14):
WPmigrate.bat migrate-pdm-transform
Figure 4-14 Transform task for Document Manager
The WPmigrate command must display a “ BUILD SUCCESSFUL
” message (Figure 4-15).
Figure 4-15 Transform task for Document Manager: BUILD SUCCESSFUL message
Important: Even if the source is wrong, the task will run to completion and report the
“ BUILD SUCCESSFUL ” message.
Also check that the files have been successfully written to the MigDirTarget directory that you
specified, as described in 4.3.1, “Modifying the Document Manager properties” on page 60.
You can find the rootworkspace directory there (Figure 4-16).
Figure 4-16 Transform task for Document Manager: Successfully transformed
Chapter 4. Migration of Document Manager and Personalization 65

If the WPmigrate command does not run successfully, check the output of the command, which can be found in portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again.
You can also check the WebSphere Portal V6 server logs.
Now that you have completed the transformation of the exported files in the work directory on
WebSphere Portal V6 server, you are ready to run the import task for Document Manager.
The import task imports Document Manager objects from the MigDirTarget directory and stores them into the WebSphere Portal V6 server repository properly.
Ensure that your WebSphere Portal V6 server is running. There is no interaction with the
WebSphere Portal V5.1 server.
Run the import task for Document Manager by typing the following in the
<portal_server_root>\migration directory in the command-line interface on the WebSphere
Portal V6 server (Figure 4-17).
WPmigrate.bat migrate-pdm-import
Figure 4-17 Import task for Document Manager
The WPmigrate command must report a BUILD SUCCESSFUL
message (Figure 4-18).
Figure 4-18 Import task for Document Manager: BUILD SUCCESSFUL message
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again.
You can also check the WebSphere Portal V6 server logs.
66 Best Practices for Migrating to IBM WebSphere Portal V6

Your migration tasks for Document Manager are now completed. You must now open your browser to log in to your WebSphere Portal V6 server to confirm that the migration tasks have successfully migrated your Document Libraries.
Use your own test scripts and validation criteria as recommended in 4.2.1, “Preparing a checklist for Document Manager validation” on page 58 to perform some spot checks.
Attention: You might have to review WebSphere Application Server content-types.props if there are rendering issues.
At time of this writing this IBM Redpaper, there is a known issue with Document Manager portlets on custom pages. Document Manager portlets on custom pages in WebSphere
Portal V5.1 server are not migrated. After Document Manager migration, you will not
see any
Document Manager portlets on the target pages. Therefore, you must add the Document
Manager portlets to the pages manually.
This section describes how to run the migration tasks for Personalization. WebSphere Portal
V6 provides a command-line tool (WPmigrate) to migrate your Personalization to the
WebSphere Portal V6 server.
The IBM WebSphere Portal V6 Information Center tells you to run the “migrate-pzn-51x” task for Personalization migration. This requires a mapped drive because it runs several Ant tasks in sequence (export
→
transform
→
import). It does not transfer the data, but relies on being able to access a directory on the WebSphere Portal V5.1 server through the WebSphere
Portal V6 server.
Because operational or security considerations may exclude drive mapping in many cases, we show you how to migrate your Personalization data without mapping a drive, by running the series of tasks one by one.
However, you must prepare a method, for instance, SSH, writable CD/DVD, to transfer the data from the WebSphere Portal V5.1 server to the WebSphere Portal V6 server.
Following is the list of topics described in this section:
1. 4.4.1, “Preparing a checklist for Personalization validation” on page 68
2. 4.4.3, “Modifying Personalization properties” on page 69
3. 4.4.4, “Creating directories for Personalization migration” on page 70
4. 4.4.5, “Running the export task for Personalization” on page 70
5. 4.4.6, “Copying files to WebSphere Portal V6 server” on page 72
6. 4.4.7, “Running the transform task for Personalization” on page 73
7. 4.4.10, “Running the import task for Personalization” on page 75
8. 4.4.11, “Validating your Personalization” on page 76
Chapter 4. Migration of Document Manager and Personalization 67

It is recommended that you prepare a checklist before Personalization migration. In many cases, there are a large number of Personalization resources and rules in workspace. You
must, therefore, perform a spot check in the workspace after migration. Table 4-4 provides a
sample checklist. If you have rules that interact with other components of WebSphere Portal, such as Document Manager, it is recommended that you include samples of the rules in the checklist.
Table 4-4 Checklist for Personalization validation
Source Target Resource/Rule Name
OK Rules Simple Doc Rule
Component
Document Manager
Restriction: Rules from earlier versions that made use of the site area property in
Workplace Web Content Management must be manually updated after Workplace Web
Content Management migration. Refer to the Web content resource collection topic in the
IBM WebSphere Portal Version 6.0 Information Center for more information: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/mig_tbl.html
If you are using only the built-in resource collections (Web content, documents, and portal user) and objects (request, session, and so on), you do not have to worry about this step.
Resource collection classes allow Personalization to connect to customer-defined data sources. Resource collections are implemented by a set of Java classes. These classes might have been generated either by wizards in IBM Rational Application Developer (or one of its predecessors such as IBM WebSphere Studio Application Developer) or might have been hand-coded. All custom application objects are hand-coded. Java classes used by resource collections and application objects must be placed in a WebSphere Application
Server-shared library. The portal migration framework does not move, migrate, or in any way touch these classes. They must be migrated manually along with the other classes you might have deployed to the application server. As of WebSphere Portal V6, a shared library is predefined for custom resource collections and application objects. You can add classes to this library by placing classes in folders representing packages or JAR files in
<wps>/pzn/v6.0/collections. These classes and JAR files will be added to the classpath of the entire portal server. You can move classes from your shared libraries into this one. If your custom shared libraries are scoped differently from this predefined library, or if you want more administrative control over the classpath, you can still use custom-defined shared libraries.
Additionally, resource collections, particularly, Structured Query Language (SQL) resource collections generated by the wizards in Rational Application Developer, might require data source definitions in the application server. The WebSphere Portal migration framework does not move, migrate, or otherwise touch customer-defined data source definitions for these collections. These data source definitions must also be migrated manually.
If your classes made use of internal or undocumented programming interfaces, the resource collection classes themselves may require custom migration.
68 Best Practices for Migrating to IBM WebSphere Portal V6

The Personalization property file is located in
<portal_server_root>\jcr\migration\conf\pzn_conf.xml. Change the properties described in
Table 4-5 to suit your environment requirements.
Table 4-5 Personalization properties that must be changed
Property name Description
SourceServerPort
TargetServerPort
The fully qualified host name and port, where WebSphere Portal is running on the V5.1 server
The fully qualified host name and port, where WebSphere Portal is running on the V6 server
ExportNode
SourceExportData
TargetExportData
TempData
SourceRepository
UserId
The path of the node that will be exported
The directory on the V5.1 server where the exported data is saved. This path must be an existing, empty directory.
The directory on the target (V6) server. The tasks after the export task are required to access the exported data from the target (V6) server. Because mapping environment is not used, the exported data must be copied to the target server’s local directory. This property is the local directory where exported data is stored.
An existing, empty directory on the V6 server. This directory is used to store temporary data.
The user ID used to connect to the WebSphere Portal V5.1 server Java
Content Repository (JCR) repository. Therefore, specify the portal administrator user ID of your WebSphere Portal V5.1 server. This must be a fully qualified DN.
SourceRepository
Password
SourceWorkspace
TargetRepository
UserId
TargetRepository
Password
TargetWorkspace
IncludeVersion
The password used to connect to the WebSphere Portal V5.1 server JCR repository. Therefore, specify the portal administrator password of your
WebSphere Portal V5.1 server.
The name of the workspace holding the V5.1 data. Unless V5.1
Personalization has been customized to use a different workspace, this must always be ROOTWORKSPACE.
The user ID used to connect to the WebSphere Portal V6 server JCR repository. Therefore, specify the portal administrator user ID of your
WebSphere Portal V6 server. Both the short name and the fully qualified DN work independently of the LDAP configuration.
The password used to connect to the WebSphere Portal V6 server JCR repository. Therefore, specify the portal administrator password of your
WebSphere Portal V6 server.
The name of the workspace that holds the V6 data. Unless Personalization
V6 has been customized to use a different workspace, this must always be
RULESWORKSPACE.
This specifies whether to migrate versions, if any, of Personalization.
Important: SourceRepositoryUserId in the properties file must be in fully qualified DN format. This is required because V5.1 cannot use short name. TargetRepositotyUserId can be a short name. Use the Portal admin user, which is specified as PortalAdminId in the wpconfig.properties file.
Chapter 4. Migration of Document Manager and Personalization 69

Important: Do not forget to take a backup of the original file.
You must create three directories for Personalization migration, one on the WebSphere
Portal V5.1 server, and the other two on the WebSphere Portal V6 server.
Create an empty export directory on the WebSphere Portal V5.1 server, for example, c:\WebSphere\PortalServer\migration\pzn\export51\. This export directory will be used for the
SourceExportData property, as described in 4.4.3, “Modifying Personalization properties” on page 69.
Create an empty export directory on the WebSphere Portal V6 server also, for example, c:\WebSphere\PortalServer\migration\pzn\export51\. This export directory is used for the
TargetExportData property, as described in 4.4.3, “Modifying Personalization properties” on page 69.
Important: As described in the WebSphere Portal V6 Information Center, you can share the SourceExportData directory with the WebSphere Portal V6 server as the
TargetExportData directory. It is recommended that you create a separate directory on the
WebSphere Portal V6 server instead of sharing the same directory. Refer to the IBM
WebSphere Portal Version 6.0 Information Center for details: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/mig_tbl.html
Create an empty work directory for import on WebSphere Portal V6 server, for example, c:\WebSphere\PortalServer\migration\pzn\import60\. This work directory will be used for the
TempData property, as described in 4.4.3, “Modifying Personalization properties” on page 69.
The TempData property must not be set to the same value as the TargetExportData property.
Your Personalization property file is ready to be used for the migration tasks.
The export task calls the DTT application on WebSphere Portal V5.1 server, which creates exported files on WebSphere Portal V5.1 server. These must be copied to the WebSphere
Portal V6 server.
Ensure that your WebSphere Portal V5.1 server is running, with the DTT application available. There is no interaction with WebSphere Portal V6 server.
Watch out for firewalls because the export task is required to communicate with your
WebSphere Portal V5.1 server through the SourceServerPort specified according to the
information provided in Table 4-5.
70 Best Practices for Migrating to IBM WebSphere Portal V6

Run the export task for Personalization by typing the following in the
<portal_server_root>\migration directory using the command-line interface on WebSphere
Portal V6 server (Figure 4-19):
WPmigrate.bat migrate-pzn-export-51x
Figure 4-19 Export task for Personalization
The WPmigrate command must report a BUILD SUCCESSFUL
message (Figure 4-20). Also
check MigrationTrace.log located in <portal_server_root>\log carefully to ensure the same.
Figure 4-20 Export task for Personalization: BUILD SUCCESSFUL message
Chapter 4. Migration of Document Manager and Personalization 71

The export task creates files under the
SourceExportData
directory that you specified
according to the information provided in Table 4-5. You can find the
rootworkspace
directory there, and see that there are files whose names are associated with your Personalization data
(Figure 4-21).
Figure 4-21 Export task for Personalization: Successful creation of files
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again.
You can also check the WebSphere Portal V5.1 server logs.
Clean up the
SourceExportData
directory before you rerun this task. If you forget to clean up the directory, you receive a BUILD FAILED message with Error 500:
“Please make sure that the export directory is empty and restart export.”
After the export task is successfully completed, the export files are created in a new directory called rootworkspace
in the
SourceExportData
directory on WebSphere Portal V5.1 server.
Copy these files to the
TargetExportData
directory on WebSphere Portal V6 server before running the transform task for Personalization.
72 Best Practices for Migrating to IBM WebSphere Portal V6

There are several ways in which to copy these files from WebSphere Portal V5.1 server to
WebSphere Portal V6 server. Select the most convenient method that allows you to complete
this task (Figure 4-22).
WebSphere Portal V5.1 server
WebSphere Portal V6 server
Figure 4-22 Copying “rootworkspace” directory from V5.1 to V6 for Personalization
After copying all the files under the rootworkspace directory, validate a few files by opening them in a text reader.
The transform task transforms all the files that are exported by the export task, and writes the transformed files to the
TempData
directory in the format required by the import task.
There is no interaction with either the WebSphere Portal V5.1 server or WebSphere Portal V6 server.
Run the export task for Personalization by typing the following in the
<portal_server_root>\migration directory in the command-line interface on WebSphere Portal
V6 server (Figure 4-23):
WPmigrate.bat migrate-pzn-transform-51x
Figure 4-23 Transform task for Personalization
Chapter 4. Migration of Document Manager and Personalization 73

Note: The commands for Personalization are slightly different from the commands for
Document Manager. The Personalization commands have a -51x suffix.
The WPmigrate command must report a BUILD SUCCESSFUL
message (Figure 4-24).
Figure 4-24 Transform task for Personalization: BUILD SUCCESSFUL message
Important: Even if the source is wrong, the task runs to completion and report a “ BUILD
SUCCESSFUL ” message.
Also check whether the files have been successfully written to the
TempData
directory, which
you specified, as described in “Creating directories for Personalization migration” on page 70.
You can find the rootworkspace directory there (Figure 4-25).
Figure 4-25 Transform task for Personalization: Successful transformation
74 Best Practices for Migrating to IBM WebSphere Portal V6

If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again.
Configuration of the cache is performed through the PersonalizationService.properties file in
<wps>/shared/app/config/services. The settings customized in this file are not
migrated. You must manually migrate the settings changed in this file.
The import task imports the transformed Personalization objects from the
TempData
directory into the WebSphere Portal V6 server repository.
Ensure that your WebSphere Portal V6 server is running. There is no interaction with
WebSphere Portal V5.1 server.
Run the import task for Personalization by typing the following in the
<portal_server_root>\migration directory using the command-line interface on the
WebSphere Portal V6 server (Figure 4-26):
WPmigrate.bat migrate-pzn-import-51x
Figure 4-26 Import task for Personalization
The WPmigrate command must report a BUILD SUCCESSFUL
message (Figure 4-27).
Figure 4-27 Import task for Personalization: BUILD SUCCESSFUL message
Chapter 4. Migration of Document Manager and Personalization 75

If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, and eliminate the issues.
You can also check the WebSphere Portal V6 server logs.
Your migration tasks for Personalization are complete. You can now open your browser to log in to your WebSphere Portal V6 server to confirm that the migration tasks have successfully migrated your Personalization workspace.
Use your own test scripts and validation criteria, as recommended in 4.4.1, “Preparing a checklist for Personalization validation” on page 68 to perform some spot checks by
previewing a selection of rules.
This section describes the postmigration tasks for Document Manager and Personalization.
These tasks are optional, depending on your environment.
The Document Manager and Personalization property files include the portal administrator’s passwords for both the WebSphere Portal servers. It is recommended that you remove these passwords.
Now that you have completed Document Manager and Personalization migration, if you want to uninstall the Document Tracking Tool from the WebSphere Portal V5.1 server, perform the following tasks:
1. Shut down WebSphere Portal V5.1 server.
2. Follow the instructions that are packaged with the Portal Update Installer about how to uninstall the fix.
3. Restart WebSphere Portal V5.1 server.
4. Uninstall icmjcr.ear from WebSphere Portal V5.1 server. Consult your WebSphere
Application Server Administrator, if necessary.
76 Best Practices for Migrating to IBM WebSphere Portal V6

5
Chapter 5.
This chapter provides the best practices for migrating your IBM Workplace Web Content
Management data from WebSphere Portal V5.1 to WebSphere Portal V6. This chapter explains the steps and provides validations along the way to help you complete a primary system Workplace Web Content Management migration.
Important: If you have a decentralized authoring system, aggregate all the current data into a single server, using syndication, and then migrate your Web Content Management data. Refer to the IBM WebSphere Portal Version 6.0 Information Center for details: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/topic/com.ibm.wp.ent.doc/wp f/mig_wcm.html
This chapter describes the Workplace Web Content Management migration process through the following topics:
򐂰
5.1, “Migration considerations” on page 78
򐂰
5.2, “Workplace Web Content Management migration” on page 79
򐂰
5.3, “Premigration tasks” on page 80
򐂰
5.3.3, “Installing the Workplace Web Content Management migration tool” on page 88
򐂰
5.3.5, “Migrating the Workplace Web Content Management user data” on page 95
򐂰
5.3.6, “Migrating the Workplace Web Content Management rendering portlets” on page 97
򐂰
5.3.7, “Postmigration tasks” on page 100
© Copyright IBM Corp. 2007. All rights reserved.
77

IBM Workplace Web Content Management’s repository architecture has changed significantly in the latest release. Workplace Web Content Management now uses the Java
Content Repository (JCR) to manage content, thus allowing for tighter integration with
Personalization and Document Manager and other JCR-related products. By moving to the
JCR, Workplace Web Content Management now supports clustering. The architecture for
Workplace Web Content Management is now more in line with current portal architectures, where clones can share the same Workplace Web Content Management repository. Unlike earlier releases, where there existed a separate Workplace Web Content Management repository, Workplace Web Content Management now inputs managed assets into the JCR database.
The migration is a process of exporting data from the Workplace Web Content Management repository, transforming each asset into a new format, and importing the assets into the JCR.
There is no simple 1-1 correlation between an old Workplace Web Content Management asset and a new Workplace Web Content Management asset represented in the JCR.
Instead, you may find many JCR nodes that represent one content item. As a result, the number of transformed items might not match the number of exported items. Similarly, the number of transformed items might not match the number of imported items.
Because the architecture has been simplified in this release, it is best to migrate only a few of your Workplace Web Content Management environments. If you are working in a production cluster, it is best to migrate only the primary node and rebuild the cluster. Each secondary node will automatically pick up the portal pages, Workplace Web Content Management rendering portlets, and now the Workplace Web Content Management content. A migration of the authoring and development environments must occur.
Syndicators and subscribers are not
migrated in this migration process. With clustering now supported, syndication only has to be set up from one environment to another, instead of one clone to another, as in earlier releases.
Custom applications must also be considered. Applications using the Web Content
Management application programming interfaces (API) have to be modified to include Web
Content Management library information. JavaServer Page (JSP) fragments that use Web
Content Management APIs must be tested and reviewed. The migration process does not move these JSPs over from the old server to the WebSphere Portal V6 server. Repackaging the Workplace Content Management enterprise application to include these JSPs for deployment into a cluster must be considered.
New enhancements to the authoring environment have reduced the necessity for custom authoring environments, such as the Custom Template Portlet. These enhancements include
more inline editing tools, custom templating, and launch page configuration. Refer to 5.3.7,
“Postmigration tasks” on page 100 for more information about these enhancements. However,
the Custom Template Portlet should still work in the WebSphere Portal V6 server, with changes to the Web Content Management Repository login through the API to account for library information. Alternatively, the default library can be set in
WCMConfigService.properties by updating the defaultLibrary property.
78 Best Practices for Migrating to IBM WebSphere Portal V6

At a high level, core Workplace Web Content Management migration must transform
Workplace Web Content Management assets from its old format to one that can be stored in the JCR. During the transformation, the migration must also parse all the existing references and update them to point to the new JCR representation of those assets. After transforming the format and updating references between the assets, the assets are imported into the
JCR.
Following is the process involved in the migration:
1. The first step in the migration is to export the data from the old repository, using export data. The export data will use the migration/exporter/lib directory and the property legacy.config.path from the migration.properties file. The migration/export/lib directory is used to access the Java archive (JAR) files required to access databases. Export data will use legacy.config.path to access the old connect.cfg and aptrixtjpe.properties. Using these two files, it will use the connection information to connect to the old repository. From
connect.cfg, it will use the <databases> tag (Example 5-1), and from the aptrixjpe.properties, it will use jdbc.* properties (Example 5-2).
Example 5-1 The <databases> tag
<Databases>
<jdbc:db2j:D:/WEBSPH~1.5/PORTAL~1/wcm/ilwwcm/db/WCMDB driver="com.ibm.db2j.jdbc.DB2jDriver" />
</Databases>
Example 5-2 jdbc.* properties
# jdbc persistency settings
# the url to the database (i.e. jdbc:db2:ILWWCM) jdbc.url=jdbc:db2j:D:/WEBSPH~1.5/PORTAL~1/wcm/ilwwcm/db/WCMDB
# the name of the user to connect to the database with jdbc.username=APP
# the password of the user to connect to the database with jdbc.password=ReplaceWithYourDbAdminPwd
# the database table which will be created to manage objects (optional).
# if this parameter is not included, then the table name will default to "AJPE".
jdbc.table=AJPE
# the database table which will be created to manage resources (optional).
# if this parameter is not included, then the table name will default to
"AJPE_RESOURCES".
jdbc.resources.table=AJPE_RESOURCES
# the database schema under which the table will be created (optional).
# if this is not specified, then this will default to the jdbc.username
# parameter.
#jdbc.tableSchema=[JDBC_SCHEMA]
# The number of items to read ahead when reading all items for index recreation.
# The default if not specified is 30.
jdbc.readAhead=50
# the maximum size of a resource in MB that can be stored within the jdbc database
(optional).
# if this parameter is not included, then the maxSize will default to 16 MB jdbc.resources.maxSize=10 jdbc.dbms.name=Cloudscape jdbc.managerStrategy=com.aptrix.pluto.util.CloudscapeManagerStrategy
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 79

jdbc.byteContentManagerStrategy=com.aptrix.pluto.util.CloudscapeByteContentManager
Strategy
2. After it has the connection information specified from the properties files, the exporter uses <portal_server_root>/migration/exporter/classpath.properties to find the JARs required by the connection information specified. If the migrator can connect, the data is exported to the path specified by the export.path property in migration.properties.
3. After the data is exported, transform the data into the new format. With JCR, some of the data structures have been replaced with standard JCR data structures. In other cases, some of the data structures have been split into multiple JCR data structures. Therefore, the number of items transformed might not match the number of items exported. The transform data action traverses through the export.path and transforms the necessary content, and places the transformed files into import.path.
4. After the content is transformed, it is ready to be imported into the JCR. This step takes the longest amount of time because of the work involved. The import requires the
Workplace Web Content Management import servlet to import the content into the system.
The Uniform Resource Locator (URL) to the import servlet is specified by the import.servlet.url property. The content is imported into a new library. This library is specified by the import.library.name property in migration.properties.
5. After the content is imported, it is necessary to configure the Authoring user interface (UI) to point to this library to view the content. There have been numerous enhancements to the Authoring UI, and therefore, the Authoring UI is not migrated. Instead, the new
Authoring UI is configured to view the migrated content.
6. After the data is migrated, the viewing portlets must be configured to reference the updated portlets. There are several files that are used internally by the migration process to map old IDs to new IDs. These mapping files are used to reconfigure the viewing portlets to point to the new IDs of the Workplace Web Content Management assets. Two tasks exist for this step, configure-local and configure-remote. Both the tasks utilize
XMLAccess to export the portlet configurations, and then replace the configurations to point to the migrated content, and finally use XMLAccess to import the portlet configurations.
The best practice is to use the Workplace Web Content Management tools to validate that your WebSphere Portal V5.1 server Workplace Web Content Management data is working properly before you export the data to the WebSphere Portal V6 server.
Important: All the content that is on the WebSphere Portal V5.1 server will be disabled until you complete all the tasks described in this chapter. Refer to the WebSphere Portal for Multiplatforms Version 5.1 Information Center for further details: http://publib.boulder.ibm.com/infocenter/wpdoc/v510/index.jsp
Following is a list of the Workplace Web Content Management tools:
򐂰 Reference Checker
򐂰 Site Checker
򐂰 Resource Checker
򐂰 Member Fixer
80 Best Practices for Migrating to IBM WebSphere Portal V6

It is recommended that you take the following points into consideration:
򐂰 Understand that moving large amounts of data will take a long time. Ensure that you perform this task at a time that does not conflict with peak usage.
򐂰 Any password-protected file that is within the Web Content Manager must be removed before migration
򐂰 Any Personalization data that does not have a rule or content spot must be removed
򐂰 Install all the required fixes before migration. Not all the migration fixes listed in the following Web site are required (some depend on what additional components you are expecting to migrate): http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927
The fixes for Workplace Web Content Management are PK34286, PK30057, and
PK30516.
In order to begin the Workplace Web Content Management migration, you must copy the config directory from the WebSphere Portal V5.1 server to a newly created temporary migration folder on WebSphere Portal V6 server. In our case, for the River Bend migration, we created a Web Content Management directory for good housekeeping:
<portal_server_root>/migration/wcm
Note: Copy the wcm db to the WebSphere Portal V6 server only when using Cloudscape for WCMDB.
Tip: Make sure that WebSphere Portal server has stopped, in order to prevent locked files when copying the Cloudscape database to the WebSphere Portal V6 server.
If your Web Content Management migration is using the Cloudscape database, you must first copy two folders, config and ilwwcm, from your WebSphere Portal V5.1 server to WebSphere
Portal V6 server. These folders are located in <portal_server_root>\wcm\ and will go into a newly created temporary directory called wcm under the migration directory of your
WebSphere Portal V6 server.
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 81

Perform the following tasks:
1. Create a directory under <portal_server_root>\migration\ called wcm (Figure 5-1).
create new directory
Figure 5-1 Creating the wcm directory on WebSphere Portal V6 server
82 Best Practices for Migrating to IBM WebSphere Portal V6

2. Copy the config and ilwwcm folders to the newly created directory (Figure 5-2).
Note: Skip the copy ilwwcm step if you are not using Cloudscape for your Workplace
Web Content Management database.
Copy to WebSphere Portal V6 server
Figure 5-2 Copying the config directory
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 83

Copy only
ilwwcm if you are using out-of-the-box Cloudscape WCMDB. Figure 5-3 shows
copying the WCMDB if you are using the Cloudscape database.
Copy this directory ONLY if you are using cloudscape database
Figure 5-3 Copy WCMDB if you are using the Cloudscape database
Depending on which data repository the old system is using, you must copy the Java
Database Connectivity (JDBC™) driver to the <portal_server_root>/wcm/migration/exporter/ directory of the WebSphere Portal V6 server and then update the exporter.classpath property
(Example 5-3) within that directory with the value that corresponds to the version of the data
repository. If the drivers already exist in a path located on the WebSphere Portal V6 server, it is easier to simply update the exporter.classpath property by appending the path.
In the River Bend scenario, DB2 was used to store the Web Content Management data and the portal configuration database. To connect to the Web Content Management database of
WebSphere Portal V5.1 server from WebSphere Portal V6 server, the DB2 Type 4 JDBC driver was used. Using the DB2 Type 4 JDBC driver (held in the db2cc.jar in the
<db2_root>/java) eliminates the necessity to catalog the database locally. Instead, the JDBC
URL (specified in aptrixjpe.properties) includes the host name to the remote database, which will then allow you to proceed with the migration.
Tip: If you are using DB2 Type 2 JDBC drivers, make sure the database is cataloged and that the relevant drivers are available before you begin the wcmmigrate tasks. However, whenever possible, use the Type 4 JDBC drivers.
Example 5-3 Updating the exporter classpath.properties
exporter.classpath = exporter/lib/ilwwcm-migration-exporter.jar:lib/ilwwcm-migration.jar:exporter/lib/d b2j.jar:exporter/lib/exclude-contentapi.jar:exporter/lib/ilwwcm-commons-copyright.
84 Best Practices for Migrating to IBM WebSphere Portal V6

jar:exporter/lib/ilwwcm-commons-properties.jar:exporter/lib/ilwwcm-commons-utils.j
ar:exporter/lib/ilwwcm-commons-version.jar:exporter/lib/ilwwcm-commons-xmlpersiste ncy.jar:exporter/lib/ilwwcm-framework.jar:exporter/lib/ilwwcm-server.jar:exporter/ lib/j2ee.jar:exporter/lib/jcr.jar:exporter/lib/wp.base.jar:exporter/lib/wp.user.ap
i.jar
(If you are using DB2 jdbc drivers, add the following string to the end of classpath=) exporter/lib/db2cc.jar:exporter/lib/<license that in is in the <runtime
Server>SQLLIB\java> Here are the possible licenses that you will might find in that directory db2jcc_license_cu.jar or db2jcc_license_cisuz.jar
(If you are using Oracle® jdbc drivers, add the following string to the end of classpath=) exporter/lib/classes12.jar
(If you are using SQL jdbc drivers, add the following string to the end of classpath=) exporter/lib/mssqlserver.jar:exporter/lib/msbase.jar:exporter/lib/msutil.jar
You must then configure aptrixjpe.properties
and connect.cfg
to the current migrated environment. In both the properties files, ensure that the JDBC driver equals the data repository version that you are using, and that it points to the wcmdb on the old system. This file must be updated only in two situations:
򐂰 The Workplace Web Content Management repository is a local Cloudscape DB, and therefore, paths to the local Cloudscape DB must be updated.
򐂰 Use Type 4 drivers when the DB2 database has not been cataloged locally.
If you are using DB2, configure aptrixjpe.properties and connect.cfg to the current migrated environment as follows:
򐂰 aptrixjpe.properties
Ensure that jdbc.url=jdbc:db2://<db2 host name>:<port number>/wcmdb is configured to point to the database of the old system and that there are no spaces before or after the
URL.
򐂰 connect.cfg
Ensure that <jdbc:db2://<db2 host name>:<port number>/wcmdb driver="com.ibm.db2.jcc.DB2Driver /> is configured to point to the database of the old system and that there are no spaces before or after the URL. Also ensure that the driver=
<jdbc driver of your RDBMS> is using the correct one and not the default Cloudscape driver (com.ibm.db2.jcc.DB2Driver).
Note: The port number for DB2 on your new system can be found under
%systemroot%/system32/drivers/etc/services on Windows systems and /etc/services on UNIX systems.
If you are using the out-of-the-box Cloudscape Web Content Management database, make sure that you are pointing to the database on the new system
that you copied from the old system.
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 85

You must update the migration.properties file that is located in the portal_server_root/wcm/migration/config directory on WebSphere Portal V6 server before running the Workplace Web Content Management migration commands. In the file, it is
necessary to confirm that the parameters are set and modified, based on Table 5-1.
Following is what you should look for in the properties file to update it for migration:
<name>.path = C:/Websphere/PortalServer/migration/wcm/<name>
Tip: Use forward slash in path names. Both Windows and UNIX can handle forward slashes.
Table 5-1 Explanation of the migration.properties file migration.properties file Explanation export.path
import.path
The path on the local file system where exported data is saved
The directory on the local file system where transformed data is saved summary.path
legacy.config.path import.servlet.url
import.library.name
The path on the local file system where summary configuration files will be created. These files will be used when migrating a secondary system.
The path on the local file system where the old
Web Content Management configuration is located
The URL of the import servlet running on the new system. Replace local host with the appropriate host name for the new system.
The name of the library created during import
Finally, increase the total transaction lifetime timeout of your new WebSphere Portal server to at least 480 seconds through the WebSphere Application Server administrative console.
Navigate to Application Servers
→
Server
→
Container Services
→
Transaction Service.
Make a note of the current total transaction lifetime timeout so that it can be restored after you have completed the migration. For more information, refer to the topic “Migrating User
Profiles” in the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wcm/wcm_migration_users.html
Restart
the Portal Application Server before you begin the wcmmigrate tasks.
Important: The WebSphere Portal server must be running on WebSphere Portal V6 before you begin the wcmmigrate tasks.
86 Best Practices for Migrating to IBM WebSphere Portal V6

Note that even if you transferred your WebSphere Portal server database from Cloudscape to a relational database management system (RDBMS), it does not mean that the Workplace
Web Content Management database was also transferred, because the Workplace Web
Content Management database is a separate configuration and does not occur when transferring WebSphere Portal server databases to another RDBMS.
If you are unsure, you can verify where your Workplace Web Content Management database resides, by opening up the <portal_server_root>/wcm/config/aptrixjpe.properties and looking
at the jdbc.* properties. Figure 5-4 shows an example of a Cloudscape database.
# jdbc persistency settings
# the url to the database (ie. jdbc:db2:ILWWCM this is the default for cloudscape) jdbc.url=jdbc:db2j:D:/WEBSPH~1.5/PORTAL~1/wcm/ilwwcm/db/WCMDB
# the name of the user to connect to the database with jdbc.username=APP
# the password of the user to connect to the database with jdbc.password=ReplaceWithYourDbAdminPwd
# the database table which will be created to manage objects (optional).
# if this parameter is not included, then the table name will default to "AJPE".
jdbc.table=AJPE
# the database table which will be created to manage resources (optional).
# if this parameter is not included, then the table name will default to "AJPE_RESOURCES".
jdbc.resources.table=AJPE_RESOURCES
# the database schema under which the table will be created (optional).
# if this is not specified, then this will default to the jdbc.username
# parameter.
#jdbc.tableSchema=[JDBC_SCHEMA]
# The number of items to read ahead when reading all items for index recreation.
# The default if not specified is 30.
jdbc.readAhead=50
# the maximum size of a resource in MB that can be stored within the jdbc database (optional).
# if this parameter is not included, then the maxSize will default to 16 MB jdbc.resources.maxSize=10 jdbc.dbms.name=Cloudscape jdbc.managerStrategy=com.aptrix.pluto.util.CloudscapeManagerStrategy
jdbc.byteContentManagerStrategy=com.aptrix.pluto.util.CloudscapeByteContentManagerStrategy
Figure 5-4 An example of a Cloudscape database
Tip: When writing this IBM Redpaper, testing the DB2 Workplace Web Content
Management took about 10 times less time to complete all the wcmmigrate commands.
Transferring the Workplace Web Content Management DB from Cloudscape to a RDBMS before performing the migration has the potential to significantly reduce the time taken for the migration.
Each environment must coordinate with its Web Content Management authoring team to spot check whether the Web Content Management functions are still available after the initial migration (before you fix the environment).
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 87

This is the initial task that must be performed prior to running all the wcmmigrate commands.
Go to the <WebSphere Portal Serverhome>\config directory on the WebSphere Portal V6
server through a command line and run the following (Figure 5-5):
wpconfig configure-wcm-migration
Figure 5-5 Migration tool command
Access the WebSphere Portal on the V6 server and check whether the application has been installed properly, by starting without error in the portal_server_root/log/SystemOut.log file
and searching for the words “ilwwcm-wcmimport” Figure 5-6.
Figure 5-6 displays the following information, indicating that the tool is successfully installed:
“Application started: ilwwcm-wcmimport”
Figure 5-6 Successful installation of the Web Content Management migration tool
88 Best Practices for Migrating to IBM WebSphere Portal V6

Performing this task validates that the current premigration tasks were updated correctly, Go to the portal_server_root/wcm/migration directory and run this command from the command
line (Figure 5-7):
wcmmigrate.bat validate -user <username> -password <password>
Figure 5-7 Running the wcmmigrate.bat validate command
If you have issues with this command, review the trace0.log file located in the portal_server_root/logs directory.
Figure 5-8 shows an example of an error that occurs when you have problems with your
property files.
Figure 5-8 Error when running the validate command
To resolve this issue, review your property files for mistyping or misconfigurations. Table 5-3
provides you with possible resolutions to the issues shown in Figure 5-8 or if you encounter
issues when running other wcmmigrate commands.
The best practice is to run the commands that are in the wcmmigrate script one at a time and verify that each step is successful. This eliminates hours of waiting to see if the import completes successfully. Another reason is that is allows you to run the import command during off peak hours to optimize performance.
Tip: wcmmigrate without options lists the available commands.
Table 5-2 describes the commands and what they accomplish.
Table 5-2 The wcmmigrate commands wcmmigrate command What it accomplishes
Validate estimate-data
Confirms that the migration.properties files, network connectivity, and user permissions are correctly configured. This command requires that you add a user name and password to the command.
Provides an estimate of the time taken and space required for the data migration
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 89

wcmmigrate command What it accomplishes export-data transform-data
Exports items from the old system
Transforms exported items so that they are ready to be imported into the new system import-data Imports the transformed items. This requires a user name and a password. a a. This command can take a long time, depending on how much data you are importing.
If your command fails or there are issues with your network connection, you can either restart or resume from the task where failure occurred.
Depending on where your task failed, it might be necessary to verify whether the required
machines are running. Table 5-3 provides information to help you overcome the possible
errors that might occur during the migration task.
Table 5-3 Troubleshooting for possible errors
Possible error
Fails on Validate
Fails on Export
Fails on Transform
Fails on Import
Fails on Configure-local
Possible cause
򐂰 Make sure that the migration.properties, legacy.config.path, is pointed to the correct set of config files
򐂰 Make sure that the config files point to the correct database. If Cloudscape is being used, ensure that the database was copied and that the config files point to it.
򐂰 Ensure that the database machine is started and is accessible from the WebSphere Portal
V6 server
򐂰 Ensure that export.path points to a usable directory structure, for example, if using
UNIX, do not
set the export path to c:\export
򐂰 Ensure that export.path has enough space for exporting all the Workplace Web Content
Management assets
򐂰 Ensure that the database server is running and is accessible
Ensure that import.path has enough space for transforming all the Workplace Web Content
Management assets
򐂰 Ensure that the Workplace Web Content
Management V6 database server is running
򐂰 Ensure that the WebSphere Portal V6 server is running
򐂰 Ensure that the WebSphere Portal server config, configure-wcm-migration, has been run
򐂰 Ensure that the WebSphere Portal V6 server is running
򐂰 Ensure that the user specified in the wcmmigrate task has the rights to execute the xmlaccess tasks
90 Best Practices for Migrating to IBM WebSphere Portal V6

Possible error
Fails on Configure-remote
Possible cause
򐂰 Ensure that the WebSphere Portal V6 server is running
򐂰 Ensure that the summary.path is correct and has been copied from the Web Content
Management V6 server
򐂰 Ensure that the <WebSphere Portal
Server>/wcm/migration/remote_rendering.pr
operties has been updated with the correct values. Using fully qualified host names is recommended.
In the portal_server_root/wcm/migration directory, issue the following command to restart or resume the tasks that were running: wcmmigrate -user <username> -password <userPassword> <command> -restart
Issue the following command to resume the tasks if the tasks timed out or the networks failed: wcmmigrate -user <username> -password <userPassword> <command> -resume
Figure 5-9 shows the resume or restart command.
Figure 5-9 Resume or restart command
Because of the complexity of the Workplace Web Content Management migration, the best practice is to run the commands one at a time as against using the “all” parameter.
The following commands are run in the portal_server_root/wcm/migration directory from a command prompt:
1. Run the following export command: wcmmigrate export-data
Note: Ensure that you see the “ Command Successful ” message before you move to the next step. If you have a failure on your hands, go to the log directory to pinpoint the issue.
2. Run the following transfer command: wcmmigrate transform-data
Note: Ensure that you see the “ Command Successful ” message before you move to the next step. If you have a failure on your hands, go to the log directory to pinpoint the issue.
Note: As you learned in 5.1, “Migration considerations” on page 78, these numbers will
not match the numbers reported on import.
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 91

3. Run the following import command: wcmmigrate import-data
Notes:
򐂰 This step is the one that takes the longest amount of time, and must be completed successfully. It takes many hours, possibly days to complete.
򐂰 It is very resource intensive and long-running.
򐂰 Because this task runs against a URL, watch out for timeouts.
򐂰 When running this command, consider the volume of data and the space that you currently have on the system that you are migrating.
After completing all the tasks, configure the portlet to the import library data from the migration.properties file (import.libray.name=<name of Library) so that you can view the migrated information.
Perform the following tasks:
1. Log in to the WebSphere Portal V6 server and select Administration, as shown in
Figure 5-10.
Click here
Figure 5-10 Launching the Administration page
92 Best Practices for Migrating to IBM WebSphere Portal V6

2. Select Launch
→
Web Content (Figure 5-11).
Click here
Figure 5-11 Launching the Web Content page
3. Select Web Content Management and click Continue to launch the Library page
(Figure 5-12).
Click the WCM tab
Figure 5-12 Launching the Library section
Click here to launch the Library
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 93

4. In the Library page, add a library by selecting the relevant library and clicking Add. To
remove a library, select the corresponding library and click Remove (Figure 5-13). Click
OK after completing the task.
Figure 5-13 Adding the migrated library
One of the components that does not
migrate to the WebSphere Portal V6 server is the
Authoring Portlet. In order to administer authoring that was on the page in WebSphere Portal
V5.1 server, add the new Workplace Web Content Management Authoring Portlet to the page. Perform the following tasks to add the new portlet:
1. Go to the Portal administration section and select Manage Pages.
2. Navigate to Select Page
→
Content Root
→
My Portal
→
Name of page
→
Web
Content Management.
3. When you are there, click the pencil icon.
4. Click Add Portlet.
94 Best Practices for Migrating to IBM WebSphere Portal V6

5. In the page that opens (Figure 5-14), search for Web Content Authoring. In the list that is
displayed, select Web Content Authoring and click OK to add the portlet to the page.
Figure 5-14 Adding the Web Content authoring portlet.
6. Work through the content in the Authoring Portlet to make sure that everything is there.
7. Preview the content, especially with regard to Personalization and Document Manager.
8. Validate the security, the templates, the workflow, and so on.
After the completion and verification of your data, update the portal user data so that the portal users can use the migrated data.
In some Web Content Management configurations, users can customize content display based on categories or key words. Their personalized list of categories and key words are stored within the Portal’s WebSphere Member Manager lookaside tables.
The WebSphere Member Manager attributes that contain the users’ categories and key words are WCM:CATEGORIES and WCM:KEYWORDS respectively. The
WCM:CATEGORIES contain IDs to the category objects in Web Content Management.
These IDs must be updated to point to the new IDs for the migrated categories. This task updates these IDs.
Note: Migrate WebSphere Member Manager before migrating the user profiles. For details, refer to the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp
.ent.doc/wpf/sec_mig_roles.html
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 95

The questions you must ask yourself before running the user task and the corresponding actions to be taken by you are listed in this section:
1. Whether you are on a primary or secondary system
If you are using the primary server, proceed to step 2.
If you are using a secondary server, copy the configuration files from the primary server to a folder, portal_server_root/migration/wcm (which you must create on the secondary system), and update the property files and configure summary.path as described in
“Updating the property files before you run the migration” on page 84 before you issue the
-user command.
Tip: Workplace Web Content Management V6 now supports clustering. Migrating a secondary server is not
necessary if you are migrating to a cluster. After the primary server has been migrated, the new WebSphere Portal V6 clones take advantage of the shared repository and shared portlets.
2. Whether your Lightweight Directory Access Protocol (LDAP) has more then 200 users
If your LDAP has more than 200 users, perform the following tasks: a. Stop the WebSphere Portal server b. Back up your wmm.xml file located in the portal_server_root/wmm directory c. Edit the wmm.xml file by increasing the settings to a number higher than the users within the LDAP directory.
Search for maximumSearchResults="200" in wmm.xml, and change “200” to a number that is higher than the number of users who are present in your current Lightweight
Directory Access Protocol (LDAP) server.
Tip: If you experience a timeout, try changing the searchTimeOutmaximum to
2,000,000 .
3. Restart the WebSphere Portal server.
4. Run the following user command: wcmmigrate users -user <username> -password <password>
Note: Ensure that you see the “ Command Successful ” message before you move to the next step. If you have a failure on your hands, go to the log directory to pinpoint the issue.
5. Restore the wmm.xml for the backup in the portal_server_root/wmm/ directory.
6. Restart the WebSphere Portal server.
96 Best Practices for Migrating to IBM WebSphere Portal V6

Now that you have successfully migrated the Workplace Web Content Management content from WebSphere Portal V5.1 server to WebSphere Portal V6 server, configure or reconfigure your rendering portlets to use the newly imported Workplace Web Content Management.
Note: If you have a small amount of rendering portlets, re-create, rather than migrate the rendering portlets to the new system.
Before you begin to import the rendering portlets, identify whether you are going to import to the primary system or the secondary system. If you are working in a clustered environment, you have to run the commands on the primary node only. In the unlikely case that you are using a secondary server, copy the configuration files from the primary server to a folder, portal_server_root/migration/wcm (which you must create on the secondary system), and
follow the instructions provided in “Updating the property files before you run the migration” on page 84 prior to running the following command from the
portal_server_root/wcm/migration directory: wcmmigrate configure-local -user WebSphere Portal Serveradmin -password WebSphere
Portal Serveradmin
Note: Ensure that you see the “ Command Successful ” message before you move to verify the configuration of the local rendering portlet.
Remote rendering portlets require additional steps to migrate because they contain information pertaining to the Workplace Web Content Management Rendering Server. Before migrating the remote rendering portlets, consider the following questions (the best practices are provided with each of these questions):
򐂰 Have you migrated the Workplace Web Content Management Rendering Server that the
Web Content Management V6 remote rendering portlets will be configured to view?
It is best practice to keep all software levels equal.
򐂰 Is the Workplace Web Content Management Rendering Server clustered?
If yes, using the Web server address is sufficient to configure the remote rendering portlets.
򐂰 Will the remote rendering portlets exist in a cluster?
If yes, the migration tasks will only have to be executed on the primary node.
򐂰 Will the remote rendering portlets point to multiple Workplace Web Content Management
Rendering Servers?
If yes, more edits of the remote_rendering.properties must take place.
򐂰 Can the Portal V6 environment communicate to the Workplace Web Content Management
Rendering Server?
Ensure that firewalls, virtual IPs, and so on have been configured to allow for connection between the remote rendering portlets and the Workplace Web Content Management
Rendering Server.
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 97

After you have answered these questions, you are ready to configure the remote rendering portlets:
1. Edit portal_server_root/wcm/migration/config/remote_rendering.properties.
2. If you have multiple Workplace Web Content Management Rendering Servers, change the remote.host.base.path.list value from “all” to the values of the previous hosts that you want to configure with the new Workplace Web Content Management Rendering Server host.
3. Uncomment the WCM_REMOTE_HOST_BASE_PATH and put in the correct value to the new Workplace Web Content Management Rendering Server.
4. Copy the summary data from the Workplace Web Content Management Rendering Server to the Portal server.
5. Update portal_server_root/wcm/migration/config/migration.properties by changing the property, summary.path, to point to that directory.
6. Run the following command: wcmmigrate configure-remote
98 Best Practices for Migrating to IBM WebSphere Portal V6

Example: Consider an environment where you have two Workplace Web Content
Management Rendering Servers that must be migrated. The URLs for the old
Workplace Web Content Management Rendering Servers are http://old_wcm_1 and http://old_wcm_2. The URLs to the new Workplace Web Content Management
Rendering Servers are http://new_wcm_1 and http://new_wcm_2.
To migrate the remote rendering portlets that point to http://old_wcm_1 to point to http://new_wcm_1:
1. Edit the value of remote.host.base.path.list to http://old_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties.
2. Edit the value of WCM_REMOTE_HOST_BASE_PATH to http://new_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties.
3. Copy the summary data from the new_wcm_1 server to a directory on the Portal server.
4. Edit the portal_server_root/wcm/migration/config/migration.properties and change the summary.path point to the data copied in step 3.
5. Run the following command: wcmmigrate configure-remote
Repeat the same process to migrate the remote rendering portlets that were configured for http://old_wcm_2 to point to http://new_wcm_2.
If you want to migrate both the remote rendering portlets that were configured for http://old_wcm_1 and http://old_wcm_2 to point to http://new_wcm_1, perform the following tasks:
1. Edit the value of remote.host.base.path.list to http://old_wcm_1,http://old_wcm_2 in portal_server_root/wcm/migration/config/remote_rendering.properties.
2. Edit the value of WCM_REMOTE_HOST_BASE_PATH to http://new_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties.
3. Copy the summary data from the new_wcm_1 server to a directory on the Portal server.
4. Edit the portal_server_root/wcm/migration/config/migration.properties and change the summary.path point to the data copied in step 3.
5. Run the following command: wcmmigrate configure-remote
7. The last step is to perform a full function check on WebSphere Portal V6 server before notifying your users.
Important: The numbers reported will be wrong, possibly 0. This is because it actually
runs XML access. As you learned in 5.1, “Migration considerations” on page 78, these
numbers will not match the numbers reported on import.
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 99

The migration process for Workplace Web Content Management does not automatically update the Web content to use the new features in WebSphere Portal V6. After migrating the content, be sure to configure the Web Content Management user interface (UI) to view the newly migrated library.
Unlike the old Workplace Web Content Management repository, there is no easy way to view a content item directly from the database. With the new JCR repository, many nodes represent one Workplace Web Content Management asset.
Many improvements have been made to the Workplace Web Content Management authoring environment in order to ease the content creator’s experience. Features such as
inline edit
, custom templates creation
, and
Launch page configurations
have been added to simplify the process of adding content.
Inline edit is where a link to edit a piece of content will be displayed when a content author is viewing the contents on a page. When the link is selected, the content automatically opens in the authoring template and is ready for editing.
The creating custom templates feature has also been added to the authoring UI. When defining an authoring template, the Web Content Management administrator can now override certain fields with JSPs. JSPs provide a multitude of customization options. This function can be used for the following:
򐂰 Formatting the field to create a uniform look
򐂰 Personalizing the list of choices a user can choose from when inputting the field
򐂰 Performing validation by adding Javascript functions
򐂰 Performing queries on external repositories to pull in data into the field, for example, pulling in IBM Content Manager references into Workplace Web Content Management content.
Configuring a Launch page can also greatly enhance the content contributor’s experience.
The Launch page can also be a JSP, which provides more flexibility. By configuring a Launch page, the content contributor will not see the typical Explorer view. Instead, the Launch page will be shown. This function can be used for the following:
򐂰 Providing a personalized list of links to authoring templates to create content, using remote actions
򐂰 Providing a list of links to content that must be updated or approved
Workplace Web Content Management V6 provides a number of capabilities in addition to its authoring environment enhancements. The three major additions are
Library enhancement
,
Link and Stylesheet components
, and
Referential integrity
.
Libraries allow for an added separation of content. In the earlier releases, content was stored in one central repository. With Libraries, you add an additional layer to this repository to group relevant content together. Each library has its own set of security. The Web Content
Management UI can be configured to show only certain libraries. Libraries can be used for the following:
򐂰 Grouping the shared components into a library referenced from other libraries
򐂰 Configuring a library per department
򐂰 Configuring a library per new Web site release
100 Best Practices for Migrating to IBM WebSphere Portal V6

The Link component allows the content creator to manage links as a Workplace Web Content
Management asset. These links can be reused in content or presentations. The link component provides a more structured component to link to both internal Workplace Web
Content Management assets and external URLs.
The Stylesheet component allows the content contributor to manage the stylesheet as a separate reusable asset. It provides for cascading stylesheets and other typical features of stylesheets such as media-type definition.
Referential integrity is a nice addition to Web Content Management. It allows users to view content being referenced from other content. It also provides the user with a choice when deleting a content item that is referenced by another content item. This is a big change from earlier releases, where deleting a reference content item left broken links.
There are many more enhancements to Web Content Management, including better
Personalization and Document Manager integration, improved rendering performance, clustering and failover, and so on. For more recommendations about updating the old Web
Content to take advantage of the new Workplace Web Content Management features, refer to the IBM WebSphere Portal Version 6.0 Information Center to utilize the new features of
Workplace Web Content Management: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en
t.doc/wcm/wcm_migration_post.html
This section provides information about primary and secondary Web Content migrations.
Note: This section can be disregarded if only one instance of WebSphere Portal with Web
Content Management is to be migrated.
A primary Web Content Management migration is the first instance to be migrated. It consists of all the steps in Web Content Management migration. If subsequent WebSphere Portal instances require migration, and these instances contain pages with Web Content
Management portlets, then other techniques are required to migrate Web Content
Management on these systems. These subsequent migrations are referred to as secondary migrations.
The data within the Web Content Management repository requires migration. In a secondary migration, this is typically accomplished by replicating the data from the primary instance to the secondary, with syndication. Syndication ensures that the identity of each piece of content is consistent across each syndicated repository. The alternative to syndication is replicating the database containing the JCR, using database-specific techniques. Consult your
Database Administrator (DBA) if you are interested in a database-specific replication.
Web Content Management user data is normally migrated using the wcmmigrate users
command, as shown in 5.3.5, “Migrating the Workplace Web Content Management user data” on page 95. This also works in a secondary migration. However, the summary data from the
primary migration is required. The summary data is located in a directory on the primary system. This data must be copied to the local machine, and then the migration tool on the local machine must be configured to ensure that it correctly identifies the summary data. After this procedure is completed, the wcmmigrate users command functions according to that
described in 5.3.5, “Migrating the Workplace Web Content Management user data” on page 95.
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 101

To copy the summary data, use the following procedure:
1. Open migration.properties on the primary system, and find the summary.path property.
2. Copy the data in the directory referred to by the summary.path property from the primary machine to the local (secondary) machine.
3. Open migration.properties on the local machine, and edit the summary.path property to refer to the copied summary data.
Web Content Management rendering portlets must be reconfigured. Perform this task by using the wcmmigrate configure-local and configure-remote commands, as long as the summary data is available. In the River Bend example, the commands behaved as described
in 5.3.6, “Migrating the Workplace Web Content Management rendering portlets” on page 97.
The alternative to using the wcmmigrate commands is to reconfigure the rendering portlets manually.
Run the following command to remove the Workplace Web Content Management migration tool: remove-wcm-migration
102 Best Practices for Migrating to IBM WebSphere Portal V6

A
Appendix A.
This appendix provides troubleshooting and other information relevant to the migration process.
© Copyright IBM Corp. 2007. All rights reserved.
103

Table A-1 shows the business portlets that are
not
migrated during portal migration.
Table A-1 Business portlets not migrated during portal migration
Common name Unique identifier (UID)
WebSphere Portal content publishing (WPCP) DCE:2b5645f0-0526-1211-0000-03703b72fbc4:1
Portal document management
Business Object Struts Application com.ibm.wps.portlets.pdm
PortletApplication_com.ibm.wps.portlets.busi
nessobject com.ibm.workplace.universalsearch.portal
Search Center Portlet Application
Lotus Collaboration Center Welcome application com.lotus.epp.deppwelcome.DeppWelcome
Portlet.50450ef473
Document Picker Application
Manage Document Libraries
Search Admin Application
Welcome
򐂰 Domino Struts Template Application
򐂰 Domino Struts Data Document Viewer
򐂰 Domino Struts IFrame Document Viewer
Business Object Builder Portlets com.ibm.wps.portlets.docP* com.ibm.wps.portlets.mdl
PSE.c04954cae56800171f9b9847e0486da9
com.ibm.wps.portlets.welcome
PortletApplication_com.ibm.wps.portlets.bof_
domino_strut com.ibm.wps.portlets.bo
com.ibm.wps.portlets.manage* com.ibm.wps.portlets.install
Admin Portlets
Portlet Installer
IBM Internet Mail Box
Sample Portlets
򐂰 QuickplacePortlet
򐂰 Quickplace Launch Portlet com.ibm.wps.portlets.wpsmail.ea
sample10.portlets.4195
com.ibm.wps.portlets.quickplace.*
Note: uid="com.ibm.wps.portlets.quickplace.WpsQ
PController" does migrate to WPS6.0
com.ibm.wps.portlets.sametime.WpsSametime
Portlet
򐂰 Sametime® Portlet
򐂰 Sametime Launch Portlet
Quick E-mail
Click-to-Action (C2A) Samples
Tourist Application (Sample portlet)
Quick Appointment
Syndicated Content (WPCP)
C2AStrutsExample application
Financial Time Portlet com.lotus.quickEmail
com.ibm.wps.portlets.shippingc2a
DG.com.ibm.wps.coop.samples.5691.pp
DCE:7d2f4560-24da-1211-0000-005d70d3ce08:
1
DCE:b067c2c0-1eba-1211-0000-02884891a5dd:1
DCE:62b7a9f0-dc7f-1201-0000-005d32bb94e8:1 com.ft.level0.Demo.1234
104 Best Practices for Migrating to IBM WebSphere Portal V6

This section walks you through an example of how to temporarily remove the privileged user access to the portal by using the xmlaccess tool. In some WebSphere Portal documentation, this is referred to as putting the portal in read-only mode.
This is how customizations were set in the River Bend portal. It is a simple but brute force method. For large environments, an experienced Portal administrator might spend time optimizing the import file. Doing so decreases the time the import task takes to run, although the outcome is the same.
The steps omit common changes that may be required because of missing Web archive
(WAR) files in the installableApps directory because of predeployed applications.
Test this process in the staging environment before using in the production environment. The task must be run during some planned downtime of the portal. It causes a load on the server, and consequently, the changes made in step 1 and step 2 in the process described here will be lost:
1. Export the production WebSphere Portal server configuration using Export.xml in <portal
as shown in Example A-1.
Example: A-1 Exporting the production WebSphere Portal server configuration
<portal_server_root>\bin>xmlaccess -in ..\doc\xml-samples\Export.xml -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -out exportAllResults.xml
2. Back up the exportAllResults.xml. This backup can be used later to return the portal to its original configuration.
3. Using a text editor, find where the Privileged User is set for access to portal artifacts, as
shown in Example A-2.
Example: A-2 Finding where the Privileged User is set for access to portal artifacts
**They presumably will need user access added, unless all authenticated is used**
<access-control externalized="false" owner="undefined" private="false">
<role actionset="Privileged User" update="set">
<mapping subjectid="uid=davidbrent,cn=users,ou=global,dc=riverbend,dc=com" subjecttype="user" update="set"/>
</role>
</access-control>
4. Change the update parameter on the actionset and the mapping tags, as shown in
Example A-3.
Example: A-3 Changing the update parameter on the actionset and the mapping tags
<access-control externalized="false" owner="undefined" private="false">
<role actionset="Privileged User" update="remove">
<mapping subjectid="uid=dominic,cn=users,ou=global,dc=riverbend,dc=com" subjecttype="user" update="remove"/>
</role>
</access-control>
Appendix A. Troubleshooting and other tips 105

5. Depending on your environment, you may want to repeat this process for other types of user access that may allow customized pages. In our example, we worked on the basis
that it is safe to leave the additional access controls as they are, as shown in Example A-4.
Example: A-4 Leaving the additional access controls as they are in the River Bend example
<role actionset="Privileged User" update="set">
<role actionset="Administrator" update="set">
<role actionset="Manager" update="set">
<role actionset="Editor" update="set">
<role actionset="Delegator" update="set">
<role actionset="Security Administrator" update="set">
6. Save this modified file with a new name, for instance, privUsersRemoved.xml, and import
it back into the portal, as shown in Example A-5.
Example: A-5 Saving the modified file with a new name and importing it back into the portal
<portal_server_root>/bin xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -in privUsersRemoved.xml -out resultsOfPrivUserRemoval.xml
7. To return the WebSphere Portal server to its original configuration, run the backed up
export file, as shown in Example A-6.
Example: A-6 Running the backed up export file
<portal_server_root>/bin xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -in ExportAllBackUp.xml -out resultsOfPrivUserRemoval.xml
When pages are deleted from the WebSphere Portal server, removing them from the system completely can be a resource-intensive task. WebSphere Portal server allows administrators the facility to delay the complete clean-up of resources until a convenient time with low-user traffic. By default, resources are not removed completely initially. Instead, they are inactivated and removed from view. By default, the clean-up schedule is every Saturday at 8 p.m., but this is fully configurable.
In our example, when migrating to our WebSphere Portal V6 server, it was occasionally necessary to delete large numbers of resources. In our environment, this was primarily to observe the effect of rerunning the tasks, applying the xmlaccess scripts, and so on. Under these circumstances, it is a best practice to turn off the delayed clean-up. It must be reapplied in production.
In WebSphere Portal V5.1, the delayed clean-up is controlled by a properties files held on each node in the environment. In WebSphere Portal V6, these properties are managed by the
Deployment Manager cell. They can be updated by going through the WebSphere
Application Server admin console, or by updating a properties file on one of the nodes and
106 Best Practices for Migrating to IBM WebSphere Portal V6

running a task. Not all the properties than can be set exist in the Admin console. In such a situation, the default values are automatically used. In order to avoid adding them to the wrong place or misspelling them, it is a best practice to update properties through the update configuration task.
This following steps describe how to achieve this:
1. Use a text editor to open the DataStoreService.properties file under
<portal_server_root>\config\properties.
2. Uncomment the scheduler.cleanup.enabled property (by removing the # character) and change the value to false . Save and close the file.
3. Run <portal_server_root>\bin\WPSconfig update-properties.
4. If you are running WebSphere Portal in a cluster configuration, replicate your changes to the cluster.
5. Restart the WebSphere Portal server.
An immediate clean-up of the deleted WebSphere Portal server artifacts can be forced by using an xmlaccess command that uses the task.xml file from the xml-samples directory. This command can be configured to change the scheduling of the clean-up task. However, if it is
run as-is, it causes the clean-up to start immediately. Example A-7 shows the command we
ran within the River Bend environment.
Example: A-7 Forcing an immediate clean-up of the deleted WebSphere Portal artifacts in the River
Bend environment
<portal_server_root>\bin>xmlaccess.bat -url http://m51e.cam.itso.ibm.com:9081/wps/config -user wpsadmin -pwd wpsadmin -in
..\doc\xml-samples\Task.xml
Following is a list of the V5.1 admin portlets:
򐂰 portletWiring
򐂰 Portlet Manager
򐂰 Manage My Portlet Applications
򐂰 Manage My Portlets
򐂰 Manage Webservices
򐂰 Themes And Skins Manager
򐂰 Edit Layout
򐂰 Concrete Properties Portlet
򐂰 Manage Pages
򐂰 Organize Favorites
򐂰 FrequentUsers
򐂰 Welcome Portlet
򐂰 Credential Vault
򐂰 Global Settings
򐂰 Manage Markups
򐂰 Appearance
򐂰 Set Permissions
򐂰 Resource View
򐂰 User and Group Permissions
򐂰 Manage Users and Groups
Appendix A. Troubleshooting and other tips 107

򐂰 Enable Tracing
򐂰 Manage Clients
򐂰 Unique Names
򐂰 URL mapping
򐂰 Welcome to WebSphere Portal
򐂰 Information Portlet
򐂰 Web Clipping Editor
򐂰 Manage Collections
򐂰 Search
򐂰 Import XML
򐂰 Manage Virtual Portals
򐂰 Login Portlet
򐂰 Edit My Profile
򐂰 Manage Search Collections
򐂰 Manage Search and Browse
򐂰 Pending Search Collection Items
򐂰 Manage Seed List
򐂰 Search and Browse
Following is a list of the V6 admin portlets:
򐂰 portletWiring
򐂰 Portlet Manager
򐂰 Manage My Portlet Applications
򐂰 Manage My Portlets
򐂰 Manage Webservices
򐂰 Themes And Skins Manager
򐂰 Edit Layout
򐂰 Concrete Properties Portlet
򐂰 Manage Pages
򐂰 Organize Favorites
򐂰 Application Layout
򐂰 FrequentUsers
򐂰 Welcome Portlet
򐂰 Credential Vault
򐂰 Global Settings
򐂰 Manage Markups
򐂰 Appearance
򐂰 Set Permissions
򐂰 Resource View
򐂰 User and Group Permissions
򐂰 Policy Resource View
򐂰 Policy Editor
򐂰 Manage Users and Groups
򐂰 Enable Tracing
򐂰 Manage Clients
򐂰 Unique Names
򐂰 URL mapping
򐂰 Welcome to WebSphere Portal
򐂰 Information Portlet
򐂰 Web Clipping Editor
򐂰 Manage Collections
򐂰 Search
򐂰 Manage Document Libraries
108 Best Practices for Migrating to IBM WebSphere Portal V6

򐂰 Document Picker
򐂰 RSS Portlet
򐂰 Import XML
򐂰 Manage Virtual Portals
򐂰 Login Portlet
򐂰 Edit My Profile
򐂰 Manage Seed List
򐂰 Manage Search Admin Portlet
򐂰 Sitemap
򐂰 Search and Browse
򐂰 Content Palette
򐂰 Template Catalog Manager
򐂰 Parameters
򐂰 Properties portlet
򐂰 Roles portlet
򐂰 Community
򐂰 Application Catalog
򐂰 People Finder JSR168
Employees of the River Bend company must be able to search the Web site of another company called itsoco. Itsoco’s Web site uses basic authentication. The employees must also be able to search the River Bend Web site itself. Therefore, the employees have defined two search collections. These collections are used by the Search and Browse portlets.
To demonstrate the migration process, the itsoco search collection migration is described here.
Perform the following tasks:
1. Navigate to Portal Settings
→
Search Administration and select itsoco collection.
2. Click Import or Export.
3. Enter a fully qualified file name with .xml extension, and click Export (Figure A-1).
Attention: All the directories in the path must exist. They will not
be created by the export process.
Figure A-1 Exporting a collection
Successful export is indicated by the following message:
“Export index OK”
Appendix A. Troubleshooting and other tips 109

4. Copy this XML file to a directory of your choice on the WebSphere Portal V6 server.
Important: Do not
copy the collection directory.
At this point, search management has moved from its location in WebSphere Portal V5.1 server, and can now be found at Search Administration
→
Manage Search
→
Search
Collections.
To define the itsoco collection in WebSphere Portal, perform the following tasks:
1. Click New Collection. This displays the New Collection page (Figure A-2).
Figure A-2 The new collection page
2. Create an empty shell into which the exported itsoco collection can be imported. Some, but not all, parameters must match the values from the WebSphere Portal V5.1 server.
The parameters for defining a search collection are:
– Location of Collection
This is the directory where the collection will reside. This does not have to exist and it does not have to match the old location.
– Name of Collection
Fill this in with the collection name. This does not have to match the old setting.
– Description of Collection
This is optional. Fill this in with the collection description. The description can match the old setting, but does not have to.
110 Best Practices for Migrating to IBM WebSphere Portal V6

– Specify Collection Language
Select this to match the old setting.
– Select Categorizer
This is optional, and will be overwritten by the import.
– Select Summarizer
This is optional, and will be overwritten by the import.
– Remove common words such as “in”, “of”, “on”, and so on from queries
Check or uncheck this to match the old setting.
Figure A-3 shows the itsoco search collection redefined for the WebSphere Portal V6
server. Click OK.
Important: Do not
create collection sources. They will be created by the import. The import will fail if a collection source is defined.
Figure A-3 The itsoco collection defined
Appendix A. Troubleshooting and other tips 111

3. The Manage Search window opens (Figure A-4). In this window, click the icon (highlighted in Figure A-4) for Import or Export collection. This is the file exported and copied to the
WebSphere Portal V6 server, as described in “Exporting the collection from WebSphere
Portal V5.1 server” on page 109.
Figure A-4 Readying to import the itsoco collection
4. Enter a fully qualified name of the exported XML file, as shown in Figure A-5. (There is no
facility to browse to find the location of the XMLM file.) Click Import.
Restriction: You cannot import into a collection that has already been populated. The import command will show an error message. If you have to reimport, delete and re-create the collection.
Figure A-5 Specifying the location of the XML file for import
112 Best Practices for Migrating to IBM WebSphere Portal V6

This returns you to the Manage Search page with a message confirming successful
import, as shown in Figure A-6. Note that the number of documents shows “0” at this
point.
Figure A-6 Import successful
5. At this point, WebSphere Portal fetches the documents from the migrated URLs and
rendexes them in the background. When you click Refresh, as displayed in Figure A-7,
the number of active documents increases. You can now browse the documents.
Figure A-7 Document count refreshed
Appendix A. Troubleshooting and other tips 113

The itsoco Web site uses basic authentication. The values entered in WebSphere Portal
V5.1 server for the itsoco collection has migrated automatically, as can be seen from
Figure A-8.
Figure A-8 Security has migrated
Restriction: When you import a portal site collection from WebSphere Portal V5.1 server to WebSphere Portal V6 server, the collection configuration data is imported, but not the document URLs. Therefore, to enable users to search the portal site collection on the target portal, you can either import the portal site collection and then manually start a crawl, or re-create the portal site.
114 Best Practices for Migrating to IBM WebSphere Portal V6

6. If you have a Portal Search Collection for your own Portal site and have moved to a new server, the host name in the URL for the site would probably have changed. In such a situation, you must re-create the content source from the scratch. If the collection does not work after migration, as happened in one of the tests in our example, it is recommended that you verify the address of the content source. This will test to see if the search engine is able to connect to the site being searched. Navigate to Manage Search
→
Search
Collections and click the itsoco collection.
7. This displays the window shown in Figure A-9. Click the wrench icon highlighted in
Figure A-9 to verify the address.
Figure A-9 Verifying the address of the content source
8. The results are displayed, as shown in Figure A-10. In our example, we saw the following
message:
EJPJP0011W: Connection failed, Host: http://9.33.85.117/itsoco/index.html, Host might be down.
Appendix A. Troubleshooting and other tips 115

Use a browser from your workstation to see if there are any issues with the itsoco site. In our case, we found that the itsoco server was not running. After it was restarted, we repeated the address verification in WebSphere Portal server and received the following message:
EJPJB0025I: Content source http://9.33.85.117/itsoco/index.html in collection itsoco collection is OK.
Figure A-10 Connection failed
116 Best Practices for Migrating to IBM WebSphere Portal V6

9. Click the icon highlighted in Figure A-11 to refresh the collection data for the itsoco
collection.
Figure A-11 Refreshing collection data for itsoco collection
10.Click OK to dismiss the pop-up warning about CPU usage and, shortly afterwards, refresh the page. In our case, we saw that the documents had been collected, as shown in
Figure A-7 on page 113.
Appendix A. Troubleshooting and other tips 117

118 Best Practices for Migrating to IBM WebSphere Portal V6

B
Appendix B.
The WebSphere Portal migration framework is designed to be extended. The example information in this appendix provides guidance about extending the migration framework.
There are two types of extensions, core migration extensions and a migration framework extension. Core migration extensions are currently limited to the core migration tasks.
However, the migration framework extension is not limited and can be used to implement any custom migration process. The most common reason for extending the framework is to provide custom filtering or transformation of the data to be migrated.
Following are the topics discussed in this appendix:
򐂰
“Overview” on page 120
򐂰
“Framework extensions” on page 120
򐂰
“Plugging into the framework” on page 122
򐂰
“Migration filters” on page 125
– Component Directory
– Required Files
򐂰
“Creating the River Bend migration sample plug-in” on page 127
© Copyright IBM Corp. 2007. All rights reserved.
119

This appendix describes how to plug into the migration framework, the ways in which your tasks can get called, and the exit points provided by the framework.
The migration framework consists of a shell script, WPmigrate, which sets up the class paths and executes tasks.
Components are plugged into the framework by defining Ant tasks in a mig_ant.xml file and exporting them by specifying the exported targets in the mig_description.xml file.
The mig_description.xml file is processed by the migration preprocessor to dynamically create an Ant build file called mig_ant_driver.xml. The exported tasks are placed in the mig_ant_driver.xml file and are called by the user or by the core migration framework.
The tasks that can be called are provided by the migration components. There is one migration component that is special, the wp.migration.core component. This component contains the high-level tasks for exporting information from the previous portal and importing the data into the current portal. The core tasks implement the migration framework and call the pluggable custom migration tasks that provide the logic required by various components to transform the previous portal data into a format that can be accepted by the current portal.
The framework allows for a seamless and simplified migration flow for the user.
The framework supports five extension points. These extension points are in the core migration component and are called the core migration extensions
. Four of these points allow components to seamlessly integrate into the base core migration targets. Components can specify which targets are to be called by each extension point, by setting various attributes when their targets are exported. The same target can be called once or multiple times by the framework.
The fifth extension point is in the overall framework itself, and is called the migration framework extension
. The migration framework extension point allows components to plug in and provide command-line accessible targets to the user. These targets can do anything that is required by the component and are not
dependent on the core migration tasks. The
Document Manager and Personalization component migration use the migration framework extension point by providing command-line callable targets to migrate the Java Content
Repository (JCR) data.
Following are the four core migration extensions:
򐂰 Pre-export
򐂰 Filter
򐂰 Preimport
򐂰 Postexport
The pre-export extension is called prior to exporting the previous portal's data. It must be used to export a subset of information to possibly determine if there is a component configured on the previous portal that is not configured on the current portal. This gives a component a chance to halt the migration before the export process begins, allowing the user
120 Best Practices for Migrating to IBM WebSphere Portal V6

to correct any configuration problems in the current portal. (In future releases, this task might be used to remotely collect specific property files, properties, or other data to allow the detection of configured components and possibly allow automated configuration on the current portal.)
The filter extension is called prior to the preimport task. This extension allows each component the opportunity to modify the XmlAccess import Extensible Markup Language
(XML) file or prepare any template files for import. No actual import must be performed during the execution of the filter extensions. There are some existing filtering tools that allow elements that have object IDs to be filtered, based on attributes. Components will use this target to modify the XmlAccess import file when there are changes to portlets, such as portlets moving from the IBM application programming interface (API) to JSR 168, changes in settings, changes in Web archive (WAR) file names, changes in configuration properties, or modifications to Web applications , such as the addition or removal of servlets or portlets. The main purpose of this task is to allow the components to transform their specific portlet data in the XmlAccess import file from a earlier version of the Portal into something that is consumable by the current version of the Portal and its portlets.
The preimport extension is called prior to the core migration import task. Components must use this extension to set up portal artifacts that must be available during the core import. An example of this would be if a component wanted to filter out its Web applications, but not the pages where the portlets are located during the filter phase, they can deploy the correct Web app with the proper object ID references for the pages. This will result in their ability to possibly perform a dynamic transformation of their application, for instance, going from the
IBM portlet API to JSR 168 in a more simplified manner than processing the entire
XmlAccess import file.
The postimport extension is called after the core migration import task. This task can be used to verify whether artifacts have been deployed properly, clear artifacts that are not required, or perform additional configuration, such as updating property files.
The migration framework extension is the simplest extension. It simply allows a target to be called from the command line by the user using the WPmigrate script. This extension must be used if there is some migration that is independent of the core migration. The JCR migration, for example, uses the migration framework extension to provide user-callable targets. This extension point must be used when there is an application that requires migration or transformation of external resources such as a database, and is not tied to the migration of a core portal artifact.
Appendix B. Extending the WebSphere Portal migration framework 121

To plug in to the migration framework, create a component directory in the
<wp_root>/migration/components, as shown in Figure B-1.
Figure B-1 Component directory
122 Best Practices for Migrating to IBM WebSphere Portal V6

Each component directory must contain the two files displayed in Figure B-2:
򐂰 mig_ant.xml
This is the file that contains the actual Ant tasks to be executed.
򐂰 mig_description.xml
This is the file that describes the exported Ant tasks.
Figure B-2 Required files
The mig_ant.xml contains custom Ant targets that the component will provide that can be called by the framework. Any number of targets can be included in this file. However, the callable targets are exported by the task definitions contained in the mig_description.xml file.
Several useful Ant variables are made available to the plug-in. Following is a list of these Ant variables:
򐂰 ${CollectorDir}
The directory where the information in the collectorOutput.zip file has been extracted to
򐂰 ${PrevWpsHostName}
The previous portal’s host name
򐂰 ${PrevWpsPort}
The previous Portal’s port value
Appendix B. Extending the WebSphere Portal migration framework 123

򐂰 ${PrevWpsContextRoot}
The previous Portal’s context root
򐂰 ${PrevPortalAdminId}
The previous Portal’s admin ID
򐂰 ${PrevPortalAdminPwd}
The previous Portal’s admin password
򐂰 ${VirtualPortal}
The name of the virtual portal. An empty string if working with the default Portal.
򐂰 ${WORK_DIR}
The work directory for the current migration process
򐂰 ${importAllFile}
The import file that is modified by the filter extension points
The mig_description.xml file contains a <tasks> element that must contain one or more nested <task> elements. Each nested <task> element describes a target that is to be exported and how and when it is called. It also provides a short help description to be optionally displayed for each target.
The <tasks> element does not support any required or optional attributes. However, it must
contain nested <task> elements, as displayed in Figure B-3.
Figure B-3 Task elements
124 Best Practices for Migrating to IBM WebSphere Portal V6

What follows is an example of how to extend the migration framework. Our example assumes that we have a specific set of pages that must be removed. This can be done by customizing the default filters, but to be safer, we created our own plug-in and used the existing filter infrastructure.
In our example, we constructed a filter to remove all the pages with a unique name starting with "riverbend.admin". Note that the pages are not
going to be removed from the previous server, they will simply be filtered from the exported XmlAccess file before we attempt to import the file into the current server.
We created a River Bend filter directory in the <wp_root>/migration/component directory by executing the following command: mkdir -p <wp_root>/migration/component
In this command, <wp_root> is the portal installation root directory.
Using a text editor, we created the mig_ant.xml and the mig_description.xml file in the
<wp_root>/migration/components/riverbend directory. We constructed an Ant task to be called during the filter phase of the migration.
Migration filters can be created to remove pages, portlets, themes, skins, or any other artifact that has an object ID and a uniquely identifiable attribute. A filter file is a properties file that contains a filters property that defines the active filters and one or more filter definitions.
In our River Bend example, we wanted to filter the pages and the child pages that have a unique name starting with "riverbend.custom.page".
When creating a filter, we used the template shown in Example B-1.
Example: B-1 Filter template
# This properties files defines a list of filters used to process the Portal data export.
# The property "filters" defines the prefix for each filter
#
# Usage of each filter: filters=<filterX>,<filterY>
<filterX>.object: xmlaccess object ID. Examples: "client", "web-app",
"content-node". Required.
<filterX>.include: Optional comma-separated list of patterns to include. If any are specified, only these will be used. Overrides excludes.
<filterX>.exclude: Optional comma-separated list of patterns to exclude.
<filterX>.searchAttr: Filtering will be applied to this attribute. If no filtering, can list any attribute type. Required.
<filterX>.requestAttr: The attribute to use to request the object the next time.
Required.
<filterX>.secondaryAttr: Optional comma-separated list of secondary filters. For example, create-type=implicit.
Appendix B. Extending the WebSphere Portal migration framework 125

The filters property indicates which filters will be used during the filtering process.
Each filter, which is required to have a name, has six attributes associated with it. The attributes are affixed to the filter name in the format ".<attribute>", where the valid attributes are:
򐂰 object
The xmlaccess element ID. Examples include "client", "web-app", "content-node".
򐂰 include
The optional comma-separated list of patterns to include. If any are specified, only these will be used. It overrides exclude.
򐂰 exclude
The optional comma-separated list of patterns to exclude.
򐂰 searchAttr
Filtering will be applied to this attribute. If there is no filtering, can list any attribute type.
Required.
򐂰 requestAttr
The attribute used to request the object the next time. Must always be objectid. Required.
򐂰 secondaryAttr
The optional comma-separated list of secondary filters. Examples include
“create-type=implicit”.
Example B-2 shows what the contents of our filter file, RiverBendPageFilter.properties, look
like after we copied the template and made the appropriate updates. The include and exclude attributes allow a regular expression to specified.
Example: B-2 Filter file
# This properties files defines a list of filters used to process the Portal data export.
# The property "filters" defines the prefix for each filter
#
# Usage of each filter:
# <filter>.object: xmlaccess object ID. Examples: "client", "web-app",
"content-node". Required.
# <filter>.include: Optional comma-separated list of patterns to include. If any are specified, only these will be used. Overrides excludes.
# <filter>.exclude: Optional comma-separated list of patterns to exclude. Same as defaultExclude but these are easier to update by end-users
# <filter>.searchAttr: Filtering will be applied to this attribute. If no filtering, can list any attribute type. Required.
# <filter>.requestAttr: The attribute to use to request the object the next time.
For example, might want to filter by uid but request by objectid. Required.
# <filter>.secondaryAttr: Optional comma-separated list of secondary filters.
For example, create-type=implicit.
# filters=riverbend-page-filter riverbend-page-filter.object=content-node riverbend-page-filter.include=
126 Best Practices for Migrating to IBM WebSphere Portal V6

riverbend-page-filter.exclude=riverbend.custom.page* riverbend-page-filter.searchAttr=uniquename riverbend-page-filter.requestAttr=objectid riverbend-page-filter.secondaryAttr=
We saved this file into our River Bend plug-in directory.
The mig_ant.xml for the River Bend component contains two targets. However, only one target will be called by the framework.
Note that when creating customized targets, they must be globally unique across the migration framework. To make them unique, append a component ID to the target name, for
example, filter-pages.com.riverbend, as shown in Example B-3.
Example: B-3 Sample mig_ant.xml
<!--
Licensed Materials - Property of IBM
5724-E76, 5724-E77, 5655-M44
(C) Copyright IBM Corp. 2001, 2006 All Rights Reserved.
Sample mig_ane.xml for red paper Riverbend
-->
<project name="wp.migration.wcm" default="filter-pages.com.riverbend" basedir=".">
<property name="portal.migration.dir" value="${basedir}/../.."/>
<property name="RiverBendWorkDir" value="${WORK_DIR}/riverbend"/>
<property name="InstalledWcmComponentDir" value="${portal.migration.dir}/components/wcm.migration" />
<property name="InstalledWcmMigAntFile" value="${InstalledWcmComponentDir}/mig_ant.xml"/>
<property name="RiverBendFilteredImportFile" value="${RiverBendWorkDir}/RiverBendFilteredImportAll.xml"/>
<property name="OidsOfRiverBendPagesToRemoveFile" value="${RiverBendWorkDir}/OidsOfRiverBendPagesToRemove.oid"/>
<property name="RiverBendFilterFile" value="${basedir}/RiverBendPageFilter.properties"/>
<!--
Create a Riverbend "work" directory
The Riverbend work directory will be used to hold temporary files created by this plug-in
the directory will be located in the following location
<wp_root>/migration/work/<portal_name>/riverbend
-->
<target name="init">
<mkdir dir="${RiverBendWorkDir}"/>
</target>
Appendix B. Extending the WebSphere Portal migration framework 127

<target name="filter-pages.com.riverbend" depends="init" unless="DoNotFilterRiverBendPages">
<!--
Filtering is a two step process. The first step scans the importAll.xml file for
object ID's that match the search filters. The object ID's are written to a file
specified by the attribute outfile.
The second step reads in the list of object ID's created by the fullExportFilter task
then it filters out each object that has a matching object ID found in the list. All
artifacts that have referential dependencies on a filtered object are also filtered.
For instance, if the page hierarchy is such that page A has child pages B and C if page A
is filtered, pages B and C are also removed.
The writeFilteredFile task will create a copy of the importAll.xml file with the
artifacts matching the object ID's in the file specified by the oidfile attribute removed.
-->
<fullExportFilter
infile="${importAllFile}"
outfile="${OidsOfRiverBendPagesToRemoveFile}"
inputproperties="${RiverBendFilterFile}"/>
<writeFilteredFile
oidfile="${OidsOfRiverBendPagesToRemoveFile}"
infile="${importAllFile}"
outfile="${RiverBendFilteredImportFile}"
checkparent="true" />
<!-- We need to replace the importAll.xml file with the one modified by this plug-in -->
<copy file="${RiverBendFilteredImportFile}" tofile="${importAllFile}" overwrite="true"/>
</target>
</project>
The mig_description.xml describes the targets available to be executed and defines when they will be called. The contents of the River Bend mig_description.xml are shown in
Example B-4.
Example: B-4 Sample mig_description.xml
<!--
Licensed Materials - Property of IBM
5724-E76, 5724-E77, 5655-M44
(C) Copyright IBM Corp. 2001, 2006 All Rights Reserved.
Riverbend mig_description.xml plug-in sample
128 Best Practices for Migrating to IBM WebSphere Portal V6

-->
<tasks>
<task name="filter-pages.com.riverbend" isxmltarget="true" nohelp="true" inall="false" dependencies="">
This task is responsible for filtering out pages from our Riverbend sample site,
</task>
</tasks>
The only task exported is "filter-pages.com.riverbend". It has the following attributes set:
򐂰 isxmltarget ="true"
This means that it gets executed during the filter phase of the import process.
򐂰 inall="false"
The target is not callable from the command line and is only called as part of the import-portal-content command processing.
򐂰 nohelp="true"
The target will not show up when help is displayed.
򐂰 dependencies=""
No dependencies
When running the migration with the sample component described earlier, all the pages in our
WebSphere Portal V5.1 server had a custom unique name that matched the string
“riverbend.custom.page”.
Appendix B. Extending the WebSphere Portal migration framework 129

130 Best Practices for Migrating to IBM WebSphere Portal V6

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this IBM Redpaper.
The following Web sites are relevant as further information sources:
򐂰 Explanation of limited support for using IBM WebSphere Portal V6.0 with IBM Rational
Application Developer 6.0
http://www-1.ibm.com/support/docview.wss?uid=swg27008730&aid=1
򐂰 IBM WebSphere Portal Version 6.0 Information Center
– Migrating the remaining access control configuration http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/sec_mig_roles.html
– Supported hardware and software for IBM WebSphere Portal Version 6.0
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/inst_req60.html
– Migrating business process applications http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wps/bpi_mig.html
– Migrating cooperative portlets that use IBM Portlet API http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/mig_coop_portlet.html
– Migrating portlets built with Struts Portlet Framework http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/mig_struts.html
– XML configuration interface: reference http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wps/adxmlref.html
– Portal configuration services http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wps/srvcfgref.html
– Verifying the migration tasks http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/mig_verify.html
– Troubleshooting migration http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wpf/mig_tbl.html
131 © Copyright IBM Corp. 2007. All rights reserved.

– Migrating user profiles http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wcm/wcm_migration_users.html
– Postmigration steps http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm
.wp.ent.doc/wcm/wcm_migration_post.html
򐂰 Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2 http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
򐂰 Open Logic http://www.openlogic.co.uk/
򐂰 Technote: Domino Application Portlet for Portal v5.x does not work on Portal v6 http://www-1.ibm.com/support/docview.wss?rs=899&uid=swg21245417
򐂰 WebSphere Portal Update Installer http://www-1.ibm.com/support/docview.wss?rs=688&uid=swg24006942
򐂰 White paper: IBM WebSphere Portal Version V6.0 Tuning Guide http://www-1.ibm.com/support/docview.wss?uid=swg27008511&aid=1
You can search for, view, or download IBM Redbooks, IBM Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy IBM Redbooks or CD-ROMs, at this Web site:
ibm.com/redbooks
IBM Support and downloads
ibm.com/support
IBM Global Services
ibm.com/services
132 Best Practices for Migrating to IBM WebSphere Portal V6

®
Red
This IBM Redpaper provides detailed information about migrating from
IBM WebSphere Portal V5.1 to IBM WebSphere Portal V6. This IBM
Redpaper introduces the key considerations and the overall decision process before providing step-by-step instructions. It also provides a troubleshooting guide. This IBM Redpaper covers all the key concepts, from stand-alone core portal environments to comprehensive enterprise deployments with clustering, IBM WebSphere Portal components such as Document Manager, Personalization, IBM
Workplace Web Content Management, and others.
Whether you are a Line-of-Business Manager looking for overall information about migration, an IT Architect planning a migration, or an
Administrator who has to perform the actual migration, this IBM
Redpaper is for you.