Skip navigation.

eDocs Home > BEA WebLogic Portal 8.1 Documentation > Upgrade Guide > Upgrading to Service Pack 4

Upgrade Guide

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Upgrading to Service Pack 4

This section provides instructions for applying Service Pack 4 (SP4) changes to your portal applications after you install that service pack. For instructions on installing service packs, see "Installing Service Packs and Rolling Patches" at:

http://download.oracle.com/docs/cd/E13196_01/platform/docs81/install/update.html

This section contains information on the following subjects:

For detailed information on the changes made for SP4, see the following sections:

 

The Service Pack Upgrade Process

Regardless of the release—8.1 or 8.1 with a previous service pack—from which you are upgrading, you follow the same basic process to complete the upgrade.

  1. Upgrade an existing SP2 or SP3 domain, or create a new SP4 domain.
  2. Upgrade existing database schema.
  3. Upgrade existing applications.
  4. Redeploy upgraded application to your production environment.
  5. Perform manual upgrade tasks to enable SP4 enhancements.

The following sections describe these steps.

 

Step 1: Upgrade an Existing SP2 or SP3 Domain or Create A New SP4 Domain

You must choose one of the following upgrade paths:

Upgrading an Existing SP2 or SP3 domain

If you choose to upgrade your existing SP2 or SP3 domain to use the new SP4 libraries, upgrade instructions vary according to the method you used to install SP4. The following sections explain your options and the required manual update steps.

WebLogic Portal Upgrade Installer

If you used the WebLogic Portal SP4 upgrade installer to update your existing SP2 or SP3 install, then you do not need to make any changes to your SP2 or SP3 domain. All scripts should pick up the appropriate new libraries for the SP4 environment.

Continue to Step 2: Upgrade Existing Database Schema on page 6-6.

Update Paths to JDK as Needed

The upgrade installer cannot update paths to the JDK because it can reside in a unique location. To update paths to point to the new JDK for SP4, edit the variables in the scripts shown in
Table 6 -4:

Table 6 -4 Variables/Scripts Containing Path

Variable

Script

JDK_HOME
BEAHOME
WEBLOGIC_HOME
PORTAL_HOME
POINTBASE_HOME

set-dbenv

JAVA_HOME
BEA_JAVA_HOME
SUN_JAVA_HOME
JDK_HOME

setDomainEnv


 

Edit URL Template File for Use with WSRP

The url-template-config.xml file, which is automatically created in a portal Web project, contains URL templates and variables for WSRP portlets. You must make the following two changes in this file for each WSRP URL template, so that the BEA-provided consumer will be able to honor mode changes and state changes from non-BEA producers:

In addition, the producer should use the wsrp: prefix for standard modes and window states in URLs, so that non-BEA consumers can recognize URLs returned by BEA-provided producers.

WebLogic Portal Full Installer

If you used the full installer and you installed SP4 in a separate directory, then you must manually update scripts in your SP2 or SP3 domain.

Update setDomainEnv

In the script setDomainEnv, update the following variables as needed:

JAVA_HOME
BEA_JAVA_HOME
SUN_JAVA_HOME
WL_HOME

Note: The file setDomainEnv contains the DOMAIN_NAME variable. Do not change the value of this variable if you are upgrading an existing domain to SP4.

Update Path to JDK as Needed

You might need to update the path to point to the new JDK for SP4. The variables and their corresponding scripts are shown in Table 6 -5:

Table 6 -5 Variables/Scripts Containing Path

Variable

Script/File

JDK_HOME
JDK_TOOLS

set-dbenv

JAVA_HOME
BEA_JAVA_HOME
SUN_JAVA_HOME
JAVA_VENDOR
JDK_HOME

setDomainEnv


 

Review and Update Other Scripts and Variables as Needed

The following table lists other variables and files that may or may not need updating, depending on which scripts you use in your environment; however, BEA recommends that you review the files in your existing domain directory to verify that you have made all needed changes.

Table 6 -6

Variable

Script/File

Notes

BEAHOME
WL_HOME
JAVA_HOME
BEA_JAVA_HOME
SUN_JAVA_HOME
JDK_HOME
POINTBASE_HOME

webappCompile
startPointBaseConsole
startWebLogic1
stopManagedWebLogic
stopWebLogic

1The file startWebLogic contains the DOMAIN_NAME variable. Do not change the value of this variable if you are upgrading an existing domain to SP4.

wlsHome.path
jdkHome.path

workshop.properties



 

Add Module Information to Database Properties File

If you are planning to reinitialize your database using the create_db.cmd/.sh script, you must manually update the db_settings.properties file, in the domain that you are upgrading, to add new module information. Later you will update the db_settings.properties file with database-specific information.

Navigate to the file db_settings.properties in the domain that you are upgrading and edit the module settings for SP4, as the following example shows. The portal module cmv and netuix module wsrp were added for SP3; the p13n module er is new in SP4. For more information on these new modules, see Database Changes for SP3 on page D-1 and Database Changes for SP4 on page C-1.

The corresponding lines of the properties file should appear like this:

p13n_modules=p13n ds au bt er
portal_modules=cm cmv wlcs wps sample_cm collaboration netuix_modules=pf wsrp

Update set-dbenv if You Plan to Run create_db

If you use the script create_db, update these variables in the script set-dbenv:

BEA_HOME
PORTAL_HOME
JDK_HOME
JDK_TOOLS
WEBLOGIC_HOME

Back Up LDAP Data

In Service Pack 4, policy reference data is stored in the RDBMS rather than in LDAP. When you access the Administration Portal for the first time in an upgraded domain, an automatic migration of this policy reference data occurs.

Back up your LDAP data prior to continuing with the upgrade process. You can make a backup by simply copying the portal_domain\portalServer\ldap directory.

Creating a New SP4 Domain

To create a new SP4 domain that mirrors your existing SP2 or SP3 domain, follow these steps:

  1. Use the Configuration Wizard.

    2. See "Creating a New WebLogic Domain" at: http://download.oracle.com/docs/cd/E13196_01/platform/docs81/confgwiz/newdom.html.

  2. Copy the LDAP information from your SP2 or SP3 domain to the new SP4 domain. LDAP information is located in the path: portal_domain\portalServer\ldap.

 

Step 2: Upgrade Existing Database Schema

Warning: If you are upgrading from an SP2 database to an SP4 database, you must first follow the steps to upgrade your database from SP2 to SP3 as described in Step 2: Upgrade Existing Database Schema on page 5-5. After following those steps, you can then follow the steps in this chapter to upgrade your database to SP4.

Scripts for upgrading an SP3 database to SP4 are located in SP4_WL_HOME\portal\upgrade\SP4 where SP4_WL_HOME is the WL_HOME directory for SP4.

For databases other than PointBase, in order to use the provided WebLogic Portal upgrade scripts, database client software must be installed and configured on the machine from which you execute the upgrade scripts.

Complete the steps in the following sections, as appropriate depending on your database type, to make your WebLogic Platform 8.1 SP3 database schema 8.1 SP4-compliant.

Upgrading a PointBase Database

  1. Shut down the WebLogic Server if it is running. The WebLogic Server must be shut down while performing the database schema upgrade steps.
  2. Back up your existing database using a method prescribed by PointBase. Ensure that the database backup you create is valid for restore purposes if you encounter a failure during the database upgrade process.
  3. Copy the workshop.dbn, workshop$1.wal, and pointbase.ini Pointbase database files from your source domain to SP4_WL_HOME\portal\upgrade\SP4.
  4. Make the following change to the SP4_WL_HOME\portal\upgrade\SP4\db_settings.properties file:
  5. Run the upgrade_db_schema_to_81SP4.cmd or .sh script to upgrade your database schema.
  6. To verify that the upgrade was successful, inspect the upgrade_db_schema_to_81SP4.log file. You can find the scripts and log file in SP4_WL_HOME\portal\upgrade\SP4.

    7. The following errors will appear in the .log file and can be ignored:

    SQL> create user weblogic password weblogic;
    SQL>
    SQL> Error Message: You must have DBA-level authority to perform this operation.
    SQL> Error SQLState: 2D086
    SQL> Error Code: 15088
    SQL>
    SQL>
    create schema weblogic authorization weblogic
    SQL>
    SQL> Error Message: Schema WEBLOGIC already exists in the database.
    SQL> Error SQLState: 2201F
    SQL> Error Code: 25228
    SQL>
    SQL> --

  7. Copy the workshop.dbn, workshop$1.wal, and pointbase.ini files from SP4_WL_HOME\portal\upgrade\SP4 to your SP4 domain, as appropriate.

    8. Note: This step is applicable whether you are using an upgraded domain or a new domain.

The database is now upgraded. Back up the upgraded database before upgrading existing applications.

Upgrading a Sybase Database

  1. Shut down the WebLogic Server if it is running. The WebLogic Server must be shut down while performing the database schema upgrade steps.
  2. Back up your existing database using a method prescribed by Sybase. Ensure that the database backup you create is valid for restore purposes if you encounter a failure during the database upgrade process.
  3. Set the "Allow Select Into/Bulkcopy" database parameter to true for your WEBLOGIC Portal database; see Listing 6-1 for an example:

Listing 6-1 Setting Allow Select Into/Bulkcopy Option in Sybase

use master
go
sp_dboption WEBLOGIC,"select into/bulkcopy",true
go
use WEBLOGIC
go
checkpoint
go
  1. Add a WEBLOGIC_INDEX SEGMENT to your WEBLOGIC Portal database for placement of non-clustered indexes in their own segment; see Listing 6-2 for an example:

Listing 6-2 Adding a WEBLOGIC_INDEX SEGMENT for Sybase

declare @vdevno int 
select @vdevno = max(convert(tinyint, substring(convert(binary(4),d.low), v.low,1))) + 1 
from master.dbo.sysdevices d, master.dbo.spt_values v 
where v.type = 'E' and v.number = 3
disk init name='WEBLOGIC_INDEX',
physname='F:\INDEXFILE\WEBLOGIC_INDEX1.DAT', 
vdevno = @vdevno ,
size=15360
go
alter database WEBLOGIC ON WEBLOGIC_INDEX = 30
go
exec sp_addsegment 'WEBLOGIC_INDEX', 'WEBLOGIC','WEBLOGIC_INDEX'
go
exec sp_dropsegment 'logsegment', 'WEBLOGIC','WEBLOGIC_INDEX'
go

Note: You can use the sp_estspace stored procedure to determine the size necessary for WEBLOGIC_INDEX.

  1. Make the following changes to the SP4_WL_HOME\portal\upgrade\SP4\db_settings.properties file:
  2. Navigate to SP4_WL_HOME\portal\upgrade\SP4 and run the upgrade_db_schema_to_81SP4.cmd or .sh script to upgrade your database schema to SP4, as appropriate. To verify that the upgrade was successful, inspect the upgrade_db_schema_to_81SP4.log file. You can find the scripts and log file in SP4_WL_HOME\portal\upgrade\SP4.

    3. The database is now upgraded. Back up the upgraded database before upgrading existing applications.

  3. Reset the "Allow Select Into/Bulkcopy" database parameter to false for the WEBLOGIC Portal database, as shown in Listing 6-3.

Listing 6-3 Resetting "Allow Select into/Bulkcopy" Option in Sybase

use master
go
sp_dboption WEBLOGIC,"select into/bulkcopy",false
go
use WEBLOGIC
go
checkpoint
go

Upgrading a SQL Server Database

  1. Shut down the WebLogic Server if it is running. The WebLogic Server must be shut down while performing the database schema upgrade steps.
  2. Back up your existing database using a method prescribed by SQL Server. Ensure that the database backup you create is valid for restore purposes if you encounter a failure during the database upgrade process.
  3. Add the WEBLOGIC_INDEX file group to your WEBLOGIC Portal database for placement of non-clustered indexes in their own file group; see Listing 6-4 for an example:

Listing 6-4 Adding the WEBLOGIC_INDEX file group for SQL Server 

use WEBLOGIC
go
ALTER DATABASE WEBLOGIC ADD FILEGROUP [WEBLOGIC_INDEX] 
GO
ALTER DATABASE WEBLOGIC ADD FILE(NAME = N'WEBLOGIC_INDEX', FILENAME = N'F:\INDEXFILE\WEBLOGIC_INDEX.NDF' , SIZE = 60, FILEGROWTH = 10%) TO FILEGROUP [WEBLOGIC_INDEX]
GO
  1. Make the following changes to the SP4_WL_HOME\portal\upgrade\SP4\db_settings.properties file:
  2. Navigate to SP4_WL_HOME\portal\upgrade\SP4 and run the upgrade_db_schema_to_81SP4.cmd or .sh script to upgrade your database schema. To verify that the upgrade was successful, inspect the upgrade_db_schema_to_81SP4.log file. You can find the scripts and log file in SP4_WL_HOME\portal\upgrade\SP4.

    3. The database is now upgraded. Back up the upgraded database before upgrading existing applications.

Upgrading an Oracle or DB2 Database

  1. Shut down the WebLogic Server if it is running. The WebLogic Server must be shut down while performing the database schema upgrade steps.
  2. Back up your existing database using a method prescribed by your database vendor. Ensure that the database backup you create is valid for restore purposes if you encounter a failure during the database upgrade process.
  3. Make the following changes to the SP4_WL_HOME\portal\upgrade\SP4\db_settings.properties file:
  4. For DB2 only. If you are not already using the DB2 command line processor (CLP) for this process, activate it now. You must run the upgrade script from the CLP.
  5. Navigate to SP4_WL_HOME\portal\upgrade\SP4 and run the upgrade_db_schema_to_81SP4.cmd or .sh script to upgrade your database schema. To verify that the upgrade was successful, inspect the upgrade_db_schema_to_81SP4.log file. You can find the scripts and log file in SP4_WL_HOME\portal\upgrade\SP4.

    6. The database is now upgraded. Back up the upgraded database before upgrading existing applications.

 

Step 3: Upgrade Existing Applications

When you upgrade from SP3 to SP4, you must change the following configurations for your application:

Re-Configure Third-Party Content Management Systems

If you are using a third-party content management system, you'll need to re-configure that repository before deploying. This allows the passwords to be re-encrypted for the new domain. If you are not switching domains when upgrading, you may skip this task.

First, remove the existing repository connection, using the Portal Administration Tools:

  1. View the Repository List tree by selecting Repository from the View drop-down list.
  2. In the Manage Repositories tree, right-click the repository you want to remove.
  3. Select Remove from the pop-up menu.

    4. Note: Be sure to write down all the configuration information you will need to re-enter.

  4. A pop-up window displays confirming that you want to remove the repository. If you want to proceed, click OK.

Then, re-connect to the repository.

  1. View the Repository List tree by selecting Repository from the View drop-down list.
  2. In the Manage Repositories tree, right click the Virtual Content Repository.
  3. Select Add Repository from the pop-up menu.
  4. In the Editor pane, provide the connection information
  5. In the Cache Properties box, edit the cache properties, if necessary. You can also choose to accept the default cache settings.
  6. Click Create.

Re-Encrypting Passwords for WSRP Producers

If you are moving to a new domain when upgrading, you'll need to re-encrypt any passwords that are used to access WSRP portlets. Encryption is domain-specific so it needs to be updated when switching domains.

If you are deploying your application as an EAR file, this needs to be done manually with the EncryptDomainString command-line utility which is used to generate an encrypted password and then place that encrypted password into the application-config.xml file before you deploy your application. The application must already exist in the new domain.

Note: If you are going to deploy an exploded application (not an EAR), you can use the Service Administration tool in Portal Administration Portal to re-set passwords. When passwords are re-entered using the Service Administration tool, they are automatically encrypted. However, the Portal Administration Tool cannot be used if you have already compressed your application to an EAR file.

A portal application's META-INF directory contains the respective application-config.xml. file where WSRP passwords are stored automatically. For example, Listing 6-5 shows the WSRP element from application-config.xml during the development phase (exploded) before deployment as an EAR file:

Listing 6-5 Development Phase Clear Text Passwords in application-config.xml

<ConsumerSecurity AdminPassword="weblogic" AdminUserName="weblogic"
   CertAlias="wsrpConsumer" CertPrivateKeyPassword="wsrppassword"
   ConsumerName="wsrpConsumer"
   IdentityAssertionProviderClass="com.bea.wsrp.security.
      DefaultIdentityAssertionProvider"
   Keystore="wsrpKeystore.jks" KeystorePassword="password"
   Name="ConsumerSecurity"/>

After the Service Administration tool is used to edit attributes, the file is saved and automatically passwords are encrypted, as shown in Listing 6-6:

Listing 6-6 .Encrypted Passwords in application-config.xml

<ConsumerSecurity AdminPassword="{3DES}3QrrUeIwN/DxlDI++1ixPw=="
   AdminUserName="weblogicc" CertAlias="wsrpConsumer"
   CertPrivateKeyPassword="{3DES}g7h+VOSAsO9pSlvYSSB2iw=="
   ConsumerName="wsrpConsumer"
   IdentityAssertionProviderClass="com.bea.wsrp.security.
      DefaultIdentityAssertionProvider"
   Keystore="wsrpKeystore.jks" KeystorePassword=
      "{3DES}1OLYVirMWOo+3sEU80cMqw=="
   Name="ConsumerSecurity" />

Encrypting Passwords

When upgrading applications that are stored as EAR files, you must manually update the encryption.

To encrypt passwords, use this procedure:

  1. Open a command box (DOS shell) and navigate to domain/portal/ (where domain is the domain directory for the application) and run setDomainEnv.cmd.
  2. At the prompt, enter 
    3. java com.bea.p13n.util.EncryptDomainString -targetDomainDir d -inputString s

    where:

    For example:

    java com.bea.p13n.util.EncryptDomainString -targetDomainDir \bea\weblogic81b\samples\domain\portal -inputString weblogic

    In this example, the input string weblogic represents administrator's password (adminpassword=weblogic; see Listing 6-7). The command line utility prints a domain specific encrypted string.

  3. Open WebLogic Workshop and the specific portal application.
  4. Select File>Open>File (Figure 6-1).

    5. Figure 6-1 Opening a File in WebLogic Workshop


     

    An Open dialog box appears.

  5. Navigate to the application's META-INF folder and open application-config.xml.

Listing 6-7 Clear text Passwords in application-config.xml

<ConsumerSecurity AdminPassword="weblogic" AdminUserName="weblogic"
   CertAlias="wsrpConsumer" CertPrivateKeyPassword="wsrppassword"
   ConsumerName="wsrpConsumer"
   IdentityAssertionProviderClass="com.bea.wsrp.security.
      DefaultIdentityAssertionProvider"
   Keystore="wsrpKeystore.jks" KeystorePassword="password"
   Name="ConsumerSecurity"/>
  1. Replace the previously encrypted passwords with those generated by the EncryptDomainString utility, as shown in Figure 6-8. You will need to run EncryptDomainString for each password in the <ConsumerSecurity>(Listing 6-7) element; for example:

Listing 6-8 Encrypted Passwords Generated by EncryptDomainString Utility 

<ConsumerSecurity AdminPassword="{3DES}3QrrUeIwN/DxlDI++1ixPw=="
   AdminUserName="weblogicc" CertAlias="wsrpConsumer"
   CertPrivateKeyPassword="{3DES}g7h+VOSAsO9pSlvYSSB2iw=="
   ConsumerName="wsrpConsumer"
   IdentityAssertionProviderClass="com.bea.wsrp.security.
      DefaultIdentityAssertionProvider"
   Keystore="wsrpKeystore.jks" KeystorePassword=
      "{3DES}1OLYVirMWOo+3sEU80cMqw=="
   Name="ConsumerSecurity" />

Note on Changing Passwords

If you need to change an administrator's password for any reason, simply changing the password will result in having to rebuild and redeploy the EAR. This is time-consuming and counterproductive. Instead, you can work around this problem by doing the following:

  1. Create a special user in the target system for a WSRP administrator. See Create a New User for more information on creating a user.
  2. Make that user a member of the administrator group. See Add a User to a Group for more information on adding a member to a group.
  3. Insert the new logon information (username and password) into the application's application-config.xml file as described in Encrypting Passwords.

Updating Portal Libraries

After you install a new service pack that includes portal library updates, you must update the libraries in the applications you have developed. Updating overwrites the existing libraries.

Before You Begin - About UUP

If you have developed your own Unified User Profile (UUP) to access user profile properties stored in an external user store, you have most likely modified and re-created the p13n_ejb.jar file in your application root directory. Because p13n_ejb.jar is one of the files overwritten in the following procedure, you should back up your existing file. After the upgrade procedure, you must re-create the updated p13n_ejb.jar with your UUP implementation. For more information, see "Setting up Unified User Profiles" in the User Management Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/users/uup.html#999527.

Update the Portal Libraries

To update your application libraries, follow these steps:

  1. Locate and delete the .workshop directory from the application that you will be working with. Do this prior to starting WebLogic Workshop.
  2. Start WebLogic Workshop 8.1 SP4.
  3. If your WebLogic server is running, shut it down by choosing, in WebLogic Workshop, Tools—>WebLogic Server—>Stop WebLogic Server.
  4. In WebLogic Workshop SP4, open the portal application that you want to update; for example, navigate to the SP3 or SP2 Portal application.
  5. In the Application window, right-click the application directory and choose Install—> Update Portal Libraries.

    6. After the portal application libraries are updated, a window appears; continue to the next step.

  6. In the displayed window, select the Web projects whose libraries you want to update, and click OK.

    7. For each selected Web project, the following warning window appears:

    Opening a File in WebLogic Workshop


     

    Click Yes to continue with the update.

    If you choose not to update a Web project's libraries using the displayed window, you can update the Web project later by right-clicking the Web project directory in the Application window and choosing Install—>Update Portal Libraries.

  7. If your application uses Commerce or Pipeline components, right-click the application directory and choose Install—>Commerce Services and Install—>Pipeline Services.
  8. If your application uses Commerce or Webflow JSP tag libraries, right-click the Web project directory in the Application window and choose Install—>Commerce Taglibs and Install—>Webflow Taglibs.
  9. If you have hidden any Web applications in the WebLogic Workshop interface, those Web applications will not be updated. Either un-hide them and perform the update as described in the previous steps, or manually replace the updated libraries in the hidden Web application(s).

    10. To apply the service pack library updates to portal applications already deployed in production, redeploy those applications after you have updated them in WebLogic Workshop. See Step 4: Redeploy the Upgraded Application for deployment instructions.

  10. Update your Portal server settings if needed by selecting Tools—>WebLogic Server—>Server Properties and editing this information.
  11. If you developed your own Unified User Profile (UUP) by modifying p13n_ejb.jar in your application root directory, re-implement your UUP in the new p13n_ejb.jar file. See Before You Begin - About UUP.
  12. Rebuild the application by selecting Build—>Build Application.
  13. Restart the server in the upgraded domain.

 

Step 4: Redeploy the Upgraded Application

The final upgrade step is to redeploy the application on your server.

For deployment instructions, see "Deploying Portal Applications" at

http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/deploy/index.html.

 

Step 5: Review Functional Changes for SP4

Review the functional changes that are described in Functional Changes for SP4. If any manual upgrade tasks are required for your particular environment, perform those tasks as instructed.

 

Skip navigation bar  Back to Top Previous Next