8 Upgrading a Clustered SOA Environment

Describes the process of upgrading to a clustered SOA environment and performing post-upgrade configuration tasks.

• Upgrading a Clustered Topology
  
• Understanding the SOA Cluster Upgrade Topology
  
• Using Secured Task Forms in a Clustered Topology
  The task form is a Java Server Page XML (.jspx) file that you create in the Oracle JDeveloper designer where you created the SOA composite containing the human task.
• Propagating Domain Configuration to Another Host
  After verifying that the upgrade was sucessful, use these steps to propagate the newly upgraded files to another host.
• Post-Upgrade Tasks for Cluster Upgrades
  

Upgrading a Clustered Topology

Table 8-1 lists the steps required to upgrade the example clustered, multi-host Oracle SOA Suite topology illustrated in Figure 8-1.

Table 8-1 Oracle SOA Suite and BPM Cluster Upgrade Roadmap

Task	For More Information
Review the upgrade topology, and identify SOAHOST1 and SOAHOST2 on your setup.	See Understanding the SOA Cluster Upgrade Topology
Shut down the Administration Server, all the Managed Servers, and the Node Managers running on SOAHOST1 or SOAHOST2.	See Stopping Servers and Processes
Perform a complete upgrade of your 11g deployment on SOAHOST1. Perform the post-upgrade configurations that apply to your environment.	See Upgrading SOA Suite and Business Process Management See Also: If Business Activity Monitoring (BAM) is part of your domain, see Upgrading a SOA with Oracle BAM Domain to 12c If Oracle Service Bus (OSB) is part of your domain, see Upgrading Oracle Service Bus (without Oracle SOA Suite) from 11g
After a successful upgrade, propagate the domain configuration of SOAHOST1 on SOAHOST2. To do this, you must pack the domain on SOAHOST1, and unpack it on SOAHOST2 in a NEW domain.	See Propagating Domain Configuration to Another Host
Restart the Administration Server and the Managed Servers on SOAHOST1 and SOAHOST2.	Starting the Admin Server and SOA Managed Servers
Perform any additional post-upgrade configuration tasks for your environment.	See Performing Post Upgrade Tasks

Understanding the SOA Cluster Upgrade Topology

Figure 8-1 shows a sample topology of a clustered Oracle SOA Suite deployment with SOA, Oracle Web Services Manager (OWSM), Oracle Service Bus (OSB) and Oracle Business Activity Monitoring (Oracle BAM) in separate clusters across two application hosts, SOAHOST1 and SOAHOST2. The Oracle HTTP Server, Administration Server, Oracle Enterprise Manager Fusion Middleware Control and database are shared with both hosts.

Specifically, this chapter describes the steps required to upgrade a WebLogic domain that contains multiple WebLogic Server clusters that are scaled out to multiple host computers. You can apply the concepts and procedures in this chapter to your own specific Oracle SOA Suite environment.

The steps required to upgrade this sample topology are described in the next section in Table 8-1.

Note:

If you are upgrading Oracle BAM with SOA, see Upgrading a SOA with Oracle BAM Domain to 12c.

Figure 8-1 Clustered SOA Topology

Description of "Figure 8-1 Clustered SOA Topology "

Using Secured Task Forms in a Clustered Topology

The task form is a Java Server Page XML (.jspx) file that you create in the Oracle JDeveloper designer where you created the SOA composite containing the human task.

If your SOA composite includes a human task form, or if task forms are deployed on non-SOA servers, then you must secure the task form after the upgrade.

Propagating Domain Configuration to Another Host

After verifying that the upgrade was sucessful, use these steps to propagate the newly upgraded files to another host.

After you have completed your single node upgrade on SOAHOST1, use these steps to propagate the newly upgraded files to another node (in this example the secondary host is called SOAHOST2).

• Executing the pack command on the server where the Admin Server and one of the Managed Servers is installed.
  
• Executing the unpack Command from the 12c Oracle Home on SOAHOST2.
  
• Copying the template file created on SOAHOST 1 to SOAHOST2.
  
• Completing the following verification steps after the unpack.
  

Executing the pack command on the server where the Admin Server and one of the Managed Servers is installed.

In our sample topology, you would execute the following on SOAHOST1:

cd /12c_ORACLE_HOME/oracle_common/common/bin

./pack.sh -domain=/11g_DOMAIN_HOME -template=domainupgradetemplate.jar -template_name=domainupgradetemplate -managed=true

In this example:

• 12c_ORACLE_HOME refers the actual path to the 12c Oracle home directory (the installation directory for the 12c (12.2.1.4.0)bits).

• Replace 11g_DOMAIN_HOME with the actual path to the upgraded domain directory.

• domainupgradetemplate.jar is a sample name for the jar file you are creating, which will contain the domain configuration files.

• domainupgradetemplate is the name assigned to the domain template file.

• By default, the domainupgradetemplate is created in the current directory where you ran the pack command. In this example, it would be created in the following directory, but you can specify a full path for the template jar file as part of the -template argument to the pack command:

  ORACLE_COMMON_HOME/common/bin/
  

The pack command creates a template archive (.jar) file that contains a snapshot of either an entire domain or a subset of a domain. You can use a template that contains a subset of a domain to create a Managed Server domain directory hierarchy on a remote machine.

Executing the unpack Command from the 12c Oracle Home on SOAHOST2.

Make sure that the Administration and Managed Servers are still stopped and then execute the unpack command to create a full domain (or a subset of a domain) used for a Managed Server domain directory on the remote machine. You may use unpack only with a template compatible with your current installation.

Note:

Do not attempt to unpack the domain on top of an existing domain. Oracle recommends that you unpack the contents of the domain upgrade template jar file into a new domain location.

It is important to note that even if you use the -overwrite_domain=true argument when unpacking the domain, the contents of the existing domain will remain in place and will cause issues with when starting the servers. For this reason, Oracle recommends that you unpack the domain template jar file into a new location, or, manually delete the contents of the existing location before you unpack.

A sample unpack command code snippet is shown below.

cd /12c_ORACLE_HOME/oracle_common/common/bin

./unpack.sh -template=domainupgradetemplate.jar - domain=NEW_DOMAIN_LOCATION

In this example:

• 12c_ORACLE_HOME refers the actual path to the 12c Oracle home directory, the installation directory for the 12c (12.2.1.4.0).

• Replace NEW_DOMAIN_LOCATION with the actual path to the upgraded domain directory.

• domainupgradetemplate.jar is a sample name for the jar file you are creating, which will contain the domain configuration files.

• domainupgradetemplate is the name assigned to the domain template file.

Copying the template file created on SOAHOST 1 to SOAHOST2.

After you perform a complete upgrade of your 11g deployment on SOAHOST1, and you have completed any post-upgrade configurations that apply to your environment, you must copy the domain template to SOAHOST2.

Use the following command to copy from SOAHOST1 the domain upgrade template JAR file created during the upgrade.

scp soadomaintemplate.jar company@SOAHOST2:12c_ORACLE_HOME/oracle_common/common/bin

Completing the following verification steps after the unpack.

1. Verify that WL_HOME, SOA_ORACLE_HOME, UMS_ORACLE_HOME in setDomainEnv.sh script from 11g domain are pointing to 12c.

   See Reapplying Customizations to setDomainEnv.sh.

2. Start the Node Manager, WebLogic Administration Server, and the Managed Servers on SOAHOST1 and SOAHOST2 in the following order:

   1. On SOAHOST1 and SOAHOST2, start the Node Manager.

   2. On SOAHOST1, start the WebLogic Administration Server.

   3. On SOAHOST1 and SOAHOST2, start the Managed Servers.

For more information, see Starting Servers and Processes. Carefully review the order in which Managed Servers should be started.

If you cannot start the servers or experience other technical issues, see Troubleshooting the Upgrade

Note:

During the upgrade, the Node Manager configuration files (nodermanager.properties, for example) are moved from 11g_DOMAIN_HOME/wlserver_10.3/ location to the 11g_ORACLE_HOME/ domains/DOMAIN_HOME/nodemanager location. Therefore, the node manager in 12c has to be started from the 11g_DOMAIN_HOME domain directory.

Post-Upgrade Tasks for Cluster Upgrades

After a successful cluster upgrade, you may need to perform additional post-upgrade configurations tasks. Perform only those tasks that pertain to your clustered environment.

• Starting the Admin Server and SOA Managed Servers
  Restart the Oracle WebLogic Administration server and any other SOA Managed servers.
• Removing OWSM Targets from SOA and OSB Clusters
  
• Updating OWSM Cross-Component Wiring
  
• Reapplying an EDNTopic to SOA JMS Module After Cluster Upgrade
  
• Preventing Duplicate Messages When Using JMS Transport Proxy Service
  

Starting the Admin Server and SOA Managed Servers

Restart the Oracle WebLogic Administration server and any other SOA Managed servers.

Start the Administration Server

When you start the Administration Server, you also start the processes running in the Administration Server, including the WebLogic Server Administration Console and Fusion Middleware Control.

To start an Administration Server, use the following script:

(UNIX) DOMAIN_HOME/bin/startWebLogic.sh

(Windows)DOMAIN_HOME\bin\startWebLogic.cmd    

When prompted, enter your user name, password and the URL of the administration server

Start the Managed Servers

Start the WebLogic Server Managed Servers with the following script:

(UNIX) DOMAIN_HOME/bin/startManagedWebLogic.sh managed_server_name admin_url 

(Windows) DOMAIN_HOME\bin\startManagedWebLogic.cmd managed_server_name admin_url

When prompted, enter your user name and password.

Start SOA servers and processes in this order:

1. Oracle Web Services Manager (OWSM) Managed Server

2. Service-Oriented Architecture (SOA) Managed Server

3. Oracle Service Bus (OSB) Managed Server

4. Business Activity Monitoring (BAM) Managed Server

Note:

The startup of a Managed Server will typically start the applications which are deployed to it. Therefore, it should not be necessary to manually start applications after the Managed Server startup.

Removing OWSM Targets from SOA and OSB Clusters

If your 12c domain includes an Oracle Web Services Manager (OWSM) in its own cluster and you have extended that domain with a SOA cluster and an OSB cluster, then post upgrade you must manually untarget the wsm-pm from the SOA and OSB clusters.

To remove the owsm-pm target from the SOA and OSB clusters:

1. Log in to the WebLogic Server Administration Console 12c.

   Enter the following URL in a browser:

   http://host name:port_number/console
   

   The port number is the port number of the Administration Server. By default, the port number is 7001.

   The login page is displayed.

2. Select Deployments from Domain Structure.

3. Select wsm-pm under Deployments.

4. In the settings for wsm-pm, select Targets.

5. Select wsm-pm component of type Enterprise Application and select Change Targets.

6. Uncheck SOA cluster and OSB cluster.

7. When prompted, click Yes to apply the changes.

8. REQUIRED: Once the wsm-pm is targeted only to the OWSM cluster, you must rewire the components as described in Updating OWSM Cross-Component Wiring.

Updating OWSM Cross-Component Wiring

After you have removed OWSM targets from SOA and OSB clusters as described in Removing OWSM Targets from SOA and OSB Clusters, you must rewire the OWSM Policy Manager components as described below:

1. Start the Administration (admin) server and one OWSM server.

2. Log in to the Oracle Enterprise Manager Fusion Middleware Control 12c console and navigate to the Cross Components Wiring > Components option.

   
   Description of the illustration cross_menu.png

3. Select OWSM Policy Manager from the list of available components:

   
   Description of the illustration owsm_comp.png

4. From the Service End Points table, select the OWSM Policy Manager t3 connection entry and click Publish. The status will change from Out of Sync to Published.

   
   Description of the illustration owsm_publish.png

5. Select OWSM Agent from the Component Type list. Select the t3 connection entry and click Bind.

   
   Description of the illustration bind.png

6. Verify that the Service Type for the service end point is OWSM Policy Manager.

   
   Description of the illustration bind_config.png

7. Repeat steps 5 and 6 to Bind the remaining component types. In this example, you will select com.oracle.ess and Fusion Middleware Control.

Reapplying an EDNTopic to SOA JMS Module After Cluster Upgrade

After upgrading a SOA Cluster domain to 12.2.1, the upgraded SOA JMS module may be missing the EDNTopic. If the JMS module is missing the EDNTopic, you must manually add the topic or UDD for this topic using the Administration Console or WLST.

See the Administration Console online help for more information on reapplying the EDNTopic.

Preventing Duplicate Messages When Using JMS Transport Proxy Service

In a 12c cluster domain, jmsServers are targeted to migratable targets, which is different from the default behavior in 11g where jmsServers were targeted to an individual server.

When you configure a 12c proxy service based on the JMS transport, set the topic distribution mode to One-Copy-Per-Application or One-Copy-Per-Server. To prevent duplicate messages, do not use Compatibility mode in a clustered environment.