Migration troubleshooting

 

Problem: Issues with supported versions of Tivoli Access Manager

WebSphere Portal V5.1 requires Tivoli Access Manager 4.1 + Fix pack 2. Some previous versions of WebSphere Portal supported older versions of Tivoli Access Manager and will not work with Tivoli Access Manager 4.1. This can create problems during the migration process.

Solution:

Choose one of the following methods for the most successful migration:

  • Install fix pack 4 on Tivoli Access Manager 3.9. Perform the WebSphere Portal migration. After the migration is complete, you will be running WebSphere Portal V5.1 with Tivoli Access Manager 3.9 + fix pack 4. This is not a supported configuration. Upgrade to Tivoli Access Manager 4.1 + fix pack 2 as soon as possible.

  • Install Tivoli Access Manager 4.1 + fix pack 2 before beginning the WebSphere Portal migration. Leave the WebSphere Portal V4.x and Tivoli Access Manager 3.9 systems intact. Install WebSphere Portal V5.1 and configure it to work with Tivoli Access Manager 4.1. Then begin the migration process. This method requires additional resources because WebSphere Portal V4.x, Tivoli Access Manager 3.9, WebSphere Portal V5.1, and Tivoli Access Manager 4.1 must all be installed and operational.

 

Problem: Exporting pages with duplicate page names causes an error

In the case of an explicit export of a component (executing export-places) an Identification is not unique error might occur.

Solution:

This might be the result of two users creating a page with same name. For example, two users can create a page called MyPage. In this case, the component needs to be renamed to be able to run the export. The exception can be overwritten by using the force flag (see the following sample). XML configuration interface will then export the first component that is found with that name.

Sample that would fail if there is more than one component named MyPage:

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

<!DOCTYPE request PUBLIC "-//IBM//DTD Portal Configuration 1.1//EN" "PortalConfig_1.1.dtd">

<request include-mapping="true">

  <portal action="locate">

    <composition action="locate" name="Root.Composition">

      <component action="locate" name="Home">

        <!--

        <component action="export" name="MyPage" force="true"/>

            -->

        <component action="export" name="MyPage"></component>

      </component>

    </composition>

  </portal>

</request>

 

Problem: HTTP 500 error encountered when running any of the migration tasks

You may receive an HTTP 500 error while running a migration task,

Solution: Open the <wp4_root>/log/appserver-out.log file. Check for the following error message:

# HotSpot Virtual Machine Error : 11

This means that WebSphere Portal V4.x was restarted due to a Java Virtual Machine crash. If you see this error in the log file, always access WebSphere Portal V4.x through a browser to verify that it is operational before running the migration tasks. You only need to check the appserver-out.log file once after WebSphere Portal V4.x restarts; if you see the error message in the log file once, the error will continue to occur.

 

Problem: Error 500 received while running migration tasks on Solaris and trying to contact WebSphere Portal V4.1.x

Open the file <wp4_root>/log/appserver-out.log. You will see that the JVM received a signal 11 and that WebSphere Portal has restarted.

Solution:

If you are running WebSphere Portal V4.1.x on Solaris, verify the level of Java that is being used under the $WAS_HOME/AppServer/java/bin directory. The version that is tested with migration is 1.3.1_08. WebSphere Application Server 4.0.2 is not certified for this version of the Java Development Kit. If you find that upgrade to fix this problem, consider using the following steps:

  1. Back up the $WAS_HOME/AppServer/java directory.

  2. Download the latest 1.3.1 JDK.

  3. Extract the JDK into a temporary subdirectory.

  4. In the extract directory, remove the jre/lib/security directory ( keep the security directory that is shipped with WebSphere Application Server V4.0.2).

  5. Stop WebSphere Application Server V4.0.2 and WebSphere Portal V4.1.x.

  6. Overlay the $WAS_HOME/AppServer/java directory structure with the extracted one.

  7. Perform the migration tasks.

  8. Restore the original Java directory.

  9. Restart WebSphere Application Server V4.0.2 and WebSphere Portal V4.1.x.

 

Problem: Migrate-pages task fails with the error Duplicate objectid attribute

The migrate-pages task may fail with the error Duplicate objectid attribute.

Solution:

Remove the work directory from <wp5_root>/migration and try the task again.

 

Problem: Migrate-pages task fails with the error Illegal page structure

The migrate-pages task may fail with the error Illegal page structure,

Solution:

Make sure that you have applied the updated fix that is supplied with the migration interim fix to WebSphere Portal V4.x. If you have not, apply the updated fix to WebSphere Portal V4.x and rerun the migrate-pages task.

 

Problem: Errors received in the trace.log file when running the migrate-wmm task

The trace.log file may report errors when running the migrate-wmm task.

Solution:

Read the following for an explanation or solution to the error conditions:

  • If you are using DB2 version 7 Fix pack 8 client and server, ignore the following errors in the Member Manager trace.log file. Migration will continue successfully after these errors are reported:

    SQL0031C File "/home/db2inst1/sqllib/bnd/db2schem.bnd" could not be opened.

    SQL0040N An error occurred on one or more bind files in list "db2cli.lst".

    SQL0082C An error has occurred which has terminated processing.

    SQL0091N Binding was ended with "3" errors and "0" warnings.

    The errors are being reported because your DB2 client is missing a db2schem.bnd file. This file was added in DB2 version 7 Fix pack 8 to address some functionality in dealing with DB2 version 8.

    If you would like to modify your client so that the errors do not continue to occur, be able to copy the missing file from your server to the client. The next time DB2 performs an implicit bind on a new database from your client's attach, the file will be accessible and the errors will not occur.

  • If you ran the migrate-wmm task on a clean Member Manager database, or if some of the tables referenced by the task are not in the database, you will receive an error message. This message can be ignored. Here is an example of an error message that is received when the table WMMLAKEYS is not in the database:

    DROP TABLE WMMLAKEYS

    ---- --- ---

    exception executing: DROP TABLE WMMLAKEYSCOM.ibm.db2.jdbc.DB2Exception:

    [IBM][CLI Driver][DB2/6000] SQL0204N "DB2INST1.WMMLAKEYS" is a name non-given a definition.

    SQLSTATE=42704

  • If a user has specified that a certain uuid exists on the LDAP server, and a match cannot be found for that uuid under the corresponding distinguished name, you will receive an error message. The migrate-wmm command will not stop due to this error, but it will not create corresponding rows for the distinguished names in the WMMLAEXTID table. You might want to check to see if the uuid exists in the LDAP for the distinguished name, but the error can be ignored. Here is an example of the error message that this scenario will generate:

    Error in WMMLAEXTID.del: Cannot add line with member_id: 157 ,alphanum_extid: null ,repositoryId: LDAP1

    Reason for error: Cannot find the uuid in the LDAP directory for the member: uid=user6,cn=users,dc=ibm,dc=com

  • You can ignore the following error message depending on your Member Manager configuration:

    Error in /usr/WebSphere5/PortalServer/migration/work/templates/wmm/db2/lookaside\WMMLAASVAL.del: Cannot find attribute userPassword in the WMS MBRATTR table...

    If your LDAP is configured with a Lookaside database, some attributes might be stored in the LDAP server (in this case, the userPassword attribute). If this is the case, the attribute does not need to be migrated to the Member Manager Lookaside database and the error message can be ignored.

 

Problem: Portlet parameters may be lost if doing a Portlet Update or a migration

If you have made changes to existing portlet parameters through the Portal 'Manage Portlet' utility, these changes will be lost after a Portlet Update is done through the 'Portlet Application' utility or through a migration to another version of WebSphere Portal that does a silent update of the portlet.

Solution:

Make note of any modifications that you made through the 'Manage Portlet' utility and reapply the changes after the portlet update is complete. For example, you can change the Notes View portlet parameters to point to a particular Notes Server/Database/View/Credential Vault Slot. After the portlet is updated, these changes will be lost and reset to the default placeholder values. For future additions of this portlet to a page, the portlet would not be configured. If you have made many copies of the portlet, each configured separately, you would lose those changes. Therefore, it is important to note any modifications that are made to portlet parameters.

 

Problem: Error page exception encountered while editing subscription for 4.x migrated struts war file

You may encounter the following exception while editing the subscription for the 4.x migrated struts war file: Error page exception

The server cannot use the error page specified for your application to handle the Original Exception printed below. Please see the Error Page Exception below for a description of the problem with the specified error page.

This could occur because the application uses the com.ibm.wps.struts.common.PortletApiUtils. This class has been deprecated on the legacy container because it uses the com.ibm.wps package name. The new class name is com.ibm.portal.struts.common.PortletApiUtils. (Note that com.ibm.wps was changed to com.ibm.portal). The class com.ibm.wps is still supported on the legacy container; however, it was not added to the standard container since this is a new version.

Solution:

Make sure that you migrate all references to com.ibm.wps.struts.common.PortletApiUtils to the com.ibm.portal.struts.common.PortletApiUtils class as part of the migration.

 

Problem: Migrate-user-groups-ac failed when migrating from V5.0.2.1

You may encounter the following error: 

javax.naming.NoPermissionException: 
[LDAP: error code 50 - 00002098: SecErr: DSID-031509EE, problem 
4003 (INSUFF_ACCESS_RIGHTS), data 0

This error is normally caused by the wpsbind user not having enough rights to the member of the group indicated in ImportGroupResult.xml.

Solution:

Add write/update permissions for that user to wpsbind and re-run the migrate-user-groups-ac task.

 

Problem: Multiple nested pages when migrating from V4.x

Multiple copies of nested pages are created when running the migrate-pages and migrate-places tasks during migration from V4.x to V5.1.

Solution:

When running the migrate-places task while migrating from V4.x to V5.1 and page deployment is enabled, you do not need to run the migrate-pages task. Running both tasks or running one task multiple times can result in multiple copies of the same page.

 

Problem: Derived pages are not migrated correctly

When using the task migrate-all to migrate derived pages, some portlets on the derived pages may not be migrated.

Solution:

Run the migrate-all task a second time.

 

Problem: The migrate-pages and migrate-places tasks fail after running successfully

The migrate-pages and migrate-places tasks can be run successfully only once. The task will fail the second time if the task has already completed successfully.

Solution:

There are two options for this problem:

  1. You can backup the WAS configuration and Portal database before running migration. If migration needs to be run again, the configuration can be restored first. To backup the configuration:

    1. Backup WAS configuration by using the WAS backupConfig tool. For more information, see backupConfig command.

    2. Backup the Portal database. When running Portal on cloudscape, make a backup of the PortalServer/cloudscape directory. For other databases, use the database tools to backup the database.

  2. You can manually remove the migrated places and pages before running migration the second time. Pages can be removed on the "Manage Pages" Portal Administration page. Removing a top-level page will cause all children pages to be deleted.

 

Problem: Migrated themes are not displayed correctly

When using the tasks migrate-all or migrate-themes-skins-config to migrate custom themes or skins, they are not displayed correctly through Manage Pages > Edit Page Properties.

Solution:

After migration, restart the Portal Server.

 

See also

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

Tivoli is a trademark of the IBM Corporation in the United States, other countries, or both.