Migration Step by Step Guide: WebSphere Portal v6.1.0.5 to

WebSphere Portal v7

Author: Dhaval PatelIBM WebSphere Portal Server Level 2 Support Specialist

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 grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.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 NONINFRINGEMENT, 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 believesappropriate without incurring any obligation to you.

Any performance data contained herein was determined in a controlled environment.Therefore, the results obtained in other operating environments may vary

significantly.

Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment

Information concerning non-IBM products was obtained from the suppliers of thoseproducts, 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.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject tochange without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

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.

This information contains sample application programs in source language, whichillustrate 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 programsconforming to the application programming interface for the operating platform forwhich 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.

If you are viewing this information soft copy, the photographs and color illustrations may not appear.

Preface -

This white paper assumes you have a good understanding and know the concepts of migration. If you are not sure, please review the general concepts of migration at the below provided location –

1) WebSphere Portal 6.1 Information Center – http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp

2) WebSphere Portal 7.0 Information Center – http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Migrating_wp7

SPECIAL NOTE: If you are using this guide on an operating system that is different than the example documented, some allowances must be made to convert commands and screens shown to your environment. This might include changing executable script commands from batch files (.bat) to shell scripts (.sh) or vice versa, or when using command-line utilities in place of graphical interfaces that might be shown.

NOTE: Migrating to a WebSphere Portal V7 cluster and managed node is not supported from WebSphere Portal V6.0.1.x and adds unnecessary complexity to the migration process.

NOTE: Migrating to a WebSphere Portal V7 cluster and managed node is supported from WebSphere Portal V6.1.x. Refer to the “Migrating a V6.1.x clustered environment” in WebSphere Portal V7 Information Center for more information.

Hence, WebSphere Portal V6.1.0.5 can be either stand-alone or clustered.

NOTE: Migrating to the empty portal 7 is not supported. Also private wires doesn't get migrated

Migrating from version 5.1 :

Migration directly to WebSphere Portal V 7 is not supported from WebSphere Portal Version 5.1.x.

• When migrating from version 5.1 you must first migrate to WebSphere Portal version 6.1. We recommend migrating to version 6.1.0.4 or later.

• Once you have migrated to WebSphere Portal version 6.1.0.4 or later, you then migrate your data and portlets to version 7.0.

Migration is not supported from Cloudscape

Migration is supported from a secure server only, and between equivalent offerings. For example, you can migrate from WebSphere Portal Enable

V6.1.0.x to WebSphere Portal Enable V7, but not from WebSphere Portal Express V6.1.0.x to WebSphere Portal Extend V7.

The table below summarizes all supported migration paths:

Table 1. Offerings and supported migration paths Offering WebSphere

Portal Express Version 7.0

WebSphere Portal Version 7.0 (Enable, Extend)

Web Content Management Version 7.0

WebSphere Portal Express V6.0.1.x on WebSphere Application Server Version 6.0

Supported Not Supported Not Supported

WebSphere Portal Server V6.0.1.x on WebSphere Application Server Version 6.0

Not Supported Supported Supported

WebSphere Portal Express Version 6.1.x on WebSphere Application Server Version 6.1

Supported Not Supported Not Supported

WebSphere Portal Server V6.1.x (Enable, Extend) on WebSphere Application Server Version 6.1

Not Supported Supported Not Supported

Web Content Management V6.1 on WebSphere Application Server Version 6.1

Not Supported Not Supported Supported

WebSphere Portal Server V6.1.x (Enable, Extend) on WebSphere Application Server Version 7.0

Not Supported Supported Not Supported

Web Content Management V6.1 on WebSphere Application Server

Not Supported Not Supported Supported

Version 7.0

Important: Migration is supported only from the two latest fix pack levels for any listed offering. For example, if you are using WebSphere Portal Version 6.1.0.1, and the two latest available fix packs are 6.1.0.4 and 6.1.0.5, you must apply one of those fix packs before you can migrate to Version 7.0.

Important Note: You cannot upgrade the source portal with a fixpack after migration if you intend to re-migrate the JCR. For example, if your source portal is running Version 6.1.0.4 and you migrate the portal to Version 7.0, you cannot then upgrade the source portal to Version 6.1.0.5 and migrate the JCR again. This is not supported.

Operation System (OS) :

You can migrate from an older version of an operating system to a newer supported version of that operating system, or from a 32–bit version of an operating system to a supported 64–bit version of that operating system

Migrating between different operating systems is not supported. For example, you cannot migrate from a Windows operating system to a UNIX operating system.

WebSphere Portal Version 7.0 does not support SUSE SLES 9. If your earlier portal runs on SLES 9, you need to upgrade to SUSE SLES 10 before migrating to WebSphere Portal Version 7.0.

Migrating from V6.1x :If you are migrating from WebSphere Portal 6.1.x, the process for migrating the source (or earlier) portal environment depends on whether the source portal uses IBM® WebSphere® Application Server Version 6.1 or 7.0.

Remote Migration Note: Remote migration is not supported if you are running WebSphere Portal V6.1.x on WebSphere Application Server V7.0. This is because remote migration can only occur if you are migrating the application server profile, which is not performed if WebSphere Portal is already installed on WebSphere Application Server V7.0.

If using a 32–bit database driver on a 64–bit machine, will need to use the 32–bit WebSphere Application Server Network Deployment Version 7 Supplements Disc 2

If using a 64–bit database driver on a 64–bit machine, will need to use the 64–bit WebSphere Application Server Network Deployment Version 7 Supplements Disc 2

General Note: Portlets and components in the source version are typically not migrated if they are not available in the version to which you are migrating. Examples include the MarketWatch portlets, Domino Document Manager portlet, Inline QuickPlaces portlet, Microsoft Exchange 2000 portlets, and portlets that were developed using WebSphere Portal Application Integrator (WPAI).

Also, migrated elements are not automatically upgraded to use features that are available in the new version. Taking advantage of new functionality that was not available in the source portal requires additional attention after migration is complete.

Chapter 1

Getting started: WebSphere Portal migration from V6.1.0.5 to V7

Introduction

This White paper describes the steps and best practices for migrating an existing Standalone WebSphere Portal 6.1.0.5 + WebSphere Application Server (WAS) 6.1.x environment to Standalone WebSphere Portal V7. To help illustrate the steps involved in this process, the migration of the yourCo Financial’s (Figure 1-1) portal is described.

Figure 1-1 yourCo Financial home page

Here are the following assumptions taken into considerations in this case study.

1) WebSphere Portal 6.1.0.5 contains the following customizations –a. At least 10 Custom Pages and one of them is a external URLb. URL mappings – Admin and Public – which points to admin and

public pages c. One Custom Theme and skind. 5 portlets used on the custom pagese. Several cloned portlets f. Various business portlets (World Clock, Bookmarks, Web

Clipper)g. Various custom usersh. At least one derived page for a useri. Portlet using portlet servicesj. Several struts portletsk. One Virtual Portall. IBM API portlet and JSF portlet

All the migration steps uses the command-line interface.

In this White Paper, the environment that is being migrated is configured to an DB2 database and is secured against the IBM Tivoli Directory Server - all running on a Windows® server.

Both WebSphere Portal V.6.1.0.5 and V.7 servers are stand-alone servers.

Pre-migration tasks -

● WebSphere Portal 6.1.0.5 -

○ Migration is supported only from the two latest fix pack levels for any listed offering. So if you don't have the latest fix pack then install it so before moving forward.

○ Install any recommended cumulative fixes and interim fixes on the

source server as suggested -- http://www-01.ibm.com/support/docview.wss?rs=688&uid=swg27007603

○ Enabled security against the LDAP Server

○ Do the database transfer. I transfered from derby to DB2. Ensure that you are running the minimum required level – either V9.1 with Fix Pack 6 or later, or V9.5 with Fix Pack 5 or later.

○ Installed the required fixes for migration mentioned in WebSphere Portal 6.1 Information Center. See Section 2.2 of this white paper

○ Changes to the scheduled cleanup service settings are not migrated. If you modified these settings in the earlier portal and want to continue using the same settings in the new portal, you must update the settings on the new portal. Keep a note to it and update the setting on the new portal after migration.

○ To ensure that the wkplc_comp.properties file contains the correct information, run the following commands:

ConfigEngine.bat validate-database-connection -DtransferDomainList=release,jcr

ConfigEngine.bat connect-database -DTransferDomainList=release,jcr

○ See the section of “Access Control“ in WebSphere Portal 6.1 Information Center and check the environment for any anonymous users with the roles listed below and change them to User:■ Privileged User ■ Editor ■ Manager■ Delegator ■ Security Administrator ■ Administrator

○ Clean up your previous environment as follows: ■ If you deleted portal pages, use the deletion cleanup service.

See the section of “Delayed cleanup of deleted portal pages” in WebSphere Portal 6.1 information center

■ If you deleted users or groups using your configured user registry, make sure to deregister those users and groups using either the XML configuration interface or the Manage Users and Groups portlet. See the section of “Deregistering users and groups” in WebSphere Portal 6.1 information center. One should use CleanupUsers.xml file provided in their <wp_home>\doc\xml-samples directory of WebSphere Portal 6.1.0.5.

■ Verify that you can stop and start WebSphere Portal and log in to the default WebSphere Portal 6.1.0.5 welcome page.

Note - The users that are considered “dead users”, their artifacts will not be migrated. This is how the migration scripts have been designed.Hence, if you want the artifacts of the dead users to be migrated over, administrator needs to re-enable the users that are marked as dead users. This should be simple as administrator can just reactivate them via LDAP.

○ Back up the databases and the entire directory structure for your existing WebSphere Portal 6.1.0.5 environment. One would be doing this as their regular maintenance strategy.

If you plan to migrate IBM Lotus Web Content Management data, complete the remaining steps :

1. On the WebSphere Portal 6.1.0.5 server, remove locks on all Web content items:

c. Go to the Administration view. d. Go to Portal Content -> Web Content Libraries. e. Click View Locked Items. f. Select all items and then click Unlock.

2. If you are migrating from source portal server which have feature pack installed (for instance, Version 6.1.5, 6.1.5.1, 6.1.5.2) , you must manually update the getNlsStrings.js file in Web Content Management to work correctly with the Version 7.0 portal.

a. On the source server, click Applications -> Content -> Web Content Management.

b. In the authoring portlet, click Edit Shared Settings. c. Add the blog library to the authoring portlet.

i. Click Library Selection. ii. Select Blog Resources from the list of available libraries,

and click Add. iii. Click OK.

d. Update the getNlsStrings.js file.i. Download the new version of the getNlsStrings.js file from

the WebSphere Portal product documentation.ii. Ensure that the Blog Resources library is selected in the

Library drop-down menu. iii. Select Components. iv. Select the check box for FILE - Get NLS Strings JS, and

click Edit. v. In the File Resource Element section, click Browse and

navigate to the updated getNlsStrings.js file that you downloaded.

vi. Click Save and read to update the file and verify your changes.

Note: If you do not update the getNlsStrings.js file before migration, the browser might display this error when displaying a blog or wiki page: ibmPortalConfig is not defined. If the error occurs after you update the getNlsStrings.js file, you might need to clear the browser's cache or delete any temporary internet files to ensure that the latest version of the file is loaded from the server.

● WebSphere Portal 7 -

○ Install IBM WebSphere Portal Version 7.0 using the defaults.isBinaryInstall="true" parameter (for example, install.bat -W defaults.isBinaryInstall="true").

This option significantly reduces installation time and helps to avoid potential conflicts. This option cannot be used when migrating from V6.0.1.x to V7.0.

Attention: If you inadvertently perform a full install (instead of installing only the binary code), you must remove the default profile as follows:

a) Use the WebSphere Application Server manageprofiles command to delete the default profile (wp_profile). For detailed instructions, see Deleting a profile in the WebSphere Application Server V7.0 Information Center.

b) Manually remove the remaining wp_profile_root directory. See your operating system documentation for instructions on command syntax.

○ Upgrade the target server to the latest fix pack level. Here is the link to the list of recommended fix packs and interim fixes -- http://www-01.ibm.com/support/docview.wss?rs=688&uid=swg27007603

○ Refer to the article which talks about WebSphere Portal 7 Service maintenance update required prior to migration – http://www-01.ibm.com/support/docview.wss?uid=swg21469821

○ When installing the new version of WebSphere Portal, ensure that

you use the same ID and access level that was used to install the earlier portal. Change the IBM WebSphere Application Server administrator user name and password on WebSphere Portal 7 to match the WebSphere Application Server administrator user name and password of the WebSphere Portal 6.1.0.5 environment.

○ If any virtual portals that exist in your earlier WebSphere Portal environment, then it will be automatically will be migrated to V7 when upgrade-profile task is executed. You donot need to use the create-virtual-portal ConfigEngine task to recreate each virtual portal in V7.

○ If the earlier WebSphere Portal environment is configured to use an external security manager then supported IBM and third-party security settings are migrated automatically.

○ Increase the transaction log size for the database you are using for the target server to prevent problems during migration.

Different factors can affect the transaction log file size that is appropriate for your environment – for example, the amount of data stored in the portal databases, or the number of primary and secondary log files in use. To avoid having migration tasks fail because the transaction log file is too small, see your DBMS documentation to determine the best option for increasing the transaction log size before you start migration. Check out the following link – http://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp? topic=/com.ibm.db2.udb.spatial.doc/cfgtranslog.html

As I am using db2, from the db2 control center I right click to the db and selected configure database logging and changed the value as suggested in above link.

○ If the portal 7 server is on AIX, Linux, Solaris, or i, increase the file descriptor limit to 200000. For example: ulimit -n 200000

The ulimit command determines the maximum number of open files that the operating system supports. By increasing the value before you migrate exported content into the new portal installation, you can avoid problems that might be caused if the value were too low. After migration is complete, you can restore the earlier value.

○ Back up the databases and the entire directory structure for your existing WebSphere Portal 7 environment. One would be doing this as their regular maintenance strategy.

Considerations -

Migration can take a while, and interruptions to your HTTP connection during the export process or import process can cause migration to fail. To avoid this problem, use the internal WAS HTTP server port. For instance, by default in wkplc.properties -- WpsHostPort=10040. If you have changed to port 80, then change it to 10040. Once the migration gets completed, one can change it back.

Deprecated Portlets - Some previously available portlets have been removed from WebSphere Portal 7 because alternative or newer functionality is available that you can use instead. If you migrate from an earlier WebSphere Portal installation that used these portlets, the portlets are migrated to provide backward compatibility, in some case they are treated as third-party portlets and may get migrated forward. Users are encouraged to transition to other available technology as appropriate.

See the section of “Migrating deprecated portlets” in WebSphere Portal 7 information center.

URL Mappings - If you have the urlmapping to the pages within the same WebSphere Portal (not crossing the VP boundaries) then the URL mappings gets migrated. If you have urlmapping to any admin pages, then it will not get migrated since the admin pages do not get migrated.

Chapter 2

2.1 Make the Portlets applications available to migration tasks

1) Make your customized resources available to migration tasks -

One doesn't need to copy their custom portlet war files to installableApps directory of WebSphere Portal 7 environment. Migration scripts would be able to take care of your custom portlets.

Some of the WAR files in the portal_server_root/installableApps directory might have been shipped with the current version. In that case, there is no need to manually upgrade those portlets.

Also, copy any custom-shared library Java archive (JAR) files from both the <app_server_root>/lib and <portal_server_root>/shared/app from WebSphere Portal 6.1.0.5 environment to <wp_profile>/PortalServer/config directory of WebSphere Portal 7 environment.

2) If you are using Cooperative portlets (c2a – click to action - using IBM API) then update your pbjportlet.jar file with the latest version of pbportlet.jar from the WebSphere Portal 7 --

● In the WebSphere Portal 7 environment, locate pbportlet.jar in the PortalServer_root/base/wp.propertybroker.legacy.impl/pb/lib directory.

● Copy the pbportlet.jar files to the WEB-INF/lib directory of the cooperative portlet application that you are migrating.

● Overwrite the JAR files if they already exist.

3) If you have struts portlet, then it should work as normal after completing the migration process. If it does not then upgrade it with the latest struts framework.

2.2 Installation of Fixes

There are two things one would need – Portal Update Installer and Fixes.

2.2.1 Installing fixes on WebSphere Portal 6.1.0.5 environment1) Download the Portal update installer for WebSphere Portal 6.1.X version – http://www-01.ibm.com/support/docview.wss?uid=swg24028760 2) Download the following fixes for WebSphere Portal 6.1.0.5 --Install any recommended cumulative fixes and interim fixes on the source server as suggested -- http://www-01.ibm.com/support/docview.wss?rs=688&uid=swg27007603

This is the cumulative fixes I installed on WebSphere Portal 6.1.0.5 -

Cumulative Fix #11 (CF011_PM29645) for Portal 6.1.0.5 / 6.1.5.2

Before you install the fixes, make sure portal server and server1 is stopped.

Now run either updatePortalWizard or updatePortal (command Line) to install the aboves fixes.

Make sure to read the ReadMe.txt for ALL the fixes that one installs.

For instance, I executed ConfigEngine.bat apply-cumfix task after installing CF11 (PM29645)

2.2.2 Installing fixes on WebSphere Portal 7 environment1) Download the Portal update installer for WebSphere Portal 7 version – http://www-01.ibm.com/support/docview.wss?uid=swg24006942

2) Download the following fixes for WebSphere Portal 7 --Install any recommended cumulative fixes and interim fixes on the source server as suggested -- http://www-01.ibm.com/support/docview.wss?uid=swg24027857

I installed the following fixes on WebSphere Portal 7 – PM25191 and PM33177

Before you install the fixes, make sure portal server and server1 is stopped.

Now run either updatePortalWizard or updatePortal (command Line) to install the aboves fixes.

2.3 Search Components from Portal 6.1.0.5

Migrating the search components in your portal might require preparation steps on the source portal and then additional steps on the migrated portal. For Migrating the search components, see the section of “Migrating search components from V6.1” in WebSphere Portal 7 Information Center.

Chapter 3In this chapter we would be doing core migration of our resources from WebSphere Portal 6.1.0.5 to 7. Remember I am doing the SAME Machine Migration. As I did migrated from a stand-alone portal 6.1.0.5 to stand-alone portal 7 I followed the section “Migrating a stand-alone portal that runs on a V6.1 application server” in WebSphere Portal 7 Information Center.

If you want to migrate the clustered portal 6.1.0.5 to clustered portal 7 then you need to follow the section “Migrating a V6.1.x clustered portal” in WebSphere Portal 7 Information Center.

If the source portal and target portal are located on the same server, you can migrate the source portal's application server profile by completing a set of manual steps or by using the IBM® WebSphere® Application Server Migration wizard to create the profile automatically for you.

WebSphere Application Server provides a Migration wizard, AppServer_root/bin/migration.bat(sh), that automatically creates the profile in the

AppServer_root/profiles directory. To create the profile in a specified location, you can use either the Profile Management Tool (PMT) (on 32-bit application server) or the manageprofiles command (on 64-bit application server). Then, when you use the Migration wizard, you can select the new profile as the target profile for migration.

Note: When pre-creating a profile, create a default application server profile and install the admin console only; do not install any sample applications.

To migrate the application server profile on i, use the manual steps provided above; WebSphere Application Server does not provide a Migration wizard on i.

If you used WebSphere Application Server Migration Wizard then it will • create a profile• execute WasPreUpgrade.bat(sh) task• execute WasPostUpgrade.bat(sh) task

Make sure it is successful. If you used Migration Wizard then you can jump to Step 5. Otherwise follow the below mentioned manual steps.

Also check out - Appendix A – for some general migration errors/exception one might get.

Step 1 : Create a wp_profile for Portal 7

Check the following first --

● Back up the databases and entire directory structure for your WebSphere Portal 6.1.0.5 environment.

● Back up the databases and entire directory structure for your existing WebSphere Portal 7 environment.

I am using the manual steps to create the wp_profile on the target portal server and migrating the wp_profile from the source portal server.

Create a directory – wp_profile7 on your target portal server. For instance, my wp_profile7 directory is at C:\wp7\wp_profile7

Navigate to <Appserver_root>\bin directory of your WebSphere Portal 7 server and run the following task.

C:\wp7\AppServer\bin>manageprofiles.bat -create -defaultPorts -enableAdminSecurity false -profileName wp_profile7 -profilePath C:\wp7\wp_profile7 -templatePath C:\wp7\AppServer\profileTemplates\default -nodeName desire -cellName desire -hostName desire.raleigh.ibm.com -isDefault -omitAction samplesInstallAndConfig defaultAppDeployAndConfig

• wp_profile_name Specifies the profile on the target server or node to which the source portal profile is to be migrated.

• profile_pathSpecifies the profile on the target server or node to which the source portal profile is to be migrated.

• source_node_nameSpecifies the node name for the node that is created with the new profile. Use a unique value within the cell or on the server.

• source_cell_nameSpecifies the cell name of the source portal profile.

• host_name Specifies the host name for the target server or deployment manager where you are creating the profile.

Note: NodeName and CellName needs to be same. if not then there would be problem with deploying the application later on.

Make sure the manageprofiles task gets completed successful as mentioned below: INSTCONFSUCCESS: Success: Profile wp_profile7 now exists. Please consult C:\wp7\wp_profile7\logs\AboutThisProfile.txt for more information about this profile.

Note: If you forgot to have the parameter profileName or mispelled it, then it will create a profile named AppSrv01.

AboutThisProfile.txt file will show the location, node name, host name and port information that got associated when the profile got created.For instance, this is from my AboutThisProfile.txt --Application server environment to create: Application serverLocation: C:\wp7\wp_profile7Disk space required: 200 MBProfile name: wp_profile7Make this profile the default: TrueNode name: desireHost name: desire.raleigh.ibm.comEnable administrative security (recommended): False

Administrative console port: 9060Administrative console secure port: 9043HTTP transport port: 9080HTTPS transport port: 9443Bootstrap port: 2809SOAP connector port: 8880Run application server as a service: FalseCreate a Web server definition: FalsePerformance tuning setting: Standard

Step 2 : Execute WASPreUpgrade command for Portal 7

Navigate to <Appserver_root>\bin directory of your WebSphere Portal 7 server and run the following task.

WASPreUpgrade.bat backup_dir source_WasHome -traceString trace_spec -traceFile trace_file -oldProfile wp_profile_name

I executed the following command : C:\wp7\AppServer\bin>WASPreUpgrade.bat C:\wp7\waspreupgradebk C:\wp6103content\AppServer -oldProfile wp_profile

• backup_dirSpecifies the directory on the source portal where the WASPreUpgrade command stores the exported profile data. If the directory does not exist, the WASPreUpgrade command creates it.

• source_WasHome Specifies the WebSphere Application Server installation directory on the source server.

• wp_profile_name Specifies the portal profile on the source server

Optional • trace_spec

Specifies the trace information that you want to collect. To gather all trace information, specify "*=all=enabled" (including the quotation marks). If you include this parameter, you must also specify the trace_file. If you do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDir/logs directory. If you specify the -traceString parameter but omit the -traceFile parameter, the command does not generate a trace file.

• trace_file Specifies the name of the output file where trace information is stored. If you do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDirectory/logs directory. If you specify the -traceString parameter but omit the -traceFile parameter, the command does not generate a trace file.

This task will create the WASPreUpgrade.<timestamp>.log file under logs of the provided backup_dir location.

NOTE: If the WASPreUpgrade task fails with out of memory error then you can edit the WasPreUpugrade command file which is located at <AppServer_root>\bin\WasPreUpgrade.bat/sh and update the -Xmx parameter of the PERFJAVAOPTION variable to have a value of at least 1024 MB. For instance: set PERFJAVAOPTION=-Xms512m -Xmx1024m -Xj9 -Xquickstart

Step 3 : Increase the Java maximum heap size for the WasPostUpgrade command on Portal 7

A) Edit the WasPostUpgrade command file which is located at <AppServer_root>\bin\WASPostUpgrade.bat/sh

B) Update the -Xmx parameter of the PERFJAVAOPTION variable to have a value of at least 1024 MB. For instance: set PERFJAVAOPTION=-Xms512m -Xmx1024m -Xj9 -XquickstartC) Save your changes.

Step 4 : Execute WASPostUpgrade command for Portal 7Navigate to <Appserver_root>\bin directory of your WebSphere Portal 7 server and run the following task.

WASPostUpgrade.bat backup_dir -profileName wp_profile_name -oldProfile old_wp_profile_name -username source_admin_user -password source_admin_password -includeApps true -backupConfig false -traceString trace_spec -traceFile trace_file

I executed the following command :

C:\wp7\AppServer\bin>WASPostUpgrade.bat C:\wp7\waspreupgradebk -profileName wp_profile7 -oldProfile wp_profile -username wpsadmin -password password -includeApps true -backupConfig false

• backup_dirSpecifies the directory where the WASPreUpgrade command stores the data that it exports from the source server, and from which the WASPostUpgrade command reads and imports data.

• wp_profile_name Specifies the new portal profile on the target server or node to which the WasPostUpgrade command migrates the source portal profile.

• old_wp_profile_name Specifies the source portal's profile name. The profile name must already exist in the backup directory specified above.

• source_admin_user Specifies the administrator ID for the source portal. Specify the login form of the administrator ID rather than the fully qualified name; for example, specify wpsadmin rather than uid=wpsadmin, o=defaultWIMFileBasedRealm.

• source_admin_password Specifies the administrator ID password for the source server.

Optional • trace_spec

Specifies the trace information that you want to collect. To gather all trace information, specify "*=all=enabled" (including the quotation marks). If you include this parameter, you must also specify the trace_file. If you do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDir/logs directory. If you specify the -traceString parameter but omit the -traceFile parameter, the command does not generate a trace file.

• trace_file Specifies the name of the output file where trace information is stored. If you do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDirectory/logs directory. If you specify the -traceString parameter but omit the -traceFile parameter, the command does not generate a trace file.

Important Note: After running the WasPostUpgrade command on a local server, it is possible to start the portal server for verification purposes. However, because the migration process is not complete, there might be errors in the SystemOut.log file. These errors are usually resolved after the

upgrade-profile task completes. It is important that you not attempt to run in production when the migrated portal is in this state. If you start the portal for verification at this point, you must stop the portal before running the upgradeConfigEngine command.

This task will create the WASPostUpgrade.<timestamp>.log file under logs of the provided backup_dir location.

Look at the logs and confirm the task got completed successfully.

You can ignore the following message if you see in the log file –WASX7017E: Exception received while running file "/C:/wp7/waspreupgradebk/install_WebDAV_for_WebSphere_Portal.ear.jy"; exception information: org.eclipse.jst.j2ee.commonarchivecore.internal.exception.DeploymentDescriptorLoadException: org.eclipse.jst.j2ee.commonarchivecore.internal.exception.DeploymentDescriptorLoadException: dd_in_ear_load_EXC_MIGR0340W: Application WebDAV_for_WebSphere_Portal.ear did not deploy

If any of the custom application failed to deploy during this task, then you needs to investigate where it is failing. One of the common scenario it may fail to deploy is because the custom application contains characters like apostrophe or single quote. If this is the case, you can also look at the Jython scripts for that custom application at <backup_dir>\profiles\wp_profile\PortalApps. You should just fix the Jython script instead of fixing in the source portal server and then try to run/deploy that custom application individually using the wsadmin command.

For instance, if you want to execute Jython file – ex1.py then one can do the following -

wsadmin> execfile ("ex1.py") or execfile("ex1.py")

wsadmin is located in <AppServer_root>\bin directory.

For more information on wsadmin reference the following link –http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/welc6topscripting.html

Step 5 : Update the wkplc.properties on Portal 7

Update <wp_profile_root>/ConfigEngine/properties/wkplc.properties with the correct WebSphere Application Server administrator password for the portal that you want to migrate.

For instance, I edited with the following :

WasUserid=uid=wasadmin,ou=dhavalp,o=wpsl2

WasPassword=password

Step 6 : Execute the ConfigEngine tool on Portal 7Navigate to <Portalserver_root>\bin directory of your WebSphere Portal 7 server and run the following task.

upgradeConfigEngine.bat profile_name -conntype connection_type -hostname host_name -port port_number -user admin_name -password admin_password

I executed the following command : C:\wp7\PortalServer\bin>upgradeConfigEngine.bat wp_profile7 -conntype SOAP -hostname desire.raleigh.ibm.com -port 16033 -user wasadmin -password password

• profile_nameSpecifies the name of the WebSphere Application Server V7 profile that is the target of the upgrade.

• connection_type Specifies the type of connection that should be established. Valid connection types are SOAP and NONE.

• host_name Specifies the host name of the application server (when migrating a stand-alone server) or Deployment Manager (when migrating a clustered environment).

• port_numberSpecifies the port number of the application server (when migrating a stand-alone server) or Deployment Manager (when migrating a clustered environment). Use the value of WasSoapPort from the wkplc.properties file.

• admin_nameSpecifies the administrator user ID for the application server.

• admin_password Specifies the password for the administrator user ID.

Trace information is stored in the UpgradeConfigEngineTrace.log file in the wp_profile_root/ConfigEngine/log directory.

Make sure the upgradeConfigEngine task gets completed successful as mentioned below: EJPMA6301I: The request was processed successfully see file C:\wp7\wp_profile7\ConfigEngine\log\UpgradeConfigEngineTrace.log for

details on the results.

Step 7 : Re-use copies of source database domains to minimize downtime on Portal 7When you migrate from IBM® WebSphere® Portal V6.1.x on IBM WebSphere Application Server V6.1, the recommended way to keep the earlier portal environment in production and reduce the amount of downtime during migration is to copy the earlier portal server JCR and Release domains, connect to the domain copies, and then update the new portal server using the domain copies. The process of connecting to the domain copies must be done after you upgrade the ConfigEngine tool but before you upgrade the V6.1.x profile.

Important: Copying the V6.1.x JCR and Release domains is recommended but not required. However, if you choose to have the new portal server point directly to the V6.1.x domains (instead of to copies of the domains), you will not be able to continue using the domains with the earlier portal server.

Below are the things i did in my environment -

Note: Instead of just re-using JCR and Release domain, I copied ALL of the domains including – feedback, likeminds, customization, community. A) Make a copy of Portal 6.0.1.5 JCR DB by running backup and restore command of db2. For instance,

db2 backup db <orig_db> to <dir>db2 restore db <orig_db> from <dir> into <new_db>

Here is the screenshot which show the backup and restore for JCR and Release domain:

B) Configure your Portal 7.x envinorment by updating the following files to reflect a connection to the ALL domain copy that you created in the previous step:

For instance, for the JCR domain :

● Open wkplc.properties file and ensure WasPassword and PortalAdminPwd parameters are correct

● Open wkplc_dbdomain.properties.properties file and configure JCR domain db. This is what it looks like after I configured

jcr.DbName=bkjcr7jcr.DbSchema=jcr (Needs to same schema value for <orig_db>)jcr.DataSourceName=wpdbDS_bkjcr7jcr.DbUrl=jdbc:db2://hostname:50000/bkjcr7:returnAlias=0;

C) If you are migrating a stand-alone environment, before connecting to the domain copies, change the WebSphere Application Server and WebSphere Portal port numbers by running the modify-ports-by-startport task.

Here is reference link for modify-ports-by-startport task -- http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Linux_standalone_Installing_WebSphere_Portal_exp7

Here are the things that I did :

Navigate to <wp_profile7>/ConfigEngine directory and execute the following task :

1) ConfigEngine.bat list-server-ports-by-name -DServerName=server1 -DwasPassword=password

ConfigEngine.bat list-server-ports-by-name -DServerName=WebSphere_Portal -DWasPassword=password

The above task will creates a server1_PortMatrix.txt and WebSphere_Portal_PortMatrix.txt under <wp_profile7>/ConfigEngine/log directory which will show you what are ports that are currently configured with your server1 and WebSphere_Portal.

Observe this will be the same ports which the wp_profile used from the source environment.

For instance, here is the output from my server1_PortMatrix.txt :

Ports for server1 :

WC_defaulthost=15000 WC_adminhost=15001 WC_defaulthost_secure=15002 WC_adminhost_secure=15003 BOOTSTRAP_ADDRESS=15004 SOAP_CONNECTOR_ADDRESS=15005

Here is the output from my WebSphere_Portal_PortMatrix.txt :

Ports for WebSphere_Portal : WC_defaulthost=15040 WC_adminhost=15027 WC_defaulthost_secure=15035 WC_adminhost_secure=15041 BOOTSTRAP_ADDRESS=15031 SOAP_CONNECTOR_ADDRESS=15033

Now as I have both source and target servers on the same machine, I can't use the same ports between the source and target servers. If not then will cause the port conflicts. For the target server I want to use the ports starting from 16000, hence I executed the following tasks

2) ConfigEngine.bat modify-ports-by-startport -DWasPassword=password -DModifyPortsServer=server1 -DStartPort=16000

ConfigEngine.bat modify-ports-by-startport -DWasPassword=password -DModifyPortsServer=WebSphere_Portal -DStartPort=16040

D) Look in the serverindex.xml file and see what are the correct ports that got associated with server1 and WebSphere Portal server.

Now modify WasSoapPort and WpsHostPort parameter in wkplc.properties with the correct port numbers.

For instance,WasSoapPort=16040WpsHostPort=16054

E) Change to the wp_profile_root/ConfigEngine directory, and then enter the following commands to validate the configuration properties:

ConfigEngine.bat validate-database-connection

ConfigEngine.bat connect-database

Note: If you just copied the Release and JCR domain, then you want to use the following commands :

ConfigEngine.bat validate-database-connection -DTransferDomainList=release,jcr

ConfigEngine.bat connect-database -DTransferDomainList=release,jcr

Important: If a database domain in the earlier portal server uses assigned custom table spaces that you want to retain for use on the new portal server (instead of using the default table spaces), you need to update the table space property file and the index space property file for the database table. Check out the sections of “Retaining custom table spaces” in the WebSphere Portal 7 Information center.

Note: If the portal uses IBM® DB2 Universal Database™ for z/OS® as the backend repository then check out the sections of “Updating the database schemas” and “Updating the configured database driver for DB2 for z/OS” in the WebSphere Portal 7 Information center.

Step 8 : Upgrading the V6.1.x profile on Portal 7

In this step we will migrate properties files, upgrade database domains, and apply other updates that are needed to bring the source profile to the V7 level by running the upgrade-profile task.

A) Navigate to the wp_profile_root/ConfigEngine directory of Portal 7 server and then run the following command:

ConfigEngine.bat upgrade-profile -DWasPassword=password -DportalAdminPwd=password

Important: If you updated the database schemas manually, you must include the parameter -DDbSafeMode=true. For example: ConfigEngine.bat upgrade-profile -DWasPassword=WasAdminPwd -DPortalAdminPwd=PortalAdminPwd -DDbSafeMode=true

Do not specify this parameter if you want the migration process to update the database schemas for you.

Step 9 : Validate the migration

● Make sure upgrade-profile task gets completed successfully. Also check there are no errors in the ConfigTrace.log and upgradeConfigEngineTrace.log in wp_profile_root/ConfigEngine/log directory.

● If you cloned the FileServer portlet in the WebSphere Portal 6.1.0.5 and supplied HTML files in the wp_old_root/installedApps/FileServer_PA_1_0_4H.ear/FileServer.war/FileServerPortlet/html directory, you must copy those files to the PortalServer_root/installedApps/Cell_name/PA_FileServer.ear/FileServer.war/FileServerPortlet/html directory, after running the portal-post-upgrade task and before restarting the server, to make the files accessible in WebSphere Portal 7.

● Start the WebSphere Portal 7 server and the hit the migrated portal URL, which is in the following format/form:http://host_name:port_number/original-context-root_migrated/portal

For instance, if your original portal URL is http://www.example.com:10040/wps/portal, the URL for the migrated

portal is http://www.example.com:10040/wps_migrated/portal.

Note: During migration, the following changes are made to the wkplc.properties file stored in the wp_profile_root/ConfigEngine/properties directory:

The property WpsContextRootOriginal is set to the original value of the context root before migration was performed. This property is for reference only and is not used by the migrated portal.

The value of the WpsContextRoot property is set to the migrated value original-context-root_migrated (for example, wps_migrated).

Chapter 33.1 WCM Migration -

By completing above steps you have completed the WebSphere Portal migration steps. If you have Web Content Management (WCM) data then need to perform additional steps to complete your web content migration as mentioned in the section of “V6.1 Web content post migration steps” in WebSphere Portal 7 Information Center.

To ensure that the portal can retrieve metadata information for resource management on remote systems after migration, configure the Resource Manager portlet with information about the remote system and the settings used to handle communication with the system as mentioned in the section of

“Configuring resource management with site management” in WebSphere Portal 7 Information Center.

3.2 Updating Themes and Skins -

3.2.1 Custom themes and skins

As the context root has been changed for the custom themes and skins this can cause problems if you have developed custom themes or skins that contain hardcoded references to the portal's context root. (This is particularly an issue after migration because the context root is modified during migration, causing hardcoded references to break.) You can update your themes and skins to remove the hardcoded references and instead use dynamic references that work properly regardless of the context root as mentioned in the section of “Updating custom themes and skins for hardcoded context root references” in WebSphere Portal 7 Information Center.

Also the above section talks about how you can change the context root for your custom themes and skins application so that you can use desired context root.

3.2.2 Modifing the context uri

You can change the context root for the Migrated Portal server by editing wkplc.properties for WpsContextRoot and wkplc_comp.properties for WpsDefaultHome and then executing modify-servlet-path configuration task to modify the portal URI.

Navigate to the wp_profile_root/ConfigEngine directory of Portal 7 server and then run the following command:

ConfigEngine.sh(bat) modify-servlet-path -DPortalAdminPwd=password -DWasPassword=password

3.3 Deploying new functionality on Portal 7 -

Migration process doesn't incorporate the new Portal 7 functionalities by default. As a result when you hit your migrated Portal 7 server it will look identical as of your source environment. Hence you would execute few manual tasks to take advantage of new functionality on migrated Portal 7 server as mentioned in the section of “Deploying new functionality in a migrated portal” in WebSphere Portal 7 Information Center.

Appendix A – Common Migration Messages

Below contains information about various migration messages and the content in the log file that one might received during the migration.

1. If the source portal server was installed using the content build (Portal + WCM) and if the target server was installed only by using Portal server binary code as WCM is not been used in source, then during the upgrade-profile task the target portal server would not start cleanly. As a result the task will fail with “Error 404: javax.servlet.UnavailableException: Initialization of one or more services failed”

Also the systemout logs will show ClassNotFoundException during the “wps” application startup as seen below :

Servlet E com.ibm.wps.engine.Servlet init EJPFD0016E: Initialization of service failed. java.lang.ClassNotFoundException: com.ibm.workplace.wcm.api.WebContentCustomWorkflowService

at java.lang.Class.forNameImpl(Native Method)at java.lang.Class.forName(Class.java:139)at

com.ibm.wps.services.ServiceManager.initInternal(ServiceManager.java:260)at

com.ibm.wps.services.ServiceManager.init(ServiceManager.java:173)at

com.ibm.wps.services.ServiceManager.init(ServiceManager.java:115)at com.ibm.wps.engine.Servlet.init(Servlet.java:252)at

com.ibm.ws.webcontainer.servlet.ServletWrapper.init(ServletWrapper.java:358)

Migrating from environment which contains WCM to an environment which doesnot contain WCM is not supported. Refer to the section of “Supported Migration Paths” in Portal 7 infocenter – http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Supported_migration_paths_wp7

2. One may see the following error in the systemout.log file while executing upgrade-profile task ---

DataStoreCont E com.ibm.wps.datastore.impl.DataStoreContext handleException EJPDB0001E:Error occurred during database access. Last SQL statement is [SELECTOID, CREATED, MODIFIED, RESOURCE_ROOT, IS_ACTIVE, IS_DEFAULT, DEFAULT_LOCALE, TYPE, CONTEXT_ROOT, THEME_SCOPE_OID FROM release.SKIN_DESC ].

com.ibm.wps.datastore.impl.DataBackendException: EJPDB0002E: Erroroccurred during database access. atcom.ibm.wps.datastore.impl.DataStoreContext.handleException(DataStoreContext.java:337) atcom.ibm.wps.datastore.impl.ResourcePersister.findInternal2(ResourcePersister.java:1150) atcom.ibm.wps.datastore.impl.ResourcePersister.findInternal(ResourcePersister.java:1050) atcom.ibm.wps.datastore.impl.ResourcePersister.findAll(ResourcePersister.java:1715)

...............

...............Caused by: java.sql.SQLException: ORA-00904: "THEME_SCOPE_OID": invalid identifier

at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.java:112) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:288) at oracle.jdbc.driver.T4C8Oall.receive(T4C8Oall.java:743)

The above error most likely points that one have missed out the steps on database copy and connection task that needs to be executed on the portal 7x server.

3. One may see the following error in the systemout.log file while executing upgrade-profile task ---

InternalGetSc E com.ibm.wps.command.scheduler.internal.InternalGetSchedulerTaskCommandAbstractCommand.throwCommandException EJPDD0009E: JNDI naming lookup failed for name = [ejb/wpsSchedulerManager].javax.naming.NameNotFoundException:Context: <cell_name>/nodes/<node_name>/servers/WebSphere_Portal, name:ejb/wpsSchedulerManager: First component in name wpsSchedulerManager notfound. [Root exception isorg.omg.CosNaming.NamingContextPackage.NotFound:IDL:omg.org/CosNaming/NamingContext/NotFound:1.0]

atcom.ibm.ws.naming.jndicos.CNContextImpl.mapNotFoundException(CNContextImpl.java:4365)atcom.ibm.ws.naming.jndicos.CNContextImpl.doLookup(CNContextImpl.java:1794)atcom.ibm.ws.naming.jndicos.CNContextImpl.doLookup(CNContextImpl.java:1749)

The above is wps_scheduler.ear application. Because this application does not start, the wps app fails to start:

The reason wps_scheduler.ear does not start is because of this exception here:

FileDocument E ADMR0104E: The system is unable to read documentcells/dmnalx0267/cus/wps_scheduler/cver/BASE/cu.xml:java.io.IOException: Permission denied at java.io.File.checkAndCreate(File.java:1704) at java.io.File.createTempFile(File.java:1792)atcom.ibm.ws.management.repository.FileDocument.createTempFile(FileDocument.java:564)

Similar exceptions would appear for few other applications.

The problem appears to be file permissions. Somehow the file permissions have become corrupted. Easiest way to fix this is to figure out which user is supposed to be running the WebSphere_Portal server, and run chown -R for whatever this user is over his entire Portal file structure (AppServer, wp_profile, PortalServer).

4. genRemMigPkg task will not get executed during portal 7x migration even if you provide the correct name of the profile. This mostly happens on the Unix/Linux/AIX environment This has been resolved in PM24941 which have been already included in Portal 7.0.0.1. Install the latest cumulative fix available for Portal 7 server before migrating.

5. In UpgradeConfigEngineTrace.log file one could see the following exceptions :- mig-stop-admin-server:

[echo] 'server1' seems being started. [echo] Stopping 'server1' ... mig-set-instance-properties: mig-stop-server-helper: [exec] ADMU0116I: Tool information is being logged in file [exec] C:\IBM\WebSphere\wp_profile\logs\server1\stopServer.log [exec] ADMU0128I: Starting tool with the wp_profile profile [exec] ADMU3101I: Using explicit host and port localhost:10005 for server: server1 [exec] ADMU0111E: Program exiting with error: javax.management.JMRuntimeException: [exec] ADMN0022E: Access is denied for the stop operation on Server MBean [exec] because of insufficient or empty credentials. [exec] ADMU4113E: Verify that username and password information is correct. If [exec] running tool from the command line, pass in the correct -username [exec] and -password. Alternatively, update the <conntype>.client.props [exec] file. [exec] ADMU1211I: To obtain a full trace of the failure, use the -trace option. [exec] ADMU0211I: Error details may be seen in the file: [exec] C:\IBM\WebSphere\wp_profile\logs\server1\stopServer.log BUILD FAILED C:\IBM\WEBSPH~1\PORTAL~1\installer\wp.migration.framework\config\includes\mig_cfg.xml:294: The following error occurred while executing this line: C:\IBM\WEBSPH~1\PORTAL~1\installer\wp.migration.framework\config\includes\mig_cfg.xml:404: The following error occurred while executing this line: C:\IBM\WEBSPH~1\PORTAL~1\installer\wp.migration.framework\config\includes\mig_cfg.xml:435: exec returned: -1 Also checking the stopServer.log file :- WsServerStop E ADMU3002E: Exception attempting to process server server1 WsServerStop E ADMU3007E: Exception javax.management.JMRuntimeException: ADMN0022E: Access is denied for the stop operation on Server MBean because of insufficient or empty credentials.

WsServerStop A ADMU3007E: Exception javax.management.JMRuntimeException: ADMN0022E: Access is denied for the stop operation on Server MBean because of insufficient or empty credentials. at com.ibm.ws.management.connector.soap.SOAPConnectorClient.handleAdminFault(SOAPConnectorClient.java:933) at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplateOnce(SOAPConnectorClient.java:901) at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplate(SOAPConnectorClient.java:667) Most likely one used the incorrect port while executing upgradeConfigEngine task. Try using the value of WasSoapPort from the wkplc.properties file for the -port parameter.

Appendix B – Portal v7 Tuning Guide

Please check out the tuning guide at http://www-10.lotus.com/ldd/portalwiki.nsf/dx/WebSphere_Portal_Tun