Oracle® Business Transaction Management

Installation Guide for WebLogic Server

Release 6.5

E18070-01

July 2010

Oracle Business Transaction Management Installation Guide for WebLogic Server, Release 6.5

E18070-01

Copyright © 2010, 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.

Contents

List of Figures

List of Tables

Preface

- Audience

- Documentation Accessibility

- Conventions

1 Introduction

- 1.1 Deployment Environment

- 1.1.1 Business Transaction Management Components

- 1.1.2 Sample Applications

- 1.1.3 Business Transaction Management Databases

- 1.2 Example Environment

- 1.3 Installation Overview

- 1.4 Configuration Overview

- 1.5 Upgrading

- 1.5.1 Before you Begin

- 1.5.1.1 General Notes

- 1.5.1.2 Transaction Server Notes

- 1.5.2 Upgrade Procedure

- 1.5.3 Post-upgrade Steps

2 Installing and Configuring Oracle Business Transaction Management

- 2.1 Before you Begin

- 2.1.1 Configuring Security

- 2.1.2 Configuring the Shared Secret

- 2.1.3 Configuring the Encryption Key

- 2.2 Setting up your WebLogic Environment

- 2.3 Mapping Users to Business Transaction Management Application Roles

- 2.4 Setting up your Business Transaction Management Databases

- 2.4.1 Database Notes

- 2.5 Installing Business Transaction Management on Production Systems

- 2.6 Installing Business Transaction Management on a Single Node

- 2.7 Installing the Online Help

- 2.8 Configuring Business Transaction Management

3 Starting and Shutting Down Oracle Business Transaction Management

- 3.1 Logging in to the Business Transaction Management Console

- 3.2 Logging out of the Business Transaction Management Console

- 3.3 Shutting down Business Transaction Management

- 3.4 Documentation

4 Scripted Configuration of Oracle Business Transaction Management

- 4.1 Invoking the CLI

- 4.2 The Configure Command

- 4.3 The registerContainer Command

List of Figures

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

List of Tables

- 1-1 Business Transaction Management software distribution packaging

- 2-1 Role Mapping in WebLogic

Preface

Oracle Business Transaction Management Installation Guide for WebLogic explains how to install Business Transaction Management (6.5) on WebLogic servers. This guide also explains how you can upgrade Business Transaction Management from release 6.1 to 6.5.

Audience

This document is intended for system administrators and others who want to do the following:

- Install Business Transaction Management (6.5) on WebLogic servers.

- Upgrade Business Transaction Management from release 6.1 to 6.5.

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

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

2 Installing and Configuring Oracle Business Transaction Management

This chapter describes how to install and configure Business Transaction Management on Oracle WebLogic.

2.1 Before you Begin

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 running Business Transaction Management on Unix-like systems, you must restart your web server with the following property set before you run reports using the Business Transaction Management performance component:

-Djava.awt.headless=true

- If you are installing Business Transaction Management into an HTTPS environment, you must ensure that your network conforms to the following conditions before you configure Business Transaction Management:

- Every component of your network that is registered with the Business Transaction Management sphere must be running SSL, and must communicate through the same Business Transaction Management sphere entry URL and port.

- You cannot mix HTTP and HTTPS URLs or ports within your Business Transaction Management servers.

- All application server names within your network must resolve consistently. In other words, application servers must be known to all components by the same host name.

2.1.1 Configuring Security

Communications between Business Transaction Management components are secured by way of a 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 (except for Business Transaction Management observers) 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 (machines hosting only Business Transaction Management observers do not need to be configured in this way).

2.1.2 Configuring the Shared Secret

You must configure the shared secret on each WebLogic server that hosts a Business Transaction Management component other than a Business Transaction Management observer. 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.

2.1.3 Configuring the Encryption Key

You must configure the encryption key on each WebLogic server that hosts a Business Transaction Management component other than a Business Transaction Management observer. 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.

Business Transaction Management provides a command line tool utility named genseckey.bat that you can use to generate a base 64-encoded, AES, 128-bit key. You can access this utility after you download and unzip the Business Transaction Management distribution ZIP file. The utility is located in the tools directory at the top level of the expanded archiveTo generate a base 64-encoded, AES, 128-bit key, run the utility without any flags, for example:

C:> genseckey
Provider     = SunJCE
Algorithm    = AES
Key strength = 128 bits (in 16 bytes)
Key value    = oylJKoTGXTHasOYwtjwA7g==

Note that in this example, the generated key happens to include two equal symbols (==) at the end of the string.

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=="

2.2 Setting up your WebLogic Environment

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

1. If you are using an external database, add the appropriate database driver to the WebLogic CLASSPATH.

2. Add ap-mto-runtime.jar into your WebLogic CLASSPATH of every server that hosts a container service (servers hosting apMain, apContainer, apMonitorNode, or apProxyNode). This JAR file is located in install_dir/archives. Note that if you do not install ap-mtoruntime.jar on the server running apMain, several Business Transaction Management system services will be displayed as degraded in the Business Transaction Management Console.
To add the JAR file to your CLASSPATH, edit WebLogic_install_dir\user_projects\domains\domainName\bin\startWebLogic.cmd. If you perform this edit while the server is running, be sure to restart WebLogic before configuring BTM.

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

3. Increase the server memory by opening your domain's setDomainEnv.cmd file in a text editor and editing the following settings (note these are minimum recommendations; the setDomainEnv.cmd file is located in your domain's bin directory):

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

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

4. In the domain in which you will install Business Transaction Management, ensure that the listen address property for the Business Transaction Management domain 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.

5. Set up an administrative user.
Business Transaction Management maps roles defined in WebLogic to its own application roles. See Chapter 2, "Mapping Users to Business Transaction Management Application Roles".

2.3 Mapping Users to Business Transaction Management Application Roles

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

To configure Business Transaction Management, you must log in as a user with the amfadmin 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.

Business Transaction Management applications rely on the WebLogic container for authentication and association of roles with users. The roles of Business Transaction Management administrator (amfadmin, slmadmin, exmadmin) are automatically mapped to the Administrators group defined in your WebLogic server. The roles of Management Console user (amfuser, slmuser, exmuser) are mapped to the groups Operators and Monitors. The roles of Business Transaction Management observer (amfobserver, slmobserver, exmobserver) are 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

amfadmin

exmadmin

slmadmin

Administrators

amfuser

exmuser

slmuser

Operators, Monitors

amfobserver

exmobserver

slmobserver

amf_limited_observer

exm_limited_observer

slm_limited_observer

amf_proxy_user

exm_proxy_user

slm_proxy_user

Everyone

exm_inspector

exm_inspector

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.

2.4 Setting up your Business Transaction Management Databases

Several Business Transaction Management system services use a database to store persistent information. In addition, another database is used to store agent message logs. The embedded database is supplied primarily for demonstrations and for situations where you will not need to migrate data. We encourage you to use an external, enterprise database management system when you initially configure Business Transaction Management, as migrating between different database systems at a later time is typically complicated). The following enterprise database management systems are supported for use with Business Transaction Management running on a WebSphere server:

- Oracle 10g

- Oracle 11g

- MS SQL Server 2000

- MS SQL Server 2005

- IBM DB2 UDB v.8.1

- Sybase ASE 12.5

Before you configure Business Transaction Management, create the following databases (these are suggested names):

- sphereServiceDB

- performanceDB

- exmServiceDB

- agentServiceDB

You must create the databases before starting configuration of Business Transaction Management. When you configure Business Transaction Management (see Chapter 2, "Configuring Business Transaction Management"), the system will automatically create the database tables. If you intend to let the system automatically create the tables, the user under which the database is run must have create table, create index, and create view privileges. (Note: For an Oracle database is not sufficient to assign the privileges to the roles associated with the user. You must explicitly assign the privileges to the user.)

Note:
If your DBA wants to create the database tables manually, Business Transaction Management supplies the datastoreUtil tool, located in the install_dir\tools directory. This utility generates the appropriate schema definitions. Please refer to the Business Transaction Management online documentation for information about this tool.

2.4.1 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, if you are using an Oracle RDBMS you must create a separate user for each Business Transaction Management database.

- If you are preparing an IBM DB2 UDB database, you must ensure that it is configured with 16k table space, 16k user temporary table space, and 16k system temporary table space (by default, IBM DB2 UDB databases are configured with 4k table spaces).

- For Sybase ASE, note the following:

- The option 'DDL in tran' should be set to true. You can set this through the Sybase central gui application or with the sp_dboption stored procedure.

- The option 'select into' should be set to true. You can set this through the Sybase central gui application or with the sp_dboption stored procedure.

- Your database must be configured to support:

- SQL Authentication Mode

- TCP/IP connections

- The agentServiceDB can be shared by multiple agents.

- For SQL Server, note the following:

- Business Transaction Management requires that the default language associated with a user has a MDY or YMD date format. The simplest way to satisfy this requirement is to use English as the default language. Note that the default language setting does not affect the language of data stored in the database.

- SQL Server 2005: The Business Transaction Management performance server uses an outer join syntax that is not supported by default by SQL Server 2005. In order to ensure that the performance server will work correctly with your MS SQL Server 2005 database, please issue the following isql command:

sp_dbcmptlevel @dbname = "performanceDB", @new_cmptlevel = 80

2.5 Installing Business Transaction Management on Production Systems

Note:
These instructions assume you are using managed instances of WebLogic.

1. Download the distribution file and unzip it into a directory (referred to as install_dir ).

2. If you haven't already done so, configure the security settings explained in the section “Configuring security” on page 6.

3. If you haven't already done so, download Current.license.xml and place it in a temporary directory.

4. In the WebLogic Administrative Console, deploy the following applications (located in install_dir\archives):

- Deploy apContainer on the Admin Server.

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

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

- Deploy apTransactionServer once on a machine other than the machine on which apMain and apPerformanceServer are deployed.

- Deploy apProxyNode on every application server that hosts business services that you want to place under management with proxy agents (use apContainer if you plan on using only plug-in agents).

- Deploy apMonitorNode on every application server where you want to monitor objects other than web services.

- Deploy apContainer on every application server where you want to monitor business services with plug-in agents only.

- (Optional) Deploy sample applications in a managed server instance that is hosting a container service. Sample applications are located in install_dir\samples\applications\WebLogic9.

5. Start all managed servers where you installed apContainer, apProxyNode, or apMonitorNode, including the Admin server.

6. Start the deployments.

2.6 Installing Business Transaction Management on a Single Node

Oracle supplies a version of Business Transaction Management that is packaged for single-node installation. This packaging of the product is intended for demonstration and training purposes, only. Download and extract AMSJavaDemo.zip, and then deploy apDemo (located in install_dir\archives). Next, configure Business Transaction Management as described below, noting that the URLs for the performance transaction servers use the same port and host name as the sphere, and that both servers start when you start the sphere server.

2.7 Installing the Online Help

The Business Transaction Management online help is packaged as a web application. Install the online help as follows:

- Locate apamshelp.ear in install_dir/archives.

- Use the WebLogic deployment tool to deploy apamshelp.ear onto the server where apMain or apDemo is deployed.

- Repeat step 2 for the server where apPerformanceServer is deployed.

2.8 Configuring Business Transaction Management

Note:
You can use the Business Transaction Management Command Line Interface (CLI) to perform a scripted configuration of Business Transaction Management. For first-time configuration, we recommend that you use the browser-based Initial Configuration Wizard, as described below. See Chapter 4, "Scripted Configuration of Oracle Business Transaction Management".

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

http://host_name: port_number/apasc

The Management Console appears.

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

3. Accept the End User License Agreement and click Next.

4. If you plan to use the Embedded Database, leave this radio button selected as the default and click Next. If you have set up an external database and created the required tables (as described in Section 2.4, "Setting up your Business Transaction Management Databases"), select the Enterprise Database radio button and click Next.

5. (If you are using an enterprise database) Fill out the connection information for the databases you are using for the system services. Be sure to use the same database names as the ones you created when you set up your databases. Note that the information you specify on this screen will carry forward and populate the agent message log database fields in step 9. Click Next when you complete this screen.

6. Double-check the default URL for the sphere—in most cases the default should be correct (unless you are running in an HTTPS environment) and you should just click Next.
Typically you install the sphere on the same machine where you install the user interface. If this is not the case, modify the sphere URL appropriately and 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 uninitialized. 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.

7. Enter the credentials of a user in your application server's Administrators group.

8. If you are using an embedded database, no database information is required, so click Next.

9. Check the database information for the agent message log database (it uses the information you specified in step 5), and then click Next.

10. Enter the URL to the container in which you installed apPerformanceServer (http://host_name:port/apcontainer/container). Make sure that you deploy apPerformanceServer before you exit this screen.

11. Enter a set of credentials of a user in the Administrator's group of the application server instance in which apPerformanceServer is deployed.

12. Enter the URL to the container in which you installed apTransactionServer (http://host_name:port/apcontainer/container). Make sure that you deploy apTransactionServer before you exit this screen.

13. Enter a set of credentials of a user in the Administrator's group of the application server instance in which apTransactionServer is deployed.

14. View the Summary information and click Finish.
Business Transaction Management validates the information you supplied during configuration, and if all the information checks out, configuration completes successfully and the Business Transaction Management Console appears.

If any configuration information cannot be validated, the following message is displayed: “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. 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 documentation. Navigate to the book “Administering and configuring AMS”, and then the sub-book “Administering Databases”.

15. Register remote application servers with the sphere.
For each node on which you deployed apContainer, apProxyNode, or apMonitorNode, you must register the application server into which the container service was deployed.

To register an application server:

1. Navigate to the Network / Infrastructure view in the Management Console.

2. Select Register > Container and refer to the online help if you need more information.
Note that Business Transaction Management provides the registerContainer command to support scripted registration of application servers. See the Business Transaction Management online documentation for more information. Navigate to the book “Administering and configuring AMS”, and then the sub-book “Command Line Utilities/AmberPoint command line interface” (CLI).

3. Repeat for each node that hosts apContainer, apProxyNode or apMonitorNode.

3 Starting and Shutting Down Oracle Business Transaction Management

Starting the WebLogic 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.

3.1 Logging in to the Business Transaction Management Console

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

http://host_name:port/apasc

Note that if you are using Firefox, a log-in page is displayed. Log in using the appropriate credentials, as described in Section 2.3, "Mapping Users to Business Transaction Management Application Roles". If you are using Internet Explorer, you must be logged into Windows with the appropriate credentials.

3.2 Logging out of the Business Transaction Management Console

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

3.3 Shutting down Business Transaction Management

You can shut down (and restart) Business Transaction Management using the WebLogic server's Administration Console.

3.4 Documentation

You can access Business Transaction Management documentation by clicking the Help button in the Business Transaction Management Console. The documentation is presented in an online help format. The documentation set includes several tutorials as well as context-sensitive help topics.

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 execute various aspects of the configuration from the command line, a Command Line Interface (CLI) is provided.

The CLI provides command-line equivalents to many configuration tasks. Relevant to this document, which describes configuration of Business Transaction Management using the browser-based configuration wizard, are the configure and registerContainer commands. Both of these commands are part of the CLI and provide an alternative to the wizard approach to configuration.

Complete documentation for the configure and registerContainer commands, as well as the entire CLI, can be found in the Business Transaction Management online help. In the Table of Contents, navigate to Administering and configuring AMS, and then the sub-topic Command line utilities/Command line interface.

4.1 Invoking the CLI

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

Command syntax:

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

4.2 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

Business Transaction Management_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 located at the following location after you have used the Configuration Wizard:

appServer_install_dir/amberpoint/globalPreferences/essentialConfiguration.xml

4.3 The registerContainer Command

The registerContainer command takes an XML configuration file as an argument. This configuration file specifies all the setup information for the application server, including agent message log database type and connection information, deployment credentials, and so on. A sample configuration file that you can use to create your own file is located in:

install_dir/samples/cli/config_files/RegisterContainer.xml

Invoking the CLI

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

Command syntax:

ap registerContainer -i inputFile -s sphereUrl -l username:password

Oracle Legal Notices

Copyright Notice

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

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

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 is software or related documentation that 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 END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware 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 that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware 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.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.