IBM WebSphere Portal V6: Best Practices for Migrating from V5.1 Front cover

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

ibm.com/redbooks

Philip Monson

Brian Cheng

Frederic Delos

Dominic Glennie

Rob Holt

Misao Ishikawa

Simon McNab

William Trotman

Red

paper

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

2.1 Migration approach between clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.1.1 The WebSphere Portal V5.1 server environment . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.1.2 The WebSphere Portal V6 server environment . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.1.3 Environment considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.2 Maintaining customizations during migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.2.1 Core WebSphere Portal customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.2.2 Content changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 3. Migration of core components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3.1 Collecting data from the WebSphere Portal V5.1 environment. . . . . . . . . . . . . . . . . . . 24

3.1.1 The Property Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.1.2 Installing the Property Collector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

© Copyright IBM Corp. 2007. All rights reserved.

iii

3.1.3 Running the Property Collector on WebSphere Portal V5.1 . . . . . . . . . . . . . . . . . 25

3.2 Copying data to WebSphere Portal V6 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3.2.1 Copying the Property Collector output file to WebSphere Portal V6 server . . . . . 26

3.2.2 Collecting Web archive files for custom portlets and copying to WebSphere Portal V6 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3.3 Migrating your portal using the WPmigrate command-line tool. . . . . . . . . . . . . . . . . . . 26

3.3.1 Extracting the data from the Property Collector output file . . . . . . . . . . . . . . . . . . 27

3.3.2 Exporting the configuration from WebSphere Portal V5.1 server . . . . . . . . . . . . . 28

3.3.3 Importing the configuration into WebSphere Portal V6 server . . . . . . . . . . . . . . . 33

3.4 Postmigration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.4.1 Restarting the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.4.2 Migrating WebSphere Member Manager database tables . . . . . . . . . . . . . . . . . . 38

3.4.3 Adjusting the page hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.4.4 Migrating the search collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.4.5 Migrating the Search and Browse Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.4.6 Migrating the credential vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3.4.7 Administration portlets and pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.4.8 The Web Clipper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.4.9 Migrating the hidden pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

3.4.10 Migrating the WebSphere Application Server artifacts-Enterprise JavaBeans . . 48

3.4.11 Migrating the global portal settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.4.12 Migrating the portal service configuration properties . . . . . . . . . . . . . . . . . . . . . 49

3.4.13 Migrating the performance settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.4.14 Migrating the struts portlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.4.15 Migrating the Click-to-Action portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.4.16 Migrating the business processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3.4.17 Migrating the FileServer portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.5 Validating the portal and fixing any remaining issues . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 4. Migration of Document Manager and Personalization . . . . . . . . . . . . . . . . 51

4.1 The Document Transfer Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.1.1 Installing the Document Transfer Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.1.2 Validating the Document Transfer Tool installation. . . . . . . . . . . . . . . . . . . . . . . . 56

4.2 Migrating the Document Manager documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

4.2.1 Preparing a checklist for Document Manager validation. . . . . . . . . . . . . . . . . . . . 58

4.3 Synchronizing Document Manager global access . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

4.3.1 Modifying the Document Manager properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

4.3.2 Creating directories for Document Manager migration . . . . . . . . . . . . . . . . . . . . . 61

4.3.3 Running the export task for Document Manager . . . . . . . . . . . . . . . . . . . . . . . . . 62

4.3.4 Copying files to the WebSphere Portal V6 server. . . . . . . . . . . . . . . . . . . . . . . . . 64

4.3.5 Running the transform task for Document Manager . . . . . . . . . . . . . . . . . . . . . . . 64

4.3.6 Running the import task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

4.3.7 Validating the Document Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

4.3.8 Postmigration task for Document Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

4.4 Migrating Personalization data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

4.4.1 Preparing a checklist for Personalization validation . . . . . . . . . . . . . . . . . . . . . . . 68

4.4.2 Custom resource collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

4.4.3 Modifying Personalization properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

4.4.4 Creating directories for Personalization migration . . . . . . . . . . . . . . . . . . . . . . . . 70

4.4.5 Running the export task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

4.4.6 Copying files to WebSphere Portal V6 server. . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

4.4.7 Running the transform task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . 73

4.4.8 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

iv Best Practices for Migrating to IBM WebSphere Portal V6

4.4.9 Migrating the Personalization cache configuration . . . . . . . . . . . . . . . . . . . . . . . . 75

4.4.10 Running the import task for Personalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.4.11 Validating your Personalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

4.5 Postmigration tasks for Document Manager and Personalization. . . . . . . . . . . . . . . . . 76

4.5.1 Removing passwords from the Document Manager and Personalization property files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

4.5.2 Uninstalling the Document Tracking Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web

Content Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

5.1 Migration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

5.2 Workplace Web Content Management migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

5.3 Premigration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

5.3.1 Copying folders from WebSphere Portal V5.1 server to

WebSphere Portal V6 server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

5.3.2 Preparing a checklist for Workplace Web Content Management validation . . . . . 87

5.3.3 Installing the Workplace Web Content Management migration tool . . . . . . . . . . . 88

5.3.4 Installing the authoring portlet to the Web Content Management page . . . . . . . . 94

5.3.5 Migrating the Workplace Web Content Management user data . . . . . . . . . . . . . . 95

5.3.6 Migrating the Workplace Web Content Management rendering portlets . . . . . . . 97

5.3.7 Postmigration tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Appendix A. Troubleshooting and other tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Business portlets not migrated during portal migration . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Temporarily halting user customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Delayed clean-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Changing the delayed clean-up property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Forcing immediate clean-up with xmlaccess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

List of admin portlets in WebSphere Portal V5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

List of admin portlets in WebSphere Portal V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Migrating the search collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Appendix B. Extending the WebSphere Portal migration framework . . . . . . . . . . . . 119

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Framework extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Core migration extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Plugging into the framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Migration filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Creating the River Bend migration sample plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Contents v

vi Best Practices for Migrating to IBM WebSphere Portal V6

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

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

Preface

This IBM® Redpaper provides detailed information about migrating from IBM WebSphere®

Portal V5.1 to IBM WebSphere Portal V6. This IBM Redpaper introduces the key considerations and the overall decision process before providing step-by-step instructions. It also provides a troubleshooting guide. This IBM Redpaper covers all the key concepts, from stand-alone core portal environments to comprehensive enterprise deployments with clustering, IBM WebSphere Portal components such as Document Manager, Personalization,

IBM Workplace™ Web Content Management, and others.

Whether you are a Line-of-Business Manager looking for overall information about migration, an IT Architect planning a migration, or an Administrator who has to perform the actual migration, this IBM Redpaper is for you.

The team that wrote this IBM Redpaper

This IBM Redpaper was produced by a team of specialists from around the world working at the International Technical Support Organization (ITSO), Cambridge MA Center.

Philip Monson is a Project Leader at the ITSO Lotus® Center in Cambridge MA. Phil has been with Lotus/IBM for 16 years, joining the company when the early versions of Lotus

Notes® were rolled out for internal use. He has served in management, technical, and consulting roles in the IT, Sales, and Development organizations.

Brian Cheng is a Portal Content Evangelist working in the WebSphere Portal Development

Organization. He uses a combination of applied knowledge gained from working with Sales,

Services, and Support, and comprehensive product knowledge gained from working on the development team, to effectively architect enterprise solutions. His primary focus is to advise and educate customers, sales and services teams, and development teams with his deep technical skills. His areas of expertise are Portal, Content Management, and Personalization.

Frederic Delos is the Technical Project Lead for IBM Early Deployment Center (EDC)

Workplace, Portal, and Composite Application Projects. He has over five years of experience in designing and deploying Next Generation Lotus Software environments for the EDC. He has developed and executed technical plans for internal Workplace and WebSphere Portal clustered production environments, and prepares technical enablement for the internal IBM systems team. He currently acts as the primary technical and change management liaison for executive-level IBM internal projects running within the Technology Adoption Program (TAP).

Dominic Glennie works as a WebSphere Portal Server consultant for the enterprise architecture division of Open Logic, an IBM premier Business Partner based in the UK

( http://www.openlogic.co.uk/) . He worked in J2EE™ and WebSphere Portal Server development, before switching to a WebSphere Portal Server infrastructure and administration role in 2005. He has worked on large WebSphere Portal engagements throughout the U.K.

Rob Holt is currently the Development Lead for the WebSphere Portal V6 migration team. He has over ten years of experience in software design and development. He has worked in various divisions of IBM, including the System and Technology Group, IBM Global Services, and the Software Group. He has worked as an IBM i5/OS® Software Developer, an IT specialist deploying WebSphere solutions, and an Installation Developer for the WebSphere

Portal and Workplace Collaboration Services products. He holds a Bachelor’s Degree in

© Copyright IBM Corp. 2007. All rights reserved.

ix

Electrical Engineering from North Carolina A&T State University in Greensboro, NC, and a

Master’s Degree in Electrical/Computer Engineering from the Old Dominion University in

Norfolk, Virginia.

Misao Ishikawa is an IT Architect with IBM BetaWorks™, leading WebSphere

Portal-managed beta programs for the last five years in Asia Pacific. He focuses on not only managing beta projects, but also on enablement programs for IBM Technical Salespersons and IBM Business Partners. He also leads beta programs for IBM Tivoli® Security products.

Previous experience includes customer projects that required integration architectures, such as Multi Vendor Solution, Nagano Olympics, and Enterprise Mail/CRM/Portal Solutions, among others.

Simon McNab works for IBM Software Support in the U.K. He provides voice and e-mail support for defects, and simple "how to" questions for the WebSphere Portal Server and the

Lotus product suite. Prior to joining Support, Simon worked in a number of service delivery roles, most recently as a WebSphere Application Server Administrator. He has been with IBM for 10 years and has a degree in Computer Sciences from the Pembroke College,

Cambridge. He has worked on two earlier IBM Redbooks™ on IBM WebSphere Application

Server on z/OS®.

William Trotman is a Software Engineer for the WebSphere Portal Server Level 2 support organization, North America. He has four years of experience working with the WebSphere

Portal Server. He holds a degree in Computer Science from North Carolina State University.

His areas of expertise include WebSphere Portal application programming interfaces (APIs) and migration.

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

Lee Berry

IBM WCM Software Engineer, IBM Software Group, Lotus

Scott Roehrig

PDM Software Engineer, IBM Software Group, Lotus

Lori Small

PDM Software Engineer, IBM Software Group, Lotus

Monica S. Harris

Software Engineer, IBM Software Group, Lotus

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

x Best Practices for Migrating to IBM WebSphere Portal V6

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

1

Chapter 1.

Getting started: WebSphere

Portal migration from V5.1 to V6

This chapter provides an overview of migrating a WebSphere Portal V5.1 environment to

WebSphere Portal V6, and the considerations that go into planning a successful move. (The detailed steps are provided in the subsequent chapters.)

This chapter covers the following topics:

򐂰

1.1, “Introduction” on page 2

򐂰

1.2, “High-level overview of WebSphere Portal migration” on page 4

򐂰

1.3, “Planning” on page 6

򐂰

1.4, “Considerations” on page 6

򐂰

1.5, “Migration checklist” on page 12

© Copyright IBM Corp. 2007. All rights reserved.

1

1.1 Introduction

This IBM Redpaper describes the steps and best practices for migrating an existing

WebSphere Portal V5.1 environment to WebSphere Portal V6. To help illustrate the steps involved in this process, the migration of the fictitious River Bend Coffee and Tea Company’s

(Figure 1-1) portal is described.

Figure 1-1 River Bend Coffee and Tea Company home page

This portal contains pages, custom portlets, and a variety of content, including Document

Manager, Personalization, and IBM Workplace Web Content Management™.

During this migration, migration steps that use the command-line interface are described. In the Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, a mention is made of a migration wizard that provides a graphical user interface (GUI) for migration: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html

The best practice is to use the command line. It provides more flexibility and allows for additional verification after each migration task.

In this IBM Redpaper, the environment that is being migrated is configured to an IBM DB2® database and is secured with an IBM Tivoli Directory Server LDAP, all running on a

Windows® server. WebSphere Portal server migration is performed between two single server instances. Both these instances can reside in managed cells, but the target

WebSphere Portal V6 server must not

be clustered at the time of migration. After the migration is completed and verified, the WebSphere Portal V6 server can be clustered.

Additional considerations for production clustered systems are covered in Chapter 2,

“Considerations for migrating enterprise environments” on page 15.

1.1.1 Understanding WebSphere Portal migration

In this case, migration is the process of reconstructing an existing IBM WebSphere Portal

V5.1 environment on to an IBM WebSphere Portal V6 environment so that the latter is identical to the former.

Following are the artifacts that are migrated in the process:

򐂰 Themes and Skins

򐂰 Pages

򐂰 Screens

򐂰 Portlet applications

򐂰 Access control

򐂰 User customization

򐂰 Virtual portals

򐂰 Markups

򐂰 Global settings

2 Best Practices for Migrating to IBM WebSphere Portal V6

򐂰 Portal resources

򐂰 Workplace Web Content Manager content and components

򐂰 Document Manager content

򐂰 Personalization rules

򐂰 Credential vault slots

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 3

Following are the key benefits:

򐂰 Improves operational efficiency and productivity by linking the right people, processes, and information so that transactions are executed quickly and accurately

򐂰 Accelerates application and content deployment through new tools and the innovative use of service-oriented architecture (SOA)

򐂰 Lowers the overall cost of portal deployment with faster performance and easier administration

򐂰 Delivers responsiveness and reliability from a leader in the enterprise portal market

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?

YES

Portal Document

Manager

Chapter 4

NO

Do you have

PZN?

YES

WebSphere Portal

Personalization

Chapter 4

NO

Do you have

WCM?

YES

WebSphere Content

Manager

Chapter 5

NO

Validate Server

Content

Figure 1-2 Migration overview

4 Best Practices for Migrating to IBM WebSphere Portal V6

This IBM Redpaper follows the migration of a portal containing many different components.

What follows is a brief explanation of each step involved in migrating to WebSphere Portal

V6.

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.

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

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

6 Best Practices for Migrating to IBM WebSphere Portal V6

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

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

򐂰 Java Server Faces Portlet

Portlets developed by using the IBM API that use the Java Server Faces (JSF) framework will not work with WebSphere Portal V6 if they were developed using Rational Application

Developer V6. The following Web site provides additional information about portlets developed using Rational Application Developer V6.

http://www-1.ibm.com/support/docview.wss?uid=swg27008730&aid=1

򐂰 Predeployed enterprise archive file

Predeployed enterprise archive (EAR) files require the installation of fix PK32308.

Download this fix and check the fix’s readme file for any additional steps that may have to be followed.

򐂰 Collaborative Portlet

WebSphere Portal V5.1 of the IBM Domino® Application Portlet does not work on

WebSphere Portal V6. At the time of writing this IBM Redpaper, V6 of the Domino

Application Portlet was being written. The following Web site provides the most recent information about this portlet: http://www-1.ibm.com/support/docview.wss?rs=899&uid=swg21245417

The other Collaborative Portlets can migrate without any issue.

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.

8 Best Practices for Migrating to IBM WebSphere Portal V6

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.

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

򐂰 Credential vault

The best method for migrating credential vault data is to use the Extensible Markup

Language (XML) Configuration Interface, which requires the installation of an interim fix

(PK28148) on both WebSphere Portal V5.1 and WebSphere Portal V6 environments.

Alternatively, you can migrate your credential vault data using Structured Query Language

(SQL) and direct database operations. The chapter “Migrating credential vault data” under the topic “Migrating the remaining access control configuration” in the IBM WebSphere

Portal Version 6.0 Information Center provides the necessary information: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp

.ent.doc/wpf/sec_mig_roles.html

Check the following migration fix download page for information about future fixes for credential vault migration: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927

1.4.5 Noncustom portlets

Many of the portlets in your WebSphere Portal environment may have been installed by default, downloaded from the IBM portlet catalog, or provided by a third party. Following is a list of some considerations pertaining to these portlets:

򐂰 IBM Business Portlets

Business Portlets are portlets that IBM provides with WebSphere Portal by default or those that are downloaded from the IBM portlet catalog. Some business portlets will not

be moved to WebSphere Portal V6 by migration. Refer to Appendix A, “Troubleshooting and other tips” on page 103 for details.

Following is a list of a few common portlets that are used in WebSphere Portal V5.1:

– Web Clipping Portlet

There are no specific changes to the Web Clipping Portlet with regard to migration.

However, WebSphere Portal V6 ships with the latest version of the Web Clipping

Portlet. Therefore, you might notice some differences if you migrate from a system using an earlier version of the Web Clipping Portlet.

– Web Page Portlet

The Web Page Portlet is deprecated. All the functionalities of the Web Page Portlet are included in the Web Clipping Portlet. As a best practice, after migration, the Web

Clipping Portlet must be used instead of the Web Page Portlet.

– IBM Application Portlet Builder

The Application Portlet Builder portlets are being replaced by the WebSphere Portlet

Factory in WebSphere Portal V6. The Application Portlet Builder portlets are not supported on WebSphere Portal V6 and will not be migrated.

򐂰 Catalog portlets

For portlets that are downloaded from the IBM portlet catalog, the support level and agreement can be verified online under the portlet’s catalog entry. For portlets that are not supported by IBM, contact the software vendor for new releases and support.

򐂰 Portlets from vendors

Check with the vendors whether any of the portlets that they have provided are certified for WebSphere Portal V6, and follow the specific migration steps, if any.

10 Best Practices for Migrating to IBM WebSphere Portal V6

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.

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

Following is a list of additional settings:

򐂰 Additional WebSphere Application Server settings

Review any WebSphere Application Server settings that might have been made to your

WebSphere Portal V5.1 and check the WebSphere Application Server Information Center to see how to make these settings in the version of WebSphere Application Server that is used by your WebSphere Portal V6 environment.

򐂰 Java virtual machine settings

The Java virtual machine (JVM™) heap size requirements have changed between

WebSphere Portal V5.1 and WebSphere Portal V6. If the memory is available, the heap size must be increased on the WebSphere Portal V6 after the initial installation. After migration, the heap size must be tuned as part of performance testing.

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

7. Install all the required fixes before migration. Not all the migration fixes listed in the following Web site are required because some may be dependent on the additional components you expect to migrate: http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927

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.

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

14 Best Practices for Migrating to IBM WebSphere Portal V6

Chapter 2.

Considerations for migrating enterprise environments

Typically, a WebSphere Portal migration will not simply take place between two static, stand-alone servers. Although the process for migrating more complex production environments is fundamentally the same, there are some additional considerations.

This chapter discusses the following topics specific to live cluster environments:

򐂰

2.1, “Migration approach between clusters” on page 16

򐂰

2.2, “Maintaining customizations during migration” on page 18

2

© Copyright IBM Corp. 2007. All rights reserved.

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 server’s node agent and halting user traffic with a method appropriate to your environment. This may, for instance, involve editing out the source node from the Hypertext

Transfer Protocol (HTTP) Server plug-in configuration file.

Attention: Applying fixes to the isolated node may alter the shared portal configuration database. This can cause the other servers to be in an inconsistent state. The fixes mentioned in this IBM Redpaper must not cause a problem, although care must be taken if any additional fixes are applied. Ensure that any fixes that are applied to the isolated node are either applied to the rest of the cluster members or are removed before restarting the node agent.

Tip: All the WebSphere Portal servers within the cluster share the same portal configuration database. Even after being isolated from the deployment manager and user traffic, the source server has the potential to put a load on this database. Therefore, consideration must be given to when migration tasks are run so that the performance impact on the production environment is minimized.

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

Also refer the IBM Redbook WebSphere Portal 6 - Best Practices for Enterprise Scale

Deployment, which is available in draft form on the Web at: http://www.redbooks.ibm.com/redpieces/abstracts/sg247387.html?Open

Important: The standard installation process provides the choice of installing WebSphere

Portal V6 with or without the WebSphere Process Server. If the node is to eventually become a part of a cluster, the installation must take place without

the WebSphere

Process Server. Otherwise, it will not be possible to create a cluster from it.

Migrating to an unmanaged node allows the potentially complex task of clustering to be treated separately from the migration process. It also means the configuration of the primary node is kept if the node is ever removed from the cell.

Tip: Because the WebSphere Portal V6 environment is built, take frequent backups of the files and the databases. Always take a backup just before federating the primary node into a cluster because errors often occur during this process.

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

These approaches are not mutually exclusive, and must be combined in a manner that is suitable to your environment. For complex environments, it is usually not possible to migrate an entire system and switch it into production during downtime. This section describes how these methods can be used.

Note: WebSphere Portal V6 server allows user customizations to be stored in a separate database domain that can be shared between clusters. This functionality is likely to be utilized to ease the migration process between V6 and the next major WebSphere Portal release, by allowing the source servers and the target servers to share the same customization database.

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.

Chapter 2. Considerations for migrating enterprise environments 19

In the River Bend environment, after migration, additional implicit pages were created by logging in as users and editing the parameters of a portlet. The page and its child-implicit

pages with the unique name wps.test1 were exported using the script shown in Example 2-1.

Example 2-1 Sample xmlaccess script for reimporting a page and all the child-implicit pages

<?xml version="1.0" encoding="UTF-8"?>

<request

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="PortalConfig_1.3.xsd"

type="export">

<!-- sample for exporting a page -->

<portal action="locate">

<content-node action="export" uniquename="wps.test1" export-descendants="true"/>

</portal>

</request>

Tip: For the implicit private pages to be exported, the export-descendents parameter of the content node in the xmlaccess request must be set to true .

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

Attention: At the time of writing this IBM Redpaper, Workplace Web Content Management libraries could not be deleted from our example River Bend environment on WebSphere

Portal V6. Check with IBM support for a fix.

Refer to Chapter 5, “Migration from WebSphere Portal V5.1 for deployments with Workplace

Web Content Management” on page 77, for details about running the Workplace Web

Content Management migration tasks.

Chapter 2. Considerations for migrating enterprise environments 21

22 Best Practices for Migrating to IBM WebSphere Portal V6

3

Chapter 3.

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.

© Copyright IBM Corp. 2007. All rights reserved.

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

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

Important: Like WPSconfig, WPmigrate appends to its log file on each execution.

However, WPmigrate overwrites any other files that it creates. Therefore, it is recommended that you make copies of these files before rerunning the command.

Tip: If there is a syntax error, for example, “WPmigrate.bat collector-extarct” instead of

“WPmigrate.bat collector-extract”, you will see the following message:

BUILD FAILED

Target ‘collector-extarct' does not exist in this project.

The export and import stages run xmlaccess. As mentioned in “Running the Property

Collector on WebSphere Portal V5.1” on page 25, it is recommended that you run xmlaccess

directly against the HTTP Listener in the WebSphere_Portal Application Server, instead of through an HTTP Server. Because the host name and the port name cannot be entered through the command line, verify that WpsHostname, WpsHostPort, XmlAccessHost, and

XmlAccessPort are set appropriately. Note that XmlAccessHost and XmlAccessPort are new parameters in WebSphere Portal V6 and do not therefore apply to WebSphere Portal V5.1.

XmlAccessHost is set to localhost by default and does not have to be changed.

For the WebSphere Portal V6 server, these parameters are set in wpconfig.properties in

<portal_server_root>\config. For the WebSphere Portal V5.1 server, they are set in wpconfig.properties, which has already been collected by the Property Collector.

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.

Chapter 3. Migration of core components 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 Purpose allout.xml

testexport.xml

xmlaccess export

Result of a command to test connectivity. If the test fails, there will be messages here to help diagnose the issue.

This task runs xmlaccess against WebSphere Portal V5.1. Therefore, WebSphere Portal

V5.1 must be running. There is no interaction with WebSphere Portal V6.

Ensure HTTP connectivity from WebSphere Portal V6 to WebSphere Portal V5.1.

Important: Check whether wmm.xml on the WebSphere Portal V5.1 server environment has the maximumSearchResults parameter set to a number that is greater than the number of portal users. Otherwise, the command will fail.

Also ensure that searchTimeOut is set to a large number, for example, 20,000,000, in order to avoid user repository searches timing out.

28 Best Practices for Migrating to IBM WebSphere Portal V6

Entering the command

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

Chapter 3. Migration of core components 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 response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testexport.xml.

[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testexport.xml.

30 Best Practices for Migrating to IBM WebSphere Portal V6

BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm

l:161: EJPXB0019E: Server response indicates an error. For status and details of

the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\defau lt\testexport.xml.

Total time: 3 seconds

In our example, we opened testexport.xml, as shown in Example 3-4.

Example 3-4 testexport.xml

<failure> com.ibm.wps.command.xml.XmlCommandServlet$AuthenticationException: EJPXA0005E:

Authorization for user wpsadmin failed.

</failure>

In our case, the cause was an incorrect password. We retyped the command with the correct password and it ran to completion.

As mentioned in “Validation” on page 25, it is common to see export portal content complete

successfully, but issue warnings. In our example, on successful export, the output shown in

Example 3-5 was displayed.

Example 3-5 Output from successful WPmigrate export portal content

[xmlaccess] EJPXB0022W: The request was processed successfully on the server, but warnings were enountered during processing. For details of the XmlAccess warnings look at file C:\WebSphere\PortalServer\migration\work\default\allout.xml.

[xmlaccess] EJPXB0020I: The request was processed successfully on the server.

BUILD SUCCESSFUL

Total time: 41 seconds

We checked C:\WebSphere\PortalServer\migration\work\default\allout.xml and searched for

<status. We found the messages shown in Example 3-6.

Example 3-6 Messages from allout.xml for successful export portal content

<status element="[web-app _1_004CSO68OD0EIGCQ_6O uid=pzn.author.1001]" result="warning">

<message id="EJPXA0185W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0185W:

The URL file://localhost/$server_root$/installableApps/pznauthorportlet.war does not point to a directory as required by predeployed portlets. You will need to adjust the URL. [web-app _1_004CSO68OD0EIGCQ_6O uid=pzn.author.1001]</message>

</status>

<status element="[web-app _1_004CSO68OD0EIGCQ_6P uid=pzn.ruleportlet.1001]" result="warning">

<message id="EJPXA0185W">com.ibm.wps.command.xml.XmlCommandException:

EJPXA0185W: The URL file://localhost/$server_root$/installableApps/pznruleportlet.war does not point to a directory as required by predeployed portlets. You will need to adjust the

URL. [web-app _1_004CSO68OD0EIGCQ_6P uid=pzn.ruleportlet.1001]</message>

</status>

<status element="[web-app _1_004CSO68OD0EIGCQ_IP uid=com.ibm.wps.portlets.Calculator.Calculator]" result="warning">

Chapter 3. Migration of core components 31

<message id="EJPXA0186W">com.ibm.wps.command.xml.XmlCommandException:

EJPXA0186W: The URL file://localhost/$server_root$/installableApps/Calculator.war does not point to a file. You will need to adjust the URL. [web-app

_1_004CSO68OD0EIGCQ_IP uid=com.ibm.wps.portlets.Calculator.Calculator]</message>

</status>

These messages refer to missing WAR files. Xmlaccess expects that the WAR files for the exported portlets will exist in <portal_server_root>\installableApps on the server, identified by localhost, which is the WebSphere Portal V5.1 server at this point.

The messages regarding pznauthorportlet.war and pznruleportlet.war messages are normal.

These portlets are part of Personalization and are supplied in predeployed EARs rather than portlet WAR files in both WebSphere Portal V5.1 and V6. Because the migration process handles this automatically, these messages can be ignored.

The message referring to Calculator.war is worth noting. In our example, we installed the

Calculator portlet on WebSphere Portal V5.1 server from the portlet catalog. This was installed using the portal admin graphical user interface (GUI), which picked up the WAR file from the local hard drive of the workstation used for the installation. Therefore, there was no copy of the WAR file in the <portal_server_root>\installableApps directory on WebSphere

Portal V5.1 server. This message does not indicate an error at this point. However, it serves as a reminder to ensure that the WAR file is made available on the WebSphere Portal V6 server before proceeding.

Important: Any references to localhost in allout.xml refer to the WebSphere Portal V5.1 server, rather than the WebSphere Portal V6 server.

Tip: If you have to investigate allout.xml for purposes of troubleshooting, search for

<status to quickly find the warning or error messages.

If necessary, search for references to the message codes identified by “message id” in the

Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, which is available on the Web at: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html

Tip: If the output file referenced in the command output does not provide enough information to resolve the cause of a failed export, it is worth checking the logs for the

WebSphere Portal V5.1 server to see if they indicate any issues.

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

Attention: The server process called by xmlaccess runs for a short time after an xmlaccess failure. If this process is still running when the export is rerun, you might see the the following message in testexport.xml:

“com.ibm.wps.command.CommandFailedException: EJPXA0166E: The XML Configuration

Interface is currently busy with another request. Please try again later.”

If this happens, wait for a short period and then retry the command.

Tip: It is recommended that you make a copy of the output files before rerunning the import portal content task so that you can compare the outcome of the reruns.

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 Purpose importAll.xml

importAllResults.xml

The final Extensible Markup Language (XML) file used for the xmlaccess import

An XML file with the results from the import process testimport.xml

An XML file with the results from a connectivity test made prior to the main xmlaccess import

Attention: The WPMigrate task is potentially very long running. The exact duration depends on your configuration.

Chapter 3. Migration of core components 33

The WPmigrate task uses the configuration values stored in wpconfig.properties on

WebSphere Portal V6 server. This must be validated before progressing further.

The WPmigrate task runs xmlaccess against WebSphere Portal V6 server. Therefore,

WebSphere Portal V6 server must be running. There is no direct interaction with WebSphere

Portal V5.1 server. If there are any shared resources, for example, the database server, there might be a performance impact on the WebSphere Portal V5.1 server environment because of a high level of activity on these resources caused by the import.

Entering the command

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

Tip: Browse importAllResults.xml even if you see the “ BUILD SUCCESSFUL ” message. There may still be issues that must be investigated before proceeding. Our results and the

corresponding explanation are documented in Example 3-12.

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.

Chapter 3. Migration of core components 35

[xmlaccess] EJPXB0019E: Server response indicates an error. For status and detai ls of the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\ default\testimport.xml.

BUILD FAILED file:C:/WebSphere/PortalServer/migration/components/wp.migration.core/mig_ant.xm

l:275: EJPXB0019E: Server response indicates an error. For status and details of

the XmlAccess error look at file C:\WebSphere\PortalServer\migration\work\defau lt\testimport.xml.

Total time: 3 seconds

In our example, we opened testimport.xml, as shown in Example 3-11.

Example 3-11 testimport.xml

<failure> com.ibm.wps.command.xml.XmlCommandServlet$AuthenticationException: EJPXA0011E:

Authentication for user wpsadmin failed.

</failure>

In our case, the cause was an incorrect password. We retyped the command with the correct password, and it ran to completion.

As mentioned in “Validation” on page 28, it is common to see the import portal content task

complete successfully, but issue warnings. In our example, on successful import, the output

shown in Example 3-12 was displayed.

Example 3-12 Output from successful import portal content task

[xmlaccess] EJPXB0022W: The request was processed successfully on the server, bu t warnings were enountered during processing. For details of the XmlAccess warni ngs look at file C:\WebSphere\PortalServer\migration\work\default\importAllResul ts.xml.

[miglogger] Oct 24, 2006 8:33:11 PM com.ibm.wps.migration.framework.logging.Migr

ationLogger execute

[miglogger] INFO: EJPMA5200I: Successfully imported XmlAccess script, import res ult in file C:\WebSphere\PortalServer\migration/work/default/importAllResults.xm

l.

post-import:

BUILD SUCCESSFUL

Total time: 13 minutes 1 second

We looked at importAllResults.xml, searched for the <status tag, and found the result shown

in Example 3-13.

Example 3-13 Status from importAllResults.xml

<status element="[credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment]" result="warning">

<message id="EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException:

EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment]</message>

36 Best Practices for Migrating to IBM WebSphere Portal V6

</status>

<status element="[credential-segment _E_004CSO68OD0EIGCQ_36 name=DefaultAdminSegment]" result="warning">

<message id="EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException:

EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_36 name=DefaultAdminSegment]</message>

</status>

The messages pertaining to credential segments are normal. This is because the migration process cannot migrate the credential vault. Our River Bend example had a Web Clipping

Portlet that accesses a Web site requiring authentication. This uses the credential vault.

Action is required as described in 3.4.6, “Migrating the credential vault” on page 45.

Tip: If you have to investigate importAllResults.xml for troubleshooting purposes, search for <status in order to quickly find the warning or error messages.

If necessary, search for references to the message codes identified by “message id” in the

Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2, which is available on the Web at: http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html

Tip: If the output file referenced in the command output does not provide enough information to resolve the cause of a failed export, it is worth checking the logs for the

WebSphere Portal V6 server to see if they indicate any issues.

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.

Chapter 3. Migration of core components 37

Important: If you decide to rerun the import for a virtual portal, you do not have to delete and recreate the virtual portal first. If you delete and recreate the virtual portal, you might face problems if delayed cleanup is enabled (as it is by default). In our case, we saw the import fail under these conditions with the following message:

“com.ibm.websphere.ce.cm.DuplicateKeyException: The statement was aborted because it would have caused a duplicate key value in a unique or primary key constraint defined on 'PAGE_INST(OID).”

We resolved this by forcing an immediate run of the cleanup service through xmlaccess as

discussed in “Forcing immediate clean-up with xmlaccess” on page 107.

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

In our case, when we started our migrated River Bend portal server for the first time and accessed http://m51g.cam.itso.ibm.com:10038/wps/portal from a browser, we saw the default

WebSphere Portal V6 server welcome (Figure 3-2) page instead of the expected River Bend

welcome page.

Figure 3-2 Welcome page immediately after migration

We addressed this by adjusting the page hierarchy from Portal User Interface

Manage

Pages. We clicked Content Root and saw the page hierarchy, as displayed in Figure 3-3. We

clicked the Up Arrow button next to My Portal.

Figure 3-3 Page hierarchy immediately after migration

Chapter 3. Migration of core components 39

This moved My Portal to the top of the list, as shown in Figure 3-4.

Figure 3-4 Fixing the page hierarchy

When we pointed our browser to http://m51g.cam.itso.ibm.com:10038/wps/portal after

making this change, we saw the River Bend welcome page (Figure 3-5).

Figure 3-5 The welcome page displays as expected

40 Best Practices for Migrating to IBM WebSphere Portal V6

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

Chapter 3. Migration of core components 41

In WebSphere Portal V5.1 server, the portlet locates its search index through the

configuration parameter called IndexName, as shown in Figure 3-7.

Figure 3-7 Configuring the Search and Browse Portlet in V5.1

42 Best Practices for Migrating to IBM WebSphere Portal V6

In WebSphere Portal V6, this is now called CollectionLocation. To fix this, we reconfigured

the Search and Browse Portlet in question. Note that the IndexName parameter in Figure 3-8

has been preserved by the migration process, but is not used. The required parameter

(CollectionLocation) is not listed on any page.

Figure 3-8 Search and Browse Portlet properties

Important: The problem is that the new parameter (CollectionLocation) is missing. If you have put your search collection in a location that is different from your WebSphere Portal

V5.1 server and updated IndexName to match this new location, this issue continues to occur.

Chapter 3. Migration of core components 43

In our case, we added the missing parameter by typing CollectionLocation in the New

Parameter box and the name of the directory that houses the collection (in our case,

c:\collections\itsoco) in the New Value box, as shown in Figure 3-9, and clicked Add, and then

OK. We then restarted the portal server.

It is recommended that you delete the redundant IndexName parameter at this point.

Figure 3-9 Fixing a Search and Browse Portlet

Attention: There is no requirement to change the location directory between versions.

This is just an example. The fix is required even if you do not change the location.

Important: You must log out and log back in to pick up this change.

44 Best Practices for Migrating to IBM WebSphere Portal V6

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.

Chapter 3. Migration of core components 45

Tip: In our test of PK28148, the following message was displayed, although the import was successful:

"EJPXA0090W">com.ibm.wps.command.xml.XmlCommandException: EJPXA0090W: It is not possible to modify credential-segment resources. Existing settings are left unchanged. [credential-segment _E_004CSO68OD0EIGCQ_35 name=DefaultUserSegment in <portal_server_root>\bin\resultsCVresults.xml.”

At the time of writing this IBM Redpaper, this was being addressed by Development.

Depending on the version of the previous system, some secrets and shared credential slots that are obsolete in the current version are migrated. These slots must be removed using the

Credential Vault administrative portlet under Administration

Access

Credential Vault.

Select Manage system vault slots and delete the following slots, if applicable:

򐂰 deployment.user

򐂰 wmm.system.id.user

򐂰 deployment.truststore

򐂰 deployment.keystore

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

If, for example, the Web site being clipped uses JavaScript™, you might see a warning

message, as shown in Figure 3-12. This issue will also be observed on the WebSphere Portal

V5.1 server if the most recent Web Clipping portlet is installed there.

.

Figure 3-12 Warning message in Clipper, postmigration

To address this, in our example, we edited the Web Clipping Portlet, as shown in Figure 3-13.

Figure 3-13 Editing the Web Clipper portlet

We then selected the Advanced Options, followed by the Modify Security Options. We

selected the box against Remove JavaScript from clipped content, as shown in Figure 3-14,

and clicked OK.

Figure 3-14 Modifying the security options

Chapter 3. Migration of core components 47

We then clicked Next, and then Finish. The message was no longer displayed, as shown in

Figure 3-15.

Figure 3-15 Web Clipper warning has been removed

The clipper for the itsoco Web site showed different issues after migration. Immediately after

the migration, the portlet displayed nothing, as shown in Figure 3-16.

Figure 3-16 itsoco clipper, postmigration

Clicking on Edit showed the cause to be missing credential vault data, as shown in

Figure 3-17. This is because the Web Clipper uses the credential vault to store authentication

data. The credential vault secret does not migrate automatically. Refer to 3.4.6, “Migrating the credential vault” on page 45 for instructions about how to correct this.

Figure 3-17 itsoco clipper with the missing credential vault data

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

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

This is discussed in 1.4.2, “Custom portlets” on page 7.

3.4.16 Migrating the business processes

This is discussed in 1.4.2, “Custom portlets” on page 7.

Chapter 3. Migration of core components 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 Best Practices for Migrating to IBM WebSphere Portal V6

4

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?

NO

YES

4.2 Migrate PDM documents

Migrate

PZN?

NO

YES

4.3 Migrate PZN data

End of Chapter 4

Figure 4-1 Document Manager and Personalization migration overview

© Copyright IBM Corp. 2007. All rights reserved.

51

Document Manager migration and Personalization migration involve the flow shown in

Figure 4-2. Each migration involves the same sequence of tasks (export

transform

→ import). However, the commands for the migration tasks are slightly different between

Document Manager and Personalization.

Following is the sequence of the tasks:

1. Performing the premigration tasks

2. Running the export task

3. Copying the exported files to the V6 server

4. Running the transform task

5. Running the import task

6. Performing validation

Migration Start

Prepare Premigration tasks

Export

Copy

Run the export task

Copy exported files to the 6.0 system

Transform Run the transform task

Import Run the import task

Validate Validate migration

Migration End

Figure 4-2 Flow of migration for Document Manager and Personalization

Although the process is independent of database and security configuration, it is required to use the same brand of software for the operating system (OS), database, and user

repository, as described in 1.4.1, “WebSphere Portal V6 environment” on page 6.

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

Following is a list of the topics described in this chapter:

򐂰

4.1, “The Document Transfer Tool” on page 54

򐂰

4.2, “Migrating the Document Manager documents” on page 57

򐂰

4.4, “Migrating Personalization data” on page 67

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

4. In the “Step 3: Map modules to application servers” window (Figure 4-4) select

WebSphere_Portal as the module for the installation and check jcrpublishwar as the module to be installed, and click Apply.

Click Next two times, leaving the default values intact, to go to the “Step 5: Summary” window.

Figure 4-4 Mapping modules to application servers

5. In the “Step 5: Summary” window (Figure 4-5), click Finish to complete the task.

Figure 4-5 Summary

6. In the page that opens, click the hyperlink Save to Master Configuration (the third line from the bottom), and then click the hyperlink Save in the Messages window to apply the changes to the master configuration.

Chapter 4. Migration of Document Manager and Personalization 55

7. Restart WebSphere_Portal.

You must now restart the WebSphere Portal V5.1 server. You may want to do this by issuing the following command in your command-line interface (assuming yours is a

Windows environment): cd <portal_server_root>\config

WPSconfig.bat stop-portal-server start-portal-server

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

2. Now check WebSphere_Portal SystemOut.log located in <portal_server_root>\log

(Figure 4-7). Look for icmjcrear. It must tell you that the application is started.

Figure 4-7 SystemOut.log: icmjcrear is started

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. 4.2.1, “Preparing a checklist for Document Manager validation” on page 58

2. 4.3, “Synchronizing Document Manager global access” on page 58

3. 4.3.1, “Modifying the Document Manager properties” on page 60

4. 4.3.2, “Creating directories for Document Manager migration” on page 61

5. 4.3.3, “Running the export task for Document Manager” on page 62

6. 4.3.4, “Copying files to the WebSphere Portal V6 server” on page 64

7. 4.3.5, “Running the transform task for Document Manager” on page 64

8. 4.3.6, “Running the import task” on page 66

9. 4.3.7, “Validating the Document Manager” on page 67

Chapter 4. Migration of Document Manager and Personalization 57

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) Name

\ (AC:Default) 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 Best Practices for Migrating to IBM WebSphere Portal V6

– Click the Assign Access icon of ICM_CONTENT_REPOSITORY.

– Check the access control for each role (Figure 4-8).

Figure 4-8 Document Manager global access in WebSphere Portal V5.1 server

2. Use the checklist shown in Table 4-2 to set the same access control on WebSphere Portal

V6 server.

Table 4-2 Checklist for Document Manager global access

Role Propagation Inheritance

Administrator On On

Groups/Users wpsContentAdministrators wpsadmins

Security Administrator On

Delegator

Manager

Editor

Privileged User

User

On

Chapter 4. Migration of Document Manager and Personalization 59

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 environment’s requirements.

Table 4-3 Document Manager properties you must change

Property name Description

MigDirSource The migration directory on the source (V5.1) server. This directory will be used for export from V5.1. Ensure that this directory is empty.

MigDirSourceShared

MigDirTarget

SourceServerPort

TargetServerPort

DocLib

The directory on the target (V6) server. The tasks that take place after the export task are required to access the exported data from the target (V6) server. Because mapping environment is not used, the exported data must be copied to the target server’s local directory. This property is the local directory where the exported data is stored.

The migration directory on the target (V6) server. This directory will be used for import to V6. Ensure that this directory is empty and is different from the

MigDirSourceShared.

The fully qualified host name and port for the V5.1 server. By default, the port for the V5.1 server is 9081. WPmigrate command communicates with the V5.1 server through this port.

The fully qualified host name and port for the V6 server. By default, the port for the V6 server is 10038. WPmigrate command communicates with the V6 server through this port.

The list of Document Libraries to migrate, separated by commas, for example, Document Manager or Document Manager, and MyLib

60 Best Practices for Migrating to IBM WebSphere Portal V6

Property name

ExportUserId

ExportPassword

ImportUserId

ImportPassword

IncludeWorkflow

IncludeVersion

Description

Set this value to the V5.1 portal administrator user ID that you specified as

PortalAdminId in wpconfig.properties. This must be a fully qualified DN.

Set this value to the V5.1 portal administrator password.

Set this value to the V6 portal administrator user ID that you specified as

PortalAdminiId in wpconfig.properties. Short name can be used even if

LDAP security is enabled.

Set this value to the V6 portal administrator password.

Change to true to migrate the workflow information, including submitted drafts.

Change to true to migrate the document versions.

Important: The best practice is to use fully qualified host names, “/” instead of “\”, and include the entire path in properties.

Also, do not forget to take a backup of the original file.

Important: ExportUserId in the properties file must be in full DN format unless the short name is unique. ImportUserId can also be short name.

Tip: For clarity, change the file names to include the reference to the system they are on.

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.

Chapter 4. Migration of Document Manager and Personalization 61

Important: As described in the WebSphere Portal Information Center, you can share the

MigDirSource directory with the V6 server (sharing can be implemented with net use or

Network File System (NFS) mount, and so on) as the MigDirSourceShared directory.

However, it is recommended that you create another directory on the V6 server because file sharing is not allowed in many production environments. This IBM Redpaper assumes that file sharing will not

be used.

The IBM WebSphere Portal Version 6.0 Information Center is available on the Web at: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp

.ent.doc/wpf/mig_tbl.html

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

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

Chapter 4. Migration of Document Manager and Personalization 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 Best Practices for Migrating to IBM WebSphere Portal V6

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

Chapter 4. Migration of Document Manager and Personalization 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 Best Practices for Migrating to IBM WebSphere Portal V6

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. 4.4.1, “Preparing a checklist for Personalization validation” on page 68

2. 4.4.3, “Modifying Personalization properties” on page 69

3. 4.4.4, “Creating directories for Personalization migration” on page 70

4. 4.4.5, “Running the export task for Personalization” on page 70

5. 4.4.6, “Copying files to WebSphere Portal V6 server” on page 72

6. 4.4.7, “Running the transform task for Personalization” on page 73

7. 4.4.10, “Running the import task for Personalization” on page 75

8. 4.4.11, “Validating your Personalization” on page 76

Chapter 4. Migration of Document Manager and Personalization 67

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 Target Resource/Rule Name

OK Rules Simple Doc Rule

Component

Document Manager

Restriction: Rules from earlier versions that made use of the site area property in

Workplace Web Content Management must be manually updated after Workplace Web

Content Management migration. Refer to the Web content resource collection topic in the

IBM WebSphere Portal Version 6.0 Information Center for more information: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp

.ent.doc/wpf/mig_tbl.html

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

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 Description

SourceServerPort

TargetServerPort

The fully qualified host name and port, where WebSphere Portal is running on the V5.1 server

The fully qualified host name and port, where WebSphere Portal is running on the V6 server

ExportNode

SourceExportData

TargetExportData

TempData

SourceRepository

UserId

The path of the node that will be exported

The directory on the V5.1 server where the exported data is saved. This path must be an existing, empty directory.

The directory on the target (V6) server. The tasks after the export task are required to access the exported data from the target (V6) server. Because mapping environment is not used, the exported data must be copied to the target server’s local directory. This property is the local directory where exported data is stored.

An existing, empty directory on the V6 server. This directory is used to store temporary data.

The user ID used to connect to the WebSphere Portal V5.1 server Java

Content Repository (JCR) repository. Therefore, specify the portal administrator user ID of your WebSphere Portal V5.1 server. This must be a fully qualified DN.

SourceRepository

Password

SourceWorkspace

TargetRepository

UserId

TargetRepository

Password

TargetWorkspace

IncludeVersion

The password used to connect to the WebSphere Portal V5.1 server JCR repository. Therefore, specify the portal administrator password of your

WebSphere Portal V5.1 server.

The name of the workspace holding the V5.1 data. Unless V5.1

Personalization has been customized to use a different workspace, this must always be ROOTWORKSPACE.

The user ID used to connect to the WebSphere Portal V6 server JCR repository. Therefore, specify the portal administrator user ID of your

WebSphere Portal V6 server. Both the short name and the fully qualified DN work independently of the LDAP configuration.

The password used to connect to the WebSphere Portal V6 server JCR repository. Therefore, specify the portal administrator password of your

WebSphere Portal V6 server.

The name of the workspace that holds the V6 data. Unless Personalization

V6 has been customized to use a different workspace, this must always be

RULESWORKSPACE.

This specifies whether to migrate versions, if any, of Personalization.

Important: SourceRepositoryUserId in the properties file must be in fully qualified DN format. This is required because V5.1 cannot use short name. TargetRepositotyUserId can be a short name. Use the Portal admin user, which is specified as PortalAdminId in the wpconfig.properties file.

Chapter 4. Migration of Document Manager and Personalization 69

Important: Do not forget to take a backup of the original file.

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

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

Chapter 4. Migration of Document Manager and Personalization 71

The export task creates files under the

SourceExportData

directory that you specified

according to the information provided in Table 4-5. You can find the

rootworkspace

directory there, and see that there are files whose names are associated with your Personalization data

(Figure 4-21).

Figure 4-21 Export task for Personalization: Successful creation of files

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

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

Chapter 4. Migration of Document Manager and Personalization 73

Note: The commands for Personalization are slightly different from the commands for

Document Manager. The Personalization commands have a -51x suffix.

Validation

The WPmigrate command must report a BUILD SUCCESSFUL

message (Figure 4-24).

Figure 4-24 Transform task for Personalization: BUILD SUCCESSFUL message

Important: Even if the source is wrong, the task runs to completion and report a “ BUILD

SUCCESSFUL ” message.

Also check whether the files have been successfully written to the

TempData

directory, which

you specified, as described in “Creating directories for Personalization migration” on page 70.

You can find the rootworkspace directory there (Figure 4-25).

Figure 4-25 Transform task for Personalization: Successful transformation

74 Best Practices for Migrating to IBM WebSphere Portal V6

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

The WPmigrate command must report a BUILD SUCCESSFUL

message (Figure 4-27).

Figure 4-27 Import task for Personalization: BUILD SUCCESSFUL message

Chapter 4. Migration of Document Manager and Personalization 75

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

5

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

© Copyright IBM Corp. 2007. All rights reserved.

77

5.1 Migration considerations

IBM Workplace Web Content Management’s repository architecture has changed significantly in the latest release. Workplace Web Content Management now uses the Java

Content Repository (JCR) to manage content, thus allowing for tighter integration with

Personalization and Document Manager and other JCR-related products. By moving to the

JCR, Workplace Web Content Management now supports clustering. The architecture for

Workplace Web Content Management is now more in line with current portal architectures, where clones can share the same Workplace Web Content Management repository. Unlike earlier releases, where there existed a separate Workplace Web Content Management repository, Workplace Web Content Management now inputs managed assets into the JCR database.

The migration is a process of exporting data from the Workplace Web Content Management repository, transforming each asset into a new format, and importing the assets into the JCR.

There is no simple 1-1 correlation between an old Workplace Web Content Management asset and a new Workplace Web Content Management asset represented in the JCR.

Instead, you may find many JCR nodes that represent one content item. As a result, the number of transformed items might not match the number of exported items. Similarly, the number of transformed items might not match the number of imported items.

Because the architecture has been simplified in this release, it is best to migrate only a few of your Workplace Web Content Management environments. If you are working in a production cluster, it is best to migrate only the primary node and rebuild the cluster. Each secondary node will automatically pick up the portal pages, Workplace Web Content Management rendering portlets, and now the Workplace Web Content Management content. A migration of the authoring and development environments must occur.

Syndicators and subscribers are not

migrated in this migration process. With clustering now supported, syndication only has to be set up from one environment to another, instead of one clone to another, as in earlier releases.

Custom applications must also be considered. Applications using the Web Content

Management application programming interfaces (API) have to be modified to include Web

Content Management library information. JavaServer Page (JSP) fragments that use Web

Content Management APIs must be tested and reviewed. The migration process does not move these JSPs over from the old server to the WebSphere Portal V6 server. Repackaging the Workplace Content Management enterprise application to include these JSPs for deployment into a cluster must be considered.

New enhancements to the authoring environment have reduced the necessity for custom authoring environments, such as the Custom Template Portlet. These enhancements include

more inline editing tools, custom templating, and launch page configuration. Refer to 5.3.7,

“Postmigration tasks” on page 100 for more information about these enhancements. However,

the Custom Template Portlet should still work in the WebSphere Portal V6 server, with changes to the Web Content Management Repository login through the API to account for library information. Alternatively, the default library can be set in

WCMConfigService.properties by updating the defaultLibrary property.

78 Best Practices for Migrating to IBM WebSphere Portal V6

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

It is recommended that you take the following points into consideration:

򐂰 Understand that moving large amounts of data will take a long time. Ensure that you perform this task at a time that does not conflict with peak usage.

򐂰 Any password-protected file that is within the Web Content Manager must be removed before migration

򐂰 Any Personalization data that does not have a rule or content spot must be removed

򐂰 Install all the required fixes before migration. Not all the migration fixes listed in the following Web site are required (some depend on what additional components you are expecting to migrate): http://www.ibm.com/support/docview.wss?rs=688&uid=swg24013927

The fixes for Workplace Web Content Management are PK34286, PK30057, and

PK30516.

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.

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 81

Perform the following tasks:

1. Create a directory under <portal_server_root>\migration\ called wcm (Figure 5-1).

create new directory

Figure 5-1 Creating the wcm directory on WebSphere Portal V6 server

82 Best Practices for Migrating to IBM WebSphere Portal V6

2. Copy the config and ilwwcm folders to the newly created directory (Figure 5-2).

Note: Skip the copy ilwwcm step if you are not using Cloudscape for your Workplace

Web Content Management database.

Copy to WebSphere Portal V6 server

Figure 5-2 Copying the config directory

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 83

Copy only

ilwwcm if you are using out-of-the-box Cloudscape WCMDB. Figure 5-3 shows

copying the WCMDB if you are using the Cloudscape database.

Copy this directory ONLY if you are using cloudscape database

Figure 5-3 Copy WCMDB if you are using the Cloudscape database

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

jar:exporter/lib/ilwwcm-commons-properties.jar:exporter/lib/ilwwcm-commons-utils.j

ar:exporter/lib/ilwwcm-commons-version.jar:exporter/lib/ilwwcm-commons-xmlpersiste ncy.jar:exporter/lib/ilwwcm-framework.jar:exporter/lib/ilwwcm-server.jar:exporter/ lib/j2ee.jar:exporter/lib/jcr.jar:exporter/lib/wp.base.jar:exporter/lib/wp.user.ap

i.jar

(If you are using DB2 jdbc drivers, add the following string to the end of classpath=) exporter/lib/db2cc.jar:exporter/lib/<license that in is in the <runtime

Server>SQLLIB\java> Here are the possible licenses that you will might find in that directory db2jcc_license_cu.jar or db2jcc_license_cisuz.jar

(If you are using Oracle® jdbc drivers, add the following string to the end of classpath=) exporter/lib/classes12.jar

(If you are using SQL jdbc drivers, add the following string to the end of classpath=) exporter/lib/mssqlserver.jar:exporter/lib/msbase.jar:exporter/lib/msutil.jar

You must then configure aptrixjpe.properties

and connect.cfg

to the current migrated environment. In both the properties files, ensure that the JDBC driver equals the data repository version that you are using, and that it points to the wcmdb on the old system. This file must be updated only in two situations:

򐂰 The Workplace Web Content Management repository is a local Cloudscape DB, and therefore, paths to the local Cloudscape DB must be updated.

򐂰 Use Type 4 drivers when the DB2 database has not been cataloged locally.

If you are using DB2, configure aptrixjpe.properties and connect.cfg to the current migrated environment as follows:

򐂰 aptrixjpe.properties

Ensure that jdbc.url=jdbc:db2://<db2 host name>:<port number>/wcmdb is configured to point to the database of the old system and that there are no spaces before or after the

URL.

򐂰 connect.cfg

Ensure that <jdbc:db2://<db2 host name>:<port number>/wcmdb driver="com.ibm.db2.jcc.DB2Driver /> is configured to point to the database of the old system and that there are no spaces before or after the URL. Also ensure that the driver=

<jdbc driver of your RDBMS> is using the correct one and not the default Cloudscape driver (com.ibm.db2.jcc.DB2Driver).

Note: The port number for DB2 on your new system can be found under

%systemroot%/system32/drivers/etc/services on Windows systems and /etc/services on UNIX systems.

If you are using the out-of-the-box Cloudscape Web Content Management database, make sure that you are pointing to the database on the new system

that you copied from the old system.

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 85

You must update the migration.properties file that is located in the portal_server_root/wcm/migration/config directory on WebSphere Portal V6 server before running the Workplace Web Content Management migration commands. In the file, it is

necessary to confirm that the parameters are set and modified, based on Table 5-1.

Following is what you should look for in the properties file to update it for migration:

<name>.path = C:/Websphere/PortalServer/migration/wcm/<name>

Tip: Use forward slash in path names. Both Windows and UNIX can handle forward slashes.

Table 5-1 Explanation of the migration.properties file migration.properties file Explanation export.path

import.path

The path on the local file system where exported data is saved

The directory on the local file system where transformed data is saved summary.path

legacy.config.path import.servlet.url

import.library.name

The path on the local file system where summary configuration files will be created. These files will be used when migrating a secondary system.

The path on the local file system where the old

Web Content Management configuration is located

The URL of the import servlet running on the new system. Replace local host with the appropriate host name for the new system.

The name of the library created during import

Finally, increase the total transaction lifetime timeout of your new WebSphere Portal server to at least 480 seconds through the WebSphere Application Server administrative console.

Navigate to Application Servers

Server

Container Services

Transaction Service.

Make a note of the current total transaction lifetime timeout so that it can be restored after you have completed the migration. For more information, refer to the topic “Migrating User

Profiles” in the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en

t.doc/wcm/wcm_migration_users.html

Restart

the Portal Application Server before you begin the wcmmigrate tasks.

Important: The WebSphere Portal server must be running on WebSphere Portal V6 before you begin the wcmmigrate tasks.

86 Best Practices for Migrating to IBM WebSphere Portal V6

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

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 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 Best Practices for Migrating to IBM WebSphere Portal V6

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 What it accomplishes

Validate estimate-data

Confirms that the migration.properties files, network connectivity, and user permissions are correctly configured. This command requires that you add a user name and password to the command.

Provides an estimate of the time taken and space required for the data migration

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 89

wcmmigrate command What it accomplishes export-data transform-data

Exports items from the old system

Transforms exported items so that they are ready to be imported into the new system import-data Imports the transformed items. This requires a user name and a password. a a. This command can take a long time, depending on how much data you are importing.

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

Fails on Export

Fails on Transform

Fails on Import

Fails on Configure-local

Possible cause

򐂰 Make sure that the migration.properties, legacy.config.path, is pointed to the correct set of config files

򐂰 Make sure that the config files point to the correct database. If Cloudscape is being used, ensure that the database was copied and that the config files point to it.

򐂰 Ensure that the database machine is started and is accessible from the WebSphere Portal

V6 server

򐂰 Ensure that export.path points to a usable directory structure, for example, if using

UNIX, do not

set the export path to c:\export

򐂰 Ensure that export.path has enough space for exporting all the Workplace Web Content

Management assets

򐂰 Ensure that the database server is running and is accessible

Ensure that import.path has enough space for transforming all the Workplace Web Content

Management assets

򐂰 Ensure that the Workplace Web Content

Management V6 database server is running

򐂰 Ensure that the WebSphere Portal V6 server is running

򐂰 Ensure that the WebSphere Portal server config, configure-wcm-migration, has been run

򐂰 Ensure that the WebSphere Portal V6 server is running

򐂰 Ensure that the user specified in the wcmmigrate task has the rights to execute the xmlaccess tasks

90 Best Practices for Migrating to IBM WebSphere Portal V6

Possible error

Fails on Configure-remote

Possible cause

򐂰 Ensure that the WebSphere Portal V6 server is running

򐂰 Ensure that the summary.path is correct and has been copied from the Web Content

Management V6 server

򐂰 Ensure that the <WebSphere Portal

Server>/wcm/migration/remote_rendering.pr

operties has been updated with the correct values. Using fully qualified host names is recommended.

In the portal_server_root/wcm/migration directory, issue the following command to restart or resume the tasks that were running: wcmmigrate -user <username> -password <userPassword> <command> -restart

Issue the following command to resume the tasks if the tasks timed out or the networks failed: wcmmigrate -user <username> -password <userPassword> <command> -resume

Figure 5-9 shows the resume or restart command.

Figure 5-9 Resume or restart command

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.

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 91

3. Run the following import command: wcmmigrate import-data

Notes:

򐂰 This step is the one that takes the longest amount of time, and must be completed successfully. It takes many hours, possibly days to complete.

򐂰 It is very resource intensive and long-running.

򐂰 Because this task runs against a URL, watch out for timeouts.

򐂰 When running this command, consider the volume of data and the space that you currently have on the system that you are migrating.

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

2. Select Launch

Web Content (Figure 5-11).

Click here

Figure 5-11 Launching the Web Content page

3. Select Web Content Management and click Continue to launch the Library page

(Figure 5-12).

Click the WCM tab

Figure 5-12 Launching the Library section

Click here to launch the Library

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 93

4. In the Library page, add a library by selecting the relevant library and clicking Add. To

remove a library, select the corresponding library and click Remove (Figure 5-13). Click

OK after completing the task.

Figure 5-13 Adding the migrated library

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

5. In the page that opens (Figure 5-14), search for Web Content Authoring. In the list that is

displayed, select Web Content Authoring and click OK to add the portlet to the page.

Figure 5-14 Adding the Web Content authoring portlet.

6. Work through the content in the Authoring Portlet to make sure that everything is there.

7. Preview the content, especially with regard to Personalization and Document Manager.

8. Validate the security, the templates, the workflow, and so on.

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 Portal’s WebSphere Member Manager lookaside tables.

The WebSphere Member Manager attributes that contain the users’ categories and key words are WCM:CATEGORIES and WCM:KEYWORDS respectively. The

WCM:CATEGORIES contain IDs to the category objects in Web Content Management.

These IDs must be updated to point to the new IDs for the migrated categories. This task updates these IDs.

Note: Migrate WebSphere Member Manager before migrating the user profiles. For details, refer to the IBM WebSphere Portal Version 6.0 Information Center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp

.ent.doc/wpf/sec_mig_roles.html

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 95

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

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.

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 97

After you have answered these questions, you are ready to configure the remote rendering portlets:

1. Edit portal_server_root/wcm/migration/config/remote_rendering.properties.

2. If you have multiple Workplace Web Content Management Rendering Servers, change the remote.host.base.path.list value from “all” to the values of the previous hosts that you want to configure with the new Workplace Web Content Management Rendering Server host.

3. Uncomment the WCM_REMOTE_HOST_BASE_PATH and put in the correct value to the new Workplace Web Content Management Rendering Server.

4. Copy the summary data from the Workplace Web Content Management Rendering Server to the Portal server.

5. Update portal_server_root/wcm/migration/config/migration.properties by changing the property, summary.path, to point to that directory.

6. Run the following command: wcmmigrate configure-remote

98 Best Practices for Migrating to IBM WebSphere Portal V6

Example: Consider an environment where you have two Workplace Web Content

Management Rendering Servers that must be migrated. The URLs for the old

Workplace Web Content Management Rendering Servers are http://old_wcm_1 and http://old_wcm_2. The URLs to the new Workplace Web Content Management

Rendering Servers are http://new_wcm_1 and http://new_wcm_2.

To migrate the remote rendering portlets that point to http://old_wcm_1 to point to http://new_wcm_1:

1. Edit the value of remote.host.base.path.list to http://old_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties.

2. Edit the value of WCM_REMOTE_HOST_BASE_PATH to http://new_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties.

3. Copy the summary data from the new_wcm_1 server to a directory on the Portal server.

4. Edit the portal_server_root/wcm/migration/config/migration.properties and change the summary.path point to the data copied in step 3.

5. Run the following command: wcmmigrate configure-remote

Repeat the same process to migrate the remote rendering portlets that were configured for http://old_wcm_2 to point to http://new_wcm_2.

If you want to migrate both the remote rendering portlets that were configured for http://old_wcm_1 and http://old_wcm_2 to point to http://new_wcm_1, perform the following tasks:

1. Edit the value of remote.host.base.path.list to http://old_wcm_1,http://old_wcm_2 in portal_server_root/wcm/migration/config/remote_rendering.properties.

2. Edit the value of WCM_REMOTE_HOST_BASE_PATH to http://new_wcm_1 in portal_server_root/wcm/migration/config/remote_rendering.properties.

3. Copy the summary data from the new_wcm_1 server to a directory on the Portal server.

4. Edit the portal_server_root/wcm/migration/config/migration.properties and change the summary.path point to the data copied in step 3.

5. Run the following command: wcmmigrate configure-remote

7. The last step is to perform a full function check on WebSphere Portal V6 server before notifying your users.

Important: The numbers reported will be wrong, possibly 0. This is because it actually

runs XML access. As you learned in 5.1, “Migration considerations” on page 78, these

numbers will not match the numbers reported on import.

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 99

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 creator’s experience. Features such as

inline edit

, custom templates creation

, and

Launch page configurations

have been added to simplify the process of adding content.

Inline edit is where a link to edit a piece of content will be displayed when a content author is viewing the contents on a page. When the link is selected, the content automatically opens in the authoring template and is ready for editing.

The creating custom templates feature has also been added to the authoring UI. When defining an authoring template, the Web Content Management administrator can now override certain fields with JSPs. JSPs provide a multitude of customization options. This function can be used for the following:

򐂰 Formatting the field to create a uniform look

򐂰 Personalizing the list of choices a user can choose from when inputting the field

򐂰 Performing validation by adding Javascript functions

򐂰 Performing queries on external repositories to pull in data into the field, for example, pulling in IBM Content Manager references into Workplace Web Content Management content.

Configuring a Launch page can also greatly enhance the content contributor’s experience.

The Launch page can also be a JSP, which provides more flexibility. By configuring a Launch page, the content contributor will not see the typical Explorer view. Instead, the Launch page will be shown. This function can be used for the following:

򐂰 Providing a personalized list of links to authoring templates to create content, using remote actions

򐂰 Providing a list of links to content that must be updated or approved

Workplace Web Content Management V6 provides a number of capabilities in addition to its authoring environment enhancements. The three major additions are

Library enhancement

,

Link and Stylesheet components

, and

Referential integrity

.

Libraries allow for an added separation of content. In the earlier releases, content was stored in one central repository. With Libraries, you add an additional layer to this repository to group relevant content together. Each library has its own set of security. The Web Content

Management UI can be configured to show only certain libraries. Libraries can be used for the following:

򐂰 Grouping the shared components into a library referenced from other libraries

򐂰 Configuring a library per department

򐂰 Configuring a library per new Web site release

100 Best Practices for Migrating to IBM WebSphere Portal V6

The Link component allows the content creator to manage links as a Workplace Web Content

Management asset. These links can be reused in content or presentations. The link component provides a more structured component to link to both internal Workplace Web

Content Management assets and external URLs.

The Stylesheet component allows the content contributor to manage the stylesheet as a separate reusable asset. It provides for cascading stylesheets and other typical features of stylesheets such as media-type definition.

Referential integrity is a nice addition to Web Content Management. It allows users to view content being referenced from other content. It also provides the user with a choice when deleting a content item that is referenced by another content item. This is a big change from earlier releases, where deleting a reference content item left broken links.

There are many more enhancements to Web Content Management, including better

Personalization and Document Manager integration, improved rendering performance, clustering and failover, and so on. For more recommendations about updating the old Web

Content to take advantage of the new Workplace Web Content Management features, refer to the IBM WebSphere Portal Version 6.0 Information Center to utilize the new features of

Workplace Web Content Management: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.wp.en

t.doc/wcm/wcm_migration_post.html

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.

Chapter 5. Migration from WebSphere Portal V5.1 for deployments with Workplace Web Content Management 101

To copy the summary data, use the following procedure:

1. Open migration.properties on the primary system, and find the summary.path property.

2. Copy the data in the directory referred to by the summary.path property from the primary machine to the local (secondary) machine.

3. Open migration.properties on the local machine, and edit the summary.path property to refer to the copied summary data.

Web Content Management rendering portlets must be reconfigured. Perform this task by using the wcmmigrate configure-local and configure-remote commands, as long as the summary data is available. In the River Bend example, the commands behaved as described

in 5.3.6, “Migrating the Workplace Web Content Management rendering portlets” on page 97.

The alternative to using the wcmmigrate commands is to reconfigure the rendering portlets manually.

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

A

Appendix A.

Troubleshooting and other tips

This appendix provides troubleshooting and other information relevant to the migration process.

© Copyright IBM Corp. 2007. All rights reserved.

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 Unique identifier (UID)

WebSphere Portal content publishing (WPCP) DCE:2b5645f0-0526-1211-0000-03703b72fbc4:1

Portal document management

Business Object Struts Application com.ibm.wps.portlets.pdm

PortletApplication_com.ibm.wps.portlets.busi

nessobject com.ibm.workplace.universalsearch.portal

Search Center Portlet Application

Lotus Collaboration Center Welcome application com.lotus.epp.deppwelcome.DeppWelcome

Portlet.50450ef473

Document Picker Application

Manage Document Libraries

Search Admin Application

Welcome

򐂰 Domino Struts Template Application

򐂰 Domino Struts Data Document Viewer

򐂰 Domino Struts IFrame Document Viewer

Business Object Builder Portlets com.ibm.wps.portlets.docP* com.ibm.wps.portlets.mdl

PSE.c04954cae56800171f9b9847e0486da9

com.ibm.wps.portlets.welcome

PortletApplication_com.ibm.wps.portlets.bof_

domino_strut com.ibm.wps.portlets.bo

com.ibm.wps.portlets.manage* com.ibm.wps.portlets.install

Admin Portlets

Portlet Installer

IBM Internet Mail Box

Sample Portlets

򐂰 QuickplacePortlet

򐂰 Quickplace Launch Portlet com.ibm.wps.portlets.wpsmail.ea

sample10.portlets.4195

com.ibm.wps.portlets.quickplace.*

Note: uid="com.ibm.wps.portlets.quickplace.WpsQ

PController" does migrate to WPS6.0

com.ibm.wps.portlets.sametime.WpsSametime

Portlet

򐂰 Sametime® Portlet

򐂰 Sametime Launch Portlet

Quick E-mail

Click-to-Action (C2A) Samples

Tourist Application (Sample portlet)

Quick Appointment

Syndicated Content (WPCP)

C2AStrutsExample application

Financial Time Portlet com.lotus.quickEmail

com.ibm.wps.portlets.shippingc2a

DG.com.ibm.wps.coop.samples.5691.pp

DCE:7d2f4560-24da-1211-0000-005d70d3ce08:

1

DCE:b067c2c0-1eba-1211-0000-02884891a5dd:1

DCE:62b7a9f0-dc7f-1201-0000-005d32bb94e8:1 com.ft.level0.Demo.1234

104 Best Practices for Migrating to IBM WebSphere Portal V6

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 actionset="Privileged User" update="set">

<role actionset="Administrator" update="set">

<role actionset="Manager" update="set">

<role actionset="Editor" update="set">

<role actionset="Delegator" update="set">

<role actionset="Security Administrator" update="set">

6. Save this modified file with a new name, for instance, privUsersRemoved.xml, and import

it back into the portal, as shown in Example A-5.

Example: A-5 Saving the modified file with a new name and importing it back into the portal

<portal_server_root>/bin xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -in privUsersRemoved.xml -out resultsOfPrivUserRemoval.xml

7. To return the WebSphere Portal server to its original configuration, run the backed up

export file, as shown in Example A-6.

Example: A-6 Running the backed up export file

<portal_server_root>/bin xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://m51e.cam.itso.ibm.com:9081/wps/config -in ExportAllBackUp.xml -out resultsOfPrivUserRemoval.xml

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

running a task. Not all the properties than can be set exist in the Admin console. In such a situation, the default values are automatically used. In order to avoid adding them to the wrong place or misspelling them, it is a best practice to update properties through the update configuration task.

This following steps describe how to achieve this:

1. Use a text editor to open the DataStoreService.properties file under

<portal_server_root>\config\properties.

2. Uncomment the scheduler.cleanup.enabled property (by removing the # character) and change the value to false . Save and close the file.

3. Run <portal_server_root>\bin\WPSconfig update-properties.

4. If you are running WebSphere Portal in a cluster configuration, replicate your changes to the cluster.

5. Restart the WebSphere Portal server.

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

Appendix A. Troubleshooting and other tips 107

򐂰 Enable Tracing

򐂰 Manage Clients

򐂰 Unique Names

򐂰 URL mapping

򐂰 Welcome to WebSphere Portal

򐂰 Information Portlet

򐂰 Web Clipping Editor

򐂰 Manage Collections

򐂰 Search

򐂰 Import XML

򐂰 Manage Virtual Portals

򐂰 Login Portlet

򐂰 Edit My Profile

򐂰 Manage Search Collections

򐂰 Manage Search and Browse

򐂰 Pending Search Collection Items

򐂰 Manage Seed List

򐂰 Search and Browse

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

򐂰 Document Picker

򐂰 RSS Portlet

򐂰 Import XML

򐂰 Manage Virtual Portals

򐂰 Login Portlet

򐂰 Edit My Profile

򐂰 Manage Seed List

򐂰 Manage Search Admin Portlet

򐂰 Sitemap

򐂰 Search and Browse

򐂰 Content Palette

򐂰 Template Catalog Manager

򐂰 Parameters

򐂰 Properties portlet

򐂰 Roles portlet

򐂰 Community

򐂰 Application Catalog

򐂰 People Finder JSR168

Migrating the search collections

Employees of the River Bend company must be able to search the Web site of another company called itsoco. Itsoco’s Web site uses basic authentication. The employees must also be able to search the River Bend Web site itself. Therefore, the employees have defined two search collections. These collections are used by the Search and Browse portlets.

To demonstrate the migration process, the itsoco search collection migration is described here.

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”

Appendix A. Troubleshooting and other tips 109

4. Copy this XML file to a directory of your choice on the WebSphere Portal V6 server.

Important: Do not

copy the collection directory.

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

– Specify Collection Language

Select this to match the old setting.

– Select Categorizer

This is optional, and will be overwritten by the import.

– Select Summarizer

This is optional, and will be overwritten by the import.

– Remove common words such as “in”, “of”, “on”, and so on from queries

Check or uncheck this to match the old setting.

Figure A-3 shows the itsoco search collection redefined for the WebSphere Portal V6

server. Click OK.

Important: Do not

create collection sources. They will be created by the import. The import will fail if a collection source is defined.

Figure A-3 The itsoco collection defined

Appendix A. Troubleshooting and other tips 111

3. The Manage Search window opens (Figure A-4). In this window, click the icon (highlighted in Figure A-4) for Import or Export collection. This is the file exported and copied to the

WebSphere Portal V6 server, as described in “Exporting the collection from WebSphere

Portal V5.1 server” on page 109.

Figure A-4 Readying to import the itsoco collection

4. Enter a fully qualified name of the exported XML file, as shown in Figure A-5. (There is no

facility to browse to find the location of the XMLM file.) Click Import.

Restriction: You cannot import into a collection that has already been populated. The import command will show an error message. If you have to reimport, delete and re-create the collection.

Figure A-5 Specifying the location of the XML file for import

112 Best Practices for Migrating to IBM WebSphere Portal V6

This returns you to the Manage Search page with a message confirming successful

import, as shown in Figure A-6. Note that the number of documents shows “0” at this

point.

Figure A-6 Import successful

5. At this point, WebSphere Portal fetches the documents from the migrated URLs and

rendexes them in the background. When you click Refresh, as displayed in Figure A-7,

the number of active documents increases. You can now browse the documents.

Figure A-7 Document count refreshed

Appendix A. Troubleshooting and other tips 113

The itsoco Web site uses basic authentication. The values entered in WebSphere Portal

V5.1 server for the itsoco collection has migrated automatically, as can be seen from

Figure A-8.

Figure A-8 Security has migrated

Restriction: When you import a portal site collection from WebSphere Portal V5.1 server to WebSphere Portal V6 server, the collection configuration data is imported, but not the document URLs. Therefore, to enable users to search the portal site collection on the target portal, you can either import the portal site collection and then manually start a crawl, or re-create the portal site.

114 Best Practices for Migrating to IBM WebSphere Portal V6

6. If you have a Portal Search Collection for your own Portal site and have moved to a new server, the host name in the URL for the site would probably have changed. In such a situation, you must re-create the content source from the scratch. If the collection does not work after migration, as happened in one of the tests in our example, it is recommended that you verify the address of the content source. This will test to see if the search engine is able to connect to the site being searched. Navigate to Manage Search

Search

Collections and click the itsoco collection.

7. This displays the window shown in Figure A-9. Click the wrench icon highlighted in

Figure A-9 to verify the address.

Figure A-9 Verifying the address of the content source

8. The results are displayed, as shown in Figure A-10. In our example, we saw the following

message:

EJPJP0011W: Connection failed, Host: http://9.33.85.117/itsoco/index.html, Host might be down.

Appendix A. Troubleshooting and other tips 115

Use a browser from your workstation to see if there are any issues with the itsoco site. In our case, we found that the itsoco server was not running. After it was restarted, we repeated the address verification in WebSphere Portal server and received the following message:

EJPJB0025I: Content source http://9.33.85.117/itsoco/index.html in collection itsoco collection is OK.

Figure A-10 Connection failed

116 Best Practices for Migrating to IBM WebSphere Portal V6

9. Click the icon highlighted in Figure A-11 to refresh the collection data for the itsoco

collection.

Figure A-11 Refreshing collection data for itsoco collection

10.Click OK to dismiss the pop-up warning about CPU usage and, shortly afterwards, refresh the page. In our case, we saw that the documents had been collected, as shown in

Figure A-7 on page 113.

Appendix A. Troubleshooting and other tips 117

118 Best Practices for Migrating to IBM WebSphere Portal V6

B

Appendix B.

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

© Copyright IBM Corp. 2007. All rights reserved.

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

to correct any configuration problems in the current portal. (In future releases, this task might be used to remotely collect specific property files, properties, or other data to allow the detection of configured components and possibly allow automated configuration on the current portal.)

The filter extension

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

Each component directory must contain the two files displayed in Figure B-2:

򐂰 mig_ant.xml

This is the file that contains the actual Ant tasks to be executed.

򐂰 mig_description.xml

This is the file that describes the exported Ant tasks.

Figure B-2 Required files

The mig_ant.xml 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 portal’s host name

򐂰 ${PrevWpsPort}

The previous Portal’s port value

Appendix B. Extending the WebSphere Portal migration framework 123

򐂰 ${PrevWpsContextRoot}

The previous Portal’s context root

򐂰 ${PrevPortalAdminId}

The previous Portal’s admin ID

򐂰 ${PrevPortalAdminPwd}

The previous Portal’s admin password

򐂰 ${VirtualPortal}

The name of the virtual portal. An empty string if working with the default Portal.

򐂰 ${WORK_DIR}

The work directory for the current migration process

򐂰 ${importAllFile}

The import file that is modified by the filter extension points

The mig_description.xml file

The mig_description.xml file contains a <tasks> element that must contain one or more nested <task> elements. Each nested <task> element describes a target that is to be exported and how and when it is called. It also provides a short help description to be optionally displayed for each target.

The <tasks> element does not support any required or optional attributes. However, it must

contain nested <task> elements, as displayed in Figure B-3.

Figure B-3 Task elements

124 Best Practices for Migrating to IBM WebSphere Portal V6

What follows is an example of how to extend the migration framework. Our example assumes that we have a specific set of pages that must be removed. This can be done by customizing the default filters, but to be safer, we created our own plug-in and used the existing filter infrastructure.

In our example, we constructed a filter to remove all the pages with a unique name starting with "riverbend.admin". Note that the pages are not

going to be removed from the previous server, they will simply be filtered from the exported XmlAccess file before we attempt to import the file into the current server.

We created a River Bend filter directory in the <wp_root>/migration/component directory by executing the following command: mkdir -p <wp_root>/migration/component

In this command, <wp_root> is the portal installation root directory.

Using a text editor, we created the mig_ant.xml and the mig_description.xml file in the

<wp_root>/migration/components/riverbend directory. We constructed an Ant task to be called during the filter phase of the migration.

Migration filters

Migration filters can be created to remove pages, portlets, themes, skins, or any other artifact that has an object ID and a uniquely identifiable attribute. A filter file is a properties file that contains a filters property that defines the active filters and one or more filter definitions.

In our River Bend example, we wanted to filter the pages and the child pages that have a unique name starting with "riverbend.custom.page".

When creating a filter, we used the template shown in Example B-1.

Example: B-1 Filter template

# This properties files defines a list of filters used to process the Portal data export.

# The property "filters" defines the prefix for each filter

#

# Usage of each filter: filters=<filterX>,<filterY>

<filterX>.object: xmlaccess object ID. Examples: "client", "web-app",

"content-node". Required.

<filterX>.include: Optional comma-separated list of patterns to include. If any are specified, only these will be used. Overrides excludes.

<filterX>.exclude: Optional comma-separated list of patterns to exclude.

<filterX>.searchAttr: Filtering will be applied to this attribute. If no filtering, can list any attribute type. Required.

<filterX>.requestAttr: The attribute to use to request the object the next time.

Required.

<filterX>.secondaryAttr: Optional comma-separated list of secondary filters. For example, create-type=implicit.

Appendix B. Extending the WebSphere Portal migration framework 125

The filters property indicates which filters will be used during the filtering process.

Each filter, which is required to have a name, has six attributes associated with it. The attributes are affixed to the filter name in the format ".<attribute>", where the valid attributes are:

򐂰 object

The xmlaccess element ID. Examples include "client", "web-app", "content-node".

򐂰 include

The optional comma-separated list of patterns to include. If any are specified, only these will be used. It overrides exclude.

򐂰 exclude

The optional comma-separated list of patterns to exclude.

򐂰 searchAttr

Filtering will be applied to this attribute. If there is no filtering, can list any attribute type.

Required.

򐂰 requestAttr

The attribute used to request the object the next time. Must always be objectid. Required.

򐂰 secondaryAttr

The optional comma-separated list of secondary filters. Examples include

“create-type=implicit”.

Example B-2 shows what the contents of our filter file, RiverBendPageFilter.properties, look

like after we copied the template and made the appropriate updates. The include and exclude attributes allow a regular expression to specified.

Example: B-2 Filter file

# This properties files defines a list of filters used to process the Portal data export.

# The property "filters" defines the prefix for each filter

#

# Usage of each filter:

# <filter>.object: xmlaccess object ID. Examples: "client", "web-app",

"content-node". Required.

# <filter>.include: Optional comma-separated list of patterns to include. If any are specified, only these will be used. Overrides excludes.

# <filter>.exclude: Optional comma-separated list of patterns to exclude. Same as defaultExclude but these are easier to update by end-users

# <filter>.searchAttr: Filtering will be applied to this attribute. If no filtering, can list any attribute type. Required.

# <filter>.requestAttr: The attribute to use to request the object the next time.

For example, might want to filter by uid but request by objectid. Required.

# <filter>.secondaryAttr: Optional comma-separated list of secondary filters.

For example, create-type=implicit.

# filters=riverbend-page-filter riverbend-page-filter.object=content-node riverbend-page-filter.include=

126 Best Practices for Migrating to IBM WebSphere Portal V6

riverbend-page-filter.exclude=riverbend.custom.page* riverbend-page-filter.searchAttr=uniquename riverbend-page-filter.requestAttr=objectid riverbend-page-filter.secondaryAttr=

We saved this file into our River Bend plug-in directory.

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>

Appendix B. Extending the WebSphere Portal migration framework 127

<target name="filter-pages.com.riverbend" depends="init" unless="DoNotFilterRiverBendPages">

<!--

Filtering is a two step process. The first step scans the importAll.xml file for

object ID's that match the search filters. The object ID's are written to a file

specified by the attribute outfile.

The second step reads in the list of object ID's created by the fullExportFilter task

then it filters out each object that has a matching object ID found in the list. All

artifacts that have referential dependencies on a filtered object are also filtered.

For instance, if the page hierarchy is such that page A has child pages B and C if page A

is filtered, pages B and C are also removed.

The writeFilteredFile task will create a copy of the importAll.xml file with the

artifacts matching the object ID's in the file specified by the oidfile attribute removed.

-->

<fullExportFilter

infile="${importAllFile}"

outfile="${OidsOfRiverBendPagesToRemoveFile}"

inputproperties="${RiverBendFilterFile}"/>

<writeFilteredFile

oidfile="${OidsOfRiverBendPagesToRemoveFile}"

infile="${importAllFile}"

outfile="${RiverBendFilteredImportFile}"

checkparent="true" />

<!-- We need to replace the importAll.xml file with the one modified by this plug-in -->

<copy file="${RiverBendFilteredImportFile}" tofile="${importAllFile}" overwrite="true"/>

</target>

</project>

The mig_description.xml describes the targets available to be executed and defines when they will be called. The contents of the River Bend mig_description.xml are shown in

Example B-4.

Example: B-4 Sample mig_description.xml

<!--

Licensed Materials - Property of IBM

5724-E76, 5724-E77, 5655-M44

(C) Copyright IBM Corp. 2001, 2006 All Rights Reserved.

Riverbend mig_description.xml plug-in sample

128 Best Practices for Migrating to IBM WebSphere Portal V6

-->

<tasks>

<task name="filter-pages.com.riverbend" isxmltarget="true" nohelp="true" inall="false" dependencies="">

This task is responsible for filtering out pages from our Riverbend sample site,

</task>

</tasks>

The only task exported is "filter-pages.com.riverbend". It has the following attributes set:

򐂰 isxmltarget ="true"

This means that it gets executed during the filter phase of the import process.

򐂰 inall="false"

The target is not callable from the command line and is only called as part of the import-portal-content command processing.

򐂰 nohelp="true"

The target will not show up when help is displayed.

򐂰 dependencies=""

No dependencies

When running the migration with the sample component described earlier, all the pages in our

WebSphere Portal V5.1 server had a custom unique name that matched the string

“riverbend.custom.page”.

Appendix B. Extending the WebSphere Portal migration framework 129

130 Best Practices for Migrating to IBM WebSphere Portal V6

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

– Migrating user profiles http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm

.wp.ent.doc/wcm/wcm_migration_users.html

– Postmigration steps http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm

.wp.ent.doc/wcm/wcm_migration_post.html

򐂰 Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2 http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html

򐂰 Open Logic http://www.openlogic.co.uk/

򐂰 Technote: Domino Application Portlet for Portal v5.x does not work on Portal v6 http://www-1.ibm.com/support/docview.wss?rs=899&uid=swg21245417

򐂰 WebSphere Portal Update Installer http://www-1.ibm.com/support/docview.wss?rs=688&uid=swg24006942

򐂰 White paper: IBM WebSphere Portal Version V6.0 Tuning Guide http://www-1.ibm.com/support/docview.wss?uid=swg27008511&aid=1

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

Back cover

IBM WebSphere Portal V6:

Best Practices for

Migrating from V5.1

®

Red

paper

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.

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