Upgrade Guide

Upgrading to WebLogic Portal 8.1

Upgrading from Compatibility Mode to WebLogic Portal 8.1

The first part of this section gives instructions on moving an application that has been upgraded to run inside the WebLogic Portal Compatibility Domain so that it will run in a regular WebLogic Portal 8.1 domain.

The remainder of this section explains WebLogic Portal 8.1 features and architectural details pertinent to upgrade issues. These aspects of the new Portal framework include Webflow support, Portal services, Content Management, and Struts support.

Before You Begin

It is not possible to move directly from a WebLogic Portal 7.0 SP2 Domain to an out-of-the-box WebLogic Portal 8.1 domain. This procedure requires a Portal Web application running in a Compatibility Domain. For detailed instructions on setting up a compatibility domain, see the Creating a Portal Compatibility Domain.

Run the 'upgradePortalFiles.cmd' utility and place your upgraded portals and portlets in your application.

While no particular location is required, the upgrade tool will arrange portals and portlets such that the portlet references in the portal are in the correct location so the easiest thing to do is copy the output from the tool directly to the web-app directory.

Ensure that the JSPs referenced by the portlets are in the correct relative location.

Procedure for Upgrading from Compatibility

To convert an application running in a Portal Compatibility Domain to one that can run in an out-of-the-box WebLogic Portal 8.1 domain, take the following steps:

Create new domain using the Domain Wizard, selecting the Express option.

Create a new application directory in your new domain—in beaApps, for example.

Create a new Portal Application.

Right-click Application in the Workshop Application tab. Choose Import and use the wizard to import the Web application you re-hosted using the steps in Hosting 7.0 Applications in 8.1 Compatibility Domain. In the dialog, choose Portal Web Project, then browse to the web application. Make sure the "Copy into Application directory" option is checked. You are prompted with the message, "Files or directories required by this project type are not present. Would you like to have Workshop update your project?" Select yes.

Use WebLogic Workshop to delete the following files:

portal_taglib.jar
portlet_taglib.jar
portal_servlet.jar

These JARs contain com.bea.portal classes that are not supported in WebLogic Portal 8.1. Review and rewrite your applications as needed to discontinue use of these classes.

If your application uses pipeline components, add support for this functionality. Right-click Application in the Application tab. Choose Install—>Pipeline Services.

If the original application had Webflow and you followed the Compatibility Domain upgrade instructions, this new project should already include Webflow support. If it does not, and you need Webflow support, add it by right-clicking the project (webApp) and selecting Install—>Webflow Taglibs.

If the application requires any EJB .jar or .war files you created, add them by right-clicking Modules in the Application pane, selecting Add Module, browsing for the files, and clicking Open.

Note: You should not need tools700.war or toolSupport.war. This procedure enables the use of WebLogic 8.1 Administration Portal against the application.

Import the data files from the META-INF/data sub-directories of the Portal Compatibility Domain application to the META-INF/data directory in the new domain. The data directory must be imported component-by-component.

To import a new data sub-directory, right-click the data directory in the Workshop Application pane and select Import. Then browse to the directory from the Portal Compatibility Domain and click Import.
To merge individual files into an existing data sub-directory, (campaigns, for example) right-click the Workshop Application pane and select Import. Then browse to the directory from the Portal Compatibility Domain and click Import. The old portlet files are not needed by the application, but they can be imported to use for reference.

Copy the upgraded portals and portlets into the web application. Place the portal directly in the <WEB-APP> directory and the portlets in the <WEB-APP>/portlets directory, which you might need to create.

This placement is not required for the application to function; however, the upgradePortalFiles tool assumes this relative location. Therefore, if you choose a different organization, you might need to modify the contentUri attribute of the netuix:portletInstance tags in the portal. Check any JSP references in the upgraded portlet files and adjust them if the specified path does not match the actual location of the JSP. WebLogic Workshop will synchronize with the file system, and the upgraded portal(s) and portlets should be visible in the web app in the Application pane.

Open the upgrade portal(s) in WebLogic Workshop, and correct the layout as desired; the upgrade tool chooses a simple single column layout that might not be suitable for your portal.

Start the server. The server will generate error messages including "EJB not deploying." This is most likely because the new connections pools and data sources do not match those from the original application. We'll fix this next.

Using the config.xml file from the Compatibility Domain as a guide, create new connection pool(s) and data source(s) as needed for your application. With the server running, go to the WebLogic Console and create pool(s) and source(s) to match those in the config.xml of the earlier version of your application.

Deploy the application using the WebLogic Console.

Make any additions to the server classpath that might be required by your application.

If errors are being generated, you might need to search for references to com.bea.portal classes. These need to be replaced with references to new classes.

(Optional) The next step is to replace Webflows with Page Flows and the WebflowServlets that are produced by the portal upgrade tool with standard WebLogic 8.1 portals. Because Webflow support can easily be added to applications in WebLogic 8.1, this step is optional.

Adding Catalog Administration

You can add WebLogic Portal catalog administration functionality to your portal applications. The following procedure allows you to create and manage catalog categories and content items. You can also create and manage catalog property sets in the WebLogic Workshop Portal Extensions and manage them in the online catalog administration tools that you add with this procedure.

Copy the tools700.war into the J2EE Application root folder.

From the <WebLogic Platform 8.1>\portal\lib directory, copy the tools700.war file into the enterprise directory for your application. For example, to add this functionality to the sample portal application, place this file in samples\portal\portalApp. The next time this application is opened in WebLogic Workshop, the catalog administration tools are deployed automatically.

Note: The location, as well as the Web Application name, are changed in WebLogic Portal Version 8.1.

If commerce services haven't been installed in the application, right-click the Application directory and select Install—>Commerce Services.

Figure 3-3 Adding Commerce Service

Adding Commerce Service

Copy the Webflow files supporting the commerce administration tools into the new application:

In the \samples\portal\portalApp\META-INF\data directory in your WebLogic 8.1 installation directory, create a directory called webapps, and within that directory, create one called tools700.

From the \beaApps\sampleportal-project\application-sync\webapps\tools\ directory in the WebLogic Portal 7.0 SP2 domain, copy the tools Webflow files into the newly-created /webapps/tool700 directory.

Rename this directory to the context root of your tools700.war file. the default is tools700.

To use these tools, open a Web browser and navigate to http://<hostname>:<port>/tools700 and click Catalog Management.

Group Portals

Group portal definitions are not upgraded: in WebLogic Portal 8.1, the corresponding mechanism is the Desktop, by which a bundle of portal components is presented to a specified audience.

Struts Support

This section provides general information for developing Struts applications in WebLogic Portal 7.0, in preparation for Struts-based Page Flows in the 8.1 release. General guidelines are also provided for upgrading a Struts-based application to run within WebLogic Portal 8.1.

Struts Applications in WebLogic Portal 7.0

WebLogic Portal 8.1 supports Struts 1.1. Keep the following guidelines in mind as you develop Struts-based applications:

Restrict Struts applications to the portlet level. Struts should not be used as a page framework or in the portal framework.
Use Struts modules (sub-apps), keep all pages for modules in a single directory, and do not share pages across modules.
Use request scoped action forms, and avoid the use of Struts plugins such as Tiles.

Support for Struts in WebLogic Portal 8.1

You can edit Struts-based application configuration files in WebLogic Workshop "source view." If you are familiar with Struts, you can edit and develop against the struts-config XML file and have these updates merged to a Java Page Flow. These updates are merged to the struts-config XML file generated from the Java Page Flow (.jpf) file. You can also merge existing Struts resources into a Page Flow file.

Note: Running Struts applications in WebLogic Portal requires changes to JSP tags to handle URL rewriting.

Upgrading Struts Applications to Page Flows in WebLogic Portal 8.1

Page Flow applications are built on Struts 1.1. WebLogic Workshop provides visual design tools and a two-way editing environment for developing Page Flows, which in turn provide a single-file model for development.

Note: Upgrading JSP pages from a Struts application to Page Flow will require some changes to JSP tags in order to take advantage of Page Flow features.

JSP Tag Replacements

Framework Reference for Portal Upgrades from 7.0 to 8.1, describes JSP tags deprecated in WebLogic Portal 8.1, suggesting replacement tags or other refactoring strategies where possible.

Upgrading Database and Metadata Files from 7.0 to 8.1

This section provides general information concerning upgrade procedures for WebLogic Portal database and metadata files. The following topics are included in this section:

Table 3 -1 describes the situations where you would use each step.

Table 3 -1

Upgrade Strategy	Perform Steps
Using PointBase, moving to a WebLogic Portal 8.1 Domain	1 through 4
Not using PointBase, moving to a WebLogic Portal 8.1 Domain	2 through 4
Using PointBase, moving WebLogic Portal 7.0 application to a Portal Compatibility Domain	1, 2, 3 and 5
Not using PointBase, moving WebLogic Portal 7.0 application to a Portal Compatibility Domain	2, 3 and 5

Upgrade Scenarios

To use your existing PointBase database with the PointBase version shipped with WebLogic 8.1, perform Step 1 below. In order to upgrade portions of Portal 7.0 to Portal 8.1, perform Steps 2 through 4. And, finally, if you are planning to run in Compatibility Mode, perform Step 5.

Note: None of these steps require that WebLogic Server be up and running, and, as a result, no XA JDBC driver should be used in connecting to the database.

Step 1: Upgrade PointBase Triggers

WebLogic 8.1 includes a more current release of PointBase (4.4). PointBase rewrote their implementation of database triggers in PointBase 4.3. As a result, you must perform the following steps to upgrade your PointBase database for use in a Version 8.1 WebLogic domain.

Shut down the WebLogic Server.

Make backup copies of the 7.0 PointBase database files. This can be accomplished by simply copying the two data files ( *$1.wal and *.dbn ) found in the ..\<7.0 domain name>\pointbase directory. Be sure to make backup copies or the data files for all pertinent domains.

Change directories to the 7.0 domain directory of interest and start the PointBase console by running the startPBConsole db_settings.properties file in the following directory:

..\bea70\weblogic70\portal\bin\win32\

Open the following file in the PointBase console and execute the SQL by choosing SQL —> Execute All:

..\bea81\weblogic81\portal\upgrade\drop_70_triggers.sql

Shut down the PointBase console.

Copy the 7.0 PointBase data files from the ..\<7.0 domain name>\pointbase directory to the 8.1 upgrade directory:

..\bea81\weblogic81\portal\upgrade\pointbase

Change directories to: ..\bea81\weblogic81\portal\upgrade and start the PointBase server and PointBase console:

..\bea81\weblogic81\common\bin\startPointBase.cmd -ini=pointbase\pointbase.ini
..\bea81\weblogic81\common\bin\startPointBaseConsole

Open the following file in the PointBase console and execute the SQL by going to SQL —> Execute All:

..\bea81\weblogic81\portal\upgrade\create_70_triggers.sql

Shut down the PointBase console and PointBase server.

Step 2: Upgrade WebLogic Portal 7.0 Schema

Complete the following steps to make your 7.0 database schema 8.1 compliant:

Back up your 7.0 database.

Change directories to ..\weblogic81\portal\upgrade.

Update db_settings.properties with your 7.0 database settings.

Run the following script: upgrade_db_schema_to_81

Review the log file, upgrade_db_schema_to_81.log, to verify that the upgrade was successful.

For Sybase databases, run the upgrade script for 7.0 to 8.1.

The WebLogic Portal 7.0 upgrade script is located at bea\weblogic700\portal\db\sybase\125\migrate\migrate_to_125.sql

For PointBase; copy the ..\weblogic81\portal\upgrade\pointbase\*$1.wal and *.dbn files to your 8.1 domain. If your 8.1 domain is not named wlpCompatability, you must rename the *$1.wal and *.dbn files to match the PointBase database name used in your domain.

The database is now upgraded to WebLogic Portal 8.1.

Note: For PointBase you will see 2 errors (example below). You can ignore these errors, as they are generated while attempting to re-create the user WEBLOGIC:

SQL> Error Message: User WEBLOGIC already exists in the database.

Step 3: Upgrade Application-Sync Files

A number of files require the xsi:schemaLocation to be updated as a result of an upgrade to Xerces. These files typically reside in a directory similar to:

..\bea70\weblogic700\user-projects\portalDomain\beaApps\portalApp-project\application-sync

Copy the 7.0 application-sync directory and its subdirectories and files to the 8.1 domain location. The application-sync should be a peer to ..\META-INF\data.

For example:
..\bea81\user_projects\applications\portalApp\META-INF\application-sync
..\bea81\user_projects\applications\portalApp\META-INF\data
From the ..\bea81\weblogic81\portal\upgrade directory, run the script by typing the following at the command line:
UpgradeApplicationSyncFiles c:\bea81\user_projects\applications\ testApp\META-INF\

When executing the upgrade script, you must specify the absolute path of the META-INF directory. The files are read from the ..\META-INF\application-sync directory (and its sub-directories) and will then be written, along with any changes to the xsi:schemaLocation parameter, to the ..\META-INF\data directory. In the event that ..\META-INF\data already exists, you are asked to rename the directory to prevent any inadvertent loss of files. Note that none of the source files are changed or moved from the ..\META-INF\application-sync directory.

Run the upgrade script:

UpgradeApplicationSyncFiles c:\bea81\user_projects\applications\ testApp\META-INF\

Review the corresponding log file, upgradeApplicationSyncFiles.log, to verify that the upgrade was successful. The same information is displayed to the console.

Step 4: Upgrade Portal and Portlet Files

Upgrade .portal and .portlet files using the script in the following directory:

..\weblogic81\portal\upgrade

From within the upgrade directory ..\weblogic81\portal\upgrade, run the script by typing the following at the command line:

upgradePortalFiles -i<source dir or source file> -o<output dir>

For example, Listing 3-1 illustrates the output if the sampleportal-project directory was copied into a directory called C:\old and a directory called C:\new were created for the transformed portal and portlet files.

Note: The upgradePortalFiles script looks recursively through all subfolders for .portal and .portlet files. None of the source files are changed.

Listing 3-1 Running the upgradePortalFiles Script

C:\weblogic81\portal\upgrade>upgradePortalFiles -iC:\old -oC:\new

C:\weblogic81\portal\upgrade>REM echo off

C:\weblogic81\portal\upgrade>C:/jdk141_03/bin/java -cp

C:/weblogic81/portal/lib/netuix/ejb/netuix_util.jar;C:/weblogic81/portal/lib/netuix/ejb/netuix.jar;C:/weblogic81/portal/lib/netuix/system/netuix_system.jar;C:/weblogic81/p13n/lib/p13n_system.jar;C:/weblogic81/server/lib/weblogic.jar com.bea.netuix.migration.PortalMigration -iC:\old -oC:\new

Processing file Bookmarks.portlet

Transformed version of Bookmarks.portlet was valid.

Saving file...

Processing file CompanyProfiles.portlet

Transformed version of CompanyProfiles.portlet was valid.

Saving file...

Processing file CustomerService.portlet

Transformed version of CustomerService.portlet was valid.

Saving file...

Processing file Dictionary.portlet

Transformed version of Dictionary.portlet was valid.

Saving file...

Processing file Email.portlet

Transformed version of Email.portlet was valid.

Saving file...

Processing file GroupToDo.portlet

Transformed version of GroupToDo.portlet was valid.

Saving file...

Processing file MyNewsletters.portlet

Transformed version of MyNewsletters.portlet was valid.

Saving file...

Processing file MyToDo.portlet

Transformed version of MyToDo.portlet was valid.

Saving file...

Processing file Newsletters.portlet

Transformed version of Newsletters.portlet was valid.

Saving file...

Processing file Portfolio.portlet

Transformed version of Portfolio.portlet was valid.

Saving file...

Processing file PrimaryCampaign.portlet

Transformed version of PrimaryCampaign.portlet was valid.

Saving file...

Processing file QuickLinks.portlet

Transformed version of QuickLinks.portlet was valid.

Saving file...

Processing file Quote.portlet

Transformed version of Quote.portlet was valid.

Saving file...

Processing file ReviewNewsletters.portlet

Transformed version of ReviewNewsletters.portlet was valid.

Saving file...

Processing file SecondaryCampaign.portlet

Transformed version of SecondaryCampaign.portlet was valid.

Saving file...

Processing file WebSearch.portlet

Transformed version of WebSearch.portlet was valid.

Saving file...

Processing file WhatsHot.portlet

Transformed version of WhatsHot.portlet was valid.

Saving file...

Processing file WorldNews.portlet

Transformed version of WorldNews.portlet was valid.

Saving file...

Processing file sampleportal.portal

Transformed version of sampleportal.portal was valid.

Saving file...

PortalMigration completed successfully.

C:\weblogic81\portal\upgrade>

The input argument (-i) should be a directory that has portals and/or portlets in it or one of its sub-directories. It is expected that users will specify a 7.0 EBCC project directory but there is no requirement that this be so. When a directory is specified for the input argument, the tool traverses the directory and all its sub-directories looking for files with a .portal or .portlet extension. Each file found is validated against the 7.0 schema. If it passes validation, the appropriate XSLT is applied. If transformation is successful, the new document is validated against the 8.1 schema. The file is written to the output directory as described below. The input argument might also be a specific .portal or .portlet file. In this case, only the specified file is processed as described above and written out as described below.

The output argument (-o) should be a directory. Under this directory, a directory named "portal" is created and any portals found in the input directory are written here after they are transformed, if they pass Version 8.1 validation. Under the "portal" directory a directory named "portlets" is created and all portlets found in the input directory are validated and written here after they are transformed. Portals or portlets that are transformed but fail the 8.1 validations are written to a sub-directory named "failed-verification" located under the output "portal" or "portlet" directories, depending on the file's type. None of the source files are changed or moved.

The output directory looks something like this when the file upgrade completes:

<output dir>

|
|-- portal (valid 8.1 portals files in here)

|
|-- failed-verification (portals that failed 8.1 validation)
|
|-- portlets (valid 8.1 portlets files in here)

______________|
______________|-- failed-verification (portlets that failed 8.1 validation)

Step 5: Upgrade ENTITLEMENT_RULESET Records

This upgrade step is necessary only if you are planning to run in compatibility mode.

Like the previous upgrade action taken with the files located under the application-sync directory, records that exist in the database must also be updated to properly reflect the new xsi:schemaLocation. Specifically, the records reside in the ENTITLEMENT_RULESET table.

Upgrade ENTITLEMENT_RULESET records in the database using the following steps:

Back up the 7.0 database.

For PointBase only: change directories to ..\bea81\weblogic81\portal\upgrade and start the PointBase server and PointBase console.

..\bea81\weblogic81\common\bin\startPointBase.cmd 
-ini=pointbase\pointbase.ini

To start the PointBase Server, you might need to pass in a parameter such as the following: -port=9095

Navigate to: ..\bea81\weblogic81\portal\upgrade.

Update upgrade.properties with your 7.0 database settings.

Run the following script: upgradeEntitlementRulesets.

Review the upgradeEntitlementRulesets.log file to verify that the upgrade was successful. The same information is displayed to the console.

For PointBase: shut down the PointBase Server

Step 6: Upgrading Existing Behavior Tracking Data

To preserve and reuse existing behavior tracking data in an upgraded application, perform the following steps:

Archive existing behavior tracking data

Create another schema within the database for the new release.

Change the connection pool settings for behavior tracking to point to the new schema.