Migracion - Best Practices

Front cover
IBM WebSphere Portal V6: Best Practices for Migrating from V5.1
Provides comprehensive step-by-step guidelines Describes enterprise considerations Includes troubleshooting guide and tips
Philip Monson Brian Cheng Frederic Delos Dominic Glennie Rob Holt Misao Ishikawa Simon McNab William Trotman
ibm.com/redbooks
Redpaper
International Technical Support Organization Best Practices for Migrating to IBM WebSphere Portal V6 February 2007
Note: Before using this information and the product it supports, read the information in Notices on page vii.
First Edition (February 2007) This edition applies to IBM WebSphere Portal V5.1 and IBM WebSphere Portal V6.
Copyright International Business Machines Corporation 2007. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
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 . . . . . . . . . . . . . . . 2.1 Migration approach between clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 The WebSphere Portal V5.1 server environment . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.2 The WebSphere Portal V6 server environment . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.3 Environment considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Maintaining customizations during migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 Core WebSphere Portal customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.2 Content changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3. Migration of core components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Collecting data from the WebSphere Portal V5.1 environment. . . . . . . . . . . . . . . . . . . 3.1.1 The Property Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2 Installing the Property Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 16 16 16 17 18 18 20 23 24 24 24 iii
Copyright IBM Corp. 2007. All rights reserved.
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 . . . . . . . . . . . . . . . . 4.1 The Document Transfer Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.1 Installing the Document Transfer Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.1.2 Validating the Document Transfer Tool installation. . . . . . . . . . . . . . . . . . . . . . . . 4.2 Migrating the Document Manager documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.1 Preparing a checklist for Document Manager validation. . . . . . . . . . . . . . . . . . . . 4.3 Synchronizing Document Manager global access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.1 Modifying the Document Manager properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.2 Creating directories for Document Manager migration . . . . . . . . . . . . . . . . . . . . . 4.3.3 Running the export task for Document Manager . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.4 Copying files to the WebSphere Portal V6 server. . . . . . . . . . . . . . . . . . . . . . . . . 4.3.5 Running the transform task for Document Manager . . . . . . . . . . . . . . . . . . . . . . . 4.3.6 Running the import task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.7 Validating the Document Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.8 Postmigration task for Document Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 Migrating Personalization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.1 Preparing a checklist for Personalization validation . . . . . . . . . . . . . . . . . . . . . . . 4.4.2 Custom resource collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.3 Modifying Personalization properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.4 Creating directories for Personalization migration . . . . . . . . . . . . . . . . . . . . . . . . 4.4.5 Running the export task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.6 Copying files to WebSphere Portal V6 server. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.7 Running the transform task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4.8 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 54 54 56 57 58 58 60 61 62 64 64 66 67 67 67 68 68 69 70 70 72 73 75
iv
Best Practices for Migrating to IBM WebSphere Portal V6
4.4.9 Migrating the Personalization cache configuration . . . . . . . . . . . . . . . . . . . . . . . . 75 4.4.10 Running the import task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 4.4.11 Validating your Personalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.5 Postmigration tasks for Document Manager and Personalization. . . . . . . . . . . . . . . . . 76 4.5.1 Removing passwords from the Document Manager and Personalization property files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.5.2 Uninstalling the Document Tracking Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 5.1 Migration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 5.2 Workplace Web Content Management migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 5.3 Premigration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 5.3.1 Copying folders from WebSphere Portal V5.1 server to WebSphere Portal V6 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 5.3.2 Preparing a checklist for Workplace Web Content Management validation . . . . . 87 5.3.3 Installing the Workplace Web Content Management migration tool . . . . . . . . . . . 88 5.3.4 Installing the authoring portlet to the Web Content Management page . . . . . . . . 94 5.3.5 Migrating the Workplace Web Content Management user data . . . . . . . . . . . . . . 95 5.3.6 Migrating the Workplace Web Content Management rendering portlets . . . . . . . 97 5.3.7 Postmigration tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Appendix A. Troubleshooting and other tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Business portlets not migrated during portal migration . . . . . . . . . . . . . . . . . . . . . . . . . . . Temporarily halting user customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delayed clean-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the delayed clean-up property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forcing immediate clean-up with xmlaccess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List of admin portlets in WebSphere Portal V5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List of admin portlets in WebSphere Portal V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migrating the search collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix B. Extending the WebSphere Portal migration framework . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Framework extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Core migration extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Plugging into the framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migration filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the River Bend migration sample plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 104 105 106 106 107 107 108 109 119 120 120 120 122 125 127 131 131 132 132
Contents
vi
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.
vii
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.
viii
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 Bachelors Degree in
ix
Electrical Engineering from North Carolina A&T State University in Greensboro, NC, and a Masters 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
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
Preface
xi
xii
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.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 Companys (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
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
Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6
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).
WebSphere Portal Core Migration Chapter 3
Do you have PDM?
NO
YES
Portal Document Manager Chapter 4
Do you have PZN?
NO
YES
WebSphere Portal Personalization Chapter 4
Do you have WCM?
NO
YES
WebSphere Content Manager Chapter 5
Validate Server Content
Figure 1-2 Migration overview
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: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wps/bpi_mig.html Click-to-Action and Cooperative Portlet For Click-to-Action (C2A)/Cooperative Portlets, the pbportlet.jar must be updated. Refer to the following Web site for more details: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/mig_coop_portlet.html Struts Portlet The steps for migration depend on the Struts Portlet Framework version that is being used by the application. Applications that package more recent versions of the Struts Portlet Framework may require no changes at all when migrating to the current version of WebSphere Portal. The following Web site provides additional information about migrating Struts Portlets: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/mig_struts.html
Java Server Faces Portlet Portlets developed by using the IBM API that use the Java Server Faces (JSF) framework will not work with WebSphere Portal V6 if they were developed using Rational Application Developer V6. The following Web site provides additional information about portlets developed using Rational Application Developer V6. http://www-1.ibm.com/support/docview.wss?uid=swg27008730&aid=1 Predeployed enterprise archive file Predeployed enterprise archive (EAR) files require the installation of fix PK32308. Download this fix and check the fixs 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: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/sec_mig_roles.html The instructions provided in the information center are specific for DB2. If you are using a database other than DB2, contact your database administrator to help determine the proper commands for your environment.
Credential vault The best method for migrating credential vault data is to use the Extensible Markup Language (XML) Configuration Interface, which requires the installation of an interim fix (PK28148) on both WebSphere Portal V5.1 and WebSphere Portal V6 environments. Alternatively, you can migrate your credential vault data using Structured Query Language (SQL) and direct database operations. The chapter Migrating credential vault data under the topic Migrating the remaining access control configuration in the IBM WebSphere Portal Version 6.0 Information Center provides the necessary information: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/sec_mig_roles.html Check the following migration fix download page for information about future fixes for credential vault migration: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927
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 portlets catalog entry. For portlets that are not supported by IBM, contact the software vendor for new releases and support. Portlets from vendors Check with the vendors whether any of the portlets that they have provided are certified for WebSphere Portal V6, and follow the specific migration steps, if any.
10
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. Important: Do not use the WebSphere Application Server migration tasks. These are not required and will cause failures. If you have made any changes to these configuration files in WebSphere Portal V5.1, you must verify whether the migration process has moved these across, and whether the values are applicable for the new WebSphere Portal V6 environment.
11
Following is a list of additional settings: Additional WebSphere Application Server settings Review any WebSphere Application Server settings that might have been made to your WebSphere Portal V5.1 and check the WebSphere Application Server Information Center to see how to make these settings in the version of WebSphere Application Server that is used by your WebSphere Portal V6 environment. Java virtual machine settings The Java virtual machine (JVM) heap size requirements have changed between WebSphere Portal V5.1 and WebSphere Portal V6. If the memory is available, the heap size must be increased on the WebSphere Portal V6 after the initial installation. After migration, the heap size must be tuned as part of performance testing.
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. http://www-1.ibm.com/support/docview.wss?uid=swg27008511&aid=1 As a best practice, perform a dry run of your migration and use it to test your application for performance issues before performing production migration.
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. 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.
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: http://www-1.ibm.com/support/docview.wss?rs=688&uid=swg24006942
12
7. Install all the required fixes before migration. Not all the migration fixes listed in the following Web site are required because some may be dependent on the additional components you expect to migrate: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927
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: http://www-1.ibm.com/support/docview.wss?rs=688&uid=swg24006942 6. Install all the required fixes before the migration. The WebSphere Portal V6 installation media contains the current required fixes for each of the supported versions of WebSphere Portal V5.0 and WebSphere Portal V5.1. These fixes are in the <portal_server_root>\migration\fixes directory of the WebSphere Portal V6 server. Find the directory for the version of WebSphere Portal server that matches the source environment and install these fixes. It is also recommended that you check the following Web site for any additional migration fixes that are required for the WebSphere Portal server version: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927 7. Run the validate database connection task on your previous environment to verify that the proper values are specified in the wpconfig.properties file because these values are required when running the migration tasks.
13
14
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
15
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 servers node agent and halting user traffic with a method appropriate to your environment. This may, for instance, involve editing out the source node from the Hypertext Transfer Protocol (HTTP) Server plug-in configuration file. Attention: Applying fixes to the isolated node may alter the shared portal configuration database. This can cause the other servers to be in an inconsistent state. The fixes mentioned in this IBM Redpaper must not cause a problem, although care must be taken if any additional fixes are applied. Ensure that any fixes that are applied to the isolated node are either applied to the rest of the cluster members or are removed before restarting the node agent.
Tip: All the WebSphere Portal servers within the cluster share the same portal configuration database. Even after being isolated from the deployment manager and user traffic, the source server has the potential to put a load on this database. Therefore, consideration must be given to when migration tasks are run so that the performance impact on the production environment is minimized.
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
16
Also refer the IBM Redbook WebSphere Portal 6 - Best Practices for Enterprise Scale Deployment, which is available in draft form on the Web at: http://www.redbooks.ibm.com/redpieces/abstracts/sg247387.html?Open Important: The standard installation process provides the choice of installing WebSphere Portal V6 with or without the WebSphere Process Server. If the node is to eventually become a part of a cluster, the installation must take place without the WebSphere Process Server. Otherwise, it will not be possible to create a cluster from it. Migrating to an unmanaged node allows the potentially complex task of clustering to be treated separately from the migration process. It also means the configuration of the primary node is kept if the node is ever removed from the cell. Tip: Because the WebSphere Portal V6 environment is built, take frequent backups of the files and the databases. Always take a backup just before federating the primary node into a cluster because errors often occur during this process.
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. 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.
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.
Chapter 2. Considerations for migrating enterprise environments
17
In many cases, there will not be enough resources to comfortably run both WebSphere Portal V5.1 server and WebSphere Portal V6 server at the same time. Doing so might cause resource contention issues, which in turn is likely to cause failures. The migration tasks do not require both the servers to be running. During the export tasks, only WebSphere Portal V5.1 server must be up. During the import tasks, only WebSphere Portal V6 server is used. As a result, the servers can share the same ports so long as they are not started at the same time.
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: http://www.ibm.com/support/docview.wss?rs=688&uid=swg27008511
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. Tip: If it is possible to update the WebSphere Portal V5.1 server staging environment with the latest user customizations from production, this staging environment can be used as the source for the migration. If user customizations are not allowed in production, the staging environment must have exactly the same configuration in the WebSphere Portal server database as in production. In this case, one of the servers within the staging environment must be used as the source for the core migration tasks. This eliminates unnecessary load on the live environment and produces the same result as using a production server. Any user customization that occurs between running the export portal content task and switching the new WebSphere Portal V6 server environment into production, is lost. There are four basic approaches to dealing with this: Migrate during downtime in the production environment. Accept losses in user customizations. Turn off customization in production for the duration of the migration process. Migrate the environment and export the pages that may have been customized from production, and import these into WebSphere Portal V6.0 server after migration. 18
These approaches are not mutually exclusive, and must be combined in a manner that is suitable to your environment. For complex environments, it is usually not possible to migrate an entire system and switch it into production during downtime. This section describes how these methods can be used. Note: WebSphere Portal V6 server allows user customizations to be stored in a separate database domain that can be shared between clusters. This functionality is likely to be utilized to ease the migration process between V6 and the next major WebSphere Portal release, by allowing the source servers and the target servers to share the same customization database.
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. 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.
19
In the River Bend environment, after migration, additional implicit pages were created by logging in as users and editing the parameters of a portlet. The page and its child-implicit pages with the unique name wps.test1 were exported using the script shown in Example 2-1.
Example 2-1 Sample xmlaccess script for reimporting a page and all the child-implicit pages
<?xml version="1.0" encoding="UTF-8"?> <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PortalConfig_1.3.xsd" type="export">  <portal action="locate"> <content-node action="export" uniquename="wps.test1" export-descendants="true"/> </portal> </request>
Tip: For the implicit private pages to be exported, the export-descendents parameter of the content node in the xmlaccess request must be set to true.
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. 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.
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 20
Attention: At the time of writing this IBM Redpaper, Workplace Web Content Management libraries could not be deleted from our example River Bend environment on WebSphere Portal V6. Check with IBM support for a fix. Refer to Chapter 5, Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management on page 77, for details about running the Workplace Web Content Management migration tasks.
21
22
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. 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.
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.
23
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. Attention: Ensure that WpsHostName in wpconfig.properties on the WebSphere Portal V5.1 server is correctly set to a fully qualified host name, and not localhost. The Collector output file is written to <portal_server_root>\config\includes\propcollectorOutput.zip. Like all WPSconfig tasks, this logs to <portal_server_root>\log\ConfigTrace.log.
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>\migration\propcollector.jar <portal_server_root>\migration\propcollector.xml Copy these to <portal_server_root>\config\includes on your WebSphere Portal V5.1 server.
24
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. Tip: If you are migrating from a cluster, the Property Collector can be run on any cluster member. Neither WebSphere Portal V5.1 nor WebSphere Portal V6 is required to be running at this time. Restriction: If you are exporting from Cloudscape, WebSphere Portal V5.1 server must be shut down. Otherwise, an exception occurs and the Collector fails. This is because Cloudscape is a single Java virtual machine (JVM) database and the Property Collector cannot access the database when the WebSphere Portal server is running.
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 Tips: -DDbPassword=wpsdb_password is not required if the value is already defined in the wpconfig.properties file. The location of the Collector output file can be overridden by using -Dcollector.output.file=<fully_qualified_file_name>, for example, WPSconfig.bat prop-collector -Dcollector.output.file=C:\tmp\collector.zip. All the directories in the path must exist.
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.
Chapter 3. Migration of core components
25
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>\migration\propcollectorOutput.zip on your WebSphere Portal V6 server. Tip: It is worth ensuring that the Collector output file on the WebSphere Portal V6 server is readable after being copied.
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 WebSphere Portal V6 server. Important: If you have any portlets in predeployed enterprise archive (EAR) files, refer to 1.4.2, Custom portlets on page 7. Copy only the customized WAR files. Do not copy the entire directory because this overwrites the new WebSphere Portal V6 server portlets.
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>\log\MigrationTrace.log.
26
Important: Like WPSconfig, WPmigrate appends to its log file on each execution. However, WPmigrate overwrites any other files that it creates. Therefore, it is recommended that you make copies of these files before rerunning the command.
Tip: If there is a syntax error, for example, WPmigrate.bat collector-extarct instead of WPmigrate.bat collector-extract, you will see the following message: BUILD FAILED Target collector-extarct' does not exist in this project. The export and import stages run xmlaccess. As mentioned in Running the Property Collector on WebSphere Portal V5.1 on page 25, it is recommended that you run xmlaccess directly against the HTTP Listener in the WebSphere_Portal Application Server, instead of through an HTTP Server. Because the host name and the port name cannot be entered through the command line, verify that WpsHostname, WpsHostPort, XmlAccessHost, and XmlAccessPort are set appropriately. Note that XmlAccessHost and XmlAccessPort are new parameters in WebSphere Portal V6 and do not therefore apply to WebSphere Portal V5.1. XmlAccessHost is set to localhost by default and does not have to be changed. For the WebSphere Portal V6 server, these parameters are set in wpconfig.properties in <portal_server_root>\config. For the WebSphere Portal V5.1 server, they are set in wpconfig.properties, which has already been collected by the Property Collector.
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>\migration\work\collector. The directories are created if they do not already exist. There are no additional considerations if you are using virtual portals. This task extracts data from the Collector output file. There is no interaction with either the WebSphere Portal V5.1 server or the WebSphere Portal V6 server.
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. 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>
Virtual portals
No actions are required for virtual portals at this time.
27
Validation
Successful completion is indicated by the following message: BUILD SUCCESSFUL You can also inspect the contents of <portal_server_root>\migration\work\collector to ensure that the contents are readable.
Troubleshooting
If you do not get a BUILD SUCCESSFUL message, examine the messages that are created and review <portal_server_root>\log\MigrationTrace.log to find out the cause.
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>\migration\work\default. Directories are created if they do not already exist. For each virtual portal, they are created in <portal_server_root>\migration\work\vp-<URL context>, where <URL context> is the URL context of the virtual portal, which is defined in Virtual portals on page 29. Table 3-1 lists the most important files.
Table 3-1 Output files from the export portal configuration File name allout.xml testexport.xml Purpose xmlaccess export Result of a command to test connectivity. If the test fails, there will be messages here to help diagnose the issue.
This task runs xmlaccess against WebSphere Portal V5.1. Therefore, WebSphere Portal V5.1 must be running. There is no interaction with WebSphere Portal V6. Ensure HTTP connectivity from WebSphere Portal V6 to WebSphere Portal V5.1. Important: Check whether wmm.xml on the WebSphere Portal V5.1 server environment has the maximumSearchResults parameter set to a number that is greater than the number of portal users. Otherwise, the command will fail. Also ensure that searchTimeOut is set to a large number, for example, 20,000,000, in order to avoid user repository searches timing out.
28

Enter the following command: <portal_server_root>\migration\WPmigrate.bat export-portal-content -DPrevPortalAdminId=portaladminid -DPrevPortalAdminPwd=password In this command: PrevPortalAdminId is a portaladminid for the WebSphere Portal V5.1 PrevPortalAdminPwd is the password for this portaladminid Tip: -DPrevPortalAdminId and -DPrevPortalAdminPwd are not required if the values have already been defined in the wpconfig.properties file collected from WebSphere Portal V5.1 server. If you prefer, you can edit the wpconfig.properties file directly on WebSphere Portal V6 server to set these values. The wpconfig.properties file can be found in <portal_server_root>\migration\work\collector\wpconfig.properties.
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 Important: The context extension is displayed in the column URL Context in the Virtual Portal Manager, as highlighted in Figure 3-1.
Figure 3-1 Virtual Portal Manager showing URL context
29
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. 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.
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:\WebSphere\PortalServer\migration\work\default\testexport.xml must be indicated. The Server response indicates an error message indicates that xmlaccess was able to contact the WebSphere Portal V5.1 server before something went wrong.
Example 3-3 WPmigrate export portal content failed
[xmlaccess] EJPXB0019E: Server ls of the XmlAccess error look default\testexport.xml. [xmlaccess] EJPXB0019E: Server ls of the XmlAccess error look default\testexport.xml.
response indicates an error. For status and detai at file C:\WebSphere\PortalServer\migration\work\ response indicates an error. For status and detai at file C:\WebSphere\PortalServer\migration\work\
30
BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm l:161: EJPXB0019E: Server response indicates an error. For status and details of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\defau lt\testexport.xml. Total time: 3 seconds In our example, we opened testexport.xml, as shown in Example 3-4.
Example 3-4 testexport.xml
<failure> com.ibm.wps.command.xml.XmlCommandServlet$AuthenticationException: EJPXA0005E: Authorization for user wpsadmin failed. </failure> In our case, the cause was an incorrect password. We retyped the command with the correct password and it ran to completion. As mentioned in Validation on page 25, it is common to see export portal content complete successfully, but issue warnings. In our example, on successful export, the output shown in Example 3-5 was displayed.
Example 3-5 Output from successful WPmigrate export portal content
[xmlaccess] EJPXB0022W: The request was processed successfully on the server, but warnings were enountered during processing. For details of the XmlAccess warnings look at file C:\WebSphere\PortalServer\migration\work\default\allout.xml. [xmlaccess] EJPXB0020I: The request was processed successfully on the server. BUILD SUCCESSFUL Total time: 41 seconds We checked C:\WebSphere\PortalServer\migration\work\default\allout.xml and searched for <status. We found the messages shown in Example 3-6.
Example 3-6 Messages from allout.xml for successful export portal content
<status element="[web-app _1_004CSO68OD0EIGCQ_6O uid=pzn.author.1001]" result="warning"> <message id="EJPXA0185W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0185W: The URL file://localhost/$server_root$/installableApps/pznauthorportlet.war does not point to a directory as required by predeployed portlets. You will need to adjust the URL. [web-app _1_004CSO68OD0EIGCQ_6O uid=pzn.author.1001]</message> </status> <status element="[web-app _1_004CSO68OD0EIGCQ_6P uid=pzn.ruleportlet.1001]" result="warning"> <message id="EJPXA0185W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0185W: The URL file://localhost/$server_root$/installableApps/pznruleportlet.war does not point to a directory as required by predeployed portlets. You will need to adjust the URL. [web-app _1_004CSO68OD0EIGCQ_6P uid=pzn.ruleportlet.1001]</message> </status> <status element="[web-app _1_004CSO68OD0EIGCQ_IP uid=com.ibm.wps.portlets.Calculator.Calculator]" result="warning">
31
<message id="EJPXA0186W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0186W: The URL file://localhost/$server_root$/installableApps/Calculator.war does not point to a file. You will need to adjust the URL. [web-app _1_004CSO68OD0EIGCQ_IP uid=com.ibm.wps.portlets.Calculator.Calculator]</message> </status>
These messages refer to missing WAR files. Xmlaccess expects that the WAR files for the exported portlets will exist in <portal_server_root>\installableApps on the server, identified by localhost, which is the WebSphere Portal V5.1 server at this point. The messages regarding pznauthorportlet.war and pznruleportlet.war messages are normal. These portlets are part of Personalization and are supplied in predeployed EARs rather than portlet WAR files in both WebSphere Portal V5.1 and V6. Because the migration process handles this automatically, these messages can be ignored. The message referring to Calculator.war is worth noting. In our example, we installed the Calculator portlet on WebSphere Portal V5.1 server from the portlet catalog. This was installed using the portal admin graphical user interface (GUI), which picked up the WAR file from the local hard drive of the workstation used for the installation. Therefore, there was no copy of the WAR file in the <portal_server_root>\installableApps directory on WebSphere Portal V5.1 server. This message does not indicate an error at this point. However, it serves as a reminder to ensure that the WAR file is made available on the WebSphere Portal V6 server before proceeding. Important: Any references to localhost in allout.xml refer to the WebSphere Portal V5.1 server, rather than the WebSphere Portal V6 server.
Tip: If you have to investigate allout.xml for purposes of troubleshooting, search for <status to quickly find the warning or error messages. If necessary, search for references to the message codes identified by message id in the Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, which is available on the Web at: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html Tip: If the output file referenced in the command output does not provide enough information to resolve the cause of a failed export, it is worth checking the logs for the WebSphere Portal V5.1 server to see if they indicate any issues.
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.
32
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.
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. Tip: When defining the virtual portals in the WebSphere Portal V6 server, the only parameter that must match the definition in V5.1 is URL Context. However, it is recommended that you keep all the parameters the same. This task writes a number of files when executing. For the default portal, they are written to <portal_server_root>\migration\work\default. The directories will be created if they do not already exist. For each virtual portal, they are created in <portal_server_root>\migration\work\vp-<URL context>. Table 3-2 describes the most important files:
Table 3-2 Files created by the import portal content task File name importAll.xml importAllResults.xml testimport.xml Purpose The final Extensible Markup Language (XML) file used for the xmlaccess import An XML file with the results from the import process 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.
33
The WPmigrate task uses the configuration values stored in wpconfig.properties on WebSphere Portal V6 server. This must be validated before progressing further. The WPmigrate task runs xmlaccess against WebSphere Portal V6 server. Therefore, WebSphere Portal V6 server must be running. There is no direct interaction with WebSphere Portal V5.1 server. If there are any shared resources, for example, the database server, there might be a performance impact on the WebSphere Portal V5.1 server environment because of a high level of activity on these resources caused by the import.

Enter the following command: <portal_server_root>\migration\WPmigrate.bat import-portal-content -DPortalAdminId=portaladminid -DPortalAdminPwd=password In this command: PortalAdminId is a portaladminid from the WebSphere Portal V6 server environment PortalAdminPwd is the password for this portaladminid Tip: -DPortalAdminId and -DPortalAdminPwd are not required if the values are already defined in the wpconfig.properties file for the WebSphere Portal V6 server.
Important: You must specify the WasUserid and WasPassword in the wpconfig.properties file. They cannot be entered on the command line.
Virtual portals
After recreating the virtual portals in the WebSphere Portal V6 server, run the command shown in Example 3-7 for each one, restarting the WebSphere Portal V6 server after each import.
Example 3-7 Virtual portals command
<portal_server_root>\migration WPmigrate import-portal-content -DPortalAdminId=portaladminid -DPortalAdminPwd=password -DVirtualPortal=URL context In this command: PortalAdminId is a portaladminid from the WebSphere Portal V6 server PortalAdminPwd is the password for this portaladminid URL context is the context extension for the virtual portal URL Important: You must specify the WasUserid and WasPassword in the wpconfig.properties file. They cannot be entered on the command line.
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, it is useful to use the tail command to monitor importAllResults.xml. You can also use your OS tools to see what processes are running and the resources they are using. Successful completion is indicated by the following message: BUILD SUCCESSFUL. 34
Tip: Browse importAllResults.xml even if you see the BUILD SUCCESSFUL message. There may still be issues that must be investigated before proceeding. Our results and the corresponding explanation are documented in Example 3-12.
Troubleshooting
If the import process does not display the BUILD SUCCESSFUL message, the following resources help diagnose the problem: Output from the command migrationTrace.log testimport.xml importAllResults.xml WebSphere Portal V6 logs The cause might be immediately obvious from the command output. If there are connectivity issues with the WebSphere Portal V6 server, for example, if it has not been started, messages such as the one shown in Example 3-8 are displayed.
Example 3-8 WPmigrate import portal content task output with the WebSphere Portal V6 server down
BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xml: 275: EJPXB0016E: An error occurred on the client: Connection refused: connect If you run WPmigrate import without making all the WAR files available in <portal_server_root>\installableApps, an output such as the one shown in Example 3-9 is displayed.
Example 3-9 WPmigrate output for missing WAR file
[warFileFilter] INFO: War files are missing from the <wp_root>/installableApps d irectory. Some portlet applications may not be deployed. [warFileFilter] C:\WebSphere\PortalServer\installableApps\Calculator.war not fou nd. BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm l:524: Missing war files have been detected. Verify the missing war files have been copied to the <wp_root>/installableApps directory. Total time: 3 minutes 34 seconds If the answer is not immediately obvious from the command output, investigate further. The command output tells you where to look next. Because the entire command output is logged to MigrationTrace.log, check MigrationTrace.log if you have lost the command output. Example 3-10, which is a failed WPmigrate import portal content task, shows that C:\WebSphere\PortalServer\migration\work\default\testimport.xml must be indicated. The Server response indicates an error message indicates that xmlaccess was able to contact the WebSphere Portal V6 server before something went wrong.
Example 3-10 WPmigrate import portal content task failed
[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testimport.xml.
35
[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testimport.xml. BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm l:275: EJPXB0019E: Server response indicates an error. For status and details of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\defau lt\testimport.xml. Total time: 3 seconds In our example, we opened testimport.xml, as shown in Example 3-11.
Example 3-11 testimport.xml
<failure> com.ibm.wps.command.xml.XmlCommandServlet$AuthenticationException: EJPXA0011E: Authentication for user wpsadmin failed. </failure> In our case, the cause was an incorrect password. We retyped the command with the correct password, and it ran to completion. As mentioned in Validation on page 28, it is common to see the import portal content task complete successfully, but issue warnings. In our example, on successful import, the output shown in Example 3-12 was displayed.
Example 3-12 Output from successful import portal content task
[xmlaccess] EJPXB0022W: The request was processed successfully on the server, bu t warnings were enountered during processing. For details of the XmlAccess warni ngs look at file C:\WebSphere\PortalServer\migration\work\default\importAllResul ts.xml. [miglogger] Oct 24, 2006 8:33:11 PM com.ibm.wps.migration.framework.logging.Migr ationLogger execute [miglogger] INFO: EJPMA5200I: Successfully imported XmlAccess script, import res ult in file C:\WebSphere\PortalServer\migration/work/default/importAllResults.xm l. post-import: BUILD SUCCESSFUL Total time: 13 minutes 1 second We looked at importAllResults.xml, searched for the <status tag, and found the result shown in Example 3-13.
Example 3-13 Status from importAllResults.xml
<status element="[credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment]" result="warning"> <message id="EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment]</message>
36
</status> <status element="[credential-segment _E_004CSO68OD0EIGCQ_36 name=DefaultAdminSegment]" result="warning"> <message id="EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_36 name=DefaultAdminSegment]</message> </status> The messages pertaining to credential segments are normal. This is because the migration process cannot migrate the credential vault. Our River Bend example had a Web Clipping Portlet that accesses a Web site requiring authentication. This uses the credential vault. Action is required as described in 3.4.6, Migrating the credential vault on page 45. Tip: If you have to investigate importAllResults.xml for troubleshooting purposes, search for <status in order to quickly find the warning or error messages. If necessary, search for references to the message codes identified by message id in the Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, which is available on the Web at: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html Tip: If the output file referenced in the command output does not provide enough information to resolve the cause of a failed export, it is worth checking the logs for the WebSphere Portal V6 server to see if they indicate any issues.
Rerun
This task can be rerun at any time, even if it has failed midway, for example, due to a time-out. However, it overwrites its output files without warning. The WebSphere Portal V6 server must be restarted before rerunning. Attention: The server process called by xmlaccess runs for a short time after an xmlaccess failure. If this process is still running when the import is rerun, you might see the following message in testimport.xml: com.ibm.wps.command.CommandFailedException: EJPXA0166E: The XML Configuration Interface is currently busy with another request. Please try again later. If this happens, wait a while and try again.
Tip: Take a copy of the output files before rerunning the import portal content task so that you can compare the outcome of any reruns.
37
Important: If you decide to rerun the import for a virtual portal, you do not have to delete and recreate the virtual portal first. If you delete and recreate the virtual portal, you might face problems if delayed cleanup is enabled (as it is by default). In our case, we saw the import fail under these conditions with the following message: com.ibm.websphere.ce.cm.DuplicateKeyException: The statement was aborted because it would have caused a duplicate key value in a unique or primary key constraint defined on 'PAGE_INST(OID). We resolved this by forcing an immediate run of the cleanup service through xmlaccess as discussed in Forcing immediate clean-up with xmlaccess on page 107.
3.4 Postmigration tasks

On successful completion of the WPmigrate tasks, you must complete a number of tasks manually. However, not all these steps apply to your configuration. Attention: If you have themes that use Personalization, you might encounter problems if, as recommended, you have not yet migrated Personalization. If this is the case, there is a URL mapping labelled Administration, which can be used in the WebSphere Portal V6 server to access the admin page. From here, you can reset the default themes on individual pages to one of the IBM defaults until you migrate Personalization. The resulting URL is: http://<hostname>:10038/wps/myportal/Administration
3.4.1 Restarting the server

The WebSphere Portal V6 server must be restarted after the WPmigrate tasks are completed.
3.4.2 Migrating WebSphere Member Manager database tables

If you are using WebSphere Member Manager, you must migrate the WebSphere Member Manager database tables using your database tools. The IBM WebSphere Portal Version 6.0 Information Center has instructions for Cloudscape and DB2 under the topic Migrating the Member Manager database using the command line: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en t.doc/wpf/sec_mig_roles.html For other databases, consult your database administrator (DBA).
3.4.3 Adjusting the page hierarchy

Your custom pages may not initially be displayed when you point your browser to <hostname>/wps/portal. This is because the WebSphere Portal V6 server already has a welcome page, which may be higher in the content node hierarchy. This can be addressed by making a change using the portal admin GUI. If you use virtual portals, you must use the portal admin GUI for each virtual portal, and repeat this step.
38
In our case, when we started our migrated River Bend portal server for the first time and accessed http://m51g.cam.itso.ibm.com:10038/wps/portal from a browser, we saw the default WebSphere Portal V6 server welcome (Figure 3-2) page instead of the expected River Bend welcome page.
Figure 3-2 Welcome page immediately after migration
We addressed this by adjusting the page hierarchy from Portal User Interface Manage Pages. We clicked Content Root and saw the page hierarchy, as displayed in Figure 3-3. We clicked the Up Arrow button next to My Portal.
Figure 3-3 Page hierarchy immediately after migration
39
This moved My Portal to the top of the list, as shown in Figure 3-4.
Figure 3-4 Fixing the page hierarchy
When we pointed our browser to http://m51g.cam.itso.ibm.com:10038/wps/portal after making this change, we saw the River Bend welcome page (Figure 3-5).
Figure 3-5 The welcome page displays as expected
40
3.4.4 Migrating the search collections

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

The Search and Browse Portlet requires a manual configuration change after migration due to a change in configuration parameters. Immediately after migration, a page with a Search and Browse Portlet shows an error, as shown in Figure 3-6.
Figure 3-6 Search and Browse Portlet, postmigration
41
In WebSphere Portal V5.1 server, the portlet locates its search index through the configuration parameter called IndexName, as shown in Figure 3-7.
Figure 3-7 Configuring the Search and Browse Portlet in V5.1
42
In WebSphere Portal V6, this is now called CollectionLocation. To fix this, we reconfigured the Search and Browse Portlet in question. Note that the IndexName parameter in Figure 3-8 has been preserved by the migration process, but is not used. The required parameter (CollectionLocation) is not listed on any page.
Figure 3-8 Search and Browse Portlet properties
Important: The problem is that the new parameter (CollectionLocation) is missing. If you have put your search collection in a location that is different from your WebSphere Portal V5.1 server and updated IndexName to match this new location, this issue continues to occur.
43
In our case, we added the missing parameter by typing CollectionLocation in the New Parameter box and the name of the directory that houses the collection (in our case, c:\collections\itsoco) in the New Value box, as shown in Figure 3-9, and clicked Add, and then OK. We then restarted the portal server. It is recommended that you delete the redundant IndexName parameter at this point.
Figure 3-9 Fixing a Search and Browse Portlet
Attention: There is no requirement to change the location directory between versions. This is just an example. The fix is required even if you do not change the location.
Important: You must log out and log back in to pick up this change.
44
3.4.6 Migrating the credential vault

This section describes the process involved in migrating the credential vault. Attention: If you use third-party vault implementation, for example, IBM Tivoli Access Manager, no additional steps are required. The existing credential secrets can be used in the WebSphere Portal V6 server. The credential vault slots are migrated as shown in Figure 3-10.
Figure 3-10 Credential vault exists after migration
However, any secret information they contained is not migrated, as can be seen from our example, which is shown in Figure 3-11.
Figure 3-11 Credential vault is empty after migration
The secret information can be migrated using your database tools or some new functionality in xmlaccess that is introduced by PK28148, which must be installed on the WebSphere Portal V5.1 server and the WebSphere Portal V6 server. Both the methods are documented in the WebSphere Portal V6 Information Center under the topic Migrating credential vault data: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en t.doc/wpf/sec_mig_roles.html Using the new xmlaccess functionality is recommended.
45
Tip: In our test of PK28148, the following message was displayed, although the import was successful: "EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment in <portal_server_root>\bin\resultsCVresults.xml. At the time of writing this IBM Redpaper, this was being addressed by Development. Depending on the version of the previous system, some secrets and shared credential slots that are obsolete in the current version are migrated. These slots must be removed using the Credential Vault administrative portlet under Administration Access Credential Vault. Select Manage system vault slots and delete the following slots, if applicable: deployment.user wmm.system.id.user deployment.truststore deployment.keystore
3.4.7 Administration portlets and pages

As described in 1.4.6, Administration portlets on page 11, the administration portlets and pages have been replaced as part of the migration. Therefore, all the customizations must be reworked, including the following: Portlets added to admin pages Authorization changes to admin portlets Admin portlets added to custom pages URL mapping to admin page A complete list of the admin portlets in WebSphere Portal V5.1 and WebSphere Portal V6 can be found in List of admin portlets in WebSphere Portal V5.1 on page 107 and List of admin portlets in WebSphere Portal V6 on page 108. Attention: If you are using the clones of these portlets, authorization information for the clones is preserved. Configuration information is preserved where possible. If the V6 portlet has new configuration parameters that are not present in V5.1, they will be set to default values. If the V6 portlet no longer uses parameters that are present in V5.1, they may be deleted. Therefore, the clones of admin portlets might not function as intended and must be verified and reconfigured if necessary.
3.4.8 The Web Clipper

Our example River Bend company required two Web Clippers, one for clipping the River Bend Web site and the other for clipping the itsoco Web site, as mentioned in Migrating the search collections on page 109. There are no issues directly relating to migration. However, WebSphere Portal V6 ships with a more recent version of the Web Clipping portlet than originally shipped with WebSphere Portal V5.1. You might encounter some issues if you have not updated this portlet in your WebSphere Portal V5.1 server.
46
If, for example, the Web site being clipped uses JavaScript, you might see a warning message, as shown in Figure 3-12. This issue will also be observed on the WebSphere Portal V5.1 server if the most recent Web Clipping portlet is installed there.
Figure 3-12 Warning message in Clipper, postmigration
To address this, in our example, we edited the Web Clipping Portlet, as shown in Figure 3-13.
.
Figure 3-13 Editing the Web Clipper portlet
We then selected the Advanced Options, followed by the Modify Security Options. We selected the box against Remove JavaScript from clipped content, as shown in Figure 3-14, and clicked OK.
Figure 3-14 Modifying the security options
47
We then clicked Next, and then Finish. The message was no longer displayed, as shown in Figure 3-15.
Figure 3-15 Web Clipper warning has been removed
The clipper for the itsoco Web site showed different issues after migration. Immediately after the migration, the portlet displayed nothing, as shown in Figure 3-16.
Figure 3-16 itsoco clipper, postmigration
Clicking on Edit showed the cause to be missing credential vault data, as shown in Figure 3-17. This is because the Web Clipper uses the credential vault to store authentication data. The credential vault secret does not migrate automatically. Refer to 3.4.6, Migrating the credential vault on page 45 for instructions about how to correct this.
Figure 3-17 itsoco clipper with the missing credential vault data
3.4.9 Migrating the hidden pages

In the standard WebSphere Portal V5.1, the pages held directly under the content root are hidden. In WebSphere Portal V6, they become viewable in the Launch dropdown menu. This can be addressed in WebSphere Portal V6 by using xmlaccess. This is described in the IBM WebSphere Portal Version V6 Information Center under the topic Marking pages as hidden under the content root: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.e nt.doc/wps/adxmlref.html
3.4.10 Migrating the WebSphere Application Server artifacts-Enterprise JavaBeans

As mentioned in 1.4.3, External components on page 8, these are not migrated automatically. You must migrate them manually.
48
3.4.11 Migrating the global portal settings

These portal configuration settings are configured using the WebSphere Portal server admin GUI. They are set on a per server basis. Therefore, this must be checked for every member in a cluster. They affect the default portal server and all the virtual portals simultaneously. Because they are not migrated, a manual check is required.
3.4.12 Migrating the portal service configuration properties

There are changes to the way that portal services are configured in WebSphere Portal V6. In WebSphere Portal V5.1, these are configured by setting values in properties files under <portal_server_root>\shared\app\config\services. In WebSphere Portal V6, these configuration settings are managed by Resource Environment Providers in the WebSphere Application Server. In WebSphere Portal V6, the settings must be changed either by a direct update by using the WebSphere Application Server admin console or by updating the corresponding value in the relevant file in <portal_server_root>\config\properties, and then running WPSconfig update-properties. This WPSconfig task reads the properties files and then makes the corresponding updates to the Resource Environment Providers in the WebSphere Application Server. In a cluster, you must force a replication to ensure that these values are the same for all the cluster members. After changing a portal service configuration property, restart the portal server. Portal service configuration properties are not automatically migrated. If you have changed any property from its default value in WebSphere Portal V5.1, refer to the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en t.doc/wps/srvcfgref.html Important: Changes made to the properties files in <portal_server_root>\config\properties have no effect until WPSconfig update-properties has been run.
3.4.13 Migrating the performance settings

For information about this, refer to the IBM WebSphere Portal Version 6 Tuning Guide: http://www-1.ibm.com/support/docview.wss?uid=swg27008511&aid=1
3.4.14 Migrating the struts portlets

This is discussed in 1.4.2, Custom portlets on page 7.
3.4.15 Migrating the Click-to-Action portlets

3.4.16 Migrating the business processes

49
3.4.17 Migrating the FileServer portlet

If you cloned the FileServer portlet in WebSphere Portal V5.1 and supplied Hypertext Markup Language (HTML) files in the <portal_server_root>\root\installedApps\FileServer.war\FileServerPortlet\html directory, copy those files to the <portal_server_root>\installedApps\FileServer.war\FileServerPortlet\html directory on the WebSphere Portal V6 server after running the import task, and then restart the server in order to make the files accessible in the current version.
3.5 Validating the portal and fixing any remaining issues

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

This chapter describes the process involved in migrating the additional components of Document Manager and Personalization from WebSphere Portal V5.1 to WebSphere Portal V6 using the command-line tools. If your additional component is only Document Manager, skip 4.4, Migrating Personalization data on page 67, as shown in Figure 4-1. If your Personalization data has some relation to the Document Manager documents, migrate the Document Manager first. Figure 4-1 shows a Document Manager and Personalization overview.
4.1 Document Transfer Tool (DTT)
Migrate PDM?
YES
4.2 Migrate PDM documents
NO
Migrate PZN?
YES
4.3 Migrate PZN data
NO
End of Chapter 4
Figure 4-1 Document Manager and Personalization migration overview Copyright IBM Corp. 2007. All rights reserved.
51
Document Manager migration and Personalization migration involve the flow shown in Figure 4-2. Each migration involves the same sequence of tasks (export transform import). However, the commands for the migration tasks are slightly different between Document Manager and Personalization. Following is the sequence of the tasks: 1. 2. 3. 4. 5. 6. Performing the premigration tasks Running the export task Copying the exported files to the V6 server Running the transform task Running the import task Performing validation
Migration Start
Prepare
Premigration tasks
Export
Run the export task
Copy
Copy exported files to the 6.0 system
Transform
Run the transform task
Import
Run the import task
Validate
Validate migration
Migration End
Figure 4-2 Flow of migration for Document Manager and Personalization
Although the process is independent of database and security configuration, it is required to use the same brand of software for the operating system (OS), database, and user repository, as described in 1.4.1, WebSphere Portal V6 environment on page 6.
At a glance
Following are the prerequisite conditions for this chapter: Installing the necessary fixes, including PK18903, PK30219, and PK30439 described in 1.5, Migration checklist on page 12 Completing all the steps described in Chapter 3, Migration of core components on page 23
52
Following is a list of the topics described in this chapter: 4.1, The Document Transfer Tool on page 54 4.2, Migrating the Document Manager documents on page 57 4.4, Migrating Personalization data on page 67
Prerequisite conditions
PK18903 includes the Document Transfer Tool (DTT), which must be installed through the WebSphere Application Server Admin Console. PK30219 (on the WebSphere Portal V5.1 server) and PK30439 (on WebSphere Portal V6 server) are fixes to deal with long user Distinguished Names (DN) in the Document Manager and Personalization property files. Without applying these fixes, migration for Document Manager and Personalization fails with an IllegalArgumentException. Important: At the time of writing this IBM Redpaper, we discovered that if the Workplace Web Content Management fix PK30516 is required, PK30439 must be installed afterwards. Ensure that you have completed the steps described in Chapter 3, Migration of core components on page 23 before continuing with the Document Manager migration process. Migrating the Document Manager data without performing this task is not supported.
Test environment for this document

Throughout this IBM Redpaper, the install location for IBM WebSphere Portal server is <portal_server_root>. We assume that the current and the earlier systems are on different physical servers because this is the most common migration scenario. If your earlier system configured into a cluster environment, we assume that one of the WebSphere Portal servers in your cluster is dedicated for the migration (for more details about the cluster environment, refer to Chapter 2, Considerations for migrating enterprise environments on page 15). In our case, we used Windows servers for the River Bend scenario. We tested two cases, one with a Cloudscape database without the Lightweight Directory Access Protocol (LDAP) and another with the DB2 and IBM Tivoli Directory Server LDAP security enabled (refer to 1.5.1, Steps to prepare your WebSphere Portal V6 environment for migration on page 12 for more details).
Chapter 4. Migration of Document Manager and Personalization
53
4.1 The Document Transfer Tool

This tool is invoked by the migration commands, and enables the transfer of Document Manager documents and Personalization data from one WebSphere Portal server to another. Install this tool on your WebSphere Portal V5.1 server environment before running the migration tasks for Document Manager and Personalization.
4.1.1 Installing the Document Transfer Tool

The Document Transfer Tool is included in the PK18903 fix. Therefore, ensure that you have already installed PK18903 on your WebSphere Portal V5.1 server environment. This is only required for Personalization and Document Manager migration. DTT(icmjcr.ear) is an enterprise application that must be installed using the WebSphere Application Server admin console. This enterprise archive (EAR) file is located in <portal_server_root>/jcr/installableApps. Install the Document Transfer Tool on WebSphere Portal V5.1 server by installing the EAR file through the WebSphere Application Server admin console on to the WebSphere Portal server: 1. Open your browser to the WebSphere Application Server admin console and log in (with the WebSphere Application Server admin user ID if security is enabled). 2. Select Applications Install New Application. 3. Select Local Path: and specify <portal_server_root>/jcr/installableApps/icmjcr.ear (Figure 4-3). Click Next four times, leaving the default values intact, to go to the Step 3: Map modules to application servers window.
Figure 4-3 Installing new application: icmjcr.ear
54
4. In the Step 3: Map modules to application servers window (Figure 4-4) select WebSphere_Portal as the module for the installation and check jcrpublishwar as the module to be installed, and click Apply. Click Next two times, leaving the default values intact, to go to the Step 5: Summary window.
Figure 4-4 Mapping modules to application servers
5. In the Step 5: Summary window (Figure 4-5), click Finish to complete the task.
Figure 4-5 Summary
6. In the page that opens, click the hyperlink Save to Master Configuration (the third line from the bottom), and then click the hyperlink Save in the Messages window to apply the changes to the master configuration.
55
7. Restart WebSphere_Portal. You must now restart the WebSphere Portal V5.1 server. You may want to do this by issuing the following command in your command-line interface (assuming yours is a Windows environment): cd <portal_server_root>\config WPSconfig.bat stop-portal-server start-portal-server
4.1.2 Validating the Document Transfer Tool installation

Perform the following tasks: 1. Check the admin console running on server1 to see if the icmjcr is installed (Figure 4-6). However, it will not show a status because the application is installed on the WebSphere_Portal, unless the WebSphere Portal server is managed by a Document Manager cell.
Figure 4-6 WebSphere Application Server admin console: icmjcrear is inactive
56
2. Now check WebSphere_Portal SystemOut.log located in <portal_server_root>\log (Figure 4-7). Look for icmjcrear. It must tell you that the application is started.
Figure 4-7 SystemOut.log: icmjcrear is started
4.2 Migrating the Document Manager documents

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

It is recommended that you prepare a validation checklist before Document Manager migration. In many cases there are a large number of documents in the Document Manager libraries. Therefore, perform a spot check in each Document Library. You might want to check if Document Manager functionalities such as Folder access control, Lock, Version, and Workflow are functioning properly before and after Document Manager migration. Table 4-4 provides a sample checklist.
Table 4-1 Checklist for Document Manager validation Source OK Target Library Document Library Folder (AC) \ (AC:Default) Name Migration Presentation Lock No Version No Workflow No
4.3 Synchronizing Document Manager global access

Before migrating, synchronize the Document Manager global access settings. Global access settings for document library inheritance might be different between the WebSphere Portal V5.1 server and the WebSphere Portal V6 server. Because the scope of migrated settings does not include global settings, synchronize the settings between the WebSphere Portal V5.1 server and the WebSphere Portal V6 server so that access control for document libraries remains the same after migration. For WebSphere Portal V5.1 server migration, any access roles on the ICM_CONTENT_REPOSITORY virtual resource on the V5.1 source server must also be set on the WebSphere Portal V6 server, using the Set Access on Root button of the Document Libraries administration portlet.
Checking the WebSphere Portal V5.1 server environment

Check your Document Manager global access on your WebSphere Portal V5.1 server by performing these tasks: 1. Open your browser to log in to your WebSphere Portal V5.1 server (Figure 4-8). Select Administration Access Resource Permissions. Select Virtual Resources as the Resource Type.
58
Click the Assign Access icon of ICM_CONTENT_REPOSITORY. Check the access control for each role (Figure 4-8).
Figure 4-8 Document Manager global access in WebSphere Portal V5.1 server
2. Use the checklist shown in Table 4-2 to set the same access control on WebSphere Portal V6 server.
Table 4-2 Checklist for Document Manager global access Role Administrator Security Administrator Delegator Manager Editor Privileged User User Propagation On On Inheritance On On Groups/Users wpsContentAdministrators wpsadmins
59
Setting up the WebSphere Portal V6 server environment

After you have checked the Document Manager global access on your WebSphere Portal V5.1 server, you are ready to set up your WebSphere Portal V6 server. Perform the following tasks: 1. Open your browser to log in to your WebSphere Portal V6 server and select Launch Administration Portal Content Document Libraries. 2. Click Set Access on Root (Figure 4-9).
Figure 4-9 Selecting Set Access on Root
3. Check and set all the access control list (ACLs) for each role. They must be the same as the ones on your WebSphere Portal V5.1 server that you checked, as described in Checking the WebSphere Portal V5.1 server environment on page 58.
4.3.1 Modifying the Document Manager properties

The Document Manager properties file is located in <portal_server_root>l\jcr\migration\conf\pdm_conf.xml. Change the properties shown in Table 4-3 to meet your environments requirements.
Table 4-3 Document Manager properties you must change Property name MigDirSource MigDirSourceShared Description The migration directory on the source (V5.1) server. This directory will be used for export from V5.1. Ensure that this directory is empty. The directory on the target (V6) server. The tasks that take place after the export task are required to access the exported data from the target (V6) server. Because mapping environment is not used, the exported data must be copied to the target servers local directory. This property is the local directory where the exported data is stored. The migration directory on the target (V6) server. This directory will be used for import to V6. Ensure that this directory is empty and is different from the MigDirSourceShared. The fully qualified host name and port for the V5.1 server. By default, the port for the V5.1 server is 9081. WPmigrate command communicates with the V5.1 server through this port. The fully qualified host name and port for the V6 server. By default, the port for the V6 server is 10038. WPmigrate command communicates with the V6 server through this port. The list of Document Libraries to migrate, separated by commas, for example, Document Manager or Document Manager, and MyLib
MigDirTarget
SourceServerPort
TargetServerPort
DocLib
60
Property name ExportUserId ExportPassword ImportUserId
Description Set this value to the V5.1 portal administrator user ID that you specified as PortalAdminId in wpconfig.properties. This must be a fully qualified DN. Set this value to the V5.1 portal administrator password. Set this value to the V6 portal administrator user ID that you specified as PortalAdminiId in wpconfig.properties. Short name can be used even if LDAP security is enabled. Set this value to the V6 portal administrator password. Change to true to migrate the workflow information, including submitted drafts. Change to true to migrate the document versions.
ImportPassword IncludeWorkflow IncludeVersion
Important: The best practice is to use fully qualified host names, / instead of \, and include the entire path in properties. Also, do not forget to take a backup of the original file.
Important: ExportUserId in the properties file must be in full DN format unless the short name is unique. ImportUserId can also be short name.
Tip: For clarity, change the file names to include the reference to the system they are on.
4.3.2 Creating directories for Document Manager migration

Create three directories for Document Manager migration, one on WebSphere Portal V5.1 server, and the other two on WebSphere Portal V6 server.
MigDirSource on WebSphere Portal V5.1 server

Create an empty export directory on WebSphere Portal V5.1 server, for example, c:\WebSphere\PortalServer\migration\pdm\export51\. This export directory will be used for the MigDirSource property described in Table 4-3.
MigDirSourceShared on WebSphere Portal V6 server

Create an empty export directory on the WebSphere Portal V6 server also, for example, c:\WebSphere\PortalServer\migration\pdm\export60\. This export directory will be used for the MigDirSourceShared property described in Table 4-3.
61
Important: As described in the WebSphere Portal Information Center, you can share the MigDirSource directory with the V6 server (sharing can be implemented with net use or Network File System (NFS) mount, and so on) as the MigDirSourceShared directory. However, it is recommended that you create another directory on the V6 server because file sharing is not allowed in many production environments. This IBM Redpaper assumes that file sharing will not be used. The IBM WebSphere Portal Version 6.0 Information Center is available on the Web at: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/mig_tbl.html
MigDirTarget on the WebSphere Portal V6 server

Create an empty work directory for import on the WebSphere Portal V6 server, for example, c:\WebSphere\PortalServer\migration\pdm\import60\. This work directory will be used for the MigDirTarget property described in Table 4-3. Ensure that this is not the same as the MigDirSourceShared property.
4.3.3 Running the export task for Document Manager

Your Document Manager property file is now ready to be used for the migration tasks. The export task calls the Document Transfer Tool application on the WebSphere Portal V5.1 server, which creates exported files on WebSphere Portal V5.1 server. These must be copied to WebSphere Portal V6 server. Ensure that your WebSphere Portal V5.1 server is running, with the Document Transfer Tool application available. There is no interaction with WebSphere Portal V6 server. Watch out for firewalls because the export task must communicate with your WebSphere Portal V5.1 server through the SourceServerPort specified according to the information provided in Table 4-3.
Running the export task

Run the export task for Document Manager by typing the following in the <portal_server_root>\migration directory in the command-line interface on the WebSphere Portal V6 server (Figure 4-10): WPmigrate.bat migrate-pdm-export-51x
Figure 4-10 Export task for Document Manager
Tip: Type WPmigrate.bat (or .sh for UNIX) on its own in order to list the available commands.
62
Validation
The WPmigrate command must report a BUILD SUCCESSFUL message (Figure 4-11). Check the MigrationTrace.log file located in the <portal_server_root>\log directory carefully to confirm.
Figure 4-11 Export task for Document Manager: BUILD SUCCESSFUL message
The export task creates files under the MigDirSource directory that you specified as per the directions provided in 4.3.1, Modifying the Document Manager properties on page 60. You can find the rootworkspace directory (and more, depending on your environment) there, and you can see that there are subdirectories whose names are associated with your Document Manager documents (Figure 4-12).
Figure 4-12 Export task for Document Manager: Successful creation of files
Troubleshooting
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, and eliminate the issues. Run the WPmigrate command again. You can also check the WebSphere Portal V5.1 server logs.
Rerun
This task requires you to clean up the MigDirSource directory before you rerun this task. If you forget to clean up the directory, you receive a BUILD FAILED message with Error 500: Please make sure that the export directory is empty and restart export.
63
4.3.4 Copying files to the WebSphere Portal V6 server

After the export task is successfully completed, the export files are created into new directories (rootworkspace and more, depending on your environment) in the MigDirSource directory on the WebSphere Portal V5.1 server. Copy all the directories in the MigDirSource directory to the MigDirSourceShared directory on WebSphere Portal V6 server before running the transform task for Document Manager.
Copying the files

There are several methods in which to copy these directories from WebSphere Portal V5.1 server to WebSphere Portal V6 server. Select the most convenient method that allows you to complete this task (Figure 4-13).
WebSphere Portal V5.1 server
WebSphere Portal V6 server
Figure 4-13 Copying all the directories from V5.1 to V6 for Document Manager
Validation
After copying all the directories under the MigDirSource directory, validate a couple of files in the MigDirSourceShared directory by opening in a text reader.
4.3.5 Running the transform task for Document Manager

The transform task transforms all the files that are exported by the export task and writes the transformed files to the MigDirTarget directory in the format required by the import task. There is no interaction with either the WebSphere Portal V5.1 server or WebSphere Portal V6 server.
64
Running the transform task

Run the export task for Document Manager by typing the following in the <portal_server_root>\migration directory in the command-line interface on WebSphere Portal V6 server (Figure 4-14): WPmigrate.bat migrate-pdm-transform
Figure 4-14 Transform task for Document Manager
Validation
The WPmigrate command must display a BUILD SUCCESSFUL message (Figure 4-15).
Figure 4-15 Transform task for Document Manager: BUILD SUCCESSFUL message
Important: Even if the source is wrong, the task will run to completion and report the BUILD SUCCESSFUL message. Also check that the files have been successfully written to the MigDirTarget directory that you specified, as described in 4.3.1, Modifying the Document Manager properties on page 60. You can find the rootworkspace directory there (Figure 4-16).
Figure 4-16 Transform task for Document Manager: Successfully transformed
65
Troubleshooting
If the WPmigrate command does not run successfully, check the output of the command, which can be found in portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again. You can also check the WebSphere Portal V6 server logs.
4.3.6 Running the import task

Now that you have completed the transformation of the exported files in the work directory on WebSphere Portal V6 server, you are ready to run the import task for Document Manager. The import task imports Document Manager objects from the MigDirTarget directory and stores them into the WebSphere Portal V6 server repository properly. Ensure that your WebSphere Portal V6 server is running. There is no interaction with the WebSphere Portal V5.1 server.
Running the import task

Run the import task for Document Manager by typing the following in the <portal_server_root>\migration directory in the command-line interface on the WebSphere Portal V6 server (Figure 4-17). WPmigrate.bat migrate-pdm-import
Figure 4-17 Import task for Document Manager
Validation
The WPmigrate command must report a BUILD SUCCESSFUL message (Figure 4-18).
Figure 4-18 Import task for Document Manager: BUILD SUCCESSFUL message
Troubleshooting
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again. You can also check the WebSphere Portal V6 server logs.
66
4.3.7 Validating the Document Manager

Your migration tasks for Document Manager are now completed. You must now open your browser to log in to your WebSphere Portal V6 server to confirm that the migration tasks have successfully migrated your Document Libraries. Use your own test scripts and validation criteria as recommended in 4.2.1, Preparing a checklist for Document Manager validation on page 58 to perform some spot checks. Attention: You might have to review WebSphere Application Server content-types.props if there are rendering issues.
4.3.8 Postmigration task for Document Manager

At time of this writing this IBM Redpaper, there is a known issue with Document Manager portlets on custom pages. Document Manager portlets on custom pages in WebSphere Portal V5.1 server are not migrated. After Document Manager migration, you will not see any Document Manager portlets on the target pages. Therefore, you must add the Document Manager portlets to the pages manually.
4.4 Migrating Personalization data

This section describes how to run the migration tasks for Personalization. WebSphere Portal V6 provides a command-line tool (WPmigrate) to migrate your Personalization to the WebSphere Portal V6 server. The IBM WebSphere Portal V6 Information Center tells you to run the migrate-pzn-51x task for Personalization migration. This requires a mapped drive because it runs several Ant tasks in sequence (export transform import). It does not transfer the data, but relies on being able to access a directory on the WebSphere Portal V5.1 server through the WebSphere Portal V6 server. Because operational or security considerations may exclude drive mapping in many cases, we show you how to migrate your Personalization data without mapping a drive, by running the series of tasks one by one. However, you must prepare a method, for instance, SSH, writable CD/DVD, to transfer the data from the WebSphere Portal V5.1 server to the WebSphere Portal V6 server. Following is the list of topics described in this section: 1. 2. 3. 4. 5. 6. 7. 8. 4.4.1, Preparing a checklist for Personalization validation on page 68 4.4.3, Modifying Personalization properties on page 69 4.4.4, Creating directories for Personalization migration on page 70 4.4.5, Running the export task for Personalization on page 70 4.4.6, Copying files to WebSphere Portal V6 server on page 72 4.4.7, Running the transform task for Personalization on page 73 4.4.10, Running the import task for Personalization on page 75 4.4.11, Validating your Personalization on page 76
67
4.4.1 Preparing a checklist for Personalization validation

It is recommended that you prepare a checklist before Personalization migration. In many cases, there are a large number of Personalization resources and rules in workspace. You must, therefore, perform a spot check in the workspace after migration. Table 4-4 provides a sample checklist. If you have rules that interact with other components of WebSphere Portal, such as Document Manager, it is recommended that you include samples of the rules in the checklist.
Table 4-4 Checklist for Personalization validation Source OK Target Resource/Rule Rules Name Simple Doc Rule Component Document Manager
Restriction: Rules from earlier versions that made use of the site area property in Workplace Web Content Management must be manually updated after Workplace Web Content Management migration. Refer to the Web content resource collection topic in the IBM WebSphere Portal Version 6.0 Information Center for more information: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/mig_tbl.html
4.4.2 Custom resource collections

If you are using only the built-in resource collections (Web content, documents, and portal user) and objects (request, session, and so on), you do not have to worry about this step. Resource collection classes allow Personalization to connect to customer-defined data sources. Resource collections are implemented by a set of Java classes. These classes might have been generated either by wizards in IBM Rational Application Developer (or one of its predecessors such as IBM WebSphere Studio Application Developer) or might have been hand-coded. All custom application objects are hand-coded. Java classes used by resource collections and application objects must be placed in a WebSphere Application Server-shared library. The portal migration framework does not move, migrate, or in any way touch these classes. They must be migrated manually along with the other classes you might have deployed to the application server. As of WebSphere Portal V6, a shared library is predefined for custom resource collections and application objects. You can add classes to this library by placing classes in folders representing packages or JAR files in <wps>/pzn/v6.0/collections. These classes and JAR files will be added to the classpath of the entire portal server. You can move classes from your shared libraries into this one. If your custom shared libraries are scoped differently from this predefined library, or if you want more administrative control over the classpath, you can still use custom-defined shared libraries. Additionally, resource collections, particularly, Structured Query Language (SQL) resource collections generated by the wizards in Rational Application Developer, might require data source definitions in the application server. The WebSphere Portal migration framework does not move, migrate, or otherwise touch customer-defined data source definitions for these collections. These data source definitions must also be migrated manually. If your classes made use of internal or undocumented programming interfaces, the resource collection classes themselves may require custom migration.
68
4.4.3 Modifying Personalization properties

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

You must create three directories for Personalization migration, one on the WebSphere Portal V5.1 server, and the other two on the WebSphere Portal V6 server.
SourceExportData on WebSphere Portal V5.1 server

Create an empty export directory on the WebSphere Portal V5.1 server, for example, c:\WebSphere\PortalServer\migration\pzn\export51\. This export directory will be used for the SourceExportData property, as described in 4.4.3, Modifying Personalization properties on page 69.
TargetExportData on WebSphere Portal V6 server

Create an empty export directory on the WebSphere Portal V6 server also, for example, c:\WebSphere\PortalServer\migration\pzn\export51\. This export directory is used for the TargetExportData property, as described in 4.4.3, Modifying Personalization properties on page 69. Important: As described in the WebSphere Portal V6 Information Center, you can share the SourceExportData directory with the WebSphere Portal V6 server as the TargetExportData directory. It is recommended that you create a separate directory on the WebSphere Portal V6 server instead of sharing the same directory. Refer to the IBM WebSphere Portal Version 6.0 Information Center for details: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/mig_tbl.html
TempData on WebSphere Portal V6 server

Create an empty work directory for import on WebSphere Portal V6 server, for example, c:\WebSphere\PortalServer\migration\pzn\import60\. This work directory will be used for the TempData property, as described in 4.4.3, Modifying Personalization properties on page 69. The TempData property must not be set to the same value as the TargetExportData property.
4.4.5 Running the export task for Personalization

Your Personalization property file is ready to be used for the migration tasks. The export task calls the DTT application on WebSphere Portal V5.1 server, which creates exported files on WebSphere Portal V5.1 server. These must be copied to the WebSphere Portal V6 server. Ensure that your WebSphere Portal V5.1 server is running, with the DTT application available. There is no interaction with WebSphere Portal V6 server. Watch out for firewalls because the export task is required to communicate with your WebSphere Portal V5.1 server through the SourceServerPort specified according to the information provided in Table 4-5.
70
Running the export task

Run the export task for Personalization by typing the following in the <portal_server_root>\migration directory using the command-line interface on WebSphere Portal V6 server (Figure 4-19): WPmigrate.bat migrate-pzn-export-51x
Figure 4-19 Export task for Personalization
Validation
The WPmigrate command must report a BUILD SUCCESSFUL message (Figure 4-20). Also check MigrationTrace.log located in <portal_server_root>\log carefully to ensure the same.
Figure 4-20 Export task for Personalization: BUILD SUCCESSFUL message
71
The export task creates files under the SourceExportData directory that you specified according to the information provided in Table 4-5. You can find the rootworkspace directory there, and see that there are files whose names are associated with your Personalization data (Figure 4-21).
Figure 4-21 Export task for Personalization: Successful creation of files
Troubleshooting
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again. You can also check the WebSphere Portal V5.1 server logs.
Rerun
Clean up the SourceExportData directory before you rerun this task. If you forget to clean up the directory, you receive a BUILD FAILED message with Error 500: Please make sure that the export directory is empty and restart export.
4.4.6 Copying files to WebSphere Portal V6 server

After the export task is successfully completed, the export files are created in a new directory called rootworkspace in the SourceExportData directory on WebSphere Portal V5.1 server. Copy these files to the TargetExportData directory on WebSphere Portal V6 server before running the transform task for Personalization.
72
Copying files
There are several ways in which to copy these files from WebSphere Portal V5.1 server to WebSphere Portal V6 server. Select the most convenient method that allows you to complete this task (Figure 4-22).
WebSphere Portal V5.1 server
WebSphere Portal V6 server
Figure 4-22 Copying rootworkspace directory from V5.1 to V6 for Personalization
Validation
After copying all the files under the rootworkspace directory, validate a few files by opening them in a text reader.
4.4.7 Running the transform task for Personalization

The transform task transforms all the files that are exported by the export task, and writes the transformed files to the TempData directory in the format required by the import task. There is no interaction with either the WebSphere Portal V5.1 server or WebSphere Portal V6 server.
Running the transform task

Run the export task for Personalization by typing the following in the <portal_server_root>\migration directory in the command-line interface on WebSphere Portal V6 server (Figure 4-23): WPmigrate.bat migrate-pzn-transform-51x
Figure 4-23 Transform task for Personalization
73
Note: The commands for Personalization are slightly different from the commands for Document Manager. The Personalization commands have a -51x suffix.
Validation
Figure 4-24 Transform task for Personalization: BUILD SUCCESSFUL message
Important: Even if the source is wrong, the task runs to completion and report a BUILD SUCCESSFUL message. Also check whether the files have been successfully written to the TempData directory, which you specified, as described in Creating directories for Personalization migration on page 70. You can find the rootworkspace directory there (Figure 4-25).
Figure 4-25 Transform task for Personalization: Successful transformation
74
4.4.8 Troubleshooting
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, eliminate the issues, and run the WPmigrate command again.
4.4.9 Migrating the Personalization cache configuration

Configuration of the cache is performed through the PersonalizationService.properties file in <wps>/shared/app/config/services. The settings customized in this file are not migrated. You must manually migrate the settings changed in this file.
4.4.10 Running the import task for Personalization

The import task imports the transformed Personalization objects from the TempData directory into the WebSphere Portal V6 server repository. Ensure that your WebSphere Portal V6 server is running. There is no interaction with WebSphere Portal V5.1 server.
Running the import task

Run the import task for Personalization by typing the following in the <portal_server_root>\migration directory using the command-line interface on the WebSphere Portal V6 server (Figure 4-26): WPmigrate.bat migrate-pzn-import-51x
Figure 4-26 Import task for Personalization
Validation
Figure 4-27 Import task for Personalization: BUILD SUCCESSFUL message
75
Troubleshooting
If the WPmigrate command does not run successfully, check the output from the command, which is located in <portal_server_root>\log\MigrationTrace.log, and eliminate the issues. You can also check the WebSphere Portal V6 server logs.
4.4.11 Validating your Personalization

Your migration tasks for Personalization are complete. You can now open your browser to log in to your WebSphere Portal V6 server to confirm that the migration tasks have successfully migrated your Personalization workspace. Use your own test scripts and validation criteria, as recommended in 4.4.1, Preparing a checklist for Personalization validation on page 68 to perform some spot checks by previewing a selection of rules.
4.5 Postmigration tasks for Document Manager and Personalization

This section describes the postmigration tasks for Document Manager and Personalization. These tasks are optional, depending on your environment.
4.5.1 Removing passwords from the Document Manager and Personalization property files
The Document Manager and Personalization property files include the portal administrators passwords for both the WebSphere Portal servers. It is recommended that you remove these passwords.
4.5.2 Uninstalling the Document Tracking Tool

Now that you have completed Document Manager and Personalization migration, if you want to uninstall the Document Tracking Tool from the WebSphere Portal V5.1 server, perform the following tasks: 1. Shut down WebSphere Portal V5.1 server. 2. Follow the instructions that are packaged with the Portal Update Installer about how to uninstall the fix. 3. Restart WebSphere Portal V5.1 server. 4. Uninstall icmjcr.ear from WebSphere Portal V5.1 server. Consult your WebSphere Application Server Administrator, if necessary.
76
Chapter 5.
Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management
This chapter provides the best practices for migrating your IBM Workplace Web Content Management data from WebSphere Portal V5.1 to WebSphere Portal V6. This chapter explains the steps and provides validations along the way to help you complete a primary system Workplace Web Content Management migration. Important: If you have a decentralized authoring system, aggregate all the current data into a single server, using syndication, and then migrate your Web Content Management data. Refer to the IBM WebSphere Portal Version 6.0 Information Center for details: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/topic/com.ibm.wp.ent.doc/wp f/mig_wcm.html This chapter describes the Workplace Web Content Management migration process through the following topics: 5.1, Migration considerations on page 78 5.2, Workplace Web Content Management migration on page 79 5.3, Premigration tasks on page 80 5.3.3, Installing the Workplace Web Content Management migration tool on page 88 5.3.5, Migrating the Workplace Web Content Management user data on page 95 5.3.6, Migrating the Workplace Web Content Management rendering portlets on page 97 5.3.7, Postmigration tasks on page 100
77
5.1 Migration considerations

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

At a high level, core Workplace Web Content Management migration must transform Workplace Web Content Management assets from its old format to one that can be stored in the JCR. During the transformation, the migration must also parse all the existing references and update them to point to the new JCR representation of those assets. After transforming the format and updating references between the assets, the assets are imported into the JCR. Following is the process involved in the migration: 1. The first step in the migration is to export the data from the old repository, using export data. The export data will use the migration/exporter/lib directory and the property legacy.config.path from the migration.properties file. The migration/export/lib directory is used to access the Java archive (JAR) files required to access databases. Export data will use legacy.config.path to access the old connect.cfg and aptrixtjpe.properties. Using these two files, it will use the connection information to connect to the old repository. From connect.cfg, it will use the <databases> tag (Example 5-1), and from the aptrixjpe.properties, it will use jdbc.* properties (Example 5-2).
Example 5-1 The <databases> tag
<Databases> <jdbc:db2j:D:/WEBSPH~1.5/PORTAL~1/wcm/ilwwcm/db/WCMDB driver="com.ibm.db2j.jdbc.DB2jDriver" /> </Databases>

Example 5-2 jdbc.* properties
# jdbc persistency settings # the url to the database (i.e. jdbc:db2:ILWWCM) jdbc.url=jdbc:db2j:D:/WEBSPH~1.5/PORTAL~1/wcm/ilwwcm/db/WCMDB # the name of the user to connect to the database with jdbc.username=APP # the password of the user to connect to the database with jdbc.password=ReplaceWithYourDbAdminPwd # the database table which will be created to manage objects (optional). # if this parameter is not included, then the table name will default to "AJPE". jdbc.table=AJPE # the database table which will be created to manage resources (optional). # if this parameter is not included, then the table name will default to "AJPE_RESOURCES". jdbc.resources.table=AJPE_RESOURCES # the database schema under which the table will be created (optional). # if this is not specified, then this will default to the jdbc.username # parameter. #jdbc.tableSchema=[JDBC_SCHEMA] # The number of items to read ahead when reading all items for index recreation. # The default if not specified is 30. jdbc.readAhead=50 # the maximum size of a resource in MB that can be stored within the jdbc database (optional). # if this parameter is not included, then the maxSize will default to 16 MB jdbc.resources.maxSize=10 jdbc.dbms.name=Cloudscape jdbc.managerStrategy=com.aptrix.pluto.util.CloudscapeManagerStrategy
Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management
79
jdbc.byteContentManagerStrategy=com.aptrix.pluto.util.CloudscapeByteContentManager Strategy 2. After it has the connection information specified from the properties files, the exporter uses <portal_server_root>/migration/exporter/classpath.properties to find the JARs required by the connection information specified. If the migrator can connect, the data is exported to the path specified by the export.path property in migration.properties. 3. After the data is exported, transform the data into the new format. With JCR, some of the data structures have been replaced with standard JCR data structures. In other cases, some of the data structures have been split into multiple JCR data structures. Therefore, the number of items transformed might not match the number of items exported. The transform data action traverses through the export.path and transforms the necessary content, and places the transformed files into import.path. 4. After the content is transformed, it is ready to be imported into the JCR. This step takes the longest amount of time because of the work involved. The import requires the Workplace Web Content Management import servlet to import the content into the system. The Uniform Resource Locator (URL) to the import servlet is specified by the import.servlet.url property. The content is imported into a new library. This library is specified by the import.library.name property in migration.properties. 5. After the content is imported, it is necessary to configure the Authoring user interface (UI) to point to this library to view the content. There have been numerous enhancements to the Authoring UI, and therefore, the Authoring UI is not migrated. Instead, the new Authoring UI is configured to view the migrated content. 6. After the data is migrated, the viewing portlets must be configured to reference the updated portlets. There are several files that are used internally by the migration process to map old IDs to new IDs. These mapping files are used to reconfigure the viewing portlets to point to the new IDs of the Workplace Web Content Management assets. Two tasks exist for this step, configure-local and configure-remote. Both the tasks utilize XMLAccess to export the portlet configurations, and then replace the configurations to point to the migrated content, and finally use XMLAccess to import the portlet configurations.
5.3 Premigration tasks

The best practice is to use the Workplace Web Content Management tools to validate that your WebSphere Portal V5.1 server Workplace Web Content Management data is working properly before you export the data to the WebSphere Portal V6 server. Important: All the content that is on the WebSphere Portal V5.1 server will be disabled until you complete all the tasks described in this chapter. Refer to the WebSphere Portal for Multiplatforms Version 5.1 Information Center for further details: http://publib.boulder.ibm.com/infocenter/wpdoc/v510/index.jsp Following is a list of the Workplace Web Content Management tools: Reference Checker Site Checker Resource Checker Member Fixer
80
It is recommended that you take the following points into consideration: Understand that moving large amounts of data will take a long time. Ensure that you perform this task at a time that does not conflict with peak usage. Any password-protected file that is within the Web Content Manager must be removed before migration Any Personalization data that does not have a rule or content spot must be removed Install all the required fixes before migration. Not all the migration fixes listed in the following Web site are required (some depend on what additional components you are expecting to migrate): http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927 The fixes for Workplace Web Content Management are PK34286, PK30057, and PK30516.
5.3.1 Copying folders from WebSphere Portal V5.1 server to WebSphere Portal V6 server
In order to begin the Workplace Web Content Management migration, you must copy the config directory from the WebSphere Portal V5.1 server to a newly created temporary migration folder on WebSphere Portal V6 server. In our case, for the River Bend migration, we created a Web Content Management directory for good housekeeping: <portal_server_root>/migration/wcm Note: Copy the wcm db to the WebSphere Portal V6 server only when using Cloudscape for WCMDB.
Tip: Make sure that WebSphere Portal server has stopped, in order to prevent locked files when copying the Cloudscape database to the WebSphere Portal V6 server. If your Web Content Management migration is using the Cloudscape database, you must first copy two folders, config and ilwwcm, from your WebSphere Portal V5.1 server to WebSphere Portal V6 server. These folders are located in <portal_server_root>\wcm\ and will go into a newly created temporary directory called wcm under the migration directory of your WebSphere Portal V6 server.
81
Perform the following tasks: 1. Create a directory under <portal_server_root>\migration\ called wcm (Figure 5-1).
create new directory
Figure 5-1 Creating the wcm directory on WebSphere Portal V6 server
82
2. Copy the config and ilwwcm folders to the newly created directory (Figure 5-2). Note: Skip the copy ilwwcm step if you are not using Cloudscape for your Workplace Web Content Management database.
Copy to WebSphere Portal V6 server
Figure 5-2 Copying the config directory
83
Copy only ilwwcm if you are using out-of-the-box Cloudscape WCMDB. Figure 5-3 shows copying the WCMDB if you are using the Cloudscape database.
Copy this directory ONLY if you are using cloudscape database
Figure 5-3 Copy WCMDB if you are using the Cloudscape database
Updating the property files before you run the migration

Depending on which data repository the old system is using, you must copy the Java Database Connectivity (JDBC) driver to the <portal_server_root>/wcm/migration/exporter/ directory of the WebSphere Portal V6 server and then update the exporter.classpath property (Example 5-3) within that directory with the value that corresponds to the version of the data repository. If the drivers already exist in a path located on the WebSphere Portal V6 server, it is easier to simply update the exporter.classpath property by appending the path. In the River Bend scenario, DB2 was used to store the Web Content Management data and the portal configuration database. To connect to the Web Content Management database of WebSphere Portal V5.1 server from WebSphere Portal V6 server, the DB2 Type 4 JDBC driver was used. Using the DB2 Type 4 JDBC driver (held in the db2cc.jar in the <db2_root>/java) eliminates the necessity to catalog the database locally. Instead, the JDBC URL (specified in aptrixjpe.properties) includes the host name to the remote database, which will then allow you to proceed with the migration. Tip: If you are using DB2 Type 2 JDBC drivers, make sure the database is cataloged and that the relevant drivers are available before you begin the wcmmigrate tasks. However, whenever possible, use the Type 4 JDBC drivers.
Example 5-3 Updating the exporter classpath.properties
exporter.classpath = exporter/lib/ilwwcm-migration-exporter.jar:lib/ilwwcm-migration.jar:exporter/lib/d b2j.jar:exporter/lib/exclude-contentapi.jar:exporter/lib/ilwwcm-commons-copyright.
84
jar:exporter/lib/ilwwcm-commons-properties.jar:exporter/lib/ilwwcm-commons-utils.j ar:exporter/lib/ilwwcm-commons-version.jar:exporter/lib/ilwwcm-commons-xmlpersiste ncy.jar:exporter/lib/ilwwcm-framework.jar:exporter/lib/ilwwcm-server.jar:exporter/ lib/j2ee.jar:exporter/lib/jcr.jar:exporter/lib/wp.base.jar:exporter/lib/wp.user.ap i.jar
(If you are using DB2 jdbc drivers, add the following string to the end of classpath=) exporter/lib/db2cc.jar:exporter/lib/<license that in is in the <runtime Server>SQLLIB\java> Here are the possible licenses that you will might find in that directory db2jcc_license_cu.jar or db2jcc_license_cisuz.jar
(If you are using Oracle jdbc drivers, add the following string to the end of classpath=) exporter/lib/classes12.jar
(If you are using SQL jdbc drivers, add the following string to the end of classpath=) exporter/lib/mssqlserver.jar:exporter/lib/msbase.jar:exporter/lib/msutil.jar You must then configure aptrixjpe.properties and connect.cfg to the current migrated environment. In both the properties files, ensure that the JDBC driver equals the data repository version that you are using, and that it points to the wcmdb on the old system. This file must be updated only in two situations: The Workplace Web Content Management repository is a local Cloudscape DB, and therefore, paths to the local Cloudscape DB must be updated. Use Type 4 drivers when the DB2 database has not been cataloged locally. If you are using DB2, configure aptrixjpe.properties and connect.cfg to the current migrated environment as follows: aptrixjpe.properties Ensure that jdbc.url=jdbc:db2://<db2 host name>:<port number>/wcmdb is configured to point to the database of the old system and that there are no spaces before or after the URL. connect.cfg Ensure that <jdbc:db2://<db2 host name>:<port number>/wcmdb driver="com.ibm.db2.jcc.DB2Driver /> is configured to point to the database of the old system and that there are no spaces before or after the URL. Also ensure that the driver= <jdbc driver of your RDBMS> is using the correct one and not the default Cloudscape driver (com.ibm.db2.jcc.DB2Driver). Note: The port number for DB2 on your new system can be found under %systemroot%/system32/drivers/etc/services on Windows systems and /etc/services on UNIX systems. If you are using the out-of-the-box Cloudscape Web Content Management database, make sure that you are pointing to the database on the new system that you copied from the old system.
85
You must update the migration.properties file that is located in the portal_server_root/wcm/migration/config directory on WebSphere Portal V6 server before running the Workplace Web Content Management migration commands. In the file, it is necessary to confirm that the parameters are set and modified, based on Table 5-1. Following is what you should look for in the properties file to update it for migration: <name>.path = C:/Websphere/PortalServer/migration/wcm/<name> Tip: Use forward slash in path names. Both Windows and UNIX can handle forward slashes.
Table 5-1 Explanation of the migration.properties file migration.properties file export.path import.path summary.path Explanation The path on the local file system where exported data is saved The directory on the local file system where transformed data is saved The path on the local file system where summary configuration files will be created. These files will be used when migrating a secondary system. The path on the local file system where the old Web Content Management configuration is located The URL of the import servlet running on the new system. Replace local host with the appropriate host name for the new system. The name of the library created during import
legacy.config.path
import.servlet.url
import.library.name
Finally, increase the total transaction lifetime timeout of your new WebSphere Portal server to at least 480 seconds through the WebSphere Application Server administrative console. Navigate to Application Servers Server Container Services Transaction Service. Make a note of the current total transaction lifetime timeout so that it can be restored after you have completed the migration. For more information, refer to the topic Migrating User Profiles in the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en t.doc/wcm/wcm_migration_users.html
Restart the Portal Application Server before you begin the wcmmigrate tasks.
Important: The WebSphere Portal server must be running on WebSphere Portal V6 before you begin the wcmmigrate tasks.
86
5.3.2 Preparing a checklist for Workplace Web Content Management validation

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

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

Performing this task validates that the current premigration tasks were updated correctly, Go to the portal_server_root/wcm/migration directory and run this command from the command line (Figure 5-7): wcmmigrate.bat validate -user <username> -password <password>
Figure 5-7 Running the wcmmigrate.bat validate command
If you have issues with this command, review the trace0.log file located in the portal_server_root/logs directory. Figure 5-8 shows an example of an error that occurs when you have problems with your property files.
Figure 5-8 Error when running the validate command
To resolve this issue, review your property files for mistyping or misconfigurations. Table 5-3 provides you with possible resolutions to the issues shown in Figure 5-8 or if you encounter issues when running other wcmmigrate commands.
Running the wcmmigrate tasks

The best practice is to run the commands that are in the wcmmigrate script one at a time and verify that each step is successful. This eliminates hours of waiting to see if the import completes successfully. Another reason is that is allows you to run the import command during off peak hours to optimize performance. Tip: wcmmigrate without options lists the available commands. Table 5-2 describes the commands and what they accomplish.
Table 5-2 The wcmmigrate commands wcmmigrate command Validate What it accomplishes Confirms that the migration.properties files, network connectivity, and user permissions are correctly configured. This command requires that you add a user name and password to the command. Provides an estimate of the time taken and space required for the data migration
estimate-data
89
wcmmigrate command export-data transform-data import-data
What it accomplishes Exports items from the old system Transforms exported items so that they are ready to be imported into the new system Imports the transformed items. This requires a user name and a password. a
a. This command can take a long time, depending on how much data you are importing.
Resuming or restarting the wcmmigrate commands

If your command fails or there are issues with your network connection, you can either restart or resume from the task where failure occurred. Depending on where your task failed, it might be necessary to verify whether the required machines are running. Table 5-3 provides information to help you overcome the possible errors that might occur during the migration task.
Table 5-3 Troubleshooting for possible errors Possible error Fails on Validate Possible cause Make sure that the migration.properties, legacy.config.path, is pointed to the correct set of config files Make sure that the config files point to the correct database. If Cloudscape is being used, ensure that the database was copied and that the config files point to it. Ensure that the database machine is started and is accessible from the WebSphere Portal V6 server Ensure that export.path points to a usable directory structure, for example, if using UNIX, do not set the export path to c:\export Ensure that export.path has enough space for exporting all the Workplace Web Content Management assets Ensure that the database server is running and is accessible Ensure that import.path has enough space for transforming all the Workplace Web Content Management assets Ensure that the Workplace Web Content Management V6 database server is running Ensure that the WebSphere Portal V6 server is running Ensure that the WebSphere Portal server config, configure-wcm-migration, has been run Ensure that the WebSphere Portal V6 server is running Ensure that the user specified in the wcmmigrate task has the rights to execute the xmlaccess tasks
Fails on Export
Fails on Transform
Fails on Import
Fails on Configure-local
90
Possible error Fails on Configure-remote
Possible cause Ensure that the WebSphere Portal V6 server is running Ensure that the summary.path is correct and has been copied from the Web Content Management V6 server Ensure that the <WebSphere Portal Server>/wcm/migration/remote_rendering.pr operties has been updated with the correct values. Using fully qualified host names is recommended.
In the portal_server_root/wcm/migration directory, issue the following command to restart or resume the tasks that were running: wcmmigrate -user <username> -password <userPassword> <command> -restart Issue the following command to resume the tasks if the tasks timed out or the networks failed: wcmmigrate -user <username> -password <userPassword> <command> -resume Figure 5-9 shows the resume or restart command.
Figure 5-9 Resume or restart command
Running the commands one at a time

Because of the complexity of the Workplace Web Content Management migration, the best practice is to run the commands one at a time as against using the all parameter. The following commands are run in the portal_server_root/wcm/migration directory from a command prompt: 1. Run the following export command: wcmmigrate export-data Note: Ensure that you see the Command Successful message before you move to the next step. If you have a failure on your hands, go to the log directory to pinpoint the issue. 2. Run the following transfer command: wcmmigrate transform-data Note: Ensure that you see the Command Successful message before you move to the next step. If you have a failure on your hands, go to the log directory to pinpoint the issue.
Note: As you learned in 5.1, Migration considerations on page 78, these numbers will not match the numbers reported on import.
91
3. Run the following import command: wcmmigrate import-data Notes: This step is the one that takes the longest amount of time, and must be completed successfully. It takes many hours, possibly days to complete. It is very resource intensive and long-running. Because this task runs against a URL, watch out for timeouts. When running this command, consider the volume of data and the space that you currently have on the system that you are migrating.
Following the step-by-step tasks

After completing all the tasks, configure the portlet to the import library data from the migration.properties file (import.libray.name=<name of Library) so that you can view the migrated information. Perform the following tasks: 1. Log in to the WebSphere Portal V6 server and select Administration, as shown in Figure 5-10. Click here
Figure 5-10 Launching the Administration page
92
2. Select Launch Web Content (Figure 5-11).
Click here
Figure 5-11 Launching the Web Content page
3. Select Web Content Management and click Continue to launch the Library page (Figure 5-12).
Click the WCM tab Click here to launch the Library Figure 5-12 Launching the Library section
93
4. In the Library page, add a library by selecting the relevant library and clicking Add. To remove a library, select the corresponding library and click Remove (Figure 5-13). Click OK after completing the task.
Figure 5-13 Adding the migrated library
5.3.4 Installing the authoring portlet to the Web Content Management page
One of the components that does not migrate to the WebSphere Portal V6 server is the Authoring Portlet. In order to administer authoring that was on the page in WebSphere Portal V5.1 server, add the new Workplace Web Content Management Authoring Portlet to the page. Perform the following tasks to add the new portlet: 1. Go to the Portal administration section and select Manage Pages. 2. Navigate to Select Page Content Root My Portal Name of page Web Content Management. 3. When you are there, click the pencil icon. 4. Click Add Portlet.
94
5. In the page that opens (Figure 5-14), search for Web Content Authoring. In the list that is displayed, select Web Content Authoring and click OK to add the portlet to the page.
Figure 5-14 Adding the Web Content authoring portlet.
6. Work through the content in the Authoring Portlet to make sure that everything is there. 7. Preview the content, especially with regard to Personalization and Document Manager. 8. Validate the security, the templates, the workflow, and so on.
5.3.5 Migrating the Workplace Web Content Management user data

After the completion and verification of your data, update the portal user data so that the portal users can use the migrated data. In some Web Content Management configurations, users can customize content display based on categories or key words. Their personalized list of categories and key words are stored within the Portals WebSphere Member Manager lookaside tables. The WebSphere Member Manager attributes that contain the users categories and key words are WCM:CATEGORIES and WCM:KEYWORDS respectively. The WCM:CATEGORIES contain IDs to the category objects in Web Content Management. These IDs must be updated to point to the new IDs for the migrated categories. This task updates these IDs. Note: Migrate WebSphere Member Manager before migrating the user profiles. For details, refer to the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp .ent.doc/wpf/sec_mig_roles.html
95
Questions to answer before running the -user command

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

Now that you have successfully migrated the Workplace Web Content Management content from WebSphere Portal V5.1 server to WebSphere Portal V6 server, configure or reconfigure your rendering portlets to use the newly imported Workplace Web Content Management. Note: If you have a small amount of rendering portlets, re-create, rather than migrate the rendering portlets to the new system. Before you begin to import the rendering portlets, identify whether you are going to import to the primary system or the secondary system. If you are working in a clustered environment, you have to run the commands on the primary node only. In the unlikely case that you are using a secondary server, copy the configuration files from the primary server to a folder, portal_server_root/migration/wcm (which you must create on the secondary system), and follow the instructions provided in Updating the property files before you run the migration on page 84 prior to running the following command from the portal_server_root/wcm/migration directory: wcmmigrate configure-local -user WebSphere Portal Serveradmin -password WebSphere Portal Serveradmin Note: Ensure that you see the Command Successful message before you move to verify the configuration of the local rendering portlet. Remote rendering portlets require additional steps to migrate because they contain information pertaining to the Workplace Web Content Management Rendering Server. Before migrating the remote rendering portlets, consider the following questions (the best practices are provided with each of these questions): Have you migrated the Workplace Web Content Management Rendering Server that the Web Content Management V6 remote rendering portlets will be configured to view? It is best practice to keep all software levels equal. Is the Workplace Web Content Management Rendering Server clustered? If yes, using the Web server address is sufficient to configure the remote rendering portlets. Will the remote rendering portlets exist in a cluster? If yes, the migration tasks will only have to be executed on the primary node. Will the remote rendering portlets point to multiple Workplace Web Content Management Rendering Servers? If yes, more edits of the remote_rendering.properties must take place. Can the Portal V6 environment communicate to the Workplace Web Content Management Rendering Server? Ensure that firewalls, virtual IPs, and so on have been configured to allow for connection between the remote rendering portlets and the Workplace Web Content Management Rendering Server.
97
After you have answered these questions, you are ready to configure the remote rendering portlets: 1. Edit portal_server_root/wcm/migration/config/remote_rendering.properties. 2. If you have multiple Workplace Web Content Management Rendering Servers, change the remote.host.base.path.list value from all to the values of the previous hosts that you want to configure with the new Workplace Web Content Management Rendering Server host. 3. Uncomment the WCM_REMOTE_HOST_BASE_PATH and put in the correct value to the new Workplace Web Content Management Rendering Server. 4. Copy the summary data from the Workplace Web Content Management Rendering Server to the Portal server. 5. Update portal_server_root/wcm/migration/config/migration.properties by changing the property, summary.path, to point to that directory. 6. Run the following command: wcmmigrate configure-remote
98
Example: Consider an environment where you have two Workplace Web Content Management Rendering Servers that must be migrated. The URLs for the old Workplace Web Content Management Rendering Servers are http://old_wcm_1 and http://old_wcm_2. The URLs to the new Workplace Web Content Management Rendering Servers are http://new_wcm_1 and http://new_wcm_2. To migrate the remote rendering portlets that point to http://old_wcm_1 to point to http://new_wcm_1: 1. Edit the value of remote.host.base.path.list to http://old_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties. 2. Edit the value of WCM_REMOTE_HOST_BASE_PATH to http://new_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties. 3. Copy the summary data from the new_wcm_1 server to a directory on the Portal server. 4. Edit the portal_server_root/wcm/migration/config/migration.properties and change the summary.path point to the data copied in step 3. 5. Run the following command: wcmmigrate configure-remote Repeat the same process to migrate the remote rendering portlets that were configured for http://old_wcm_2 to point to http://new_wcm_2. If you want to migrate both the remote rendering portlets that were configured for http://old_wcm_1 and http://old_wcm_2 to point to http://new_wcm_1, perform the following tasks: 1. Edit the value of remote.host.base.path.list to http://old_wcm_1,http://old_wcm_2 in portal_server_root/wcm/migration/config/remote_rendering.properties. 2. Edit the value of WCM_REMOTE_HOST_BASE_PATH to http://new_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties. 3. Copy the summary data from the new_wcm_1 server to a directory on the Portal server. 4. Edit the portal_server_root/wcm/migration/config/migration.properties and change the summary.path point to the data copied in step 3. 5. Run the following command: wcmmigrate configure-remote 7. The last step is to perform a full function check on WebSphere Portal V6 server before notifying your users. Important: The numbers reported will be wrong, possibly 0. This is because it actually runs XML access. As you learned in 5.1, Migration considerations on page 78, these numbers will not match the numbers reported on import.
99
5.3.7 Postmigration tasks

The migration process for Workplace Web Content Management does not automatically update the Web content to use the new features in WebSphere Portal V6. After migrating the content, be sure to configure the Web Content Management user interface (UI) to view the newly migrated library. Unlike the old Workplace Web Content Management repository, there is no easy way to view a content item directly from the database. With the new JCR repository, many nodes represent one Workplace Web Content Management asset. Many improvements have been made to the Workplace Web Content Management authoring environment in order to ease the content creators experience. Features such as inline edit, custom templates creation, and Launch page configurations have been added to simplify the process of adding content. Inline edit is where a link to edit a piece of content will be displayed when a content author is viewing the contents on a page. When the link is selected, the content automatically opens in the authoring template and is ready for editing. The creating custom templates feature has also been added to the authoring UI. When defining an authoring template, the Web Content Management administrator can now override certain fields with JSPs. JSPs provide a multitude of customization options. This function can be used for the following: Formatting the field to create a uniform look Personalizing the list of choices a user can choose from when inputting the field Performing validation by adding Javascript functions Performing queries on external repositories to pull in data into the field, for example, pulling in IBM Content Manager references into Workplace Web Content Management content. Configuring a Launch page can also greatly enhance the content contributors experience. The Launch page can also be a JSP, which provides more flexibility. By configuring a Launch page, the content contributor will not see the typical Explorer view. Instead, the Launch page will be shown. This function can be used for the following: Providing a personalized list of links to authoring templates to create content, using remote actions Providing a list of links to content that must be updated or approved Workplace Web Content Management V6 provides a number of capabilities in addition to its authoring environment enhancements. The three major additions are Library enhancement, Link and Stylesheet components, and Referential integrity. Libraries allow for an added separation of content. In the earlier releases, content was stored in one central repository. With Libraries, you add an additional layer to this repository to group relevant content together. Each library has its own set of security. The Web Content Management UI can be configured to show only certain libraries. Libraries can be used for the following: Grouping the shared components into a library referenced from other libraries Configuring a library per department Configuring a library per new Web site release
100
The Link component allows the content creator to manage links as a Workplace Web Content Management asset. These links can be reused in content or presentations. The link component provides a more structured component to link to both internal Workplace Web Content Management assets and external URLs. The Stylesheet component allows the content contributor to manage the stylesheet as a separate reusable asset. It provides for cascading stylesheets and other typical features of stylesheets such as media-type definition. Referential integrity is a nice addition to Web Content Management. It allows users to view content being referenced from other content. It also provides the user with a choice when deleting a content item that is referenced by another content item. This is a big change from earlier releases, where deleting a reference content item left broken links. There are many more enhancements to Web Content Management, including better Personalization and Document Manager integration, improved rendering performance, clustering and failover, and so on. For more recommendations about updating the old Web Content to take advantage of the new Workplace Web Content Management features, refer to the IBM WebSphere Portal Version 6.0 Information Center to utilize the new features of Workplace Web Content Management: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en t.doc/wcm/wcm_migration_post.html
Primary and secondary Web Content Management migrations

This section provides information about primary and secondary Web Content migrations. Note: This section can be disregarded if only one instance of WebSphere Portal with Web Content Management is to be migrated. A primary Web Content Management migration is the first instance to be migrated. It consists of all the steps in Web Content Management migration. If subsequent WebSphere Portal instances require migration, and these instances contain pages with Web Content Management portlets, then other techniques are required to migrate Web Content Management on these systems. These subsequent migrations are referred to as secondary migrations. The data within the Web Content Management repository requires migration. In a secondary migration, this is typically accomplished by replicating the data from the primary instance to the secondary, with syndication. Syndication ensures that the identity of each piece of content is consistent across each syndicated repository. The alternative to syndication is replicating the database containing the JCR, using database-specific techniques. Consult your Database Administrator (DBA) if you are interested in a database-specific replication. Web Content Management user data is normally migrated using the wcmmigrate users command, as shown in 5.3.5, Migrating the Workplace Web Content Management user data on page 95. This also works in a secondary migration. However, the summary data from the primary migration is required. The summary data is located in a directory on the primary system. This data must be copied to the local machine, and then the migration tool on the local machine must be configured to ensure that it correctly identifies the summary data. After this procedure is completed, the wcmmigrate users command functions according to that described in 5.3.5, Migrating the Workplace Web Content Management user data on page 95.
101
To copy the summary data, use the following procedure: 1. Open migration.properties on the primary system, and find the summary.path property. 2. Copy the data in the directory referred to by the summary.path property from the primary machine to the local (secondary) machine. 3. Open migration.properties on the local machine, and edit the summary.path property to refer to the copied summary data. Web Content Management rendering portlets must be reconfigured. Perform this task by using the wcmmigrate configure-local and configure-remote commands, as long as the summary data is available. In the River Bend example, the commands behaved as described in 5.3.6, Migrating the Workplace Web Content Management rendering portlets on page 97. The alternative to using the wcmmigrate commands is to reconfigure the rendering portlets manually.
Removing the Workplace Web Content Management migration tool

Run the following command to remove the Workplace Web Content Management migration tool: remove-wcm-migration
102
Appendix A.
Troubleshooting and other tips

This appendix provides troubleshooting and other information relevant to the migration process.
103
Business portlets not migrated during portal migration

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

This section walks you through an example of how to temporarily remove the privileged user access to the portal by using the xmlaccess tool. In some WebSphere Portal documentation, this is referred to as putting the portal in read-only mode. This is how customizations were set in the River Bend portal. It is a simple but brute force method. For large environments, an experienced Portal administrator might spend time optimizing the import file. Doing so decreases the time the import task takes to run, although the outcome is the same. The steps omit common changes that may be required because of missing Web archive (WAR) files in the installableApps directory because of predeployed applications. Test this process in the staging environment before using in the production environment. The task must be run during some planned downtime of the portal. It causes a load on the server, and consequently, the changes made in step 1 and step 2 in the process described here will be lost: 1. Export the production WebSphere Portal server configuration using Export.xml in <portal as shown in Example A-1.
Example: A-1 Exporting the production WebSphere Portal server configuration
<portal_server_root>\bin>xmlaccess -in ..\doc\xml-samples\Export.xml -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -out exportAllResults.xml 2. Back up the exportAllResults.xml. This backup can be used later to return the portal to its original configuration. 3. Using a text editor, find where the Privileged User is set for access to portal artifacts, as shown in Example A-2.
Example: A-2 Finding where the Privileged User is set for access to portal artifacts
**They presumably will need user access added, unless all authenticated is used** <access-control externalized="false" owner="undefined" private="false"> <role actionset="Privileged User" update="set"> <mapping subjectid="uid=davidbrent,cn=users,ou=global,dc=riverbend,dc=com" subjecttype="user" update="set"/> </role> </access-control> 4. Change the update parameter on the actionset and the mapping tags, as shown in Example A-3.
Example: A-3 Changing the update parameter on the actionset and the mapping tags
<access-control externalized="false" owner="undefined" private="false"> <role actionset="Privileged User" update="remove"> <mapping subjectid="uid=dominic,cn=users,ou=global,dc=riverbend,dc=com" subjecttype="user" update="remove"/> </role> </access-control>
Appendix A. Troubleshooting and other tips
105
5. Depending on your environment, you may want to repeat this process for other types of user access that may allow customized pages. In our example, we worked on the basis that it is safe to leave the additional access controls as they are, as shown in Example A-4.
Example: A-4 Leaving the additional access controls as they are in the River Bend example
<role <role <role <role <role <role
actionset="Privileged User" update="set"> actionset="Administrator" update="set"> actionset="Manager" update="set"> actionset="Editor" update="set"> actionset="Delegator" update="set"> actionset="Security Administrator" update="set">
6. Save this modified file with a new name, for instance, privUsersRemoved.xml, and import it back into the portal, as shown in Example A-5.
Example: A-5 Saving the modified file with a new name and importing it back into the portal
<portal_server_root>/bin xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -in privUsersRemoved.xml -out resultsOfPrivUserRemoval.xml 7. To return the WebSphere Portal server to its original configuration, run the backed up export file, as shown in Example A-6.
Example: A-6 Running the backed up export file
<portal_server_root>/bin xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -in ExportAllBackUp.xml -out resultsOfPrivUserRemoval.xml
Delayed clean-up
When pages are deleted from the WebSphere Portal server, removing them from the system completely can be a resource-intensive task. WebSphere Portal server allows administrators the facility to delay the complete clean-up of resources until a convenient time with low-user traffic. By default, resources are not removed completely initially. Instead, they are inactivated and removed from view. By default, the clean-up schedule is every Saturday at 8 p.m., but this is fully configurable. In our example, when migrating to our WebSphere Portal V6 server, it was occasionally necessary to delete large numbers of resources. In our environment, this was primarily to observe the effect of rerunning the tasks, applying the xmlaccess scripts, and so on. Under these circumstances, it is a best practice to turn off the delayed clean-up. It must be reapplied in production.
Changing the delayed clean-up property

In WebSphere Portal V5.1, the delayed clean-up is controlled by a properties files held on each node in the environment. In WebSphere Portal V6, these properties are managed by the Deployment Manager cell. They can be updated by going through the WebSphere Application Server admin console, or by updating a properties file on one of the nodes and
106
running a task. Not all the properties than can be set exist in the Admin console. In such a situation, the default values are automatically used. In order to avoid adding them to the wrong place or misspelling them, it is a best practice to update properties through the update configuration task. This following steps describe how to achieve this: 1. Use a text editor to open the DataStoreService.properties file under <portal_server_root>\config\properties. 2. Uncomment the scheduler.cleanup.enabled property (by removing the # character) and change the value to false. Save and close the file. 3. Run <portal_server_root>\bin\WPSconfig update-properties. 4. If you are running WebSphere Portal in a cluster configuration, replicate your changes to the cluster. 5. Restart the WebSphere Portal server.
Forcing immediate clean-up with xmlaccess

An immediate clean-up of the deleted WebSphere Portal server artifacts can be forced by using an xmlaccess command that uses the task.xml file from the xml-samples directory. This command can be configured to change the scheduling of the clean-up task. However, if it is run as-is, it causes the clean-up to start immediately. Example A-7 shows the command we ran within the River Bend environment.
Example: A-7 Forcing an immediate clean-up of the deleted WebSphere Portal artifacts in the River Bend environment
<portal_server_root>\bin>xmlaccess.bat -url http://m51e.cam.itso.ibm.com:9081/wps/config -user wpsadmin -pwd wpsadmin -in ..\doc\xml-samples\Task.xml
List of admin portlets in WebSphere Portal V5.1

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

Following is a list of the V6 admin portlets: portletWiring Portlet Manager Manage My Portlet Applications Manage My Portlets Manage Webservices Themes And Skins Manager Edit Layout Concrete Properties Portlet Manage Pages Organize Favorites Application Layout FrequentUsers Welcome Portlet Credential Vault Global Settings Manage Markups Appearance Set Permissions Resource View User and Group Permissions Policy Resource View Policy Editor Manage Users and Groups Enable Tracing Manage Clients Unique Names URL mapping Welcome to WebSphere Portal Information Portlet Web Clipping Editor Manage Collections Search Manage Document Libraries 108
Document Picker RSS Portlet Import XML Manage Virtual Portals Login Portlet Edit My Profile Manage Seed List Manage Search Admin Portlet Sitemap Search and Browse Content Palette Template Catalog Manager Parameters Properties portlet Roles portlet Community Application Catalog People Finder JSR168
Migrating the search collections

Employees of the River Bend company must be able to search the Web site of another company called itsoco. Itsocos Web site uses basic authentication. The employees must also be able to search the River Bend Web site itself. Therefore, the employees have defined two search collections. These collections are used by the Search and Browse portlets. To demonstrate the migration process, the itsoco search collection migration is described here.
Exporting the collection from WebSphere Portal V5.1 server

Perform the following tasks: 1. Navigate to Portal Settings Search Administration and select itsoco collection. 2. Click Import or Export. 3. Enter a fully qualified file name with .xml extension, and click Export (Figure A-1). Attention: All the directories in the path must exist. They will not be created by the export process.
Figure A-1 Exporting a collection
Successful export is indicated by the following message: Export index OK
109
4. Copy this XML file to a directory of your choice on the WebSphere Portal V6 server. Important: Do not copy the collection directory.
Creating the collection in WebSphere Portal V6 server

At this point, search management has moved from its location in WebSphere Portal V5.1 server, and can now be found at Search Administration Manage Search Search Collections. To define the itsoco collection in WebSphere Portal, perform the following tasks: 1. Click New Collection. This displays the New Collection page (Figure A-2).
Figure A-2 The new collection page
2. Create an empty shell into which the exported itsoco collection can be imported. Some, but not all, parameters must match the values from the WebSphere Portal V5.1 server. The parameters for defining a search collection are: Location of Collection This is the directory where the collection will reside. This does not have to exist and it does not have to match the old location. Name of Collection Fill this in with the collection name. This does not have to match the old setting. Description of Collection This is optional. Fill this in with the collection description. The description can match the old setting, but does not have to.
110
Specify Collection Language Select this to match the old setting. Select Categorizer This is optional, and will be overwritten by the import. Select Summarizer This is optional, and will be overwritten by the import. Remove common words such as in, of, on, and so on from queries Check or uncheck this to match the old setting. Figure A-3 shows the itsoco search collection redefined for the WebSphere Portal V6 server. Click OK. Important: Do not create collection sources. They will be created by the import. The import will fail if a collection source is defined.
Figure A-3 The itsoco collection defined
111
3. The Manage Search window opens (Figure A-4). In this window, click the icon (highlighted in Figure A-4) for Import or Export collection. This is the file exported and copied to the WebSphere Portal V6 server, as described in Exporting the collection from WebSphere Portal V5.1 server on page 109.
Figure A-4 Readying to import the itsoco collection
4. Enter a fully qualified name of the exported XML file, as shown in Figure A-5. (There is no facility to browse to find the location of the XMLM file.) Click Import. Restriction: You cannot import into a collection that has already been populated. The import command will show an error message. If you have to reimport, delete and re-create the collection.
Figure A-5 Specifying the location of the XML file for import
112
This returns you to the Manage Search page with a message confirming successful import, as shown in Figure A-6. Note that the number of documents shows 0 at this point.
Figure A-6 Import successful
5. At this point, WebSphere Portal fetches the documents from the migrated URLs and rendexes them in the background. When you click Refresh, as displayed in Figure A-7, the number of active documents increases. You can now browse the documents.
Figure A-7 Document count refreshed
113
The itsoco Web site uses basic authentication. The values entered in WebSphere Portal V5.1 server for the itsoco collection has migrated automatically, as can be seen from Figure A-8.
Figure A-8 Security has migrated
Restriction: When you import a portal site collection from WebSphere Portal V5.1 server to WebSphere Portal V6 server, the collection configuration data is imported, but not the document URLs. Therefore, to enable users to search the portal site collection on the target portal, you can either import the portal site collection and then manually start a crawl, or re-create the portal site.
114
6. If you have a Portal Search Collection for your own Portal site and have moved to a new server, the host name in the URL for the site would probably have changed. In such a situation, you must re-create the content source from the scratch. If the collection does not work after migration, as happened in one of the tests in our example, it is recommended that you verify the address of the content source. This will test to see if the search engine is able to connect to the site being searched. Navigate to Manage Search Search Collections and click the itsoco collection. 7. This displays the window shown in Figure A-9. Click the wrench icon highlighted in Figure A-9 to verify the address.
Figure A-9 Verifying the address of the content source
8. The results are displayed, as shown in Figure A-10. In our example, we saw the following message: EJPJP0011W: Connection failed, Host: http://9.33.85.117/itsoco/index.html, Host might be down.
115
Use a browser from your workstation to see if there are any issues with the itsoco site. In our case, we found that the itsoco server was not running. After it was restarted, we repeated the address verification in WebSphere Portal server and received the following message: EJPJB0025I: Content source http://9.33.85.117/itsoco/index.html in collection itsoco collection is OK.
Figure A-10 Connection failed
116
9. Click the icon highlighted in Figure A-11 to refresh the collection data for the itsoco collection.
Figure A-11 Refreshing collection data for itsoco collection
10.Click OK to dismiss the pop-up warning about CPU usage and, shortly afterwards, refresh the page. In our case, we saw that the documents had been collected, as shown in Figure A-7 on page 113.
117
118
Appendix B.
Extending the WebSphere Portal migration framework

The WebSphere Portal migration framework is designed to be extended. The example information in this appendix provides guidance about extending the migration framework. There are two types of extensions, core migration extensions and a migration framework extension. Core migration extensions are currently limited to the core migration tasks. However, the migration framework extension is not limited and can be used to implement any custom migration process. The most common reason for extending the framework is to provide custom filtering or transformation of the data to be migrated. Following are the topics discussed in this appendix: Overview on page 120 Framework extensions on page 120 Plugging into the framework on page 122 Migration filters on page 125 Component Directory Required Files Creating the River Bend migration sample plug-in on page 127
119
Overview
This appendix describes how to plug into the migration framework, the ways in which your tasks can get called, and the exit points provided by the framework. The migration framework consists of a shell script, WPmigrate, which sets up the class paths and executes tasks. Components are plugged into the framework by defining Ant tasks in a mig_ant.xml file and exporting them by specifying the exported targets in the mig_description.xml file. The mig_description.xml file is processed by the migration preprocessor to dynamically create an Ant build file called mig_ant_driver.xml. The exported tasks are placed in the mig_ant_driver.xml file and are called by the user or by the core migration framework. The tasks that can be called are provided by the migration components. There is one migration component that is special, the wp.migration.core component. This component contains the high-level tasks for exporting information from the previous portal and importing the data into the current portal. The core tasks implement the migration framework and call the pluggable custom migration tasks that provide the logic required by various components to transform the previous portal data into a format that can be accepted by the current portal. The framework allows for a seamless and simplified migration flow for the user.
Framework extensions
The framework supports five extension points. These extension points are in the core migration component and are called the core migration extensions. Four of these points allow components to seamlessly integrate into the base core migration targets. Components can specify which targets are to be called by each extension point, by setting various attributes when their targets are exported. The same target can be called once or multiple times by the framework. The fifth extension point is in the overall framework itself, and is called the migration framework extension. The migration framework extension point allows components to plug in and provide command-line accessible targets to the user. These targets can do anything that is required by the component and are not dependent on the core migration tasks. The Document Manager and Personalization component migration use the migration framework extension point by providing command-line callable targets to migrate the Java Content Repository (JCR) data.
Core migration extensions

Following are the four core migration extensions: Pre-export Filter Preimport Postexport
The pre-export extension

The pre-export extension is called prior to exporting the previous portal's data. It must be used to export a subset of information to possibly determine if there is a component configured on the previous portal that is not configured on the current portal. This gives a component a chance to halt the migration before the export process begins, allowing the user
120
to correct any configuration problems in the current portal. (In future releases, this task might be used to remotely collect specific property files, properties, or other data to allow the detection of configured components and possibly allow automated configuration on the current portal.)
The filter extension

The filter extension is called prior to the preimport task. This extension allows each component the opportunity to modify the XmlAccess import Extensible Markup Language (XML) file or prepare any template files for import. No actual import must be performed during the execution of the filter extensions. There are some existing filtering tools that allow elements that have object IDs to be filtered, based on attributes. Components will use this target to modify the XmlAccess import file when there are changes to portlets, such as portlets moving from the IBM application programming interface (API) to JSR 168, changes in settings, changes in Web archive (WAR) file names, changes in configuration properties, or modifications to Web applications, such as the addition or removal of servlets or portlets. The main purpose of this task is to allow the components to transform their specific portlet data in the XmlAccess import file from a earlier version of the Portal into something that is consumable by the current version of the Portal and its portlets.
The preimport extension

The preimport extension is called prior to the core migration import task. Components must use this extension to set up portal artifacts that must be available during the core import. An example of this would be if a component wanted to filter out its Web applications, but not the pages where the portlets are located during the filter phase, they can deploy the correct Web app with the proper object ID references for the pages. This will result in their ability to possibly perform a dynamic transformation of their application, for instance, going from the IBM portlet API to JSR 168 in a more simplified manner than processing the entire XmlAccess import file.
The postimport extenstion

The postimport extension is called after the core migration import task. This task can be used to verify whether artifacts have been deployed properly, clear artifacts that are not required, or perform additional configuration, such as updating property files.
The migration framework extension

The migration framework extension is the simplest extension. It simply allows a target to be called from the command line by the user using the WPmigrate script. This extension must be used if there is some migration that is independent of the core migration. The JCR migration, for example, uses the migration framework extension to provide user-callable targets. This extension point must be used when there is an application that requires migration or transformation of external resources such as a database, and is not tied to the migration of a core portal artifact.
Appendix B. Extending the WebSphere Portal migration framework
121
Plugging into the framework

To plug in to the migration framework, create a component directory in the <wp_root>/migration/components, as shown in Figure B-1.
Figure B-1 Component directory
122
Each component directory must contain the two files displayed in Figure B-2: mig_ant.xml This is the file that contains the actual Ant tasks to be executed. mig_description.xml This is the file that describes the exported Ant tasks.
Figure B-2 Required files
The mig_ant.xml file

The mig_ant.xml contains custom Ant targets that the component will provide that can be called by the framework. Any number of targets can be included in this file. However, the callable targets are exported by the task definitions contained in the mig_description.xml file. Several useful Ant variables are made available to the plug-in. Following is a list of these Ant variables: ${CollectorDir} The directory where the information in the collectorOutput.zip file has been extracted to ${PrevWpsHostName} The previous portals host name ${PrevWpsPort} The previous Portals port value
123
${PrevWpsContextRoot} The previous Portals context root ${PrevPortalAdminId} The previous Portals admin ID ${PrevPortalAdminPwd} The previous Portals admin password ${VirtualPortal} The name of the virtual portal. An empty string if working with the default Portal. ${WORK_DIR} The work directory for the current migration process ${importAllFile} The import file that is modified by the filter extension points
The mig_description.xml file

The mig_description.xml file contains a <tasks> element that must contain one or more nested <task> elements. Each nested <task> element describes a target that is to be exported and how and when it is called. It also provides a short help description to be optionally displayed for each target. The <tasks> element does not support any required or optional attributes. However, it must contain nested <task> elements, as displayed in Figure B-3.
Figure B-3 Task elements
124
What follows is an example of how to extend the migration framework. Our example assumes that we have a specific set of pages that must be removed. This can be done by customizing the default filters, but to be safer, we created our own plug-in and used the existing filter infrastructure. In our example, we constructed a filter to remove all the pages with a unique name starting with "riverbend.admin". Note that the pages are not going to be removed from the previous server, they will simply be filtered from the exported XmlAccess file before we attempt to import the file into the current server. We created a River Bend filter directory in the <wp_root>/migration/component directory by executing the following command: mkdir -p <wp_root>/migration/component In this command, <wp_root> is the portal installation root directory. Using a text editor, we created the mig_ant.xml and the mig_description.xml file in the <wp_root>/migration/components/riverbend directory. We constructed an Ant task to be called during the filter phase of the migration.
Migration filters
Migration filters can be created to remove pages, portlets, themes, skins, or any other artifact that has an object ID and a uniquely identifiable attribute. A filter file is a properties file that contains a filters property that defines the active filters and one or more filter definitions. In our River Bend example, we wanted to filter the pages and the child pages that have a unique name starting with "riverbend.custom.page". When creating a filter, we used the template shown in Example B-1.
Example: B-1 Filter template
# This properties files defines a list of filters used to process the Portal data export. # The property "filters" defines the prefix for each filter # # Usage of each filter: filters=<filterX>,<filterY> <filterX>.object: xmlaccess object ID. Examples: "client", "web-app", "content-node". Required. <filterX>.include: Optional comma-separated list of patterns to include. If any are specified, only these will be used. Overrides excludes. <filterX>.exclude: Optional comma-separated list of patterns to exclude. <filterX>.searchAttr: Filtering will be applied to this attribute. If no filtering, can list any attribute type. Required. <filterX>.requestAttr: The attribute to use to request the object the next time. Required. <filterX>.secondaryAttr: Optional comma-separated list of secondary filters. For example, create-type=implicit.
125
The filters property indicates which filters will be used during the filtering process. Each filter, which is required to have a name, has six attributes associated with it. The attributes are affixed to the filter name in the format ".<attribute>", where the valid attributes are: object The xmlaccess element ID. Examples include "client", "web-app", "content-node". include The optional comma-separated list of patterns to include. If any are specified, only these will be used. It overrides exclude. exclude The optional comma-separated list of patterns to exclude. searchAttr Filtering will be applied to this attribute. If there is no filtering, can list any attribute type. Required. requestAttr The attribute used to request the object the next time. Must always be objectid. Required. secondaryAttr The optional comma-separated list of secondary filters. Examples include create-type=implicit. Example B-2 shows what the contents of our filter file, RiverBendPageFilter.properties, look like after we copied the template and made the appropriate updates. The include and exclude attributes allow a regular expression to specified.
Example: B-2 Filter file
# This properties files defines a list of filters used to process the Portal data export. # The property "filters" defines the prefix for each filter # # Usage of each filter: # <filter>.object: xmlaccess object ID. Examples: "client", "web-app", "content-node". Required. # <filter>.include: Optional comma-separated list of patterns to include. If any are specified, only these will be used. Overrides excludes. # <filter>.exclude: Optional comma-separated list of patterns to exclude. Same as defaultExclude but these are easier to update by end-users # <filter>.searchAttr: Filtering will be applied to this attribute. If no filtering, can list any attribute type. Required. # <filter>.requestAttr: The attribute to use to request the object the next time. For example, might want to filter by uid but request by objectid. Required. # <filter>.secondaryAttr: Optional comma-separated list of secondary filters. For example, create-type=implicit. # filters=riverbend-page-filter riverbend-page-filter.object=content-node riverbend-page-filter.include=
126
riverbend-page-filter.exclude=riverbend.custom.page* riverbend-page-filter.searchAttr=uniquename riverbend-page-filter.requestAttr=objectid riverbend-page-filter.secondaryAttr= We saved this file into our River Bend plug-in directory.
Creating the River Bend migration sample plug-in

The mig_ant.xml for the River Bend component contains two targets. However, only one target will be called by the framework. Note that when creating customized targets, they must be globally unique across the migration framework. To make them unique, append a component ID to the target name, for example, filter-pages.com.riverbend, as shown in Example B-3.
Example: B-3 Sample mig_ant.xml
<!-Licensed Materials - Property of IBM 5724-E76, 5724-E77, 5655-M44 (C) Copyright IBM Corp. 2001, 2006 All Rights Reserved. Sample mig_ane.xml for red paper Riverbend --> <project name="wp.migration.wcm" default="filter-pages.com.riverbend" basedir="."> <property name="portal.migration.dir" value="${basedir}/../.."/> <property name="RiverBendWorkDir" value="${WORK_DIR}/riverbend"/> <property name="InstalledWcmComponentDir" value="${portal.migration.dir}/components/wcm.migration" /> <property name="InstalledWcmMigAntFile" value="${InstalledWcmComponentDir}/mig_ant.xml"/> <property name="RiverBendFilteredImportFile" value="${RiverBendWorkDir}/RiverBendFilteredImportAll.xml"/> <property name="OidsOfRiverBendPagesToRemoveFile" value="${RiverBendWorkDir}/OidsOfRiverBendPagesToRemove.oid"/> <property name="RiverBendFilterFile" value="${basedir}/RiverBendPageFilter.properties"/>
<!-Create a Riverbend "work" directory The Riverbend work directory will be used to hold temporary files created by this plug-in the directory will be located in the following location <wp_root>/migration/work/<portal_name>/riverbend --> <target name="init"> <mkdir dir="${RiverBendWorkDir}"/> </target>
127
<target name="filter-pages.com.riverbend" depends="init" unless="DoNotFilterRiverBendPages"> <!-Filtering is a two step process. The first step scans the importAll.xml file for object ID's that match the search filters. The object ID's are written to a file specified by the attribute outfile. The second step reads in the list of object ID's created by the fullExportFilter task then it filters out each object that has a matching object ID found in the list. All artifacts that have referential dependencies on a filtered object are also filtered. For instance, if the page hierarchy is such that page A has child pages B and C if page A is filtered, pages B and C are also removed. The writeFilteredFile task will create a copy of the importAll.xml file with the artifacts matching the object ID's in the file specified by the oidfile attribute removed. --> <fullExportFilter infile="${importAllFile}" outfile="${OidsOfRiverBendPagesToRemoveFile}" inputproperties="${RiverBendFilterFile}"/> <writeFilteredFile oidfile="${OidsOfRiverBendPagesToRemoveFile}" infile="${importAllFile}" outfile="${RiverBendFilteredImportFile}" checkparent="true" />  <copy file="${RiverBendFilteredImportFile}" tofile="${importAllFile}" overwrite="true"/> </target> </project> The mig_description.xml describes the targets available to be executed and defines when they will be called. The contents of the River Bend mig_description.xml are shown in Example B-4.
Example: B-4 Sample mig_description.xml
<!-Licensed Materials - Property of IBM 5724-E76, 5724-E77, 5655-M44 (C) Copyright IBM Corp. 2001, 2006 All Rights Reserved. Riverbend mig_description.xml plug-in sample 128
--> <tasks> <task name="filter-pages.com.riverbend" isxmltarget="true" nohelp="true" inall="false" dependencies=""> This task is responsible for filtering out pages from our Riverbend sample site, </task> </tasks> The only task exported is "filter-pages.com.riverbend". It has the following attributes set: isxmltarget ="true" This means that it gets executed during the filter phase of the import process. inall="false" The target is not callable from the command line and is only called as part of the import-portal-content command processing. nohelp="true" The target will not show up when help is displayed. dependencies="" No dependencies When running the migration with the sample component described earlier, all the pages in our WebSphere Portal V5.1 server had a custom unique name that matched the string riverbend.custom.page.
129
130
Related publications
The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this IBM Redpaper.
Online resources
The following Web sites are relevant as further information sources: Explanation of limited support for using IBM WebSphere Portal V6.0 with IBM Rational Application Developer 6.0 http://www-1.ibm.com/support/docview.wss?uid=swg27008730&aid=1 IBM WebSphere Portal Version 6.0 Information Center Migrating the remaining access control configuration http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wpf/sec_mig_roles.html Supported hardware and software for IBM WebSphere Portal Version 6.0 http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wpf/inst_req60.html Migrating business process applications http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wps/bpi_mig.html Migrating cooperative portlets that use IBM Portlet API http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wpf/mig_coop_portlet.html Migrating portlets built with Struts Portlet Framework http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wpf/mig_struts.html XML configuration interface: reference http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wps/adxmlref.html Portal configuration services http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wps/srvcfgref.html Verifying the migration tasks http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wpf/mig_verify.html Troubleshooting migration http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wpf/mig_tbl.html
131
Migrating user profiles http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wcm/wcm_migration_users.html Postmigration steps http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm .wp.ent.doc/wcm/wcm_migration_post.html Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2 http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html Open Logic http://www.openlogic.co.uk/ Technote: Domino Application Portlet for Portal v5.x does not work on Portal v6 http://www-1.ibm.com/support/docview.wss?rs=899&uid=swg21245417 WebSphere Portal Update Installer http://www-1.ibm.com/support/docview.wss?rs=688&uid=swg24006942 White paper: IBM WebSphere Portal Version V6.0 Tuning Guide http://www-1.ibm.com/support/docview.wss?uid=swg27008511&aid=1
How to get IBM Redbooks

You can search for, view, or download IBM Redbooks, IBM Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy IBM Redbooks or CD-ROMs, at this Web site: ibm.com/redbooks
Help from IBM

IBM Support and downloads ibm.com/support IBM Global Services ibm.com/services
132
Back cover
IBM WebSphere Portal V6: Best Practices for Migrating from V5.1
Provides comprehensive step-by-step guidelines Describes enterprise considerations Includes troubleshooting guide and tips
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.
Redpaper
INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION
BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.
For more information: ibm.com/redbooks

Migracion - Best Practices

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Migracion - Best Practices

Transféré par

Droits d'auteur :

Formats disponibles

Front cover

Copyright IBM Corp. 2007. All rights reserved.

Best Practices for Migrating to IBM WebSphere Portal V6

Best Practices for Migrating to IBM WebSphere Portal V6

Copyright IBM Corp. 2007. All rights reserved.

Best Practices for Migrating to IBM WebSphere Portal V6

The team that wrote this IBM Redpaper

Become a published author

Best Practices for Migrating to IBM WebSphere Portal V6

Best Practices for Migrating to IBM WebSphere Portal V6

Getting started: WebSphere Portal migration from V5.1 to V6

Copyright IBM Corp. 2007. All rights reserved.

1.1.1 Understanding WebSphere Portal migration

Best Practices for Migrating to IBM WebSphere Portal V6

1.1.2 Migration versus upgrade

1.1.3 Reasons for migrating

Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6

1.2 High-level overview of WebSphere Portal migration

WebSphere Portal Core Migration Chapter 3

Do you have PDM?

Do you have PZN?

Do you have WCM?

Validate Server Content

Figure 1-2 Migration overview

Best Practices for Migrating to IBM WebSphere Portal V6

1.2.1 Premigration tasks

1.2.2 Core migration

1.2.3 Document Manager and Personalization components

1.2.4 Workplace Web Content Management components

Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6

1.4.1 WebSphere Portal V6 environment

Best Practices for Migrating to IBM WebSphere Portal V6

1.4.2 Custom portlets

Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6

1.4.3 External components

Best Practices for Migrating to IBM WebSphere Portal V6

Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6

1.4.5 Noncustom portlets

Best Practices for Migrating to IBM WebSphere Portal V6

1.4.6 Administration portlets

1.4.7 Search indexes

1.4.8 Virtual portals

1.4.9 Themes and skins

1.4.10 Uniform Resource Locator mappings

1.4.11 WebSphere Application Server artifacts

Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6

1.5 Migration checklist

1.5.1 Steps to prepare your WebSphere Portal V6 environment for migration

Best Practices for Migrating to IBM WebSphere Portal V6

Chapter 1. Getting started: WebSphere Portal migration from V5.1 to V6

Best Practices for Migrating to IBM WebSphere Portal V6

Considerations for migrating enterprise environments

Copyright IBM Corp. 2007. All rights reserved.

2.1 Migration approach between clusters

2.1.1 The WebSphere Portal V5.1 server environment

2.1.2 The WebSphere Portal V6 server environment

Best Practices for Migrating to IBM WebSphere Portal V6

2.1.3 Environment considerations

Hypertext Transfer Protocol Server considerations

Same physical server migration

Chapter 2. Considerations for migrating enterprise environments

2.2 Maintaining customizations during migration

2.2.1 Core WebSphere Portal customizations