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

Contents

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

Introduction

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

Shut Down the OC4J instance in your OracleAS instance

opmnctl stopproc gid="OC4J_Instance"

Note:
1. OC4J_Instance refers to the OC4J instance where your Portal Tools application was deployed. Typically, it will be "OC4J_Portal" instance.
2. $INSTALL_HOME refers to the OracleAS installation home. The installation home in case of OC4J instance running in OracleAS instance would  be the root directory of your OracleAS installation (You will find directories named "bin", "Apache", "lib", "jlib" etc. under this directory). In case of standalone OC4J instance, installation home is the root directory of your OC4J installation (You will find directories named "bin", "j2ee", "javacache", "jdbc" etc. under this directory).

eg opmnctl stopproc gid="OC4J_Portal"
if your Portal Tools application is running in OC4J_Portal instance.

Shut Down a stand-alone OC4J instance

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

• copy $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/*  to $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/
• copy $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools.ear to $BACKUPDIR/j2ee/OC4J_Instance/applications/

Note:

If the Portal Tools application is running in an OC4J instance in an OracleAS instance, OC4J_Instance refers to the OC4J instance where the Portal Tools application has been deployed. This instance is usually the OC4J_Portal instance. 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 OracleAS or 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/wireless/lib/* to $INSTALL_HOME/wireless/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:

• $unzip_directory denotes the directory where you have unzipped the pdk.zip. The libraries and the components to which they belong are described above. 
• Create the target directories if they do not already exist.
• If installing on an OC4J instance in OracleAS, $INSTALL_HOME is your OracleAS installation home (also called $IAS_HOME).
• If installing on a stand-alone OC4J instance, $INSTALL_HOME is the root directory of your OC4J installation (also called $OC4J_HOME). You will find directories named "bin", "j2ee", "javacache", "jdbc" etc. under this directory. 
• Only copy them 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.

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.

• If your Portal Tools application is running in an OC4J instance in OracleAS with Oracle Enterprise Manager (OEM), follow the steps in the section Redeploying to an OracleAS instance Using Oracle Enterprise Manager(OEM). 
• If your Portal Tools application is running in an OC4J instance in OracleAS instance and you do not have OEM installed, follow the steps under Manually Redeploying to an OracleAS Instance Using dcmctl.
• If your Portal Tools application is running in a stand-alone OC4J instance, follow the steps in the section, Redeploying to a Stand-Alone OC4J Instance .

1. Log into OEM. You can usually access OEM at http://{server}:1810/
2. Click on the OracleAS mid-tier where you have the Portal Tools application running. You will see a list of all your system components in your mid-tier.
3. Click on the OC4J instance where you have the Portal Tools application running. If you are deploying on the OracleAS mid-tier that is being used for OracleAS Portal, there will normally be an OC4J instance named "OC4J_Portal". You should see the Portal Tools application in the list of applications for this OC4J instance.
4. Click Start to start the OC4J instance.
   
5. After starting OC4J instance, select the Portal Tools radio button in the list of applications, then click Redeploy.
6. On the next page, enter the following information:

J2EE Application : $unzip_directory/pdk/portalTools/portalTools.ear

7. Click Redeploy.

Manually Redeploying to an OracleAS instance Using dcmctl

This section assumes that you do not have OEM installed (or you wish to redeploy the Portal Tools application manually without using OEM). 

Warning: Before using dcmctl to manage an OracleAS instance, make sure there are no OEM processes managing that same instance. If multiple processes are managing the same instance, there is a risk of inconsistencies or corruption of the data used to manage the instance.

To redeploy the Portal Tools application using dcmctl:

1. Start the OC4J instance where Portal Tools application is deployed. To start the OC4J instance, execute the following command :
   

   opmnctl startproc gid="OC4J_Instance"

2. To redeploy portalTools.ear, execute the following command :

   $INSTALL_HOME/dcm/bin/dcmctl redeployApplication -v -f EarFilePath -a ApplicationName -co OC4J_Instance
   

   where:

   • EarFilePath is the location of the EAR file to be deployed. Its value is $unzip_directory/pdk/portalTools/portalTools.ear.
   • ApplicationName is the name of the application. Its value would be "portalTools".
   • OC4J_Instance is the name of the OC4J instance where the Portal Tools application is running.

   eg dcmctl redeployApplication -v -f $unzip_directory/pdk/portalTools/portalTools.ear -a portalTools -co OC4J_Portal
   

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

• Web Clipping Provider
• OmniPortlet Provider

Note: 

• For New Install type, $BACKUPDIR refers to the old OracleAS installation home.
• If the PDK version you are upgrading from is not specified, you need to perform the step for all versions.

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 manually added any portlet definitions to Web Clipping Provider's provider.xml file before upgrading, copy them to the destination Oracle home.

4. 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. 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:
   Change the value to locale.
The tags are shown in the example below.

      <defaultLocale>en</defaultLocale>
      <localePersonalizationLevel>locale</localePersonalizationLevel>

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

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

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

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

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

The following links describe how to configure each provider and register it with OracleAS Portal:

1. Web Clipping Provider

2. OmniPortlet Provider

3. Sample Provider

Testing the Upgrade

Troubleshooting After the Upgrade

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

• Cause: The user has added an OmniPortlet or Simple Parameter Form portlet from PDK 9.0.2.4.0 and has not yet customized it.
• Action: Click the Define the portlet link and customize the OmniPortlet definition.

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

• Cause: Check the application.log for errors.
• Action: If the data source files were referred from files in the OmniPortlet Web application, they were probably removed during the upgrade. Copy them back to the appropriate location(s) from $BACKUPDIR.

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

• Cause: These portlet definitions were probably not transferred to the new provider.xml.
• Action: Copy the new portlet definitions to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml.

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.

• Cause: The new code base of OmniPortlet renders the "Define the portlet" link when the portlet is first dropped to page.
• Action: After you define the portlet, the data is displayed onto the portlet. If you want to display pre-configured data in the newly dropped portlet, you need to put the following tag in provider.xml :

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

• Cause: Either the name of the column you selected starts with a numeric character or it contains special character(s) other than alphanumeric character(s) and '_' (underscore) character. The special character(s) could be space, '%' etc. All instances of such special characters are replaced by '_' ( underscore) character. For example, if column name before upgrade was 'Department No', after upgrade it will be displayed as 'Department_No'.
• Action: You need to select the (renamed) column again in all such cases.