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

Contents

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

Introduction

Pre-upgrade steps

Shut Down Your OC4J Instance

Shut Down the OC4J instance in your Oracle9iAS 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 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

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

Backing Up Old Portal Tools Libraries

• pdkjava.jar
• ptlshare.jar
• wce.jar

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

• 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

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

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

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

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 .

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

7. Click Redeploy.

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

• 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 information (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/webClipping/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 information  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/webClipping/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 restores 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

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