# Oracle9iAS Portal Developer Kit (PDK)
Portal Tools: Upgrading From Release 9.0.2.4.0 to Release 9.0.2.6.2

Creation Date: | June 30, 2003
Status: | Production
Version: | PDK Release 2 (9.0.2.6.2 and later)

### Contents

> Introduction
> Pre-upgrade steps
> Upgrade
> Post-upgrade configuration
> Testing the Upgrade
> Troubleshooting

## Introduction

This document contains information about how to upgrade your Portal Tools application from 9.0.2.4.0 to 9.0.2.6.2. This document is valid only for upgrading Portal Tools from the 9.0.2.4.0 release. For installing the Portal Tools application, please refer to the installing.portaltools.html.

## Pre-upgrade steps

### Shut Down Your OC4J Instance

Before upgrading your Portal Tools application, shut down the OC4J instance in your Oracle 9iAS instance or the stand-alone 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 the OC4J instance in your Oracle9iAS instance

To shut down, you can use the following command from $INSTALL_HOME/opmn/bin directory:

> 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 Oracle 9iAS installation home. The installation home in case of OC4J instance running in Oracle9iAS instance would be the root directory of your Oracle9iAS 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

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 Old Portal Tools Libraries

The following PDK-Java jar files will be replaced with newer versions of the respective files in this upgrade process. Locate the existing copies of following files:

- pdkjava.jar
- ptlshare.jar
- wce.jar

and copy them to a safe location so you can restore them if necessary. These files are usually found in $INSTALL_HOME/portal/jlib. Copy the files under this directory to $BACKUPDIR/portal/jlib directory -

> copy $INSTALL_HOME/portal/jlib/* to $BACKUPDIR/portal/jlib/

> Note : $BACKUPDIR refers to directory where you have decided to back-up the files. $INSTALL_HOME refers to the Oracle9iAS installation home. See the above note for more information.

### 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:

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

Note:

> If the Portal Tools application is running in an OC4J instance in an Oracle9iAS 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

### Removing the Old Library Path Settings

Before you upgrade your Portal Tools application, you may want to remove your old library path settings from your existing file. There have been some changes to manifest files of
PDK-Java jar files and these library path entries are not required anymore.

Check if the pdkjava.jar file is in the library path in the $INSTALL_HOME/j2ee/OC4J_Instance/config/application.xml file.

The path may look like the following::

> <library path="D:\9iasclient\portal/jlib/pdkjava.jar"/>
> <library path="D:\9iasclient\portal/jlib/ptlshare.jar"/>

If the pdkjava.jar file is in the library path, remove the Portal Tools library paths from $INSTALL_HOME/j2ee/OC4J_Instance/application-deployments/portalTools/orion-application.xml. These paths look like the following:

> <library path="../../../../portal/jlib/pdkjava.jar" />
> <library path="../../../../portal/jlib/ptlshare.jar" />

If the pdkjava.jar is not part of library path settings in $INSTALL_HOME/j2ee/OC4J_Instance/config/application.xml, then remove all except pdkjava.jar entry from $INSTALL_HOME/j2ee/OC4J_Instance/application-deployments/portalTools/orion-application.xml.

### 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 Oracle9iAS 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/BC4J/lib/* to $INSTALL_HOME/BC4J/lib/
> 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 Oracle9iAS, $INSTALL_HOME is your Oracle9iAS 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 Oracle9iAS with Oracle Enterprise Manager (OEM), follow the steps in the section Redeploying to an Oracle9iAS instance Using Oracle Enterprise Manager(OEM).
- If your Portal Tools application is running in an OC4J instance in Oracle9iAS instance and you do not have OEM installed, follow the steps under Manually Redeploying to an Oracle9iAS 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 .

Redeploying to an Oracle9iAS instance Using Oracle Enterprise Manager (OEM)
This section assumes that you have OEM configured to access the Oracle9iAS installation where your Portal Tools application is running. If you do not have OEM configured, follow the instructions manually redeploying to an Oracle9iAS Instance using dcmctl. To redeploy your Portal Tools application using OEM:

1. Log into OEM. You can usually access OEM at http://{server}:1810/
2. Click on the Oracle9iAS 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 Oracle9iAS mid-tier that is being used for Oracle9iAS 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

1. Click Redeploy.

The PortalTools application will now be re-deployed.

Manually Redeploying to an Oracle9iAS 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 Oracle9iAS 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 Configuration

### 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:

- OmniPortlet Provider
- Web Clipping Provider
- Sample Provider

To Restore the OmniPortlet Provider Settings :

1. Copy the <preferenceStore> tag information from $BACKUPDIR/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml and replace the corresponding entry of <preferenceStore> tag in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml. The <preferenceStore> tag would be a child tag of <provider> tag and after <session>....</session> tag. For example, the sample <preferenceStore> tag should like the following :

   > <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
   > <name>omniPortletprefStore</name>
   > </preferenceStore>

2. Copy the <proxyInfo> tag information ( if you had previously configured OmniPortlet to use a proxy) from $BACKUPDIR/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml and change it to a child entry in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml after the <providerInstanceClass>...</providerInstanceClass>tag. Place the <proxyInfo> tag as a child tag of <provider> tag and located after the <preferenceStore>....</preferenceStore> tag. The following is an example of the <proxyInfo> tag:

> <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
> <httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
> <httpProxyPort>80</httpProxyPort>
> </proxyInfo>

3. If your Portal Tools application is running in an OC4J instance in an Oracle9iAS instance and you have redeployed your Portal Tools application using OEM or dcmctl, you must copy all the directories under $BACKUPDIR/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/ to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/. Doing so restores the customization data for all the portlets you are using in Oracle9iAS Portal from this provider.
4. If you manually added portlet definitions to the OmniPortlet Provider's provider.xml file before the upgrade, you must manually copy them to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml.

To Restore Web Clipping Provider settings:

1. Copy the <preferenceStore> tag information from $BACKUPDIR/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml and replace the corresponding entry of the <preferenceStore> tag in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml. Place the <preferenceStore> tag as a child tag of <provider> tag and after <studioUrl>....</studioUrl> tag. The following is an example of the <preferenceStore> tag:

> <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
> <name>webClippingprefStore</name>
> </preferenceStore>

2. Copy the <proxyInfo> tag informatio n (if you had previously configured Web Clipping provider to use proxy) from $BACKUPDIR/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml and change it to a child entry in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/webClip ping/WEB-INF/providers/webClipping/provider.xml after <providerInstanceClass>...</providerInstanceClass>tag. Place the <proxyInfo> tag as a child tag of <provider> tag and after the <preferenceStore>....</preferenceStore> tag. The following is an example of the <proxyInfo> tag:

> <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
> <httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
> <httpProxyPort>80</httpProxyPort>
> </proxyInfo>

3. Copy the <studioUrl> tag informatio n from $BACKUPDIR/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml and change it to a child entry in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/webClip ping/WEB-INF/providers/webClipping/provider.xml after <containerRenderer>...</containerRenderer>tag. Place the <studioUrl> tag as a child tag of <provider> tag and after the <containerRenderer>....</containerRenderer> tag. The following is an example of the <studioUrl> tag:

> <studioUrl>http://www.mycompany.com/portalTools/webClipping/htdocs/wcstudio/jsp/wcs.jsp</studioUrl>

4. Copy the <repositoryInfo> tag information from $BACKUPDIR/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml and replace the corresponding entry of <repositoryInfo> tag in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml. The <repositoryInfo> tag would be a child tag of <provider> tag and after <preferenceStore>....</preferenceStore> tag The sample <repositoryInfo> tag would like the following :

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

Pay attention to the <useRAA> tag as it wasn't there in the previous version. Be sure to include it within the <repositoryInfo> tag because the new Web Clipping Provider needs it. Also make sure to specify a value of "false" for this tag as shown in the example above to indicate that Repository Access APIs (RAA) are not being used
5. If your Portal Tools application is running in an OC4J instance in an Oracle9iAS instance and you have redeployed the Portal Tools application using OEM or dcmctl, you must copy all the directories under $BACKUPDIR/applications/webClipping/omniPortlet/WEB-INF/providers/webClipping/ to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/. Doing so restore s the customization data for all the portlets you are using in Oracle9iAS Portal from this provider.
6. If you manually added any portlet definitions to the Web Clipping Provider's provider.xml file, you must manually copy them to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml.

To Restore Sample Provider settings:

1. Copy the <preferenceStore> tag information from $BACKUPDIR/applications/portalTools/sample/WEB-INF/providers/omniPortletSample/provider.xml and replace the corresponding entry of <preferenceStore> tag in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/sample/WEB-INF/providers/omniPortletSample/provider.xml. Place the <preferenceStore> tag as a child tag of the <provider> tag and after the <session>....</session> tag. The following is an example of the sample <preferenceStore> tag:

> <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
> <name>omniPortletprefStore</name>
> </preferenceStore>

2. Copy the <proxyInfo> tag information (if you had previously configured OmniPortlet to use a proxy) from $BACKUPDIR/applications/portalTools/sample/WEB-INF/providers/omniPortletSample/provider.xml and place it as child entry in $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/sample/WEB-INF/providers/omniPortletSample/provider.xml after <providerInstanceClass>...</providerInstanceClass>tag. Place the <proxyInfo> tag as a child tag of <provider> tag and after the <preferenceStore>....</preferenceStore> tag. The following is an example of the <proxyInfo> tag:

> <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
> <httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
> <httpProxyPort>80</httpProxyPort>
> </proxyInfo>

3. If your Portal Tools application is running in an OC4J instance in an Oracle9iAS instance and you have redeployed the Portal Tools application using OEM or dcmctl, you must copy all the directories under $BACKUPDIR/applications/portalTools/sample/WEB-INF/providers/omniPortletSample/ to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/sample/WEB-INF/providers/omniPortletSample/. Doing so restores all the customization data for all the portlets you are using in Oracle9iAS Portal from this provider.
4. If you manually added any portlet definitions to the Sample Provider's provider.xml file, you must now manually copy them to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/sample/WEB-INF/providers/omniPortletSample/provider.xml.

### Upgrading the Web Clipping Repository

The instructions on upgrading the Web Clipping Repository are included in the sections below on Configuring the Providers under Portal Tools, specifically in the document on how to Configure the Web Clipping Provider, and therefore does not need to be isolated as a separate action.

### 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 Oracle9iAS 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 Oracle9iAS Portal:

1. Web Clipping Provider

2. OmniPortlet Provider

3. Sample 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://server: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 PortalTools version 9.0.2.4.0 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.

- Cause: The user has added an OmniPortlet or Simple Parameter Form portlet from PDK-Nov 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.

Revision History: |
Revision No | Last Update
1.0 | September 3, 2003

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