Upgrade Guide

Compatibility Domain

Hosting 7.0 Applications in 8.1 Compatibility Domain

WebLogic Portal 8.1 supports a Compatibility Domain to enable upgraded WebLogic Portal 7.0 portal applications to be hosted on the newer version of the product. This section includes instructions on creating a Compatibility Domain, as well as steps required to upgrade your existing portal application to run in such a domain.

Note: The WebLogic Portal 8.1 Compatibility Domain originally supported applications built on WebLogic Portal 7.0 SP2. The WebLogic Portal 8.1 SP2 Compatibility Domain supports applications build on WebLogic Portal 7.0 SP4.

Compatibility Explained

The 8.1 release of WebLogic Platform introduces significant changes to the platform in which Portal applications run. To ease the transition from WebLogic Portal 7.0 to 8.1, the Compatibility Domain enables 7.0 portal applications to be run on the new platform with minimal alterations.

The Compatibility Domain is a feature introduced in WebLogic Portal 8.1 in which an existing 7.x portal (and domain), possibly in a cluster, with existing data in the database, can be 'upgraded' to run in a specially-configured Compatibility Domain. This allows you to take advantage of the new platform features in new applications while also running existing applications within the same instance of WebLogic Platform.

Features and Limitations of the Compatibility Domain

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

Generally speaking, portals built in WebLogic Portal 7.0 which are re-hosted to run in a Portal Compatibility Domain can be administered using the Weblogic 8.1 Administration Portal. No WebLogic Portal 8.1 features are supported in a portal enterprise application running in a Portal Compatibility Domain. Development tools such as the E-Business Control Center, WebLogic Workshop (any version) are not supported against applications running in a Portal Compatibility Domain.

Development Issues

This section includes some considerations that may affect your upgrade planning, depending on how your applications are implemented.

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. The Framework File Reference section includes information meant to assist in refactoring existing code. You can also consult the Javadoc at the following link:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/navReference.html

MBean Configuration Mechanism

In WebLogic Portal 7.0, the portal MBeans (mail service, campaign service, ad service, behavior tracking, events, caches, etc) were configured in the WebLogic Server console. A portal plug-in for the server console allowed you to change these settings.

In Portal Compatibility Mode, this portal plug-in is not present. In WebLogic Portal 8.1, these settings are exposed in the Portal Administration Tools, which do not run against an application in a Portal Compatibility Domain.

The solution is to edit the application-config.xml file (in the ENT-APP directory), change the settings, then re-start the server.

Runtime and Administrative Issues

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

Portal Compatibility Domain supports all runtime features of the WebLogic Portal 7.0 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 8.1 Portal Domain supports users in a single provider (RDBMS or LDAP) will work with a portal. The net difference is that the fileRealm users and groups will no longer be automatically available in a Portal Compatibility Domain. These are typically system users and groups.

Listing Parent Groups

In Portal Compatibility Domain, the WebLogic Administration Portal does not list parent groups to which a user belongs, a change from WebLogic Portal 7.0. If groups A and B were subgroups of C, and a user were a member of A and B, the User Details screen would list all three groups in WebLogic Portal 7.0 Administration Portal, but only groups A and B in the Portal Compatibility Domain Administration Portal.

Authentication Providers in Portal Compatibility Domain

This section explains authentication considerations that may arise when creating new portals meant to run inside a Portal Compatibility Domain.

User and Group Management

Due to the design of WebLogic Portal 8.1, Portal User and Group Management can work with a single Security Authentication Provider (the first one listed in the console). This is a domain-level configuration -- all Portal enterprise applications (more specifically, User and Group Management calls by the portal applications) in the domain can only see users and groups in the first Security Authentication Provider.

Default WebLogic Portal 8.1 Domains are configured to use the Default Authentication Provider (LDAP). By default, portals use LDAP to store and access users and groups.

A Portal Compatibility Domain uses the RDBMSAuthenticationProvider to provide access to the users and groups from the WebLogic 7.0 SP2 domain, because generally these were stored in the database. Therefore, portals running in a Portal Compatibility Domain will generally use RDBMS to store and access users and groups.

If the out of the box WebLogic Portal 8.1 domain and the Portal Compatibility Domain use different Authentication Providers, there are two choices:

Configure the domain to use RDBMS Authentication, and manually migrate LDAP users and groups (from the out of the box WebLogic Portal 8.1 domain) to the RDBMS. Passwords are not preserved in this procedure.
Configure the domain to use LDAP Authentication, and manually migrate RDBMS users/groups (from the 'upgraded' portal) to LDAP. Passwords are not preserved in this procedure.

Note: If the WebLogic 7.0 SP2 domain uses LDAP instead of RDBMS authentication for users and groups, the Portal Compatibility domain will likewise use LDAP, meaning it will use the same provider as the out of the box WebLogic Portal 8.1 domain.

To avoid this issue, any new portals designed in an out of the box WebLogic Portal 8.1 domain should be configured to use RDBMSAuthenticationProvider.

This would require simply installing the RDBMSAuthenticationProvider and designating it the first provider in the list in the console, directly following the creation of the new domain.

Procedure for Hosting in Compatibility

The process for hosting an existing WebLogic Portal 7.0 application to run inside a Portal Compatibility Domain includes three phases:

Note: This procedure is based on the following assumptions:

The compatibility domain is called 'portalCompatibilityDomain' and is created at user_projects\domains\portalCompatibilityDomain.

The 'upgraded to compatibility' portal applications directory is user_projects\applications\... (the apps can be stored anywhere)

Creating a Portal Compatibility Domain

This section explains the steps necessary to create a Portal Compatibility Domain.

Before You Begin

This procedure requires that the following elements be in place:

Complete WebLogic Portal 8.1 Installation
Existing WebLogic Portal 7.0 Domain
db_settings.properties file from the existing Domain

Portal Compatibility starts with the portal domain configured via the portal Configuration Wizard template, and continues with a manual process for configuring the domain and 7x enterprise applications. A primary goal is that very few code changes will be required for a domain/ent-app that uses only Portal. Most of the configuration steps involve replacing jars and editing configuration files.

Discover SystemAdministrator Users From Existing Domain

Start the WebLogic Portal 7.0 server, open the Portal Administration Tools, and make a list of the users in the SystemAdministrator group. You will need this when upgrading the domain.

Backup Existing Domain

Make backup copies of the existing domain, enterprise applications and of course, the database.

Step 1: Create New Portal Domain

Use the Configuration Wizard in WebLogic Portal 8.1 to create a new Portal domain, using the Express setup option and the template for the Basic WebLogic Portal Domain. Use the same domain username and password as you used for the existing WebLogic Portal 7.0 domain.

Note: This procedure illustrates a domain called "portalCompatibilityDomain", but it can be named anything.

Copy the dmsBase Directory from the WebLogic Portal 7.0 domain directory to the Portal Compatibility Domain directory.

Transfer Commerce Properties.

If you were using commerce features in the WebLogic Portal 7.0 domain, copy the weblogiccommerce.properties file from the weblogic700\portal\ directory to the weblogic81\portal\ directory.

Next, modify the compatibility domain's startWeblogic script to reference this newly copied properties file.

For example, add the following line to the script:
-Dcommerce.properties=<absolute path to weblogiccommerce.properties>

Step 2: Edit Start Script

Make the following edits to the startWeblogic.cmd script for the new WebLogic Portal 8.1 Compatibility Domain:

For All Databases:

Add this line just before the server startup line (roughly 330 - beginning with "'if %WLS_REDIRECT_LOG%"=="" ('): set CLASSPATH=%WLP_HOME%\lib\portal_system.jar;%WLP_HOME%\lib\commerce_system.jar;%CLASSPATH%

For PointBase only:

Configure the database host, port, instance name, and the WebLogic Server host and port, in the following scripts, using the values in your db_settings.properties file as a guideline:

startWebLogic.cmd/.sh

For example, change this:
call "%WL_HOME%\common\bin\stopPointBase.cmd" -port=9093 -name=workshop ...
to this, assuming you used the default PointBase instance and port:
call "%WL_HOME%\common\bin\stopPointBase.cmd" -port=9092 -name=wlportal ...

stopWebLogic.cmd/.sh

For example, change this:
call "%WL_HOME%\common\bin\startPointBase.cmd" -port=9093 ... . . . call "%WL_HOME%\common\bin\stopPointBase.cmd" -port=9093 -name=workshop ...
to this, assuming you used the default PointBase instance and port:
call "%WL_HOME%\common\bin\startPointBase.cmd" -port=9092 ... . . . call "%WL_HOME%\common\bin\stopPointBase.cmd" -port=9092 -name=wlportal ...

Step 3: Configure the New Domain

Edit the following settings for the new domain:

If the existing WebLogic Portal 7.0 domain had SSL enabled, enable SSL for the new WebLogic Portal 8.1 Compatibility Domain by editing config.xml and setting Enabled="true" in the <SSL> entry under the <Server> section.
Server port settings (Listen Port) are in the config.xml file in the existing WebLogic Portal 7.0 domain directory. Verify they are the same in the config.xml file for the new domain.

Step 4: Configure the Database

The upgrade process requires that the new domain have access to the existing database. Database settings are contained in files within the domain directory for both 7.0 and 8.1. The steps that follow ensure that the database settings in the new 8.1 domain match those in the existing 7.0 domain.

Set the JDBCConnectionPool Entry

Configure the <JDBCConnectionPool> URL settings in the 8.1 Portal Compatibility Domain's config.xml file to correspond to the URL settings in the config.xml file for the existing WebLogic Portal 7.0 domain, matching the database host, port, and schema name. Listing 2-1 and 2-2 show sample JDBCConnectionPool entries for a new WebLogic Portal 8.1 Compatibility Domain.

Listing 2-1 JDBCConnectionPool Entry for PointBase

<JDBCConnectionPool Name="cgPool" Targets="portalServer" 
CapacityIncrement="1" 
DriverName="com.pointbase.jdbc.jdbcUniversalDriver" 
InitialCapacity="5" MaxCapacity="50" 
Password="{3DES}dYceZKN2mwcfajtJC6uzSg==" 
Properties="user=weblogic;" RefreshMinutes="0" 
ShrinkPeriodMinutes="15" ShrinkingEnabled="true" 
SupportsLocalTransaction="true" TestConnectionsOnRelease="false" 
TestConnectionsOnReserve="false" URL="jdbc:pointbase:server://localhost:9093/wlportal"/>

Listing 2-2 JDBCConnectionPool Entry for Oracle

<JDBCConnectionPool CapacityIncrement="1" 
DriverName="oracle.jdbc.driver.OracleDriver" 
InitialCapacity="25" MaxCapacity="25" Name="cgPool" 
Password="weblogic" 
Properties="user=weblogic" 
RefreshMinutes="0" ShrinkingEnabled="false" 
Targets="portalServer" TestConnectionsOnReserve="false" 
URL="jdbc:oracle:thin:@<dbhost>:1521:<dbSID>"/> 
<JDBCDataSource JNDIName="weblogic.jdbc.pool.commercePool" 
Name="commercePool" PoolName="cgPool" Targets="portalServer"/>

Note: A JDBC datasource has been added to Listing 2-2 for access to the WebLogic Portal 7.0 data.

Update the Database Configuration Files

Update Portal Compatibility Domain files to reference correct database configuration settings:
Configure the 8.1 Portal Compatibility Domain's db_settings.properties file to correspond to the settings in the db_settings.properties file for the existing WebLogic Portal 7.0 domain, matching the host, db_name, port, dblogin, dbpassword, and connection fields. Listings 2-3 and 2-4 show sample configuration settings for a new WebLogic Portal 8.1 Compatibility Domain.

Listing 2-3 Database Configuration Entry for PointBase

#@IF_USING_POINTBASE@
database=POINTBASE
db_version=44
jdbcdriver=com.pointbase.jdbc.jdbcUniversalDriver
host=localhost
db_name=portal
port=9093
dblogin=WEBLOGIC
dbpassword=WEBLOGIC
connection=jdbc:pointbase:server://localhost:9093/wlportal
pointbase_ini=pointbase/pointbase.ini
#@ENDIF_USING_POINTBASE@

Listing 2-4 Database Configuration Settings for Oracle

database=ORACLE_THIN 
db_version=817 
jdbcdriver=oracle.jdbc.driver.OracleDriver 
server=<dbSID>
port=1521 
dblogin=USERNAMEGOESHERE 
dbpassword=PASSWORDGOESHERE 
connection=jdbc:oracle:thin:<dbHost>:1521:<dbSID>

Prepare PointBase Files for Schema Upgrade

The PointBase instance requires a few preparatory steps before the schema upgrade:
Follow the steps in section Upgrade PointBase Triggers. These steps prepare the PointBase files in upgrade/pointbase to be schema-upgraded.

Upgrade Database Schema

Before the actual data can be migrated from the existing database, the schema must be updated. This applies to all databases, which require the preparatory steps described in the Upgrade WebLogic Portal 7.0 Schema section of Overview.

Upgrade Existing Data

This step causes the contents of the ENTITLEMENT_RULESET table to be updated.

All Databases

Follow the steps in the section Upgrade ENTITLEMENT_RULESET Records section of Overview.

Specifically, the following changes are made by this procedure:

For each row in the ENTITLEMENT_RULESET table, this modifies the value of the RULESET_DOCUMENT column as follows: The XML text http://www.bea.com/servers/p13n/xsd/rules/core/2.1.1 rules-core-2_1_1.xsd is prepended to the <cr:rule-set> element's xsi:schemaLocation attribute value.

PointBase Only

For PointBase only, copy the upgraded .wal and .dbn files from the upgrade/pointbase/ directory to the WebLogic Portal 8.1 Compatibility Domain directory (or wherever your .wal/.dbn files are).

Security Upgrade

The remainder of the steps required to prepare the new Portal Compatibility Domain involve upgrading the security. The following tasks are included in this section:

Install an RDBMSAuthenticationProvider to access existing users and groups stored in the RDBMS.
Any portal users and groups previously in fileRealm.properties required for access for the portal running in portal compatibility will need to be added to the RDBMS and their passwords reset.
The PortalSystemAdministrators group is required by portal compatibility (and WebLogic Portal 8.1 in general) in order to make changes in the WebLogic Portal Administration Tools, so this group is manually added to the RDBMS.
Users with portal administrator privileges in the existing WebLogic Portal 7.0 domain are added to the PortalSystemAdministrators group.
Any ACLs configured in the WebLogic Portal 7.0 fileRealm.properties (or on an LDAP store) must be reconfigured: they will not be automatically migrated by the upgrade process.

Install and Configure the RDBMS Authentication Provider

The RDBMS Authentication Provider allows users and groups stored in a WebLogic Portal 7.0-based RDBMS store to be accessed from a portal in release 8.1 using the WebLogic Security Service Provider Interface (SSPI). This allows the WebLogic 8.1 Portal to work with users and groups defined in WebLogic Portal 7.0's RDBMSRealm, with minimal changes.

You can skip this section if your 7.0 domain did not use the RDBMSRealm. If you are unsure of whether you used the RDBMSRealm, open the config.xml file in the WebLogic Portal 7.0 domain. If the file does not contain a stanza for <RDBMSRealm> then your 7.0 domain did not use the RDBMSRealm and you can skip this section. If config.xml does contain this stanza, check the value of BasicRealm in the <CachingRealm> stanza; if it matches the Name in the <RDBMSRealm>, then your 7.0 domain did use the RDBMSRealm and you must complete the steps in this section.

Step 1: Configure the Authentication Provider

Use this procedure to configure the Authentication Provider in the new Compatibility Domain:

In the new WebLogic Portal 8.1 Compatibility Domain, run the startWeblogic script and navigate to the following URL in the browser: http://localhost:7501/console. You may need to adjust the host name and port to match the settings in config.xml.

Click Configure a new RDBMSAuthenticator and set the control flag to SUFFICIENT, and click Create.

Click the Details tab and edit the database settings according to the config.xml and db_settings.properties in the previous section.

For example, using sampleportal with PointBase, the settings would be as in Listing 2-5, and using sampleportal with Oracle, the settings would be as in Listing 2-6.

Click Apply.

Go to Security-->Realms-->myrealm-->Providers--> and select Authentication.

Select DefaultAuthenticator (the LDAP provider), set the control flag to SUFFICIENT, and click Apply.

Select Security-->Realms-->myrealm-->Providers--> and select Authentication.

Click Re-order the Configured Authentication Providers, make the RDBMSAuthenticator appear first in the list, and click Apply.

Shut down the server.

Listing 2-5 Authentication Settings for PointBase

Database Driver: com.pointbase.jdbc.jdbcUniversalDriver 
Database URL: jdbc:pointbase:server://localhost:9092/wlportal 
Schema Properties: user=WEBLOGIC;password=WEBLOGIC;server=jdbc:pointbase:server://localhost:9092/wlportal 
Minimum Password Length: whatever it was in 7.x (ie 1 character for 7x sampleportal)

Listing 2-6 Authentication Settings for Oracle

Database Driver: oracle.jdbc.driver.OracleDriver Database URL: jdbc:oracle:thin:@myOraDB:1521:myOraInstance Database Username: weblogic Database Password: weblogic Schema Properties: user=weblogic;password=weblogic Minimum Password Length: 8

Step 2: Add PortalSystemAdministrators Group Using RDBMSAuthentication

This section is applicable only if your 7.0 domain used the RDBMSRealm.

In order to support using the WebLogic Portal 7.0 Administration Tools, the PortalSystemAdministrators group must be added to the RDBMSAuthenticationProvider. If users and groups were stored in the database in the existing WebLogic Portal 7.0 domain, the PortalSystemAdministrators group must be added to RDBMSAuthentication.

Using the SQL editor of your choice (for example, SQL*Plus, PointBase Console), run the following SQL:

insert into GROUP_SECURITY( GROUP_ID, GROUP_NAME ) values ( 900, 'PortalSystemAdministrators' );

insert into ENTITY( ENTITY_ID, ENTITY_NAME, ENTITY_TYPE ) values ( 900, 'PortalSystemAdministrators', 'Group' );

Note: 900 is a reserved number in this index, so there should be no problem with this operation.

Step 3: Add PortalSystemAdministrators Group Using Outside Authentication Store

This section is applicable only if your 7.0 domain did not use the RDBMSRealm.

If users and groups were not stored in the database in the existing WebLogic Portal 7.0 domain, add the PortalSystemAdministrators group to the LDAP (or other) store.

You may want to migrate any ACLs in the fileRealm.properties file of the existing WebLogic Portal 7.0 domain.

Upgrading the Enterprise Application

This section describes how to configure a WebLogic Portal 7.0 enterprise application to run in the WebLogic Portal 8.1 Compatibility Domain that you created by following the instructions in the Creating a Portal Compatibility Domain section.

In the section below, ENT-APP refers to the directory for your enterprise application, and WEB-APP refers to the directory for your web application(s).

Before You Begin

This section includes instructions for re-hosting enterprise applications to run in the new WebLogic Portal 8.1 Compatibility Domain. Make sure you have performed the backup steps described in the Before You Begin section of Creating a Portal Compatibility Domain.

For sampleportal only:

Make sure the values in the db_settings.properties file in your 7.0 Domain directory are consistent with those in your 8.1 Compatibility Domain. If you have changed your 8.1 settings to match the 7.0 settings, you can skip the remaining steps in this section.

Run configca.bat/sh from your 7.0 Domain directory. This creates an updated version of BlackBoxNoTx.rar in your 7.0 enterprise application directory.

Copy BlackBoxNoTx.rar from your enterprise application directory to the customerservice portlet directory. For example:

cp\bea70\weblogic700\samples\portal\sampleportalDomain\beaApps\ sampleportal\BlackBoxNoTx.rar\bea70\weblogic700\samples\portal\ sampleportalDomain\beaApps\sampleportal\sampleportal\portlets\ customerservice

Procedure for Each Enterprise Application

For each enterprise application to be upgraded for the new domain, follow these steps:

Copy the enterprise application directory from the existing WebLogic Portal 7.0 domain to the WebLogic Portal 8.1 Compatibility Domain.

Delete the following objects:

/Datasync subdirectory
/tools subdirectory
/toolSupport subdirectory
All BEA-provided enterprise-level .jar files, .war files, .ear files, and .rar files for the enterprise application (i.e., those files in the enterprise application directory). For example, if you were upgrading sampleportal, you would delete all .jar, .war, and .rar files from the <8.1 domain>\applications\sampleportal directory. Remove *only* BEA-provided files.

Create Enterprise Application Directory with the following hierarchy:
<ENT-APP dir name>\APP-INF\lib.

For example, if you were upgrading sampleportal you would create
<8.1 domain>\applications\sampleportal\APP-INF\lib.

Copy the following files from the <bea81>\weblogic81 directory to your new APP-INF\lib directory

portal\lib\commerce\ejb\commerce_util.jar
portal\lib\netuix\system\ext\ejb\dom4j-full.jar
portal\lib\netuix\ejb\netuix_util.jar
portal\lib\wps\ejb\wps_util.jar
portal\lib\portal\ejb\portal_util.jar

Copy the following objects into files from the <bea81>\weblogic81 directory to your <ENT-APP dir name> directory:

portal\lib\content.jar
portal\lib\content_repo.jar
portal\lib\tools700.war
portal\lib\toolSupport.war
portal\lib\wps-toolSupport.war
portal\lib\commerce\ejb\commerce.jar
portal\lib\netuix\ejb\netuix.jar
portal\lib\netuix\ejb\pipeline.jar
portal\lib\netuix\ejb\prefs.jar
portal\lib\portal\ejb\portal.jar
portal\lib\wps\ejb\wps.jar
p13n\lib\p13n_ejb.jar
p13n\lib\datasync.war

Make the following changes in the <ENT-APP>/<WEB-APP>/WEB-INF/lib for each of the web applications in your enterprise application:

delete the p13n_servlet.jar if it exists
replace ad_taglib.jar with weblogic81/portal/lib/wps/web/ad_taglib.jar
replace cm_taglib.jar with weblogic81/portal/lib/wps/web/cm_taglib.jar
replace ph_taglib.jar with weblogic81/portal/lib/wps/web/ph_taglib.jar
replace pz_taglib.jar with weblogic81/portal/lib/wps/web/pz_compat_taglib.jar and weblogic81/portal/lib/wps/web/pz_taglib.jar
replace p13n_servlet.jar with weblogic81/portal/lib/wps/web/wps_servlet.jar
replace webflow_servlet.jar with weblogic81/portal/lib/netuix/web/webflow_servlet.jar
replace webflow_taglib.jar with weblogic81/portal/lib/netuix/web/webflow_taglib.jar
add or replace cat_taglib.jar with weblogic81/portal/lib/commerce/web/cat_taglib.jar
add weblogic81/portal/lib/commerce/web/eb_taglib.jar
add/replace productTracking_taglib.jar with weblogic81/portal/lib/commerce/web/productTracking_taglib.jar
replace dam_taglib.jar with weblogic81/portal/lib/portal/web/dam_taglib.jar
replace ent_taglib.jar with weblogic81/portal/lib/portal/web/ent_taglib.jar
replace portal_servlet.jar with weblogic81/portal/lib/portal/web/portal_servlet.jar
replace portal_taglib.jar with weblogic81/portal/lib/portal/web/portal_taglib.jar
replace portlet_taglib.jar with weblogic81/portal/lib/portal/web/portlet_taglib.jar
replace ren_taglib.jar with weblogic81/portal/lib/portal/web/ren_taglib.jar
replace res_taglib.jar with weblogic81/portal/lib/portal/web/res_taglib.jar
replace util_taglib.jar with weblogic81/portal/lib/portal/web/util_taglib.jar
replace visitor_taglib.jar with weblogic81/portal/lib/portal/web/visitor_taglib.jar
replace vum_taglib.jar with weblogic81/portal/lib/portal/web/vum_taglib.jar
replace es_taglib.jar with weblogic81/p13n/lib/es_taglib.jar
replace i18n_taglib.jar with weblogic81/p13n/lib/i18n_taglib.jar
replace ps_taglib.jar with weblogic81/p13n/lib/ps_taglib.jar
replace tracking_taglib.jar with weblogic81/p13n/lib/tracking_taglib.jar
replace um_taglib.jar with weblogic81/p13n/lib/um_taglib.jar
replace weblogic-tags.jar with weblogic81/server/ext/weblogic-tags.jar
If you are upgrading sampleportal, replace xmlx-tags.jar (used by moreNews portlet) with weblogic81/samples/server/examples/build/examplesWebApp/WEB-INF/lib/xmlx-tags.jar

Make the following changes in the application.xml file in the <ENT-APP>/META-INF/ directory:

Replace <web-uri>tools</web-uri> with <web-uri>tools700.war</web-uri>
Replace <web-uri>datasync</web-uri> with <web-uri>datasync.war</web-uri>
Replace <web-uri>toolSupport</web-uri> with <web-uri>toolSupport.war</web-uri>

Note: Replace the <web-uri>, not the <context-root>.

Remove references to the following BEA-supplied ejb modules: (if present)

document.jar
ejbadvisor.jar
events.jar
mail.jar
pipeline.jar
placeholder.jar
property.jar
rules.jar
usermgmt.jar
catalogws.jar
customer.jar
ebusiness.jar
campaign.jar

Retain the following BEA-supplied ejb module listing: (if present)

portal.jar

Add the following ejb module references:

netuix.jar
pipeline.jar
prefs.jar
p13n_ejb.jar
wps.jar
content_repo.jar
content.jar
commerce.jar

Make the following changes in the application-config.xml file in the <ENT-APP>/META-INF/ directory:

If using commerce, replace any existing AttributeLoader reference with this one:

<AttributeLoader Name="AttributeLoader" RequestLoaders="com.bea.campaign.ShoppingCartAttributeLoader" />

Within the ApplicationConfiguration node, after the last DocumentConnectionPool entry, add the following entry:

Listing 2-7 DocumentConnectionPool Entry

<ContentManagement Name="ContentManagement"> 
<ContentStore Name="adapter" ClassName="com.bea.p13n.content.adapter.RepositoryImpl" 
Properties="CONTENT_MANAGER_HOME=${APPNAME}.BEA_personalization.DocumentManager" /> 
</ContentManagement> 
<CommercePipelineComponentSupport 
JdbcPoolName="weblogic.jdbc.jts.commercePool" />

Content Management Configuration

The SamplePortal application provided with WebLogic Portal 7.0 uses a custom Document Provider Interface (DPI) integration for content management. If the enterprise application you are upgrading also uses such an integration, this generally implies that you have one or more JSPs using code similar to that in Listing 2-8. If this is the case, take the steps in the section Step 1: Change the Content Management application-config.xml File.

Listing 2-8 Custom Content Management JSP Code

<pz:contentSelector ... contentHome="java:comp/env/ejb/NewsletterManager"  <-- NOTE this is not the standard value of "<%=ContentHelper.DEF_DOCUMENT_MANAGER_HOME%>" />

Step 1: Change the Content Management application-config.xml File

Make the following modifications to support this Content Management feature:

For each additional document provider, add a <ContentStore> section to the <ContentManagement> node. The <jndi-name> for the document provider can be found in weblogic-ejb-jar.xml. For sampleportal, the entry is as follows:

<jndi-name>${APPNAME}.BEA_portal_examples.NewsletterDocumentManager</jndi-name>

Set the CONTENT_MANAGER_HOME property of the <ContentStore> to be the JNDI name used to look up the documentprovider. For the sampleportal, the entry is as follows:

Properties="CONTENT_MANAGER_HOME=${APPNAME}.BEA_portal_examples.NewsletterDocumentManager"

For sampleportal, add this as a second <ContentManagement> element, as shown in Listing 2-9:

Listing 2-9 The second <ContentManagement> element for sampleportal

<ContentStore 
Name="newsletters" 
ClassName="com.bea.p13n.content.adapter.RepositoryImpl" 
Properties="CONTENT_MANAGER_HOME=${APPNAME}.BEA_portal_examples.NewsletterDocumentManager" />

Step 2: Edit the web.xml File

For each web application, make the following change to the web.xml file in the <ENT-APP>/<web-app>/WEB-INF/ directory:

Replace the code in Listing 2-10 with that in Listing 2-11.

Listing 2-10 pz_taglib.jar reference

<taglib> 
<taglib-uri>pz.tld</taglib-uri> 
<taglib-location>/WEB-INF/lib/pz_taglib.jar</taglib-location> 
</taglib>

Listing 2-11 pz_compat_taglib.jar reference

<taglib> 
<taglib-uri>pz.tld</taglib-uri> 
<taglib-location>/WEB-INF/lib/pz_compat_taglib.jar</taglib-location> 
</taglib>

Step 3: Edit the config.xml File

This section lists two modifications to the config.xml file; one for commerce support, the other for every enterprise application.

If the enterprise application uses commerce features, edit the config.xml file, inserting the following StartupClass section above any application listings, and setting the Target to the servername, as shown in Listing 2-12.

Listing 2-12 StartupClass Entry for Commerce Support

<StartupClass 
ClassName="com.beasys.commerce.ebusiness.security.KeyBootstrap" 
LoadBeforeAppActivation="true" 
FailureIsFatal="false" 
Name="Commerce KeyBootstrap" 
Targets="portalServer"/>

Add a reference to the enterprise application(s), complete with the correct path, Examples using sample applications that shipped with WebLogic Portal 7.0 are shown in Listing 2-13, Listing 2-14, Listing 2-15, and Listing 2-16.

Note: The following notes apply to Listing 2-13, Listing 2-14, Listing 2-15, and Listing 2-16:

References to the enterprise applications depend on the application itself. Consult the config.xml file in your existing WebLogic Portal 7.0 application, as well as the META-INF/application.xml file you modified above to get the correct values for your particular application.
If the application contains an EJB which is built during the application build, comment out the EJB deployment for now. For example, see the commented EJBComponent in Listing 2-13.
The portal.jar is only present for certain enterprise applications.
If the existing WebLogic Portal 7.0 application used commerce, then update the paymentWSApp and taxWSApp applications, setting the deployed="true".
Be sure to verify paths.

Listing 2-13 SAMPLEPORTAL config.xml File

<Application Deployed="true" Name="sampleportal" 
Path="D:\bea81\weblogic81\samples\portal\sampleportal" TwoPhase="true"> 
<ApplicationConfiguration Name="sampleportal" 
Targets="portalServer" URI="META-INF/application-config.xml"/> 
<ConnectorComponent Name="BlackBoxNoTx" Targets="portalServer" URI="BlackBoxNoTx.rar"/> 
<EJBComponent Name="commerce" Targets="portalServer" URI="commerce.jar"/> 
<EJBComponent Name="p13n_ejb" Targets="portalServer" URI="p13n_ejb.jar"/> 
<EJBComponent Name="portal" Targets="portalServer" URI="portal.jar"/> 
<!-- <EJBComponent Name="sampleportal" Targets="portalServer" URI="sampleportal.jar"/>  --> 
<EJBComponent Name="wps" Targets="portalServer" URI="wps.jar"/> 
<EJBComponent Name="pipeline" Targets="portalServer" URI="pipeline.jar"/> 
<EJBComponent Name="portalmanager" Targets="portalServer" URI="netuix.jar"/> 
<EJBComponent Name="prefs" Targets="portalServer" URI="prefs.jar"/> 
<EJBComponent Name="content" Targets="portalServer" URI="content.jar"/> 
<EJBComponent Name="contentrepo" Targets="portalServer" URI="content_repo.jar"/> 
<WebAppComponent Name="datasync" ServletReloadCheckSecs="300"

Targets="portalServer" URI="datasync.war"/> 
<WebAppComponent Name="defaultWebApp" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="defaultWebApp"/> 
<WebAppComponent Name="sampleportal" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="sampleportal"/> 
<WebAppComponent Name="toolSupport" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="toolSupport.war"/> 
<WebAppComponent Name="tools" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="tools700.war"/> 
</Application>
	<Application Deployed="true" Name="wlpDocsApp" 
Path="D:\bea81\weblogic81\portal\lib" 
StagedTargets="portalServer" TwoPhase="true"> 
<WebAppComponent IndexDirectoryEnabled="false" Name="wlpDocs" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="wlpDocs.war"/> 
</Application>

Listing 2-14 P13NApp config.xml File

<Application Deployed="true" Name="p13nApp" 
Path="D:\gibi12\weblogic81\samples\portal\p13nApp" TwoPhase="true"> 
<ApplicationConfiguration Name="p13nApp" Targets="portalServer" URI="META-INF/application-config.xml"/> 
<EJBComponent Name="commerce" Targets="portalServer" URI="commerce.jar"/> 
<EJBComponent Name="p13n_ejb" Targets="portalServer" URI="p13n_ejb.jar"/> 
<EJBComponent Name="wps" Targets="portalServer" URI="wps.jar"/> 
<EJBComponent Name="pipeline" Targets="portalServer" URI="pipeline.jar"/> 
<EJBComponent Name="portalmanager" Targets="portalServer" URI="netuix.jar"/> 
<EJBComponent Name="prefs" Targets="portalServer" URI="prefs.jar"/> 
<EJBComponent Name="content" Targets="portalServer" URI="content.jar"/> 
<EJBComponent Name="contentrepo" Targets="portalServer" URI="content_repo.jar"/> 
<WebAppComponent Name="datasync" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="datasync.war"/> 
<WebAppComponent Name="defaultWebApp" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="defaultWebApp"/> 
<WebAppComponent Name="p13n" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="p13n"/> 
<WebAppComponent Name="toolSupport" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="toolSupport.war"/> 
<WebAppComponent Name="tools" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="tools700.war"/> 
</Application> 
<Application Deployed="true" Name="wlpDocsApp" 
Path="D:\gibi12\weblogic81\portal\lib" 
StagedTargets="portalServer" TwoPhase="true"> 
<WebAppComponent IndexDirectoryEnabled="false" Name="wlpDocs" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="wlpDocs.war"/> 
</Application>

Listing 2-15 WLCSApp config.xml File

<Application Deployed="true" Name="wlcsApp" 
Path="D:\gibi12\weblogic81\samples\portal\wlcsApp" TwoPhase="true"> 
<ApplicationConfiguration Name="wlcsApp" Targets="portalServer" URI="META-INF/application-config.xml"/> 
<EJBComponent Name="commerce" Targets="portalServer" URI="commerce.jar"/> 
<EJBComponent Name="p13n_ejb" Targets="portalServer" URI="p13n_ejb.jar"/> 
<!-- <EJBComponent Name="wlcsSample" Targets="portalServer" URI="wlcsSample.jar"/> --> 
<EJBComponent Name="wps" Targets="portalServer" URI="wps.jar"/> 
<EJBComponent Name="pipeline" Targets="portalServer" URI="pipeline.jar"/> 
<EJBComponent Name="portalmanager" Targets="portalServer" URI="netuix.jar"/> 
<EJBComponent Name="prefs" Targets="portalServer" URI="prefs.jar"/> 
<EJBComponent Name="content" Targets="portalServer" URI="content.jar"/> 
<EJBComponent Name="contentrepo" Targets="portalServer" URI="content_repo.jar"/> 
<WebAppComponent Name="datasync" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="datasync.war"/> 
<WebAppComponent Name="defaultWebApp" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="defaultWebApp"/> 
<WebAppComponent Name="wlcs" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="wlcs"/> 
<WebAppComponent Name="toolSupport" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="toolSupport.war"/> 
<WebAppComponent Name="tools" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="tools700.war"/> </Application> 
<Application Deployed="true" Name="wlpDocsApp" 
Path="D:\gibi12\weblogic81\portal\lib" 
StagedTargets="portalServer" TwoPhase="true"> 
<WebAppComponent IndexDirectoryEnabled="false" Name="wlpDocs" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="wlpDocs.war"/> 
</Application>

Listing 2-16 StockPortal config.xml File

<Application Deployed="true" Name="stockportal" 
Path="D:\gibi15\weblogic81\samples\portal\portal" TwoPhase="true"> 
<ApplicationConfiguration Name="portal" Targets="portalServer" URI="META-INF/application-config.xml"/> 
<EJBComponent Name="commerce" Targets="portalServer" URI="commerce.jar"/> 
<EJBComponent Name="p13n_ejb" Targets="portalServer" URI="p13n_ejb.jar"/> 
<!--        <EJBComponent Name="stockportal" Targets="portalServer" URI="stockportal.jar"/> --> 
<EJBComponent Name="portal" Targets="portalServer" URI="portal.jar"/> 
<EJBComponent Name="wps" Targets="portalServer" URI="wps.jar"/> 
<EJBComponent Name="pipeline" Targets="portalServer" URI="pipeline.jar"/> 
<EJBComponent Name="portalmanager" Targets="portalServer" URI="netuix.jar"/> 
<EJBComponent Name="prefs" Targets="portalServer" URI="prefs.jar"/> 
<EJBComponent Name="content" Targets="portalServer" URI="content.jar"/> 
<EJBComponent Name="contentrepo" Targets="portalServer" URI="content_repo.jar"/> 
<WebAppComponent Name="datasync" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="datasync.war"/> 
<WebAppComponent Name="defaultWebApp" 
ServletReloadCheckSecs="300" Targets="portalServer" URI="defaultWebApp"/> 
<WebAppComponent Name="stockportal" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="stockportal"/> 
<WebAppComponent Name="toolSupport" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="toolSupport.war"/> 
<WebAppComponent Name="tools" ServletReloadCheckSecs="300" 
Targets="portalServer" URI="tools700.war"/> 
<WebAppComponent Name="workshop" ServletReloadCheckSecs="0" 
Targets="portalServer" URI="workshop"/> 
</Application>

Modify Code

Search the code from the existing WebLogic Portal 7.0 application for calls to the following class:

com.bea.p13n.util.jdbc.SequencerFactory createSequencer( String, DataSource) method. Any calls to this method must be updated as follows:

Replace the code in Listing 2-17 with that in Listing 2-18.

Listing 2-17 A Call to createSequencer Class: Before

sequencer = SequencerFactory.createSequencer("ORDER_LINE_ID_SEQUENCE", getDataSource());

Listing 2-18 A Call to createSequencer Class: After

sequencer = SequencerFactory.createSequencer( "ORDER_LINE_ID_SEQUENCE" );

Note: Exceptions are different, so you may also need to update any enclosing try/catch blocks.

Step 1: Upgrade Web Service Client Proxies

Find all web service proxy (client) code used by the enterprise application or by the Web application. Usually there is a .wsdl file, a *Codec.java or *_Stub.java.

Delete the Web service proxy code such as:

*Codec.java
*_Stub.java
*_Impl.java
*ServicePort.java
*Request.java
*RequestElement.java
*Response.java
*ResponseElement.java
*Service.java

This section uses concrete examples of steps taken to make the WLCSApp compliant with the new framework.

Delete the following files in the src/examples/wlcs/sampleapp/payment directory:

ArrayOfResponseElementCodec.java
PaymentService.java
PaymentService.xml
PaymentService_Impl.java
PaymentServicePort.java
PaymentServicePort_Stub.java
PSRequest.java
PSRequestCodec.java
PSResponse.java
PSResponseCodec.java
PSResponseElement.java
PSResponseElementCodec.java

Delete the following file in the src/language_builtins/lang directory:

ArrayOfStringCodec.java

Delete the following files in the src/examples/wlcs/sampleapp/tax directory:

ArrayOfAVSResponseElementCodec.java
ArrayOfTaxRequestElementCodec.java
ArrayOfTaxResponseElementCodec.java
AVSRequest.java
AVSRequestCodec.java
AVSResponse.java
AVSResponseCodec.java
AVSResponseElement.java
AVSResponseElementCodec.java
TaxRequest.java
TaxRequestCodec.java
TaxRequestElement.java
TaxRequestElementCodec.java
TaxResponse.java
TaxResponseCodec.java
TaxResponseElement.java
TaxResponseElementCodec.java
TaxService.java
TaxService.xml
TaxService_Impl.java
TaxServicePort.java
TaxServicePort_Stub.java

Make a backup of the source tree.
Start WebLogic server.

Step 2: Change Web Service Proxies

If you modified the web service proxies in the WebLogic Portal 7.0 domain, you need to do the same modifications in the new domain. In any case, the files will need to be re-generated because the generated proxy jar file code has changed.

Note: The proxy code needs to be in a separate jar in the APP-INF/lib directory to work at runtime. It will not work if we simply compile it and stick it in wlcsSample.jar. Therefore, a proxy jar file must be generated, then any changed proxy files must be manually replaced.

Here is an example of a target which generates proxy jar files -- add an entry such as Listing 2-19 to your build file.

Listing 2-19 Web Service Proxy Rewrite Entry

<target name="stubgen" > 
<property name="taxWsdlUrl"  
value="http://localhost:7501/taxws/TaxService?WSDL" /> 
<property name="payWsdlUrl"  
value="http://localhost:7501/payws/PaymentService?WSDL" /> 
<clientgen wsdl="${taxWsdlUrl}" packageName="examples.wlcs.sampleapp.tax" 
clientJar="taxwsproxy.jar" /> 
<clientgen wsdl="${payWsdlUrl}" packageName="examples.wlcs.sampleapp.payment" 
clientJar="paywsproxy.jar" /> 
</target>

Upgrade Application-Synch Files

Follow the 'upgrade application-sync' steps in the Upgrade Application-Sync Files section.

Final Adjustments to the Domain

This set of steps requires at least one enterprise application to be upgraded and deployed, since it requires the WebLogic 7.0 Portal Administration Tools.

Add Users to PortalSystemAdministrators Group

Add all members of the WebLogic 7.0 Portal SystemAdministrator group to the PortalSystemAdministrators group.

This procedure is explained using sampleportal.

Launch the server in your 8.1 compatibility domain.

Open Weblogic Portal Administration Tools at http://localhost:7501/sampleportalTools and login as weblogic/weblogic, or whatever system userid and password you used to create the 8.1 compatibility domain.

In User Management, under Groups, select PortalSystemAdministrators

Select the users in the WebLogic Portal 7.0 SystemAdministrator group, and add them to PortalSystemAdministrators.

Log into the WebLogic Server Console, go to Security -> Realms -> myRealm -> Global Roles, and click on "Configure a new Global role".

administrator
demosa1
demosa2

Save the changes and shut down the server.

Upgrade CustomerRole in SSPI to point to RDBMS groups.

If the existing WebLogic 7.0 domain contained an application that uses commerce, the CustomerRole security role must be associated with the wlcs_customer RDBMS group. This modification is necessary because normally the CustomerRole security role is associated with the wlcs_customer LDIFT group, and therefore won't perform correctly with members of the wlcs_customer RDBMS group.

Note: To perform this configuration, the assignment must be removed from the default LDIFT files. This means that if you delete the server directory (which includes LDAP information), you will need to do these steps again.

To associate the CustomerRole security role with the wlcs_customer RDBMS group, take the following steps:

Edit the compatibility domain's DefaultRoleMapperInit.ldift file, deleting the following section:

dn: cn=::CustomerRole,ou=ERole,ou=@realm@,dc=@domain@

objectclass: top

objectclass: ERole

cn: ::CustomerRole

EExpr:: Z3dsY3NfY3VzdG9tZXIK

Edit the compatibility domain's security.xml file, deleting the following sections:

Listing 2-20 ns1:group Entry

<ns1:group name="wlcs_customer">
<ns1:roleMemberOf ref="CustomerRole"/> 
</ns1:group>

Listing 2-21 ns1:role Entry

<ns1:role name="CustomerRole" description="View/modify the wlcs customer settings"/>

Delete the portalServer directory inside the compatibility domain. This directory is named <yourEnterpriseApplicationName>Server.

Start the WebLogic Portal Server

Log into the WebLogic Server console, and click Configure a new global role.

Name the new role CompatibilityCustomerRole, and click Apply.

From the Conditions tab, select Caller is a member of the group and click Add.

Enter group name wlcs_customer and click Add, OK, then Apply.

Shutdown the server

Users and Groups Specified in fileRealm.properties

Any system-level users and groups which under 7x were specified in fileRealm.properties must be added to the authentication provider used by WebLogic Portal 8.1.

Unlike WebLogic Portal 7.0, which allowed users and groups to be stored in both fileRealm (where system users and groups were stored) and the main store (where typical users and groups were stored), WebLogic Portal 8.1 works with users and groups in the single authentication provider.

Therefore, if you want to support system users and groups (weblogic, Operators, Monitors, etc) in the portal, you will need to move these users over to the authentication provider. This applies to any system users or groups in the fileRealm that you wish to provide portal access and portal tool access in the new Portal Compatibility Domain.

Note: This step is not needed for sampleportal, wlcsApp, p13nApp, or stockportal.