Upgrade Guide

Upgrading WebLogic Integration 8.5 to WebLogic Integration 8.5 SP5

This section provides information on upgrading to WebLogic Integration 8.5 Service Pack 5 (SP5).

 

---

Topics Included in this Section

Before You Begin

Lists important steps to complete before you begin the upgrade process.

Upgrading a WebLogic Integration 8.5 Installation to SP5

Summarizes your choices for upgrading to WebLogic Integration 8.5 SP5.

Upgrading a Domain from WebLogic Integration 8.5 to SP5

Gives the procedure for upgrading an existing domain based on WebLogic Integration 8.5 to WebLogic Integration 8.5 SP5.

Creating a New Domain and Deploying Existing Applications to It

Gives the procedure for creating a new domain based on the WebLogic Integration 8.5 SP5 installation, and deploying existing applications into that domain.

Before You Begin

Before you begin the procedures described in this section, be sure to do the following:

Make sure the WebLogic Integration and WebLogic Platform resources in your domains have been upgraded to WebLogic Integration 8.5. For more information, see Upgrading to WebLogic Integration 8.5.
Back up your applications, database schema, other application data, and domains.
If you plan to run the WebLogic Platform end2end example or WebLogic Integration sample applications after you upgrade to SP5, remove the following two subdirectories.

WL_HOME/samples/domains/end2end/wliconfig
WL_HOME/samples/domains/integration/wliconfig

These directories contain data that is not uninstalled and that may cause errors to be generated if you run these sample applications after upgrading.

Make sure you have Apache Ant 1.5 or later installed on your machine. For information about obtaining, installing, and using Apache Ant, visit the following Web site:

http://ant.apache.org/

Note that if you plan to install iWay Adapters for BEA WebLogic, the iWay Adapter installation program assumes that the WebLogic Integration installation directory is named weblogic81. If you are installing WebLogic Integration 8.5 SP5 into a directory not named weblogic81, you need to take additional steps to complete the installation of the iWay Adapters. For more information, see Installing the iWay Adapters for BEA WebLogic.
Shut down any running WebLogic Server instances.

Upgrading a WebLogic Integration 8.5 Installation to SP5

You can upgrade an installation of WebLogic Integration 8.5 to SP5 using one of the following ways:

• Performing a complete, new installation

Using this option, you create a new installation of WebLogic Integration 8.5 SP5 that is separate from the existing WebLogic Integration 8.5 installation. When installing WebLogic Integration 8.5 SP5 in this manner, you should install it in a separate BEA Home directory from the existing WebLogic Integration 8.5 installation. For this type of installation, you can use either the net installer or package installer of WebLogic Integration 8.5 SP5 for your operating system.

If you choose to install WebLogic Integration 8.5 SP5 in a new BEA Home directory, you can redeploy existing domains and applications in the new SP5 installation.

Installing WebLogic Integration 8.5 SP5 in a new BEA Home directory is recommended when you need to retain versions of your applications that are running on the earlier release of WebLogic Platform.

For information about installing WebLogic Integration 8.5 SP5 as a separate installation, see Installing WebLogic Integration at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/install/index.html

• Using Smart Update or the package upgrade installer

These tools allow you to install a service pack for the WebLogic Integration 8.5 software currently installed in an existing BEA Home directory. Installing a service pack does not replace an entire installation, but rather updates it with just the changes, additions, and bug fixes for it.

This method of upgrading an installation is recommended if you plan to upgrade all your applications to the latest service pack, and have no need to retain versions of those applications that are running on the previous release of WebLogic Integration 8.5.

For information about using Smart Update, see "Installing Service Packs and Rolling Patches" in Installing WebLogic Integration at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs85/install/index.html

Note: If you are upgrading a WebLogic Integration 8.5 installation on a HP-UX 11i on Itanium system, you must use the package upgrade installer instead of Smart Update. For more information, see the restriction described at the following URL in "Known Limitations" in the BEA WebLogic Platform Release Notes:

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

Upgrading a Domain from WebLogic Integration 8.5 to SP5

After you have upgraded the WebLogic Integration 8.5 software to SP5 using either of the methods described in Upgrading a WebLogic Integration 8.5 Installation to SP5, you can upgrade existing domains as explained in the following sections:

• When to Upgrade an Existing Domain
• Applications and Domains You Can Upgrade
• Upgrade Steps

When to Upgrade an Existing Domain

Using procedure described in this section, you upgrade the applications and database schema in an existing domain so that they point to the new WebLogic Integration 8.5 installation. This upgrade path is typically appropriate in the following situations:

• You have a complex, highly customized domain, and you prefer to retain those customizations rather than attempt to replicate them in a new domain.
• In some cases you might be able to avoid having to redeploy your existing applications, which would otherwise be required if you were to create a new domain for them.

Applications and Domains You Can Upgrade

You can upgrade applications and resources in any domain created by the Configuration Wizard that is based upon any of the following domain templates:

• WebLogic Server Examples Domain
• Avitek Medical Records Sample Domain
• Basic WebLogic Platform Domain
• Basic WebLogic Integration Domain
• Basic WebLogic Portal Domain
• Basic WebLogic Server Domain
• Basic WebLogic Workshop Domain

Depending on the degree to which an existing domain has been customized—for example, you have modified the scripts that start WebLogic Server or set environment variables—there may be steps that you need to perform in addition to those presented in this section.

Upgrade Steps

To upgrade a domain from WebLogic Integration 8.5 to SP5, complete the following steps:

Shut down any running instances of the database server with which any WebLogic Integration 8.5 domain is configured, except PointBase. If your domain is configured with PointBase, the PointBase server is started during the upgrade procedure, as explained in step 6.
Open a UNIX shell or Windows command prompt window, as appropriate.
Set the ANT_OPTS environment variable on your machine to -Xmx256m, to ensure that Ant has enough memory available to complete the domain upgrade procedure. To set the ANT_OPTS variable, enter the command appropriate for your operating system:

Windows:

prompt> set ANT_OPTS=-Xmx256m

UNIX:

prompt> setenv ANT_OPTS -Xmx256m

Go to the following directory:

WL_HOME/integration/upgrade

Create an options.properties file that contains settings for your domain environment. The WL_HOME/integration/upgrade directory contains the file options.properties.sample, which you can use as a template for creating this file.

Define the properties shown in Table 2-1. The values shown in bold must be used specifically, unless indicated otherwise.

Note: Use "/" as a file separator in directory paths.

Table 2-1 Values You Specify in the options.properties File 

Set the following property...	To the following values...
current.version=sp4	sp4
domain.path=path	The absolute path of the directory containing the domain to be upgraded. For example: c:/bea/user_projects/domains/myDomain
beahome.path=path	The absolute path of the BEA Home directory in which the pre-upgraded WebLogic Integration 8.5 software is installed. For example: c:/bea
beahome.latest.path=path	The absolute path of the BEA Home directory in which the WebLogic Integration 8.5 SP5 software is installed. For example: c:/bea
os=both	The default value of both. Note: If you specify the property os=unix, substitutions may be skipped when executing the upgrade Ant script target as described in step 10. Therefore, we recommend that you use the default property os=both; this ensures that all paths are properly upgraded. If you choose run the upgrade script using the os=unix property, you should run the update_paths target manually.
weblogic=weblogic81_wli85	The name of the directory in which the WebLogic Integration 8.5 software (pre-upgrade) is installed. The default is weblogic81_wli85.
weblogic.latest=weblogic81_wli85	The name of the directory in which the WebLogic Integration 8.5 SP5 software is installed. The default is weblogic81_wli85.
db_upgrade=true	The value true for any supported database except PointBase. If the domain is configured to use PointBase, set this property to false.
platform.hp=false	Value of false, which is the default value in the options.properties.sample file. For HP-UX platforms, however, this property must be set to true.


 

If your domain is configured to use PointBase, complete the following steps:
Go to the domain's root directory. For example:

prompt> cd c:\bea\user_projects\domains\myDomain

Run the setDomainEnv script:
On Windows: setDomainEnv.cmd
On UNIX: setDomainEnv.sh
Start the PointBase server, if it is not already running:

Windows:

prompt> WL_HOME\common\bin\startPointBase.cmd -port=9093 -debug=0 -console=false -background=true -ini=DOMAIN_HOME\pointbase.ini > DOMAIN_HOME/pointbase.log 2>&1

UNIX:

prompt> WL_HOME/common/bin/startPointBase.sh -port=9093 -debug=0 -console=false -background=true -ini=DOMAIN_HOME\pointbase.ini > DOMAIN_HOME/pointbase.log 2>&1

Note: This is a generic PointBase startup command. You may need to customize this command if you are not using the default directories.

Enter the following command:

prompt> ant -f domain_upgrade.xml upgrade_dbs

Enter the following command to upgrade the JDK version reference:

prompt> ant -f domain_upgrade.xml update_paths

Modify the workshop.properties file to update the following definitions, as appropriate:
• wlsHome.path, which points to the new WebLogic Server Home directory. For example:

wlsHome.path=C:/bea/weblogic81_wli85

• jdkHome.path, which points to the Java SDK installation directory. For example:

jdkHome.path=C:/bea/jrockit81sp4_142_08

Run the setWLSEnv script (setWLSEnv.sh on UNIX; setWLSEnv.cmd on Windows), which is located in the following directory:

WL_HOME/server/bin

Run the domain_upgrade.xml script to upgrade the WebLogic Integration resources in your domain, using the following syntax:

ant -f domain_upgrade.xml upgrade -Doptions.properties=your_options_file
-Dsingle.node=true|false -Ddb_type=your_db_vendor -Ddb_user=user_name
-Ddb_password=password -Ddb_server=your_server:port
-Ddb_name=database_name

In the preceding syntax:

• your_options_file represents the options.properties file that you created in step 5.
• If you are upgrading a single-node domain, set the -Dsingle.node parameter to true. If you are upgrading a clustered domain, set this parameter to false.
Remove the domain server's .wlnotdelete subdirectory and all its contents. This subdirectory, which contains the server's cache, is located in the domain's server directory. For example:

BEA_HOME/user_projects/domains/mydomain/examplesServer/.wlnotdelete

Removing the .wlnotdelete subdirectory ensures that all domain upgrade changes become effective when the server is restarted.

Note: To see the available Ant targets and a description of each, enter the following command from the WL_HOME/integration/upgrade directory:

prompt> ant -f domain_upgrade.xml usage

If your domain does not contain WebLogic Portal resources, redeploy your application in the upgraded domain. This step completes the SP5 upgrade procedure.

If your domain contains WebLogic Portal resources, complete the following additional steps:

Upgrade the domain to use the new WebLogic Portal SP5 libraries and database modules, which may be appropriate if you want to preserve a highly customized domain, including LDAP setup. The following procedure summarizes the steps that are required:
Go to the following directory:

WL_HOME/portal/upgrade/SP5

Run the WebLogic Portal database update script, pf_update_system_data.sql.
Make a backup copy of the upgraded database.

For complete details about each of these steps, see "Step 2: Upgrade Existing Portal Framework Data" in "Upgrading to Service Pack 5" in the WebLogic Portal 8.1 Upgrade Guide at the following URL:

http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/upgrade/servicepack4to5.html

Upgrade your WebLogic Portal applications in the domain by completing the following steps:
When upgrading applications that are stored as EAR files, you must manually update the encryption.
Start WebLogic Workshop 8.1 SP5. If the server is running, shut it down in Workshop by choosing Tools—>  WebLogic Server—>  Stop WebLogic Server.
In WebLogic Workshop, open the portal application you want to update.
In the Application window, right-click the application directory and choose Install—>  Update Portal Libraries. In the Application window, right-click the application directory and choose Install—>  Update Portal Libraries. Workshop prompts you to indicate whether you want to overwrite files with SP5 versions. Click OK.

After the portal application libraries are updated, a dialog box prompts you to select Web projects in the application that you want to have updated.

Select the Web projects for which you want to have the libraries updated, and click OK.
Redeploy your application in the upgraded domain.

For complete details about upgrading WebLogic Portal resources and applications in an existing domain, see "Upgrading to Service Pack 5" in the WebLogic Portal 8.1 Upgrade Guide at the following URL:

http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/upgrade/servicepack4to5.html

Congratulations! You have completed the WebLogic Integration 8.5 SP5 upgrade procedure.

Creating a New Domain and Deploying Existing Applications to It

This section explains how to create a new domain that points to the WebLogic Integration 8.5 SP5 installation and deploy existing applications to that domain. This method may also require additional steps; for example, upgrading your existing applications. However, by creating a new domain, you ensure that your domain is based on the latest domain template.

This upgrade path is typically appropriate in the following situations:

• You are comfortable recreating your domain configuration.
• Redeploying your applications is not an issue.

To create a new domain and deploy existing applications to it, complete the following steps:

Use the Configuration Wizard to create a new domain that is based on an out-of-the-box domain template, as appropriate for your application.

For more information, see Creating a New WebLogic Domain in Creating WebLogic Configurations Using the Configuration Wizard.

For domains running in production mode without the PointBase database, the nopointbase option must be passed to the startWebLogic script (startWebLogic.cmd on Windows; startWebLogic.sh on UNIX). Otherwise, the server will not start correctly; WebLogic Integration 8.5 SP5 enables PointBase even when it is not used by the configuration.
For an application using an Application Integration control that was originally deployed using the WebLogic Workshop auto-deploy feature, you must first undeploy the application and then redeploy it using the WebLogic Integration Administration Console or the command-line deployer.
If your application does not contain WebLogic Portal, redeploy your application in the new domain. This completes the SP5 upgrade procedure.

For an application that incorporates WebLogic Portal, complete the following additional steps:

If you are doing a complete, new installation as part of your upgrade, update the WebLogic Portal scripts as necessary, as explained in "WebLogic Portal Full Installer" in "Upgrading to Service Pack 5" in the WebLogic Portal 8.1 Upgrade Guide at the following URL:

http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/upgrade/servicepack4to5.html

Upgrade the domain to use the new WebLogic Portal SP5 libraries and database modules, which may be appropriate if you want to preserve a highly customized domain, including LDAP setup. The following procedure summarizes the steps that are required:
Go to the following directory:

WL_HOME/portal/upgrade/SP5

Run the WebLogic Portal database update script, pf_update_system_data.sql.
Make a backup copy of the upgraded database.
Upgrade your WebLogic Portal applications in the domain by completing the following steps:
If you are using a third-party content management system, re-configure that repository before deploying it. This reconfiguration allows the passwords to be re-encrypted for the new domain.
Re-encrypt any passwords that are used to access WSRP portlets. Encryption is domain-specific so it needs to be updated when you switch domains. Also, when upgrading applications that are stored as EAR files, you must manually update the encryption.
Start WebLogic Workshop 8.1 SP5. If the server is running, shut it down in Workshop by choosing Tools—>  WebLogic Server—>  Stop WebLogic Server.
In WebLogic Workshop, open the portal application you want to update.
In the Application window, right-click the name of the application directory and choose Install—>  Update Portal Libraries. Workshop prompts you to indicate whether you want to overwrite the existing files with SP5 versions. Click OK.

After the portal application libraries are updated, a dialog box prompts you to select Web projects in the application that you want to have updated.

Select the Web projects for which you want to have libraries updated, and click OK.
Restart the server.
Start WebLogic Workshop, and deploy your existing applications into the new domain.

For complete details about upgrading WebLogic Portal resources and applications in an existing domain, see "Upgrading to Service Pack 5" in the WebLogic Portal 8.1 Upgrade Guide at the following URL:

http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/upgrade/servicepack4to5.html

Congratulations! You have completed the WebLogic Integration 8.5 SP5 upgrade procedure.