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

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.
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:

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.
Remove any plug-in agents from the structure tab on the Network / Services view or the Explorer.
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.
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

Start the Business Transaction Management Console and re-install the plug-in agents.
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.
If you are using correlations, check that the correct start message is selected on the Correlation Runtime Setting screen.
If your release 6.1 correlations had logging enabled, you need to manually enable logging after upgrading by editing the correlation runtime settings.
If necessary, remap customers to correlations.
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, shut down the server and install ap-mto-runtime.jar into the WAS_install_dir/lib directory of every server that hosts the container service (servers hosting apMain, apContainer, apMonitorNode, apProxyNode, apPerformanceServer, and apTransactionServer). You can find this JAR file in install_dir/archives.

Restart the server.