redp4227

ibm.com/redbooks Redpaper
Front cover
IBM WebSphere Portal
V6: Best Practices for
Migrating from V5.1
Philip Monson
Brian Cheng
Frederic Delos
Dominic Glennie
Rob Holt
Misao Ishikawa
Simon McNab
William Trotman
Provides comprehensive
step-by-step guidelines
Describes enterprise
considerations
Includes troubleshooting
guide and tips

International Technical Support Organization
Best Practices for Migrating to IBM WebSphere Portal
V6
February 2007

© 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.
First Edition (February 2007)
This edition applies to IBM WebSphere Portal V5.1 and IBM WebSphere Portal V6.
Note: Before using this information and the product it supports, read the information in “Notices” on
page vii.

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

iv Best Practices for Migrating to IBM WebSphere Portal V6
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

Contents v
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

vi Best Practices for Migrating to IBM WebSphere Portal V6

© Copyright IBM Corp. 2007. All rights reserved. vii
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not give you any license to these patents. You can send license inquiries, in
writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time
without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring
any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which 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.

viii Best Practices for Migrating to IBM WebSphere Portal V6
Trademarks
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.

© Copyright IBM Corp. 2007. All rights reserved. ix
Preface
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.
The team that wrote this IBM Redpaper
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

x Best Practices for Migrating to IBM WebSphere Portal V6
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
Become a published author
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

Preface xi
Comments welcome
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

xii Best Practices for Migrating to IBM WebSphere Portal V6

© Copyright IBM Corp. 2007. All rights reserved. 1
Chapter 1. Getting started: WebSphere
Portal migration from V5.1 to V6
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
1

2 Best Practices for Migrating to IBM WebSphere Portal V6
1.1 Introduction
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.
1.1.1 Understanding WebSphere Portal migration
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

Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6 3
Portal resources
Workplace Web Content Manager content and components
Document Manager content
Personalization rules
Credential vault slots
1.1.2 Migration versus upgrade
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.
1.1.3 Reasons for migrating
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

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
1.2 High-level overview of WebSphere Portal migration
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).
Figure 1-2 Migration overview
WebSphere Portal
Core Migration
Chapter 3
Portal Document
Manager
Chapter 4
WebSphere Portal
Personalization
Chapter 4
WebSphere Content
Manager
Chapter 5
Validate Server
Content
Do
you have
PDM?
Do
you have
PZN?
Do
you have
WCM?
NO
YES
YES
NO
YES
NO

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.
1.2.1 Premigration tasks
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.)
1.2.2 Core migration
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.
1.2.3 Document Manager and Personalization components
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.
1.2.4 Workplace Web Content Management components
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.

1.3 Planning
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
1.4 Considerations
This section explains some elements of the WebSphere Portal environment that must be
reviewed before starting the migration.
1.4.1 WebSphere Portal V6 environment
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

1.4.2 Custom portlets
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:
.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:
.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:
.ent.doc/wpf/mig_struts.html

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.
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.
1.4.3 External components
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.

1.4.4 Security
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:
.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.

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:
.ent.doc/wpf/sec_mig_roles.html
Check the following migration fix download page for information about future fixes for
credential vault migration:
1.4.5 Noncustom portlets
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.

1.4.6 Administration portlets
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.
1.4.7 Search indexes
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.
1.4.8 Virtual portals
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.
1.4.9 Themes and skins
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.
1.4.10 Uniform Resource Locator mappings
Uniform Resource Locator (URL) mappings to pages that are filtered out during the migration
must be re-created after the migration.
1.4.11 WebSphere Application Server artifacts
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.
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.
Important: Do not use the WebSphere Application Server migration tasks. These are not
required and will cause failures.

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.
1.4.12 Performance
If your system has had performance problems in the past, it is recommended that you review
the WebSphere Portal V6 Tuning Guide.
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.
1.5 Migration checklist
Before starting the migration, several tasks must be performed to prepare the WebSphere
Portal V5.1 and WebSphere Portal V6 environments.
1.5.1 Steps to prepare your WebSphere Portal V6 environment for migration
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:
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.

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:
1.5.2 Steps to prepare your WebSphere Portal V5.1 environment for migration
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:
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>migrationfixes 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:
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 2. Considerations for migrating
enterprise environments
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

2.1 Migration approach between clusters
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.
2.1.1 The WebSphere Portal V5.1 server environment
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.
2.1.2 The WebSphere Portal V6 server environment
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.
Unmanaged node
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
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.

Chapter 2. Considerations for migrating enterprise environments 17
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
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.
Managed node
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.
2.1.3 Environment considerations
This section provides information about the various environment considerations.
Hypertext Transfer Protocol Server 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.
External database
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.
Same physical server migration
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.
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.
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.
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.

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.
Performance considerations
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:
2.2 Maintaining customizations during migration
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.
2.2.1 Core WebSphere Portal customizations
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.
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.
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.

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.
Halting customizations in production
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.
Updating portal configuration changes
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.
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.
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.

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

<portal action="locate">
<content-node action="export" uniquename="wps.test1" export-descendants="true"/>
</portal>
</request>
2.2.2 Content changes
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.
Updating Document Manager 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.
Updating Personalization artifacts
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.
Updating Workplace Web Content Management content
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
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.
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.

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

Chapter 3. Migration of core components
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.
At a glance
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.
3
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.

3.1 Collecting data from the WebSphere Portal V5.1
environment
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.
3.1.1 The Property Collector
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.
The Collector output file is written to
<portal_server_root>configincludespropcollectorOutput.zip.
Like all WPSconfig tasks, this logs to <portal_server_root>logConfigTrace.log.
3.1.2 Installing the Property Collector
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>migrationpropcollector.jar
<portal_server_root>migrationpropcollector.xml
Copy these to <portal_server_root>configincludes on your WebSphere Portal V5.1 server.
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.

Chapter 3. Migration of core components 25
3.1.3 Running the Property Collector on WebSphere Portal V5.1
This section describes how to run the Property Collector on WebSphere Portal V5.1.
Neither WebSphere Portal V5.1 nor WebSphere Portal V6 is required to be running at this
time.
Running the Property Collector
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
Validation
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.
Troubleshooting
If the Collector does not run successfully, check the output from the command and the
ConfigTrace.log.
Rerun
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.
Tip: If you are migrating from a cluster, the Property Collector can be run on any cluster
member.
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.
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:tmpcollector.zip.
All the directories in the path must exist.

3.2 Copying data to WebSphere Portal V6 server
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.
3.2.1 Copying the Property Collector output file 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>migrationpropcollectorOutput.zip on your
3.2.2 Collecting Web archive files for custom portlets and copying to
WebSphere Portal V6 server
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
3.3 Migrating your portal using the WPmigrate command-line
tool
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.
At a glance
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>logMigrationTrace.log.
Tip: It is worth ensuring that the Collector output file on the WebSphere Portal V6 server is
readable after being copied.
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 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.
3.3.1 Extracting the data from the Property Collector output file
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>migrationworkcollector. 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.
Entering the command
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.
Virtual portals
No actions are required for virtual portals at this time.
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.
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>

Validation
Successful completion is indicated by the following message:
BUILD SUCCESSFUL
You can also inspect the contents of <portal_server_root>migrationworkcollector to ensure
that the contents are readable.
Troubleshooting
If you do not get a BUILD SUCCESSFUL message, examine the messages that are created and
review <portal_server_root>logMigrationTrace.log to find out the cause.
Rerun
This can be rerun at any time. Note that it will overwrite its output files without warning.
3.3.2 Exporting the configuration from WebSphere Portal V5.1 server
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>migrationworkdefault. Directories are
created if they do not already exist. For each virtual portal, they are created in
<portal_server_root>migrationworkvp-<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
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.
File name Purpose
allout.xml xmlaccess export
testexport.xml Result of a command to test connectivity. If the
test fails, there will be messages here to help
diagnose the issue.
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.

Entering the command
Enter the following command:
<portal_server_root>migrationWPmigrate.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
Virtual portals
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
Figure 3-1 Virtual Portal Manager showing URL context
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>migrationworkcollectorwpconfig.properties.
Important: The context extension is displayed in the column URL Context in the Virtual
Portal Manager, as highlighted in Figure 3-1.

Validation
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.
Troubleshooting
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:WebSpherePortalServermigrationworkdefaulttestexport.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:WebSpherePortalServermigrationwork
defaulttestexport.xml.
[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai
ls of the XmlAccess error look at file C:WebSpherePortalServermigrationwork
defaulttestexport.xml.
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.

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:WebSpherePortalServermigrationworkdefau
lttestexport.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:WebSpherePortalServermigrationworkdefaultallout.xml.
[xmlaccess] EJPXB0020I: The request was processed successfully on the server.
BUILD SUCCESSFUL
Total time: 41 seconds
We checked C:WebSpherePortalServermigrationworkdefaultallout.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">

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

3.3.3 Importing the configuration into WebSphere Portal V6 server
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.
This task writes a number of files when executing. For the default portal, they are written to
<portal_server_root>migrationworkdefault. The directories will be created if they do not
already exist. For each virtual portal, they are created in
<portal_server_root>migrationworkvp-<URL context>.
Table 3-2 describes the most important files:
Table 3-2 Files created by the import portal content task
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.
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.
File name Purpose
importAll.xml The final Extensible Markup Language (XML) file
used for the xmlaccess import
importAllResults.xml 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.

redp4227

Recommended

Recommended

More Related Content

What's hot

What's hot (16)

Similar to redp4227

Similar to redp4227 (20)

redp4227