Upgrade Guide

Upgrading to Service Pack 6

This section provides instructions for applying Service Pack 6 (SP6) 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 functional changes that might require you to perform manual tasks or configuration changes, see the following sections:

Functional Changes Affecting Your WebLogic Portal Environment

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.

Upgrade an existing SP4 or SP5 domain, or create a new SP6 domain.

Upgrade existing database data.

Note: No database schema changes are required for Service Pack 6; however, you must update the default markup in the database, using the provided script, to be SP6 compliant.

Upgrade existing applications.

Redeploy upgraded application to your production environment.

Perform manual upgrade tasks to enable SP6 enhancements, if applicable.

The following sections describe these steps.

Step 1: Upgrade an Existing SP4 or SP5 Domain or Create A New SP6 Domain

You must choose one of the following upgrade paths:

Upgrade your existing SP4 or SP5 domain to use the new SP6 libraries and database modules.

Typically you would use this upgrade path if you want to preserve a highly customized domain, including LDAP setup.

Create a new domain with the SP6 Configuration Wizard that mirrors your existing SP4 or SP5 domain.

Typically you would use this path if you are comfortable recreating your domain configuration, and you want to ensure that your domain is based on the latest domain template. If you are using this method, skip to Creating a New SP6 Domain on page 8-5.

Upgrading an Existing SP4 or SP5 Domain

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

WebLogic Portal Upgrade Installer

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

Continue to Step 2: Upgrade Existing Applications.

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 SP5, edit the variables in the scripts shown in
Table 8 -10:

Table 8 -10 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:

Replace _mode with wsrp-mode
Replace _state with wsrp-windowState

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 SP6 in a separate directory, then you must manually update scripts in your SP4 or SP5 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 SP6.

Update Path to JDK as Needed

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

Table 8 -11 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 8 -12 Other Variables and Files

Variable	Script/File	Notes
`BEAHOME WL_HOME JAVA_HOME BEA_JAVA_HOME SUN_JAVA_HOME JDK_HOME POINTBASE_HOME`	`webappCompile startPointBaseConsole startWebLogic1stopManagedWebLogic stopWebLogic`	`1`The file `startWebLogic` contains the `DOMAIN_NAME` variable. Do not change the value of this variable if you are upgrading an existing domain to SP6.
wlsHome.path jdkHome.path	workshop.properties

Creating a New SP6 Domain

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

Use the Configuration Wizard.

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

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

Step 2: Upgrade Existing Applications

When you upgrade from SP5 to SP6, you must change the following configurations for your application:

Re-configure your third-party content management system, if applicable.
Re-set the passwords for your WSRP portlets, if applicable
Update the portal libraries in any applications you developed. Updating overwrites the existing libraries.

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:

View the Repository List tree by selecting Repository from the View drop-down list.

In the Manage Repositories tree, right-click the repository you want to remove.

Select Remove from the pop-up menu.

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

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.

View the Repository List tree by selecting Repository from the View drop-down list.

In the Manage Repositories tree, right click the Virtual Content Repository.

Select Add Repository from the pop-up menu.

In the Editor pane, provide the connection information

In the Cache Properties box, edit the cache properties, if necessary. You can also choose to accept the default cache settings.

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 8-1 shows the WSRP element from application-config.xml during the development phase (exploded) before deployment as an EAR file:

Listing 8-1 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 passwords are automatically encrypted, as shown in Listing 8-2:

Listing 8-2 .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:

Open a command box (DOS shell) and navigate to domain/portal/ (where domain is the domain directory for the application) and run setDomainEnv.cmd.

At the prompt, enter

java com.bea.p13n.util.EncryptDomainString -targetDomainDir d -inputString s

where:

d is the domain directory to which the portal application is being deployed; for example,
s is the input password to encrypt

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 8-3). The command line utility prints a domain specific encrypted string.

Open WebLogic Workshop and the specific portal application.

Select File > Open > File (Figure 8-1).

Figure 8-1 Opening a File in WebLogic Workshop

Opening a File in WebLogic Workshop

An Open dialog box appears.

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

Listing 8-3 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"/>

Replace the previously encrypted passwords with those generated by the EncryptDomainString utility, as shown in Figure 8-4. You will need to run EncryptDomainString for each password in the <ConsumerSecurity>(Listing 8-3) element; for example:

AdminPassword="weblogic"
CertPrivateKeyPassword="wsrppassword"
KeystorePassword="password"

Listing 8-4 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:

Create a special user in the target system for a WSRP administrator. See Create a New User for more information on creating a user.

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.

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:

Locate and delete the .workshop directory from the application that you will be working with. Do this prior to starting WebLogic Workshop.

Start WebLogic Workshop 8.1 SP6.

If your WebLogic server is running, shut it down by choosing, in WebLogic Workshop, Tools—>WebLogic Server > Stop WebLogic Server.

In WebLogic Workshop SP6, open the portal application that you want to update; for example, navigate to the SP5 or SP4 Portal application.

In the Application window, right-click the application directory and choose Install > Update Portal Libraries.

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

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

For each selected Web project, the following warning window appears:
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.

If your application uses Commerce or Pipeline components, right-click the application directory and choose Install > Commerce Services and Install >—>Pipeline Services.

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.

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

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 3: Redeploy the Upgraded Application for deployment instructions.

Update your Portal server settings if needed by selecting Tools > WebLogic Server > Server Properties and editing this information.

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.

Rebuild the application by selecting Build > Build Application.

Restart the server in the upgraded domain.

Step 3: Redeploy the Upgraded Application

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

For deployment instructions, see the WebLogic Portal Production Operations Guide at

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

Step 4: Review Functional Changes for SP6

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