OracleAS Portal Developer Kit (PDK)
Portal Tools: Upgrading to Release 10.1.2.0.2 and later

Last Updated: June 23, 2005
Status: Production
Version: PDK Release 2 (10.1.2.0.2 and later)

Contents

Introduction
New Install Type
Upgrade Install Type
    Pre-upgrade Steps
    Upgrade Steps
Post-upgrade Steps
Testing the Upgrade
Troubleshooting

Introduction

Note: Starting with PDK 9.0.4.1.0, the PDK download is intended to be installed and deployed in a standalone OC4J instance only. If you plan to use PDK in an Oracle Application Server instance, you must get and install the corresponding Oracle Application Server releases or patchsets.

This document contains information about how to upgrade your Portal Tools application from an earlier version of Portal Tools to the latest  version. Please check the Application Server minimum requirement in the Portal Tools Release Notes to see if you need to install Portal Tools on a later version of the Application Server. If so, follow the steps indicated for New Install type. If you are upgrading Portal Tools on the same Application Server, follow the steps indicated for Upgrade Install type.

New Install Type

To install Portal Tools on a new Application Server, you first need to deploy the Portal Tools Application on the new Application Server, then restore the provider settings from the old Application Server:

  1. Follow the steps described in the Deploying the Portal Tools Application section of the Installing Portal Tools document.
  2. Then follow the steps described in the Post-upgrade Steps section.
  3. Change the provider registration URLs in all the portals where you have registered your providers from the old Application Server to the new Application Server. You can typically do this by clicking on Edit Registration for the provider name on the Providers tab of the Navigator, under Locally Built Providers or Registered Providers. Then click on the Connection tab and change the first part of the provider registration URL from:

    http://<old_host>:<old_port>/...

    to:

    http://<new_host>:<new_port>/...

    For example, change the OmniPortlet provider registration URL from:

    http://<old_host>:<old_port>/portalTools/omniPortlet/providers/omniPortlet

    to:

    http://<new_host>:<new_port>/portalTools/omniPortlet/providers/omniPortlet

    Change the URL for both OmniPortlet and Web Clipping providers.

Upgrade Install Type

Pre-upgrade Steps

Shut Down Your OC4J Instance

Before upgrading your Portal Tools application, shut down the OC4J instance where your Portal Tools application is running. This step is required before backing-up the Portal Tools application related files and libraries to ensure that none of the files are in-use at the time of backup.

Shut Down a stand-alone OC4J instance

To shut down a stand-alone OC4J instance, you can use the following command from $OC4J_HOME/j2ee/home directory:

java -jar admin.jar ormi://host:port/ admin admin_password -shutdown

Backing Up Files  

The upgrade process will overwrite some files in your current installation. You should copy these files to a safe location so you can restore them if necessary.

Note : $BACKUPDIR refers to directory where you have decided to back-up the files.

Backing Up Old Libraries

In the Deploying the Portal Tools Application section of the Installing Portal Tools document, you will be copying a number of libraries. You should copy them up to $BACKUPDIR.

Backing Up an Old Portal Tools Application

All files related to your existing Portal Tools application will be replaced during upgrade process. Copy the following files to a safe location so you can restore the individual providers' settings and user preference data:
If your application is running in a stand-alone OC4J instance, OC4J_Instance refers to the "home" instance.

Upgrading Your Portal Tools Application

Copying the Required Files

Once you've removed the library paths from your existing files, copy the shared JAR files from the new PDK to the target stand-alone OC4J instance. Only copy these files if the supplied libraries are newer than your current installation. It is always a good practice to back up existing files in your current installation prior to copying.

copy $unzip_directory/pdk/portalTools/lib/jlib/* to $INSTALL_HOME/jlib/
copy $unzip_directory/pdk/portalTools/lib/portal/jlib/* to $INSTALL_HOME/portal/jlib/
copy $unzip_directory/pdk/portalTools/lib/ultrasearch/lib/* to $INSTALL_HOME/ultrasearch/lib/
copy $unzip_directory/pdk/portalTools/lib/wireless/lib/* to $INSTALL_HOME/wireless/lib/
copy $unzip_directory/pdk/portalTools/lib/bibeans/lib/* to $INSTALL_HOME/bibeans/lib/
copy $unzip_directory/pdk/libcommon/portal/jlib/* to $INSTALL_HOME/portal/jlib/
copy $unzip_directory/pdk/libcommon/webcache/jlib/* to $INSTALL_HOME/webcache/jlib/
copy $unzip_directory/pdk/libcommon/jlib/* to $INSTALL_HOME/jlib/

Notes:

Redeploying the Portal Tools Application

After you've copied the new files into your OC4J instance, you will need to redeploy the Portal Tools application.

Redeploying the PortalTools application in a stand-alone OC4J instance

This section assumes that your Portal Tools application is running in a stand-alone OC4J instance. To redeploy the Portal Tools application:

  1. Copy the portalTools.ear from $unzip_directory to the applications directory in your OC4J instance by using the following command:

    copy $unzip_directory/pdk/portalTools/portalTools.ear to $INSTALL_HOME/j2ee/OC4J_Instance/applications

  2. Delete the $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools directory.
  3. Delete the $INSTALL_HOME/j2ee/OC4J_Instance/application-deployments/portalTools directory.
  4. Restart the OC4J server to redeploy the Portal Tools application by executing the following command from $INSTALL_HOME/j2ee/home/: 

    java -jar oc4j.jar

Post-upgrade Steps

Restoring the Individual Providers Settings

Since redeploying the Portal Tools application overwrites your old provider settings, you'll need to restore the original individual provider settings. You only need to restore these settings for the providers you want to continue to use, and had configured before the upgrade. Before doing the restore, you should shut down the OC4J with the steps described in Shut Down your OC4J instance. The Portal Tools application contains the following providers: 

Note: 

To Restore Web Clipping Provider Settings:

  1. If Web Clipping was configured to use a proxy: copy the <proxyInfo> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml to the destination Oracle home.

    The <proxyInfo> tag is a child of the <provider> tag and appears in the file following the <preferenceStore>...</preferenceStore> tag. The <proxyInfo> tag is shown in the example below.

    <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
       <httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
       <httpProxyPort>80</httpProxyPort>
    </proxyInfo>
  2. Copy the <repositoryInfo> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml to the destination Oracle home.

    The <repositoryInfo> tag is a child of the <provider> tag and appears in the file following the <preferenceStore>...</preferenceStore> tag. The <repositoryInfo> tag is shown in the example below.

    <repositoryInfo class="oracle.portal.wcs.provider.info.DatabaseInformation">
       <useRAA>false</useRAA>
       <databaseHost>mycompany.dbhost.com</databaseHost>
       <databasePort>1521</databasePort>
       <databaseSid>iasdb</databaseSid>
       <databaseUsername>webclip_user</databaseUsername>
       <databasePassword>AX3tR</databasePassword>
       <useASO>false</useASO>
    </repositoryInfo>
  3. If you had updated the <trustedCertificateLocation> tag information, copy it from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml to the destination Oracle home. Ensure the value points to a valid file location. 

  4. If you had manually added any portlet definitions to Web Clipping Provider's provider.xml file before upgrading, copy them to the destination Oracle home.

  5. For PDK 9.0.2.4.0 only: After starting the instance, follow these steps to access the Web Clipping Provider Test Page:

    1. Access the following URL:

      http://<host>:<port>/portalTools/webClipping/providers/webClipping

      The Web Clipping Provider Test page appears. If you have specified the same database for the Repository Target as that previously used for a PDK 9.0.2.4.0 installation, a Repository upgrade is also necessary. In this case, the Web Clipping Provider Test Page provides an Upgrade (from 9.0.2.4.0) link that you can click to perform installation of new tables and migration of existing Clipping Definitions to the latest versions.

      Note:  If you perform the upgrade, the Clipping Definitions stored in the Web Clipping Repository will no longer work with PDK 9.0.2.4.0.

    2. Click the Upgrade (from 9.0.2.4.0) link.

      Tables are added to the database schema hosting the Web Clipping repository, and all Definitions are upgraded.

To Restore the OmniPortlet Provider Settings :

  1. For PDK 9.0.2.4.0 only: Copy the <useHashing> tag within the <preferenceStore> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home. If there is no <useHashing> tag in the source Oracle home, omit it in the destination Oracle home as well.

    The <preferenceStore> tag is a child of the <provider> tag and appears in the file following the <session>...</session> tag. The <preferenceStore> tag is shown in the example below.

    <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
       <name>omniPortletprefStore</name>
       <useHashing>true</useHashing>
    </preferenceStore>
  2. If OmniPortlet was configured to use a proxy: Copy the <proxyInfo> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home.

    The <proxyInfo> tag is a child of the <provider> tag and appears in the file following the <preferenceStore>...</preferenceStore> tag. The <proxyInfo> tag is shown in the example below.

    <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
       <httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
       <httpProxyPort>80</httpProxyPort>
    </proxyInfo>
  3. If you had updated the <trustedCertificateLocation> tag information, copy it from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home. Ensure the value points to a valid file location. 

  4. Update the <defaultLocale> and <localePersonalizationLevel> tags within the <portlet> tag.
    For <defaultLocale> tag:
    Copy the <defaultLocale> tag from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home. If there is no <defaultLocale> tag in the source Oracle home, enter the JVM default locale of the source instance as the value of the <defaultLocale> tag in the destination Oracle home. To find out what the JVM default locale is, you can alter the following statement in $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/htdocs/omniPortlet/TestPage.jsp from: 
    <uix:globalHeader text="<%= pageTitle.toString() %>"/>
    to:
    <uix:globalHeader text="<%= pageTitle.toString() + \"+\" + java.util.Locale.getDefault() %>"/>
    Then, bring up the OmniPortlet provider test page at:
    http://<server>:<port>/portalTools/omniPortlet/providers/omniPortlet
    Note the string in the banner. If it says: "Provider Test Page: omniPortlet+en", then the JVM default locale is "en".
    Remember to undo your change above when done.

    For <localePersonalizationLevel> tag:
    Copy the old value from backed up provider.xml. If no old value in backed up provider.xml, simply set the value to locale.
    The tags are shown in the example below.

       <defaultLocale>en</defaultLocale>
       <localePersonalizationLevel>locale</localePersonalizationLevel>
  5. Copy all directories under $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/ to the destination Oracle home. This restores the customizations to the portlets you are using in OracleAS Portal from this provider.

  6. If you had manually added any portlet definitions to OmniPortlet Provider's provider.xml file before upgrading, copy them to the destination Oracle home.

  7. Configure the Secured data Repository as specified below. Ensure that you have copied the repositoryInfo tag information in the Web Clipping provider.xml as specified in the Web Clipping Settings above.

  8. For PDK 9.0.2.4.0 only: After starting the instance, follow these steps to access the OmniPortlet Provider Test Page:

    1. Access the following URL:

      http://<host>:<port>/portalTools/omniPortlet/providers/omniPortlet

      The OmniPortlet Provider Test page appears.

    2. Click the Edit link adjacent to the status of the Secured Data Repository. In the Repository Settings section of the Edit Provider: webClipping page, the database connection information for Web Clipping Repository is shown.

    3. Click OK to save the settings.

      The OmniPortlet's provider.xml file is updated with the correct <vaultId> tag to save secured data into the repository.

  9. For PDK 9.0.2.6.2 only, if the OmniPortlet Secured Data Repository was configured: Copy the <vaultId> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home.

    The <vaultId> tag is a child of the <provider> tag and appears in the file following the <provider> tag. The <vaultId> tag resembles the following:

    <vaultId>2</vaultId>

Configuring the Providers under Portal Tools

Now that Portal Tools is deployed and you have restored the individual provider settings, you can start the OC4J that you have previously shut down, so that you can configure the individual providers and begin using them in an OracleAS Portal instance. You can configure the providers from the Portal Tools home page:

http://server:port/portalTools

The home page lists the providers under Portal Tools. Click each link to display the provider's test page and configure the provider.

Testing the Upgrade

After you have completed the above steps, you can test your upgraded Portal Tools application. First, access the Portal Tools home page at http://<host>:<port>/portalTools. This page lists the providers under the Portal Tools. Click any of these links to display a pre-configured provider test page. You can also verify that the portlets from earlier version of PortalTools are showing the expected results on the portal pages where they had been already put. Refer to the Troubleshooting section if an unexpected behavior occurs.

Troubleshooting After the Upgrade

This section contains information on resolving issues you may encounter after the upgrade. 

When you view a page containing an OmniPortlet or Simple Parameter Form portlet, you see a "Define the portlet" link.

An OmniPortlet that uses an XML or CSV data source now show errors.

Portlet definitions you manually created in the previous version of the Portal Tools application now show errors.

You created portlet definitions for the previous version of OmniPortlet. When you add these portlets to a page, they display the "Define the portlet" link.

<showDefineLink>false</showDefineLink> This tag should be put after end of <header> tag  under <definition> tag under your portlet definition.

After upgrade, when you perform "edit defaults" on an upgraded instance of a portlet, you see <None> in the field(s) where you had chosen some column from data-source (before upgrade).

Revision History:
Revision No Last Update
1.0 June 30, 2003
1.1 September 15, 2003
2.0 November 17, 2003
2.4 December 7, 2004
3.0 June 23, 2005


Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065, USA
http://www.oracle.com/
Worldwide Inquiries:
1-800-ORACLE1
Fax 650.506.7200
Copyright and Corporate Info