1 Introduction

Oracle distributes Business Transaction Management in a zip file. You extract deployment units from the file and use your application server's deployment tools to distribute the Business Transaction Management components. The information provided in this guide can help you install and configure a general purpose Business Transaction Management system suitable for experimenting with the system functions and use cases. The deployment configuration and resources required in a production environment can vary based on a variety of factors, such as anticipated throughput, message size, type and number of applied management policies, and so forth. An Oracle consultant can help you determine the appropriate configuration and resource requirements for your specific needs.

1.1 Deployment Environment

Oracle designed Business Transaction Management for use in a distributed application environment, and we expect that you will deploy various Business Transaction Management components onto multiple machines and application servers.

1.1.1 Business Transaction Management Components

Business Transaction Management consists of multiple deployment units. The main function of each unit is described below:

  • apMain contains all the central Business Transaction Management system services and user interface applications, and, most notably the sphere. The sphere is the Business Transaction Management component that manages the Business Transaction Management environment. In addition, apMain contains a subdeployment for the F5 intermediary.

  • apContainer holds the container service, which is required for registering remote application servers to the sphere. You can deploy apContainer to any application server that hosts business services, and that server will be capable of supporting plug-in agents only. You would deploy apContainer where you want to monitor traffic on the application server or install plug-ins, but do not want a proxy or monitor agent.

  • apProxyNode contains the container service and a deployment for the proxy agent. You can deploy apProxyNode to any application server that hosts business services, and that server will be capable of supporting proxy agents.

  • apPerformanceServer contains the service-level management components. You deploy apPerformanceServer on a node other than where apMain and apTransactionServer are deployed. In addition, apPerformanceServer contains a sub-deployment for a container service. While you typically do not deploy the performance components in an application server that hosts business services, the inclusion of the container service makes discovery available if necessary.

  • apTransactionServer contains the transaction management components. You deploy apTransactionServer on a node other than where apMain and apPerformanceServer are deployed. In addition, apTransactionServer contains a sub-deployment for a container service. While you typically do not deploy the performance components in an application server that hosts business services, the inclusion of the container service makes discovery available if necessary.

  • apMonitorNode contains the pieces necessary to configure a nano-agent. Nano-agents provide a way to monitor components other than web services, such as Enterprise JavaBeans (EJBs), databases (via JDBC), and remote method invocation (RMI) components. Nano-agents can also be used to monitor JAX-RPC web services on platforms where you do not want to install apContainer. You deploy apMonitorNode in any application server where you want to monitor observer-discovered services. Nano-agents provide a way to monitor ASP.NET web services.

  • apEProxy contains a deployment for the proxy agent. You use this deployment unit to install a proxy agent in an application server that does not support a container service. This type of proxy installation is called an open agent. See the Business Transaction Management online documentation for more information.

  • apamshelp contains the online help. You deploy apamshelp to both the node where apMain is deployed and the node where apPerformanceServer is deployed.

1.1.2 Sample Applications

The Business Transaction Management ZIP file contains two sample applications: Tutorial and Bookmart. Each application consists of a web service deployment and a client application. These applications are located in the install_dir\samples\applications directory of your unzipped Business Transaction Management distribution. You can deploy these applications in any application server where a container service is deployed. In addition to using these applications with the tutorials provided in the documentation, you can discover the sample services to verify your installation.

1.1.3 Business Transaction Management Databases

Business Transaction Management is distributed with an embedded database. This database is included for use in demonstrations and other non-production situations, such as training. If you plan to use this embedded database, no further setup is required.

For production and other long-lived installations, you must set up an external, enterprise database.

1.2 Example Environment

Although you can install all the Business Transaction Management components into a single container, this is not the recommended deployment scenario. Single-container installation is useful for demonstrations and for learning how to use the product, however this scenario might not scale successfully, depending on the number of business services or volume of message traffic, just to name a few factors.

For example, we recommend that you deploy the apPerformanceServer and apTransactionServer components on separate machines than that containing apMain. These components typically perform a large amount of performance analysis computations. Dividing processes across CPUs/environments will allow you to control memory and processor resources.

If you choose to configure Business Transaction Management components on a single server for demonstration or training purposes, see Section 2.6, "Installing Business Transaction Management on a Single Node"

The diagram below shows a typical distributed application environment, and the relationship of the Business Transaction Management components to that environment.

Figure 1-1 Deployment of Business Transaction Management components in a typical application environment

Graphic showing deployment of product.

1.3 Installation Overview

Installation of Business Transaction Management consists of deploying the Business Transaction Management application components on the appropriate nodes in your environment. As described above, Business Transaction Management is designed for distributed installation and Business Transaction Management components are typically deployed on multiple nodes in your environment.

Table 1-1 Business Transaction Management software distribution packaging

Deployment Name Sub-deployments Deployment strategy

apMain

apasc

apcentral

apcontainer

exmui

f5Intermediary

Deploy once per Business Transaction Management environment

apPerformanceServer

apcontainer

apwebui

aqms

domain

notifier

Deploy once per Business Transaction Management environment, on a separate node from apMain and apTransactionServer.

apTransactionServer

apcontainer

apexmrt

Deploy once per Business Transaction Management environment, on a separate node from apMain and apPerformanceServer.

apContainer

apcontainer

Deploy on each node where you want to monitor business services with a plug-in agent. In order to implement plug-in agents in a WebLogic 9.2 managed server environment, you must deploy apContainer on the Admin Server.

apProxyNode

apcontainer

Eproxy

Deploy on each node where business services will be managed with proxy or plug-in agents.

apEProxy

eProxy

Deploy on any node where you need an open agent (see the online documentation for more information).

apMonitorNode

apmonitor

apcontainer

Deploy on any node where you want to monitor objects other than web services. The nano-agent processor is used in conjunction with the nano-agent observer (see the Business Transaction Management online documentation for more information).

apamshelp

apamshelp

Deploy twice—once on the node on which apMain is deployed and once on the node on which apPerformanceServer is deployed.

bookmart

bookmart

Sample application

bookmartClient

bookmartClient

Client interface for bookmart sample application

tutorial

tutorial

Sample application

tutorialBackup

tutorialBackup

Additional copy of tutorial sample application for failover tutorial

tutorialClient

tutorialClient

Client interface for tutorial sample application

1.4 Configuration Overview

Once you have deployed Business Transaction Management, you configure it using the browser-based configuration wizard. You can also use a command line script (see Chapter 4, "Scripted Configuration of Oracle Business Transaction Management"). For first-time configuration, we recommend that you use the browser-based wizard. The wizard produces an XML output file that can be used with the command line script for subsequent configurations.

The general configuration procedure includes the following steps:

  • choose the type of database (if you use an enterprise database you must set it up prior to configuring BTM)

  • identify the sphere URL—the default provided in the wizard is usually correct unless you are running HTTPS

  • specify administrative credentials for the container into which the sphere is installed

  • specify the URL of the performance component

  • specify the URL of the transaction component

  • specify administrative credentials for the container into which the performance components are installed

After completing the initial setup, register each container into which you have deployed apContainer. You can register a container from the Business Transaction Management Console or by using the registerContainer command.

1.5 Upgrading

Oracle recommends that all new customers start with release 6.5. Similarly, existing customers with early stage projects should upgrade to release 6.5. We recommend that customers with existing production deployments, especially those that include customized solutions, work with the Oracle consulting team to plan their upgrade to release 6.5.

1.5.1 Before you Begin

Observe the following notes before you begin the upgrade procedure.

1.5.1.1 General Notes

  • You must install the later version of Business Transaction Management in the same location as the existing version.

  • Upgrading plug-in agents is not supported. You must remove the plug-in agents before upgrading, and then re-implement them in the later version.

  • You must upgrade the apPerformanceServer, apTransactionServer, and apMain at the same time.

  • You can perform a rolling upgrade of other containers running deployments such as apContainer, apEProxyNode, and apMonitorNode, however long-term mixed version systems are not supported.

  • Backup the Business Transaction Management persistent storage directories and databases before you begin the upgrade procedure.

1.5.1.2 Transaction Server Notes

  • If you are using the apTransactionServer and have built correlations, you must upgrade all Business Transaction Management components at the same time. Note that you are not required to update your release 6.1 observers.

  • If you are using correlations with plug-in agents, you must export the correlations before uninstalling the plug-in agent. You will then import the correlations once the new version of Business Transaction Management is up and running (after you reinstall the plug-in agents).

1.5.2 Upgrade Procedure

To upgrade from release 6.1 to 6.5, do the following:

  1. If you are using correlations that include services managed with plug-in agents, use the exportCorrelations utility to export the correlations. The utility is located in the apTransactionServer_install_dir\tools directory. If you have mapped customers to messages, please make a note of them as you will need to remap the relationships after you upgrade.

  2. Remove any plug-in agents from the structure tab on the Network / Services view or the Explorer.

  3. Navigate to the Performance Admin page (from the Administration section of the E-Menu) and remove the plug-in agents listed in the Agents section.

  4. Download the distribution file onto each node where Business Transaction Management components are installed and deploy the appropriate components.

1.5.3 Post-upgrade Steps

  1. Start the Business Transaction Management Console and re-install the plug-in agents.

  2. If you exported correlation definitions, import them now using the importCorrelations utility. Be sure to specify -overwrite none on the command line so that it will not overwrite any existing correlations.

  3. If you are using correlations, check that the correct start message is selected on the Correlation Runtime Setting screen.

  4. If your release 6.1 correlations had logging enabled, you need to manually enable logging after upgrading by editing the correlation runtime settings.

  5. If necessary, remap customers to correlations.

  6. Navigate to the Network / System view and check the status of the LTA_Service. If it is running and working correctly, no further steps are required. If the LTA_Service is degraded, add ap-mto-runtime.jar into the WebLogic CLASSPATH of every service that hosts a container service (servers hosting apMain, apContainer, apMonitorNode, or apProxyNode). This JAR file is located in install_dir/archives. Add the JAR file to the CLASSPATH by editing WebLogic_install_dir\user_projects\domains\domainName\bin\startWeb-Logic.cmd.

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

    Note:

    If you point to the JAR files in the archives directory, be sure this directory does not get deleted.