2 Installing and Configuring Oracle Business Transaction Management

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.

-Dcom.amberpoint.IdentityAssertion.SharedSecret=MySecretString

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

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

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

2.2 Setting up your WebLogic Environment

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:

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

2.5 Installing Business Transaction Management on Production Systems

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

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.