Skip navigation.
Downloads | Product Documentation | Support

Upgrade Guide

# Upgrading WebLogic Portal Applications

# Overview

This document explains the strategies and procedures for upgrading WebLogic Portal 7.0 SP2 applications to WebLogic Portal 8.1. The following topics are introduced in this section:

- The Upgrade Process
- Comparing Supported Features
- How to Upgrade Existing Applications

# The Upgrade Process

There are two paths for upgrading your WebLogic Portal 7.0 SP2 portal web application to WebLogic Portal 8.1:

- Compatibility: Allows for the configuration of an existing WebLogic Portal 7.0 SP2 portal web application to run on the 8.1 portal server.

Hosting an existing Portal Web application in a Portal Compatibility Domain requires following the procedure outlined in the Hosting 7.0 Applications in 8.1 Compatibility Domain section.

- Upgrade: Allows for the upgrade of WebLogic Portal 7.0 SP2 portal applications and resources to WebLogic Portal 8.1.

Hosting an existing Portal Web application in a WebLogic Portal 8.1 domain requires following the procedure outlined in the Upgrading from Compatibility Mode to WebLogic Portal 8.1 section.

## Definitions

To clarify the different activities described by this document, a brief list of terms is included:

  Migration

  Moving an application/domain from a third party technology to a BEA product. (For example, migrating a customer from IBM, webMethods or "home grown" to BEA.)

  Upgrade

  Updating BEA platform (and components) from older release/Service Pack to newer release/Service Pack. This includes updating existing application/domain to run in newer version, for example, 7.0 to 8.1.

  Interoperability

  (1) The capability of an application deployed in one release or service pack to communicate with another application that is deployed in a different release or service pack. (2) The capability of WebLogic Platform components to communicate with third-party software via standard protocols.

  Compatibility

  Application built using one release/Service Pack running in another release/Service Pack. This may or may not involve rebuilding the application.

# Comparing Supported Features

This section outlines significant feature changes between the WebLogic Portal 7.0 SP2 and the WebLogic 8.1 release. For detailed descriptions and implementation details, consult Portal Framework Details.

The portal framework in WebLogic Portal 7.0 has a one-to-one mapping with the portal it represents, which is in- line with the single portal per web application architecture. Changes made to this framework will impact the portal and all group portals, with limited provisions for changes based on runtime factors. This code was not originally designed to be modified by end users and was instead considered part of the product itself. However, users who wished to change the way that the portal behaved or make significant changes to the way that the portal looked were forced to modify this framework.

Note: This section provides a summary of feature and framework changes general to WebLogic Portal 8.1. For detailed information on each of these issues, consult Portal Framework Details.

In WebLogic Portal 8.1, the framework has been designed to allow users to more readily modify the look and the feel of the product. Instead of the single collection of JSP files for a portal, any portal may use a look and feel, which in turn is comprised of a skin and a skeleton. The portal framework is an XML skeleton that replaces the framework JSPs, allowing users to easily modify the behavior of the portal without modifying the underlying BEA code.

## Look and Feel

The look and feel of a portal is determined primarily by the code used to render the HTML, the styles used by the HTML, and the images displayed. In 7.0 only the skin could be changed to obtain a different look and feel, but in 8.1 there is a look and feel document that sets the skin and the skeleton, with the latter being the framework that is used to render the elements.

The look and feel file used in 8.1 is an XML document with a .laf extension that defines the name, the skin to use, and the skeleton to use. This allows one skeleton to be used with multiple skins, or vice- versa, with the former being the most likely case. Creating or modifying the look and feel file in 8.1 involves working with XML directly as there is no visual editor provided.

## Stylesheets

WebLogic Portal 8.1 uses Cascading Stylesheets (CSS) to a greater extent than 7.0, with more tags and improved structure.

In WebLogic Portal 7.0, a single `main.css` file contains entries for portal, portlet, pages, and other elements using a single-level naming convention. Examples include .titlebar, .portletcontainer, .pageheader, etc. Creating a new skin includes modifying the main.css file and setting the desired values for these tags.

In WebLogic Portal 8.1, multiple files are used for this task:

- `body.css`: Portal body (header, footer, etc.) styles
- `book.css`: Book, page, and menu styles
- `button.css`: Button styles
- `fix.css`: Browser bug- fix styles
- `form.css`: Form, input, and text area styles
- `layout.css`: Layout and placeholder styles
- `window.css`: Portlet styles

The naming convention in WebLogic Portal 8.1 is multi- level, providing more granularity and flexibility when using styles. Examples include bea-portal-book-primary-menu, bea-portal-window-titlebarcontainer, bea-portal-body-footer, etc. As with WebLogic Portal 7.0, creating a new skin includes copying an existing skin and modifying the styles.

## Properties

In WebLogic Portal 8.1, a skin.properties file contains entries that define the paths to images, links, scripts, and so on. In most cases it will not be necessary to modify this file, but the option to do so provides increased flexibility for locating resources.

## Scripts

There are a few JavaScript functions that are used in WebLogic Portal 8.1 for popup menus, initialization, and so on. These may be modified on a per-skin basis, but it is recommended that application specific scripts be placed in separate files.

## Images

Skins in the new release use fewer application-specific images. These images may be modified when creating custom skins.

## Skeletons

The skeletons used in WebLogic Portal 8.1 are roughly equivalent to the framework JSPs in WebLogic Portal 7.0, but the code, tags, and overall structure are quite different. There is no direct path to transfer WebLogic Portal 7.0 framework modifications to skeleton in WebLogic Portal 8.1, but a JSP developer should be able to do the conversion manually.

### JSP

The JSPs in a skeleton directory use scriptlets and JSP tags to render the various elements of the portal. Files include `body.jsp`, `book.jsp`, `popupmenu.jsp`, etc. which correspond to the portal elements. Modifications to these files can change the way that the elements are rendered as well as the way that they behave.

### Layouts

Layouts are similar to those in WebLogic Portal 7.0, but have added flexibility and functionality. The layouts are derived from three base types: grid, border, and flow. These place elements on a grid, at the center, north, south, east, or west, or in a horizontal or vertical flow, respectively.

## Definition

The layouts in WebLogic Portal 8.1 are defined in XML in the form of .layout files. These files specify the type of layout to use (grid/border/flow), the number of columns, the HTML to use for the tools, and naming. When creating a new layout it is easiest to start with an existing layout definition and modify it.

- HTML Files

The HTML files included in layouts in WebLogic Portal 8.1 are for use by WebLogic Workshop and the WebLogic Administration Portal. These HTML files use specific classes to specify the layout and placeholders, and will be similar to the JSPs. The HTML is used to render the layouts and modify the contents of placeholders.

- JSP Files

The JSP files included in layouts in WebLogic Portal 8.1 are used to render the layout on a page and are part of the skeleton. There is one file for each layout type, including gridlayout.jsp, borderlayout.jsp, and flowlayout.jsp. These may be modified as part of the skeleton, but in general it is suggested that custom layouts be created if these do not behave in the desired way. For example, a spanning layout may allow portlets to span rows or columns.

### Group Portals

Group portal definitions will not be 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.

## Webflow Support and Limitations

Portlet Webflow files can be upgraded, and can be used in conjunction with Page Flows.

WebLogic Workshop allows Webflow support to be added to existing WebLogic Portal 8.1 applications. This means Webflow portlets can run inside a WebLogic Portal 8.1. All Webflow presentation node types can be supported. An entire Webflow file can be supported, along with all its semantics, such as chaining.

Webflow and Pageflow portlets can be used in a common page. Page Flows can call Webflow files, allowing existing pipeline components and input processors to be leveraged. Page Flows can call out to Webflows and map the return to a forward in the Pageflow.

### Exceptions

Page Flow JSPs cannot call validators. Webflow presentation nodes can be supported as long as they are the endpoint of a Webflow.

## Pageflows

Provided they call the Webflow's entry point (using the syntax origin - namespace - event) Page Flows can call Webflow presentation nodes.

The resulting WebflowResponse can be used to construct a Java Pageflow Forward using the URI or URL constructors, but the Processor Nodes are definitely still in the loop.

## Portal Services

Content from an existing WebLogic Portal 7.0 repository can be consumed and leveraged into any existing integration or process. The WebLogic Portal 8.1 Virtual Content Repository allows the content management administration tools to be used against content in a WebLogic Portal 7.0 repository. Additionaly, a new bulkloader tool supports moving content from the flat WebLogic Portal 7.0 repository into WebLogic Portal 8.1 repositories, enabling you to take advantage of the new content management features.

## Security

WebLogic Portal 8.1 implements the WebLogic Server SSPI and uses the default LDAP store for user information.

- Existing customers will be able to continue to leverage their RDBMS user stores by leveraging an SSPI Authentication Provider that will be provided for connecting to a RDBMS
- Entitlement segments on WebLogic Portal 7.0 cannot be upgraded because of the change to leveraging the WLS SSPI. Customers will need to create roles using the WebLogic Administration Portal for entitlements.

### Commerce and Personalization

The only significant change to commerce functionality is that the JSP tools for orders, payments and catalog are no longer included in the WebLogic Administration portal.

Note: For instructions on adding Catalog Administration tools to an out of the box WebLogic Portal 8.1 application, consult the Adding Catalog Administration section in Upgrading from Compatibility.

Regarding personalization, property set schema and values remain unchanged and require no upgrade.

Behavior tracking requires current data be archived and re-hosted in a new schema. The procedure is outlined Step 7: Upgrading Existing Behavior Tracking Data.

### Struts

Some customers may have existing struts applications or desire to start developing Struts applications on WebLogic Portal 7.0 because of the move to Pageflows in the WebLogic Portal 8.1 release which are built on Struts 1.1. Guidelines on hosting Struts-based applications in WebLogic Portal 8.1 are listed in Struts Support.

# How to Upgrade Existing Applications

When considering the route to run your WebLogic Portal 7.0 SP2 applications on WebLogic Portal 8.1, two choices are available immediately: to host the application to run in a Portal Compatibility Domain, explained in the "Hosting 7.0 Applications in 8.1 Compatibility Domain" section, or to upgrade the application to run in WebLogic Portal 8.1, explained in the "Upgrading from Compatibility Mode to WebLogic Portal 8.1" section. The bulk of this guide is devoted to the Portal Compatibility Domain path, but also includes significant information required for re-implementation for WebLogic Portal 8.1.

## Compatibility Domain

An existing Weblogic Portal 7.0 application can be converted to run in a Portal Compatibility Domain using the procedure detailed in Hosting 7.0 Applications in 8.1 Compatibility Domain.

Figure 1-1 Upgrade to Compatibility Domain

The capabilities and limitations of this configuration are explained here:

### Features and Limitations of the Compatibility Domain

This section explains features and limitations in a Portal Compatibility Domain for the purpose of upgrade planning and strategy.

Generally speaking, WebLogic 7.0 portals running in a Portal Compatibility Domain can be administered using the 7.0 Weblogic Portal Administration Tools. WebLogic Portal 8.1 features are generally not supported in a portal enterprise application running in the Portal Compatibility Domain. Development support is also limited. For instance, neither the E-Business Control Center nor WebLogic Workshop is supported for use with any application once it has been upgraded to run in a Portal Compatibility Domain.

- XA - Transaction Level Support

In the Compatibility Domain, the `com.bea.p13n.util.jdbc.SequencerFactory` is not backward compatible. In order to support XA, the seqencer must have its own datasource. So all the APIs where you could pass one in have been removed. For information on replacing Upgrading from Compatibility Mode to WebLogic Portal 8.1 section of this document.

- MBean Configuration Mechanism

The configuration of Portal MBeans (mail service, campaign service, ad service, behavior tracking, events, caches, etc) has changed: in a Portal Compatibility Domain, these settings must be changed by editing the <ent-app>/META-INF/application-config.xml file and re-starting the server.

- Using Existing Campaigns

If you are using existing campaigns in a compatibility domain, use the content JSP tags from the previous release. If you are creating new campaigns or using existing campaigns in a new domain, use the latest content JSP tags.

### Runtime and Administrative Issues

This section explains issues concerning running and administering applications in Compatibility Domain, and discusses differences between 7.0 and 8.1 applications.

Portal Compatibility Domain supports all runtime features of the WLP 7.0 SP2 with the following exceptions:

- In the WebLogic Portal Administration Tools, Payment Management will not be available.
- FileRealm users and groups will not be automatically available.

The Compatibility Domain supports a slightly limited security model: WebLogic Portal 7.0 portals work with users and groups in both the RDBMS and LDAP realms (with a single provider) and those in `fileRealm.properties`. A WebLogic Portal 8.1 Portal Domain supports users in a single provider (RDBMS or LDAP) that will work with a portal. The net difference is that the fileRealm users and groups will no longer be automatically available in a Compatibility Domain. These are typically system users and groups.

## Upgrading to Weblogic Portal 8.1

Upgrading from Compatibility Mode to WebLogic Portal 8.1 includes the information required for re-implementing an existing Weblogic Portal 7.0 application to run in WebLogic Portal 8.1. The capabilities and limitations of this configuration are explained here, along with general description of new platform features included in WebLogic Portal 8.1.

Figure 1-2 Re-Implementation for WebLogic Portal 8.1

### Conversion of Portal and Portlet Definition Files

WebLogic Portal 8.1 includes a command line tool `upradePortalFiles.cmd` (`.sh`) that converts `.portal` and `.portlet` files from version 7.0 SP2 to version 8.1. This file resides in the `<WebLogic_Home>\portal\upgrade` directory. For more information, please refer to Step 4: Upgrade Portal and Portlet Files in Database and Metadata Upgrade Steps.

### Portal Web Applications

Portal Web applications built on WebLogic Portal 7.0 SP2 can be run on WebLogic Portal 8.1, using the upgrade procedure listed in the Upgrading from Compatibility Mode to WebLogic Portal 8.1 section.

### Look and Feel Components

WebLogic Portal 7.0 skins and UI components can be re-hosted to Look and Feels and appropriate components in the WebLogic Portal 8.1 release. For details on Look and Feel implementation, consult the Connecting to an Active Directory Server section.