Upgrade Guide
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:
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.
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.
The following sections describe these steps.
You must choose one of the following upgrade paths:
Typically you would use this upgrade path if you want to preserve a highly customized domain, including LDAP setup.
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.
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.
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.
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:
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.
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.
In the script setDomainEnv
, update the following variables as needed:
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.
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:
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.
To create a new SP6 domain that mirrors your existing SP4 or SP5 domain, follow these steps:
See "Creating a New WebLogic Domain" at: http://download.oracle.com/docs/cd/E13196_01/platform/docs81/confgwiz/newdom.html.
When you upgrade from SP5 to SP6, you must change the following configurations for your application:
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:
Then, re-connect to the repository.
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" />
When upgrading applications that are stored as EAR files, you must manually update the encryption.
To encrypt passwords, use this procedure:
domain
/portal/
(where domain
is the domain directory for the application) and run setDomainEnv.cmd
.java com.bea.p13n.util.EncryptDomainString -targetDomainDir
d
-inputStrings
d
is the domain directory to which the portal application is being deployed; for example, s
is the input password to encryptjava 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.
Figure 8-1 Opening a File in WebLogic Workshop
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"/>
<ConsumerSecurity>(
Listing 8-3)
element; for example: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" />
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:
application-config.xml
file as described in Encrypting Passwords.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.
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.
To update your application libraries, follow these steps:
.workshop
directory from the application that you will be working with. Do this prior to starting WebLogic Workshop.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.
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.
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.
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.
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.