2 Installing and Configuring Oracle Business Transaction Management

Upgrading from a Previous Version of Release 11g

This section explains how to upgrade an installation of Business Transaction Management to the latest version of release 11g. You can use these instructions for upgrading release 11g only. If your installation of Business Transaction Management is older than release 11g, enter a service request at My Oracle Support (http://support.oracle.com) for assistance in upgrading your installation.

Business Transaction Management supports a rolling, center-out, in-place upgrade, as described here:

• Rolling upgrade means that you do not have to upgrade all the components at the same time.

• Center-out upgrade means you first upgrade the central servers, then upgrade the monitors, and then, optionally, upgrade the observers according to the following rules:

  • The central servers, monitors, and observers must all be release 11g to begin with.

  • You must upgrade the central servers and monitors to the same version of release 11g.

  • You are permitted to upgrade the central servers and monitors without upgrading the observers (meaning that observers are permitted to be older than the central servers and monitors). In this case, however, you cannot take advantage of new functionality that depends on upgraded observers.

  • You must not upgrade observers to a version that is newer than the central servers and monitors (unless the observer readme file indicates that the versions are compatible).

• In-place upgrade means that you upgrade components by simply replacing them with new components, without editing configuration settings.

To upgrade your Business Transaction Management 11g installation:

1. Download the distribution archive that contains the Business Transaction Management central servers and monitor (BTMJava.zip) and unzip it into a directory (referred to as Install_Dir).

2. 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. Only the owner can even 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.

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

   You do not have to shut down the monitors at this point, but you must shut down all of the central servers.

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

5. Restart the central servers.

6. Shut down, redeploy, and restart each monitor (btmMonitor.ear).

   You do not have to shut down all the monitors at the same time. You can perform this task one monitor at a time, if you like. However, you must perform this task for all monitors. Business Transaction Management is not designed to run for an extended time with a version mismatch between the central servers and monitors.

7. Optional – Upgrade the observers.

   For this release, you are not required to upgrade the observers. The observers can remain at an older version of release 11g than the central servers and monitors. In such a case, the monitors operate in compatibility mode in relation to the observers. However, you might not be able to take advantage of new functionality unless you do upgrade the observers. For instructions on upgrading the observers, refer to the Business Transaction Management online help (in the TOC, navigate to Administering BTM > Setting up Observation > Upgrading Observers).

Before You Install

Please note the following third-party requirements and environment settings:

• Business Transaction Management requires Macromedia Flash v9 or higher.

• If you are using Internet Explorer, you must configure the browser to allow the Flash player Active X control. Consult your Internet Explorer documentation for instructions on enabling this setting.

• If you are using a Windows Firewall, you need to configure the firewall to make it aware of each port into which you install Business Transaction Management. Consult your Microsoft Windows documentation for instructions.

• If you are installing Business Transaction Management into an HTTPS-only environment (that is, an environment in which there is no HTTP traffic between components), you must do one of the following:

  • Ensure that your application servers are listening only on HTTPS ports.

    Or

  • Modify each web.xml file packaged in each of the Business Transaction Management WAR files so as to specify that only HTTPS access is allowed. You can do this by simply uncommenting the <security-constraint> element that is provided in those files. The element looks like this:

    <security-constraint>
      <display-name>Require SSL communication</display-name>
      <web-resource-collection>
        <web-resource-name>All AmberPoint system services</web-resource-name>
        <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
    </security-constraint>
    

-Dcom.amberpoint.IdentityAssertion.SharedSecret=MySecretString

-Dcom.amberpoint.security.encryption.aes.defaultKey=MyEncryptionKey

-Dcom.amberpoint.security.encryption.aes.defaultKey="oylJKoTGXTHasOYwtjwA7g=="

Setting up your WebLogic Environment

1. Add the appropriate database driver to the WebLogic CLASSPATH. (Drivers are supplied in the Business Transaction Management distribution in the Install_Dir/jdbc directory.)

2. Increase the server memory by opening WL_install_dir\user_projects\domains\domainName\bin\setDomainEnv.cmd in a text editor and editing the following settings (note these are minimum recommendations):

   • MEM_ARGS=-Xms256m -Xmx768m (There is one entry for this.)

   • -XX:MaxPermSize=256m (There are several entries for this; edit them all.)

3. For the domain in which you will install Business Transaction Management, ensure that the listen address property is set to a valid host name. By default, this property is empty, which defaults to 127.0.0.1. Do not leave this field empty.

4. Set up an administrative user.

   Business Transaction Management maps roles defined in WebLogic to its own application roles. See Mapping WebLogic Users to Business Transaction Management Roles for more information.

Setting up your WebSphere Environment

1. Add the appropriate database driver to the WebSphere CLASSPATH. (Drivers are supplied in the Business Transaction Management distribution in the Install_Dir/jdbc directory.)

   If you edit the CLASSPATH while the server is running, be sure to restart WebSphere before configuring Business Transaction Management.

2. Use the WebSphere Administrative Console to specify Initial Heap Size of no less than 256, and Maximum Heap Size of no less than 1024.

   Perform this task on each WebSphere instance in which you install Business Transaction Management components.

3. Enable global security on WAS, including application and Java 2 security.

   Perform this task on each WebSphere instance in which you install Business Transaction Management components.

4. Set up an administrative user.

   Business Transaction Management maps roles defined in WebSphere to its own application roles. See Mapping WebSphere Users to Business Transaction Management Roles for more information.

Mapping Users to Business Transaction Management Application Roles

The Management Console uses roles to authorize access to various features of the user interface.

To configure Business Transaction Management, you must log in as a user with the btmAdmin role. For information on setting up user accounts and assigning roles, see the “Authentication and Role Mapping” topic in the Business Transaction Management online help.

Setting up your Business Transaction Management Databases

Several Business Transaction Management system services use a database to store persistent information and log messages. You must use an Oracle 10g or 11g RDBMS for these databases. Before you configure Business Transaction Management, create the following database users (these are suggested names):

• sphereDB

• measurementDB

• transactionDB

• messageLogDB

You can create the database users in the same Oracle instance or in separate instances. You must create these users before starting configuration of Business Transaction Management. When you configure Business Transaction Management (see Initial Configuration of Business Transaction Management), the system will automatically create the appropriate database tables.

If you prefer to create the schemas manually for the first three of these databases (sphereDB, measurementDB, and transactionDB), your DBA can create them beforehand (see the following note). If you intend to let the system automatically create these tables and indexes, the database users must have create table, create index, create view, and analyze privileges. You cannot create the fourth schema (messageLogDB) beforehand because the system must be able to create and drop tables dynamically in response to changes in your monitored applications. For this database, the user must have create table, drop table, create index, create view, and analyze privileges. (Note: It is not sufficient to assign the privileges to the roles associated with the user. You must explicitly assign the privileges to the user.)

Installing Business Transaction Management

1. Download the distribution archive (BTMJava.zip) and unzip it into a directory (referred to as Install_Dir).

2. Optional security step for UNIX-like operating systems – If you want to set file 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. Only the owner can even 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.

3. If you haven't already done so, configure the security settings explained in Configuring Security.

4. Using your application server's administration console, deploy the following applications (located in Install_Dir\archives):

   • Deploy btmMain on a Managed Server that will act as the central application server (take all the defaults).

   • Deploy btmPerformanceServer once on a machine other than the machine on which btmMain is deployed. This application contains the service-level management components.

   • Deploy btmTransactionServer once on a machine other than the machine on which btmMain and btmPerformanceServer are deployed.

   • Deploy btmMonitor at least once, but as many times as needed for your monitoring requirements. Do not deploy on the same machine as btmMain, btmTransactionServer, or btmPerformanceServer.

5. For WebLogic – Start all managed servers where you deployed Business Transaction Management components.

6. Start the deployments.

Initial Configuration of Business Transaction Management

1. Point a web browser at the server that hosts btmMain. Use a URL in the form of:

   http://host_name:port_number/btmui
   

   The Management Console login page opens.

2. Log in using a set of credentials from the container's administrators group.

3. The introductory page of the Configuration wizard opens; click Next.

   The Database Type page opens.

4. Choose External Database and then click Next (the embedded database is not supported for production systems).

   The External Database Configuration page opens.

5. Provide the connection string to your Oracle instance and the user names and passwords for the database users you created in Setting up your Business Transaction Management Databases. If you created the users on separate Oracle instances, first select Custom so that you can provide multiple connection strings. Then, click Next.

   The Sphere URL page opens.

6. Ensure that the URL for the sphere is correct—in most cases the default should be correct (unless you are running in an HTTPS environment). Then, click Next.

   Note:

   If you click the Test Sphere URL link and the sphere URL is correct, the system displays a Sphere Status page that indicates that the sphere is not initialized. This is expected and the sphere service will be initialized at the completion of the configuration. If the URL is incorrect, the browser displays a “page not found” error.

   The Local Container Setup page opens.

7. This page lets you specify DNS aliases for the network node on which you installed btmMain.

   The use of aliases helps avoid the creation of duplicate endpoints when users register services manually or when the system observes message traffic at an alias address. Use a comma to separate multiple addresses.

8. Enter the URL of the container to which you deployed btmPerformanceServer in the form of http://HostName:Port/btmcontainer/container/.

   This URL must end with “/btmcontainer/container/”. Make sure that you deploy apPerformanceServer before you exit this screen.

   Then click Next. The Local Container Setup page opens again (unless you deployed btmPerformanceServer to the same machine as btmMain).

9. This page lets you specify DNS aliases for the network node on which you installed btmPerformanceServer.

10. Enter the URL of the container to which you deployed btmTransactionServer in the form http://HostName:Port/btmcontainer/container/.

    This URL must end with “/btmcontainer/container/”. Make sure that you deploy btmTransactionServer before you exit this screen.

    Then click Next. The Local Container Setup page opens again (unless you deployed btmTransactionServer to the same machine as btmPerformanceServer or btmMain).

11. This page lets you specify DNS aliases for the network node on which you installed btmTransactionServer.

12. View the Summary information and click Finish.

    Business Transaction Management validates the information you supplied during configuration, and if all the information is valid, configuration completes successfully and the Business Transaction Management Console appears.

    If certain configuration information cannot be validated, Business Transaction Management displays an error message as well as a check box with the following text: “Ignore these errors and proceed with a potentially incompletely configured system.” In general you should attempt to correct the configuration error(s). However, you also have the option of proceeding to a partially configured Business Transaction Management by enabling the checkbox and clicking Finish again. If you choose to access the partially configured system, you will need to correct the configuration errors before you can successfully use the product. For example, if your database connection information was not accurate, you will need to re-configure it from within the Management Console. For information about configuring databases after initial configuration, refer to the Business Transaction Management online help.

13. You have completed the initial configuration of Business Transaction Management, but before you can discover and monitor your business services, you must register your btmMonitor deployment with the Sphere, and install observers. For information about registering monitors and installing observers, refer to the Business Transaction Management online help.