Contents

Title and Copyright Information

Preface

Audience

Documentation Accessibility

Conventions

1 Introduction

Deployment Environment

Business Transaction Management Components

Business Transaction Management Database

Example Environment

Installation Overview

Configuration Overview

2 Installing and Configuring Oracle Business Transaction Management

Upgrading from a Previous Version of Release 11g

Before You Install

Configuring Security

Configuring the Shared Secret

Configuring the Encryption Key

Setting up your WebLogic Environment

Setting up your WebSphere Environment

Mapping Users to Business Transaction Management Application Roles

Mapping WebLogic Users to Business Transaction Management Roles

Mapping WebSphere Users to Business Transaction Management Roles

Setting up your Business Transaction Management Databases

Database Notes

Installing Business Transaction Management

Initial Configuration of Business Transaction Management

3 Starting and Shutting Down Oracle Business Transaction Management

Logging in to the Management Console

Logging out of the Management Console

Shutting Down Business Transaction Management

Documentation

4 Scripted Configuration of Oracle Business Transaction Management

The configure Command

Invoking the CLI

Oracle® Business Transaction Management

Installation Guide

11g

E20124-03

June 2011

Oracle Business Transaction Management Installation Guide, 11g

E20124-03

Copyright © 2011, Oracle and/or its affiliates. All rights reserved.

Primary Author: Alan Davidson 

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Preface

Oracle Business Transaction Management Installation Guide explains how to install the Business Transaction Management 11g central servers and monitors on the following application servers:

Oracle WebLogic 10.3.2, 10.3.3, or 10.3.4

IBM WebSphere 7.0

This guide does not provide instructions for installing Business Transaction Management observers or for replicating monitors. For information on those topics, refer to the Business Transaction Management online help.

Audience

This document is intended for system administrators and others who want to install Business Transaction Management 11g.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.

Conventions

The following text conventions are used in this document:

Convention | Meaning
boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.
italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Introduction

This guide explains how to install Business Transaction Management central servers and monitors. It does not provide instructions for installing Business Transaction Management observers or for replicating monitors. For information on those topics, refer to the Business Transaction Management online help.

Oracle distributes the Business Transaction Management central servers and monitors 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.

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.

Business Transaction Management Components

At the highest level, Business Transaction Management consists of three types of components:

Central servers – The central servers are application EAR files that you deploy to an application server. There are three central servers. You deploy only one instance of each of these servers, and for performance considerations you should deploy each to a separate application server. You must not deploy any of the central servers to an application server that hosts services or components you intend to monitor. The central servers are:

Main Server (btmMain.ear) – Contains all the central Business Transaction Management system services and user interface applications, including the sphere. The sphere is the Business Transaction Management component that manages the Business Transaction Management environment. In addition, btmMain.ear contains subdeployments for the web-based user interface and the F5 intermediary.

Performance Server (btmPerformanceServer.ear) – Contains the service-level management components. Deploy btmPerformanceServer.ear on an application server other than where btmMain.ear or btmTransactionServer.ear are deployed.

Transaction Server (btmTransactionServer.ear) – Contains the transaction management components. You deploy btmTransactionServer.ear on an application server other than where btmMain.ear or btmPerformanceServer.ear are deployed.

Observers – Observers are sets of libraries that you install into the application server that hosts the business applications you want to monitor. The observers monitor messages and calls between the components of your applications. Observers are capable of monitoring many types of components, and are classified according to the type that they monitor, for example, JAX-WS, JAX-RPC, EJB, JDBC, etc. Installation of observers is not explained in this guide. Refer to the Business Transaction Management online help for information about installing observers.

Monitors (btmMonitor.ear) – Monitors collect application performance and usage measurements from observers. The monitor is an application EAR file that you deploy to an application server. For large systems, you can deploy multiple monitors, either as singletons or replicates. For performance reasons, you should not deploy the monitor on an application server where the central servers are deployed.

Business Transaction Management Database

Business Transaction Management requires an Oracle RDBMS.

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 btmPerformanceServer and btmTransactionServer components on separate machines than that containing btmMain. 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.

You should also deploy btmMonitor on a machine separate from the other Business Transaction Management components. Depending on your monitoring requirements, you might need to deploy multiple instances of btmMonitor. You can deploy multiple instances of btmMonitor either as individual instances or as replicated instances behind a load balancer. For information about replicating btmMonitor, refer to the online help topic entitled, “Replicating the Monitor”.

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

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

btmMain

btmcentral

btmcontainer

btmhelp

btmui

f5Intermediary

Deploy once per Business Transaction Management environment.

btmPerformanceServer

btmcontainer

btmperformance

Deploy once per Business Transaction Management environment, on a separate node from btmMain and btmTransactionServer.

btmTransactionServer

btmcontainer

btmtransaction

Deploy once per Business Transaction Management environment, on a separate node from btmMain and btmPerformanceServer.

btmMonitor

btmmonitor

Deploy on as many nodes as needed. The monitor is used in conjunction with the observer (see the online help for more information about observers or replicating the monitor).

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 "Scripted Configuration of Oracle Business Transaction Management" for more information). 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:

Provide the connection information for your database.

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

Specify the URL of the performance component.

Specify the URL of the transaction component.

2 Installing and Configuring Oracle Business Transaction Management

This chapter describes how to install and configure Business Transaction Management on the following platforms:

Oracle WebLogic 10.3.2, 10.3.3, or 10.3.4

IBM WebSphere 7.0

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:

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

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:

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.

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.

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.

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

Restart the central servers.

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.

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>

Configuring Security

Communications between Business Transaction Management components are secured by way of trusted assertions. This means that for your Business Transaction Management components to communicate with each other, and for your Business Transaction Management installation to function properly, every Business Transaction Management component must be configured with the same value for the shared secret.

Business Transaction Management also encrypts sensitive data contained in the communications between its components. It encrypts this data for both on-the-wire communications and storage in the Business Transaction Management databases.

These security mechanisms are enabled by default, and all Business Transaction Management components are preconfigured with a default value for both the shared secret and the encryption key. This default security configuration fully enables the security mechanisms and, at the same time, simplifies the installation of Business Transaction Management.

However, because every Business Transaction Management installation uses the same default values, using the default values is a potential security threat. For demonstration purposes, and perhaps for development environments, using the default values might be adequate. But, in production environments, you should tighten security by providing your own unique values. You should also use your own values in your test environment before deploying Business Transaction Management into your production environment. If you intend to provide your own values, you should perform that configuration on each machine hosting a Business Transaction Management component before you deploy the component.

Configuring the Shared Secret

You must configure the shared secret on each application server that hosts a Business Transaction Management component. To configure the shared secret, create a Java system property named com.amberpoint.IdentityAssertion.SharedSecret in the server and set its value to your shared-secret string, for example:

-Dcom.amberpoint.IdentityAssertion.SharedSecret=MySecretString

where MySecretString is your own secret string.

Configuring the Encryption Key

You must configure the encryption key on each application server that hosts a Business Transaction Management component. To configure the encryption key, create a Java system property named com.amberpoint.security.encryption.aes.defaultKey in the server and set its value to your encryption key, for example:

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

where MyEncryptionKey is a base 64-encoded, AES, 128-bit key.

After generating your encryption key, you can copy and paste it in order to set the value of your com.amberpoint.security.encryption.aes.defaultKey property. If your key includes special characters, you should enclose it in double quotes, for example:

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

Setting up your WebLogic Environment

Note:

If you are using WebLogic Node Manager, you will use the WebLogic Administrative Console to adjust settings rather than edit scripts.

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

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

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.

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

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.

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.

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.

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.

Mapping WebLogic Users to Business Transaction Management Roles

Business Transaction Management applications rely on the WebLogic container for authentication and association of roles with users. The role of Business Transaction Management administrator (btmAdmin) is automatically mapped to the Administrators group defined in your WebLogic server. The role of Business Transaction Management user (btmUser) is mapped to the groups Operators and Monitors. The role of Business Transaction Management observer (btmObserver) is mapped to the group Everyone, granting all authenticated users observer privileges. The following table lists the Business Transaction Management application roles and their default container role mapping:

Table 2-1 Role Mapping in WebLogic

Business Transaction Management Application Roles
Container Group

btmAdmin

Administrators

btmUser

Operators, Monitors

btmObserver

Everyone

btmInspector

btmInspector

You can modify these default mappings in the WebLogic deployment descriptor file (weblogic.xml). For more information on setting up user accounts and assigning roles, see the “Authentication and Role Mapping” topic of the Business Transaction Management online help.

Mapping WebSphere Users to Business Transaction Management Roles

The application role of Business Transaction Management administrator (btmAdmin) is automatically mapped to the Administrators group on Windows systems, or the adm, sys, and bin groups on Unix-like systems. The roles of Business Transaction Management user (btmUser) and observer (btmObserver) are mapped to all authenticated users on your system. Note that the default mapping assumes the WebSphere security value of Local OS setting for the Active user registry setting. If you are using a different security setup, you may have to remap users/groups based on your authentication domain settings. The table below lists the Business Transaction Management application roles and their default container role mapping:

Table 2-2 Role Mapping in WebSphere

Business Transaction Management Application Roles
Container Group

btmAdmin

Administrators

btmUser, btmObserver

all authenticated users

btmInspector

btmInspector

You can change these mappings using the WebSphere Administrative Console. For information on setting up user accounts and assigning roles, see the “Authentication and Role Mapping” topic in the Business Transaction Management online help. Log in to the Business Transaction Management Management Console using credentials from an account in one of these groups.

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

Note:

Your DBA can manually create the tables and indexes for the sphereDB, measurementDB, and transactionDB databases using the datastoreUtil utility. You can find this utility in the tools directory of your Business Transaction Management installation. This utility generates the appropriate schema definitions. Documentation on this utility is provided in the online help. You can access the online help after you install Business Transaction Management and start the Initial Configuration wizard. The wizard provides a Help button.

Database Notes

Put the database driver in the classpath of your application server.

Each Business Transaction Management database must be in a separate schema. For example, you must create a separate user for each Business Transaction Management database.

Your database must be configured to support:

SQL Authentication Mode

TCP/IP connections

The messageLogDB can be shared by multiple monitors.

Installing Business Transaction Management

Note:

These instructions assume that if you are installing onto WebLogic servers, you are using managed instances of WebLogic.

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

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:

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.

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.

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

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.

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

Start the deployments.

Initial Configuration of Business Transaction Management

Note:

For first-time configuration, we recommend that you use the browser-based Configuration wizard, as described below. However, for subsequent installations, you might want to use the Command Line Interface (CLI) to perform a scripted configuration of Business Transaction Management. For more information, see "Scripted Configuration of Oracle Business Transaction Management".

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.

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

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

The Database Type page opens.

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

The External Database Configuration page opens.

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.

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.

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.

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

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

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

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

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.

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.

3 Starting and Shutting Down Oracle Business Transaction Management

Starting the application server automatically starts Business Transaction Management.

After starting Business Transaction Management, you access its facilities and administer it using a web-based interface called the Business Transaction Management Console (or the Management Console).

Logging in to the Management Console

Open a URL of the following form in a web browser:

http://hostname:port/btmui

Replace hostname:port with the name of the machine on which you installed btmMain, and the port number on which it is accessible.

The web browser will display a log-in page. Log in using the appropriate credentials, as described in Mapping Users to Business Transaction Management Application Roles.

Logging out of the Management Console

To log out of the Management Console, click the Logout link in the upper-right corner of the page.

Shutting Down Business Transaction Management

You can shut down (and restart) Business Transaction Management using the application server's administration console.

Documentation

You can access Business Transaction Management documentation by clicking the Help button in the Management Console.

4 Scripted Configuration of Oracle Business Transaction Management

As stated earlier in this document, when you configure Business Transaction Management for the first time, we recommend that you use the browser-based Configuration Wizard. For users who want to later execute various configuration tasks from the command line, a command line interface (CLI) is provided.

The CLI provides command-line equivalents to many configuration tasks. The CLI command relevant to this document is the configure command. This command provides an alternative to the wizard approach to configuration.

You can find complete documentation for the configure command, as well as the entire CLI, in the Business Transaction Management online help.

The configure Command

The configure command takes an XML configuration file as an argument. This configuration file specifies all the setup information for Business Transaction Management, including database type and connection information, deployment credentials, and so on. You can develop this configuration input file in either of the following ways:

Use a sample file that is provided with the Business Transaction Management distribution. Sample application server-specific files are located in:

Install_Dir/samples/cli/config_files/yourAppServerConfig.xml

Install_dir is the directory where you unzipped your Business Transaction Management distribution.

Use the generated configuration file that is output when you perform initial configuration of Business Transaction Management using the browser-based Configuration Wizard. The wizard produces a configuration file that contains all the configuration information (sphere URL, database connection information, performance server location, authentication credentials, and so on). You can use this configuration file as input to the configure command. The generated configuration file is named essentialConfiguration.xml.

On WebLogic servers, essentialConfiguration.xml is located inside the WebLogic installation directory at:

user_projects/domains/MyDomain/servers/MyServer/btmstorage/MyDomain/globalPreferences

On WebSphere servers, essentialConfiguration.xml is located inside the WebSphere installation directory at:

profiles/MyProfile/btmstorage/MyNode/MyServer/btmMain/globalPreferences

Invoking the CLI

The CLI executable is located in the Install_Dir/tools directory—btmcli.bat for Windows and btmcli.sh for Unix-like systems.

Command syntax for use with the configure command:

btmcli configure -i inputFile -s sphereUrl -l username:password

You can avoid placing the username and password on the command line by setting the AP_USER_LOGIN environment variable before executing the CLI, for example:

set AP_USER_LOGIN=MyUsername:MyPassword

Deployment of Business Transaction Management components in a typical application environment. At left are three containers running btmMain, btmPerformanceServer, and btmTransactionServer. In the middle are two containers running btmMonitor. On the right are three containers running business services that are monitored by observers.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2010, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

Hazardous Applications Notice

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Trademark Notice

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Third-Party Content, Products, and Services Disclaimer

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.