2 Upgrading Business Transaction Management

This chapter explains how to perform an in-place upgrade of Business Transaction Management from any version of release 11 or 12 to the current version of release 12. Performing an in-place upgrade means that you upgrade components by simply replacing them with new components, and without editing configuration settings.

A complete upgrade of Business Transaction Management consists of upgrading these components:

If any of these components are older than release 11, do not attempt to perform an upgrade using the instructions in this chapter. Instead, enter a service request at My Oracle Support (http://support.oracle.com) for assistance in upgrading your installation.

The order in which you upgrade your central servers and monitors depends on the release version from which you are upgrading:

After upgrading both the central servers and monitors, you can upgrade your observers. If your observers are older than release version 11, you must upgrade them. If your observers are at release version 11 or higher, you can either upgrade them or leave them as they are. Note, however, that if you do not upgrade the observers, you cannot take advantage of new functionality that depends on upgraded observers.

Note:

The upgrading of central servers older than release 12.1.0.3 adds an observer authentication field to new Observer Communication policies that you create. This observer authentication field is enabled by default. If you want to use observer authentication, you must also upgrade your observers. Observers from releases older than 12.1.0.3 do not have the capability to authenticate themselves. If you don't upgrade your observers to 12.1.0.3, then you must disable the observer authentication field in any new policies that you create or else the observer will not be able to connect with the monitor.

Observers are permitted to be older than the central servers and monitors, but you must never install a version of the observer that is newer than the central servers and monitors.

Note:

In comparing version numbers between the observer and the central servers and monitors, you need be concerned only with the digits up to the second point. For example, in “11.2.0.1”, you need to consider only the “11” and the “2”. Digits after the second point refer to patches and are not important in determining compatibility between the observer and the central servers and monitors.

To determine the version of your installed observer, open the observer's NanoAgent.log file and search for the line that displays the release number, for example:

INFO: Release 11.1.0.4: build 25237 of b21 (11.1.0.4/147754) on 2011-05-13

For information about locating the NanoAgent.log file, see Chapter 14, "Logging Observer Errors and Debugging Information."

Upgrading the Central Servers and Monitors

Note:

Before beginning the upgrade procedure, we suggest that you deactivate your RMI probe unless you require monitoring of RMI calls. Most applications utilize RMI by way of higher-level APIs, such as JAX-RPC, JAX-WS, EJB, and JMS. If your application utilizes RMI only by way of these higher-level APIs, you should deactivate the RMI probe. However, if your application calls RMI directly, you should leave it activated.

To deactivate your RMI probe, first open your Observer Communication policy. The Active Probes section of the policy provides an Enable Discovery and Monitor Upon Discovery checkbox for each type of probe. Deselect both of these checkboxes for RMI. If you are using multiple Observer Communication policies, you should perform this task for each policy.

After deactivating your RMI probe, you should unregister any RMI components that have been discovered. To unregister an RMI component, select the component (modeled as a service) in the Business Transaction Management Console and choose Modify > Delete Your_Service Registration, where Your_Service is the name of your RMI component. You can alternatively use the unregister CLI command. For more information, refer to the Business Transaction Management online help.

To upgrade your Business Transaction Management installation:

  1. Back up your Business Transaction Management databases and configuration data.

    For information on how to perform this task, refer to the online help topic Backing up and Restoring Business Transaction Management. You can locate this topic by first choosing Help > Help in the Management console. After the online help opens, navigate to Administration of Business Transaction Management > Backing up and Restoring Business Transaction Management in the Contents pane.

    Note:

    The central servers must be running in order for you to access the online help.
  2. Back up the persistent storage directories for each of the central servers and monitors.

    For information on the locations of the persistent storage directories, refer to the online help topic Persistent Data. You can locate this topic by first choosing Help > Help in the Management console. After the online help opens, navigate to Administration of Business Transaction Management > Persistent Data in the Contents pane.

  3. Ensure that all WebLogic domains in which the Business Transaction Management central servers and monitors are installed include the Java Required Files (JRF) template. (If you are upgrading a 12.1.0.3 installation, then you have already met this requirement.)

    If any of these domains doesn't include the JRF template, extend the domain and add the template. You will get the following exception when you attempt to start the server if the JRF template is not included in the domain:

    java.lang.ClassNotFoundException: oracle.security.jps.wls.listeners.JpsApplicationLifecycleListener
    

    Note:

    The JRF template is part of the Oracle Application Development Framework (ADF) runtime, which means that you must install the ADF runtime into your WebLogic installation before you can extend any domain with the JRF template. When installing the ADF runtime, take care to install the release version that matches your version of WebLogic. You can download the ADF runtime at:
    http://www.oracle.com/technetwork/developer-tools/adf/downloads/index.html
    
  4. Locate the distribution archive that contains the Business Transaction Management central servers and monitor and unzip it into a directory (referred to henceforth as Install_Dir).

    The distribution archive is named BTM_Servers_*.zip, where * is the Business Transaction Management version number.

  5. Optional security step for UNIX-like operating systems – If you want to set permissions on the files that make up the distribution to the most restrictive level that still maintains functionality, complete this step:

    1. Locate setPermissions.sh at the top level of Install_Dir.

      This script contains commands for setting file permissions of all regular files to Owner – read/delete; all directories to Owner – read/execute/delete; and all scripts to Owner – read/execute/delete.

      Note:

      These permission levels are extremely restrictive, for example, only the owner can read the files.
    2. On a command line, at the top level of Install_Dir, run this command:

      source setPermissions.sh
      

      This command runs the commands in the script file and sets permissions for all files and directories in the expanded archive.

  6. Upgrade the central server and monitor EAR files:

    If you are upgrading from release 12.1.0.2 or 12.1.0.3, you can either upgrade all of your central server and monitor EAR files together, or upgrade all of your central server EAR files and then upgrade your monitor EAR files one at a time.

    If you are upgrading from a release older than 12.1.0.2, you must upgrade all of your central server and monitor EAR files together.

    To upgrade the central server and monitor EAR files together:

    1. Shut down all of the central servers and monitors (btmMain.ear, btmPerformanceServer.ear, btmTransactionServer.ear, and btmMonitor.ear).

      It is essential that you shut them all down.

      For information about shutting down Business Transaction Management components, see Chapter 13, "Starting and Shutting Down Business Transaction Management."

    2. Using your application server's deployment tools, redeploy each of the central servers and monitors using your new EAR files located in Install_Dir\archives.

    3. Restart the central servers and monitors.

      When upgrading from a release older than 12.1.0.3, restarting the central servers triggers the in-place upgrade of Business Transaction Management data. During this process, the system might suffer from reduced performance and some of the data might be temporarily unavailable. This process should complete within 30 minutes. If you are simply patching a 12.1.0.3 installation, your system should start up at its normal speed.

      For information about starting Business Transaction Management components, see Chapter 13, "Starting and Shutting Down Business Transaction Management."

    4. Notify all Business Transaction Management users to flush their web browser caches.

      The Management Console contains a number of Adobe Flash widgets. Web browsers normally cache these widgets and will continue to use the older cached widgets until you either flush the cache or restart your web browser.

    To upgrade the central server EAR files followed by the monitor EAR files:

    1. Shut down all of the central servers (btmMain.ear, btmPerformanceServer.ear, and btmTransactionServer.ear).

      For information about shutting down Business Transaction Management components, see Chapter 13, "Starting and Shutting Down Business Transaction Management."

    2. Using your application server's deployment tools, redeploy each of the central servers using your new EAR files located in Install_Dir\archives.

    3. Restart the central servers.

      When upgrading release 12.1.0.2, restarting the central servers triggers the in-place upgrade of Business Transaction Management data. During this process, the system might suffer from reduced performance and some of the data might be temporarily unavailable. This process should complete within 30 minutes. If you are simply patching a 12.1.0.3 installation, your system should start up at its normal speed.

      For information about starting Business Transaction Management components, see Chapter 13, "Starting and Shutting Down Business Transaction Management."

    4. Notify all Business Transaction Management users to flush their web browser caches.

      The Management Console contains a number of Adobe Flash widgets. Web browsers normally cache these widgets and will continue to use the older cached widgets until you either flush the cache or restart your web browser.

    5. Shut down your monitors (btmMonitor.ear), redeploy them using your new EAR file located in Install_Dir\archives, and restart them.

      You can perform this step for all monitors at once, or perform it individually for each monitor.

After you are finished with upgrading the central servers and monitors, and the system has settled down, you can optionally upgrade your observers by following the instructions in the next section.

Note:

This is important! Read the online help topic named Functional Upgrade Issues for information about further upgrade-related tasks you might have to perform and about changes in behavior you should expect to see in your upgraded system. You can locate this topic by first choosing Help > Help in the Management console. After the online help opens, navigate to Overview of Oracle Business Transaction Management in the Contents pane.

Upgrading Observers

You must upgrade the Business Transaction Management central servers and monitors, as described in the preceding section, before upgrading the observers.

Note:

This installation guide provides instructions for upgrading observers to versions that are included as part of release 12.1.0.3. If you want to upgrade an observer to a version from an earlier release, consult the installation guide from that earlier release. In particular, if you want to upgrade an observer for WebLogic 9.2, Oracle Service Bus 10gR3, WebSphere, JBoss, or ASP.NET, consult the installation guide for release 12.1.0.2.2. All release 12.1.x observers are compatible with the current release.

The procedure for upgrading observers is specific to the application server and observer type. Refer to the following sections for detailed instructions on upgrading observers:

Note:

For detailed information about a specific observer's compatibility and functionality, refer to the README.txt file located in the observer's nanoagent directory after you expand the observer ZIP file.

Upgrading Observers on WebLogic 10.3

This section describes how to upgrade an observer installed into a WebLogic 10.3 application server.

In releases previous to 12.1.0.3, a variety of observers were provided for installing into WebLogic 10.3 servers. Each type of observer contained a set of probes that gave it the ability to monitor a particular set of component types. For example, the JavaEE observer contained probes for monitoring JavaEE components and the SOA observer contained probes for monitoring SOA components. In the current release, only a single “universal” observer is provided for installing into WebLogic 10.3 servers. This universal observer contains a superset of all the probes contained in the older observers, making it capable of monitoring the superset of component types that were previously monitorable.

After upgrading to the universal observer, your system will have the ability to discover and monitor new types of components. Depending upon your system and your monitoring needs you might, or might not, want to monitor new component types. Before upgrading to the universal observer, you should review and adjust, if necessary, the active probes in your Observer Communication policy. For more information on this topic, read the online help topic named Functional Upgrade Issues. You can locate this topic by first choosing Help > Help in the Management console. After the online help opens, navigate to Overview of Oracle Business Transaction Management in the Contents pane.

You can use the WebLogic universal observer to upgrade these types of observers:

  • JavaEE observer for WebLogic 10.3

  • Oracle Fusion Applications observer

  • Oracle SOA Suite observer

  • Oracle Service Bus 11gR1 observer

Note:

If you require an updated version of an observer that monitors only JavaEE, Oracle Fusion Applications, Oracle SOA Suite, or Oracle Service Bus, enter a service request at My Oracle Support (http://support.oracle.com) for assistance.

Separate procedures are provided for three different upgrade paths. The procedure you use depends on the type and release version of your observer and whether your WebLogic server is Node-Manager configured or script-configured. These are the procedures to choose from:

Upgrading 12.1.0.3 or 12.1.0.2.2 Observers, or the 12.1.0.2.0 Observer for JavaEE

Use this procedure to upgrade the following observers on WebLogic servers:

  • release 12.1.0.3 “universal” observer

  • all release 12.1.0.2.2 observers

  • release 12.1.0.2.0 observer for JavaEE

  1. Locate the distribution ZIP file for the observer (BTMObserver_Wls_10.3_Universal_*.zip).

  2. Shut down the WebLogic application server in which the observer is installed.

  3. Make a backup copy of the WL_HOME\nanoagent directory.

    The string WL_HOME refers to your WebLogic server's home directory, which is the weblogic92, wlserver_10.0, or wlserver_10.3 directory located in your WebLogic installation directory.

  4. Delete the WL_HOME\nanoagent directory.

  5. Unpack the observer distribution ZIP file into WL_HOME.

    Unpacking the ZIP file creates directories named nanoagent and security_add_ons. The nanoagent directory contains three subdirectories named bin, config, and lib.

  6. Ensure that the user account running WebLogic has at least the following privileges:

    • read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)

    • read permission on all JAR files in the lib directory

  7. If you originally installed the observer by editing script files rather than by using the Node Manager, replace your new observer script file with the observer script file located in your backup copy of the nanoagent directory. If you use the Node Manager, you can skip this step.

    On Windows systems, the observer script file is located at:

    WL_HOME\nanoagent\bin\nanoEnvWeblogic.cmd
    

    On UNIX-like systems, the observer script file is located at:

    WL_HOME/nanoagent/bin/nanoEnvWeblogic.sh
    
  8. Restart your WebLogic server.

Upgrading a 12.1.0.2.0 Observer for SOA or OSB 11gR1, or an 11 or 12.1.0.1 Observer for JavaEE on a Node Manager-Configured Server

Use this procedure to upgrade the following observers to the current release in a WebLogic 10.3 Node Manager-configured environment:

  • release 12.1.0.2.0 observer for Oracle SOA Suite

  • release 12.1.0.2.0 observer for Oracle Service Bus 11gR1

  • release 11 or 12.1.0.1 observer for JavaEE

  1. Locate the distribution ZIP file for the observer (BTMObserver_Wls_10.3_Universal_*.zip).

  2. Open the WebLogic Administration Console (the default URL is http://machine_name:7001/console).

  3. Remove WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar from your managed server's classpath (this setting was required by the version of the observer you are upgrading from, but must be removed for the current release):

    1. Using the Domain Structure pane (on the left), navigate to Environment > Servers.

    2. In the Servers table, click your managed server.

    3. Display the Configuration / Server Start tab.

    4. Click Lock & Edit.

      Note:

      These instructions assume you are operating in a production environment and that your WebLogic server's Automatically Acquire Lock and Activate Changes setting is therefore disabled. However, if this setting is enabled as it might be in a development environment, you do not have to click Lock & Edit in order to make changes and you do not have to activate changes after saving them.
    5. Delete the entry from the Class Path field as follows:

      For Windows systems, delete this string:

      WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
      

      For UNIX-like systems, delete this string:

      WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
      
    6. Keep this page open.

  4. With the Configuration / Server Start tab still displayed, edit your WebLogic startup arguments as follows:

    1. Remove JVM arguments from the Arguments field as follows (these settings were required by the previous release of the observer but must be removed for the current release):

      For Windows systems, remove these arguments:

      -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor -javaagent:WL_HOME\nanoagent\lib\bootstrap\aspectwerkz-jdk5-2.0.jar
      

      For UNIX-like systems, remove these arguments:

      -Daspectwerkz.classloader.preprocessor=com.amberpoint.nanoagent.plugins.APAspectPreProcessor -javaagent:WL_HOME/nanoagent/lib/bootstrap/aspectwerkz-jdk5-2.0.jar
      
    2. Configure the observer bootstrap module into your server by adding a JVM argument to the Arguments field as follows.

      For Windows systems, add this argument:

      -javaagent:WL_HOME\nanoagent\lib\bootstrap\ap-nano-bootstrap.jar
      

      For UNIX-like systems, add this argument:

      -javaagent:WL_HOME/nanoagent/lib/bootstrap/ap-nano-bootstrap.jar
      
  5. Click Save and then click Activate Changes.

    You should receive the following status:

    “All changes have been activated. No restarts are necessary. Settings updated successfully.”

  6. Shut down the WebLogic managed server in which the observer is installed.

  7. Delete the WL_HOME\nanoagent directory from your WebLogic managed server.

    The string WL_HOME refers to the server's home directory, which is the wlserver_10.3 directory located in your server's installation directory. For the remainder of this procedure, replace the string WL_HOME with the actual path to the WebLogic home directory.

  8. Unpack the observer distribution ZIP file into WL_HOME.

    Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories bin, config, and lib.

  9. Ensure that the user account running the WebLogic server has at least the following privileges:

    • read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)

    • read permission on all JAR files in the lib directory

  10. If you inserted <filter> and <filter-mapping> elements into the web.xml files of your web applications during your original installation of the observer, you must now remove those elements.

    The elements to remove from the web.xml files are these:

    <filter>
      <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name>
      <filter-class>
       com.amberpoint.nanoagent.bootstrap.servlet.FilterHandlerBootstrap
      </filter-class>
    </filter>
    <filter-mapping>
      <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>
    
  11. Restart your WebLogic server.

Upgrading a 12.1.0.2.0 Observer for SOA or OSB 11gR1, or an 11 or 12.1.0.1 Observer for JavaEE on a Script-Configured Server

Use this procedure to upgrade the following observers to the current release in a WebLogic 10.3 script-configured environment:

  • release 12.1.0.2.0 observer for Oracle SOA Suite

  • release 12.1.0.2.0 observer for Oracle Service Bus 11gR1

  • release 11 or 12.1.0.1 observer for JavaEE

Note:

When you originally installed the observer, you either installed it into all servers defined in the WebLogic installation or into servers of specific domains. The term global install refers to installing the observer into all servers, and the term domain install refers to installing the observer into a specific domain.

In the following procedure, you will replace the nanoagent directory and its contents. If you installed the observer as a global install, the nanoagent directory is located inside your WebLogic server's home directory, which is the wlserver_10.3 directory located in your WebLogic installation directory.

If you installed the observer as a domain install, the nanoagent directory is located inside your domain directory. In this case, you need to repeat this procedure for each domain in which you installed the observer.

  1. Locate the distribution ZIP file for the observer (BTMObserver_Wls_10.3_Universal_*.zip).

  2. Shut down the WebLogic application server in which the observer is installed.

  3. Make a backup copy of your observer script file.

    The observer script file is the nanoEnvWeblogic.cmd or nanoEnvWeblogic.sh file located inside the nanoagent/bin directory.

  4. Delete the nanoagent directory.

  5. Unpack the observer distribution ZIP file into the directory from which you deleted the nanoagent directory.

    Unpacking the ZIP file creates a directory named nanoagent that contains three subdirectories bin, config, and lib.

  6. Ensure that the user account running WebLogic has at least the following privileges:

    • read permission on the nanoagent/config and nanoagent/lib directories (on UNIX-like systems traverse permission is also required)

    • read permission on all JAR files in the lib directory

  7. Open your new observer script file for editing and open your backup copy so you can copy settings from it.

  8. Ensure that the values of the NANOAGENT_HOME and NANOAGENT_CONFIGURATION_URL variables in your new observer configuration file match the values in your backup copy.

  9. If you inserted <filter> and <filter-mapping> elements into the web.xml files of your web applications during your original installation of the observer, you must now remove those elements.

    The elements to remove from the web.xml files are these:

    <filter>
      <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name>
      <filter-class>
       com.amberpoint.nanoagent.bootstrap.servlet.FilterHandlerBootstrap
      </filter-class>
    </filter>
    <filter-mapping>
      <filter-name>ORACLE_BTM_WEB_APP_OBSERVER</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>
    
  10. Restart your WebLogic server.

Upgrading the Observer for WCF

This section explains how to upgrade an observer for WCF.

  1. Unpack the observer distribution file (BTMObserver_Iis_6-7_Wcf35_*.zip) into a temporary directory (referred to henceforth as observer_temp).

    Unpacking the ZIP file creates a nanoagent directory containing two subdirectories—config and lib. The lib directory contains the observer DLL files.

  2. Make a note of the version number of the new DLLs.

    To find the version number, open the Windows Properties dialog box for one of the DLL files and click the Version tab.

  3. Use gacutil.exe or a Windows Explorer to copy all of the DLL files from observer_temp\nanoagent\lib to the global application cache (GAC; normally located at C:\WINDOWS\assembly).

  4. Using a text editor, open the application configuration file that contains the observer configuration code that you added when you originally installed the observer.

    The file is either the machine.config, or a web.config file.

  5. In the application configuration file, locate the two occurrences of the Version attribute that refer to the version number of the observer DLLs.

    The elements containing the Version attributes are inside a </behaviorExtensions> element and should look similar to this:

    <add name="APEPInterceptor" type="AmberPoint.NanoAgent.DotNet.Wcf.APEPBehaviorExtnElem, AmberPoint.NanoAgentWCF, Version=64000.64000.25233.19024, Culture=neutral, PublicKeyToken=d8685c0afbb35893"/>
    
    <add name="APServiceInterceptor" type="AmberPoint.NanoAgent.DotNet.Wcf.APServiceBehaviorExtnElem, AmberPoint.NanoAgentWCF, Version=64000.64000.25233.19024, Culture=neutral, PublicKeyToken=d8685c0afbb35893"/>
    
  6. Edit the setting of the Version attribute so that it matches the version number of the new observer DLLs, and then save and close the file.

    Note:

    If you configured the observer into multiple web.config files on the machine, edit the Version attributes in each file.
  7. Optional – Remove the old observer DLLs from the GAC (unless they are being used by another observer on the machine).

    The name of each observer DLL begins with the string “AmberPoint”. To remove a DLL, right-click it and choose Uninstall.

    Note:

    The observer for ASP.NET uses many of the same DLLs as the observer for WCF. If you have the observer for ASP.NET installed on the machine, you must not remove the version of the DLLs that are being used by it.