Skip Headers

Oracle® Real User Experience Insight Accelerator for Oracle E-Business Suite Guide Release 5.1 for Linux x86-64 Part Number E14896-02 |
Home | Book List | Contents | Index | Contact Us

Previous | Next
| View PDF

# 1 Installation and Configuration

This chapter describes the procedure for installing the EBS Package, and configuring your application definitions within RUEI to enable the accurate monitoring of EBS-based applications.

## 1.1 Why Use This Accelerator Pack?

This accelerator package for RUEI enables out-of-the-box monitoring of EBS modules. This monitoring supports user session tracking, the discovery of end-user performance issues, and the identification of application issues associated with EBS modules running both the OA and JTT frameworks, as well as Oracle Forms applications running in servlet mode.

This accelerator package automatically discovers all installed EBS modules, and translates network objects to business functions. This facilitates the measurement and monitoring of real-user transactions, from initial query to their commit as part of business transactions. Individual user actions are automatically matched to the correct module, form, or formblock in order to provide contextual analysis. This state-of-the-art monitoring solution supports the creation of KPIs for critical packaged applications, and the analysis of real-user business transactions.

## 1.2 Working Within a Forms-Only Environment

The information presented in this guide is relevant to all EBS customers. However, customers working within a Forms-only environment should pay particular attention to the issues highlighted in this section.

In order for RUEI to accurately report on EBS-based applications, it needs information about your production environment. In particular, it needs to map functional areas to reported names. As explained in Section 1.10, "Synchronizing RUEI With the EBS Production Environment", this is done through running the `create_EBS_info.sh` script. Customers within Forms-only environments are also recommended to run this script and upload the generated .`txt` files.

Manually Creating Functional Mappings

The `create_EBS_info.sh` script uses a number of EBS database tables to retrieve information about the installation and configuration of your Oracle Forms instance. The exact database tables used are fully described in Section 2.2, "Database Tables".

However, the APPLSYS.FND_APPLICATION, APPLSYS.FND_APPLICATION_TL, APPLSYS.FND_FORM, APPLSYS.FND_FORM_TL and other tables used by the script do not exist in a Forms-only environment. Therefore, you can either rely on the default (template) mappings provided with RUEI (described later in this section), or you can specify the required mappings by creating the associated .`txt` files manually.

When creating these files manually, the following tab-separated files are required:

- `EBS_formname2details.txt`: specifies a functional description for each form. Each line in the file should have the following format:

      formname{TAB}form_description

  For example:

      ADSAPCRD        Credit Card Expense Transaction Entry
      ADSAPPRC        Procurement Card Transaction Entry
      ADSCONC         Running Jobs
      ADSCONC         Tax Locations
      ADSCSCRC        Healthcare CC
      ADSMAILI        Mail InformationADSRSETUP       ADS Repurpose Setup
      ADSSOE          Custom Order EntryADSSOE          View Person Life Event Information
      AKDAPREG        Application Module Parameters Registry

- `EBS_formname2appshort.txt`: specifies the short (3-letter) version of the application name of which each form is part. Each line in the file should have the following format:

      formname{TAB}short_application_name

  For example:

      ADSAPCRD        ads
      ADSAPPRC        ads
      ADSCONC         ads
      ADSCSCRC        ads
      ADSMAILI        ads
      ADSRSETUP       ads
      ADSSOE          ads
      AKDAPREG        ak
      AKDATTRS        ak
      AKDFLOWB        ak

- `EBS_appsort2appname.txt`: specifies the mapping between the short (3-letter) application name and the full application name. It has the following format:

      short_application_name{TAB}application_name

  For example:

      abm     Activity Based Management (Obsolete)
      ad      Applications DBA
      ads     Applications Demonstration Services
      ads_dev ADS Development
      ahl     Complex Maintenance Repair and Overhaul
      ahm     Hosting Manager(Obsolete)
      ak      Common Modules-AK
      alr     Alert
      ame     Approvals Management
      amf     Fulfillment Services (Obsolete)

Be aware the created configuration files must be uploaded for each required suite in a .`zip` file. This may only contain non-empty .`txt` files. In addition, all files must be in the root directory. That is, subdirectories are not permitted. It is important you upload the correct configuration file for the required suite, and that it is based on the actual production environment. The procedure to update the configuration file is fully described in Section 1.10, "Synchronizing RUEI With the EBS Production Environment".

Relying on the Default (Template) Mapping

If manually creating the required mappings is not practical, you can simply rely on the default (template) mappings already configured within RUEI. While this approach provides an adequate level of reporting, it is subject to the following restrictions:

- `form_name`: normally this would be the 8-character technical name translated to a functional description. However, because this is not available, the 8-character technical name is reported instead.

- `app`: normally this would be derived from the mapping file that connects the form name with the application. However, because this is not available, the first three letters of the form name are reported instead.

- `application_name`: normally this would be derived from the mapping file. However, because this is not available, the `app` is reported instead. For example, "eds" instead of "Application Demonstration Services" as shown in Figure 2-1.

Keeping Matching Information up-to-date

Because Forms-only environments typically change over time, it is strongly recommended that you regularly review your mapping information. Be aware the above restrictions will also apply to any forms that have been added to your environment since your last ran the `create_EBS_info.sh` script or manually created the mapping files.

## 1.3 Overview

EBS is based on several frameworks. Because these frameworks allow customers to extend their applications with their own functionality, RUEI requires information about their implementation in order to correctly monitor them.

The EBS monitoring functionality provided with this package supports all out-of-the-box EBS functionality, as well as some level of customization. It is possible that certain EBS customizations may provide unexpected reporting results within RUEI. This mainly concerns the mapping of functional areas to reported names.

In order to facilitate the correct monitoring of EBS-based applications by RUEI, you need to do the following:

1. Configure the Oracle Forms server to enable End User Monitoring. While RUEI is 100% non-intrusive, you will need to re-start your EBS server after changing this option.

2. (Optionally) enable Forms over SSL instead of Forms-encryption.

3. Install the package RPMs on the RUEI Reporter system.

4. Verify the scope of monitored traffic.

5. Specify the cookie technology used to track user sessions.

6. Create and configure the EBS suite(s) required for your EBS-based applications.

7. Synchronize the information held within RUEI with the EBS production environment.

8. Verify and evaluate the EBS suite configuration.

Each of these steps are discussed in more detail in the following sections.

## 1.4 Enabling End User or Chronos Monitoring

End User Monitoring is Forms functionality that triggers additional information messages to be sent by the applet to the Web server. These additional messages are required by RUEI to retrieve screen definitions (such as formname) that are otherwise not sent over the connection. End User Monitoring functionality was introduced in Forms 6i as Chronos messaging. This functionality is not available in Oracle Forms 9.0.4. In release 10.1.2 and higher, this functionality is called End User Monitoring.

Depending on the Oracle Forms version you are using, follow the procedure described in the relevant section below. If you are not using Oracle Forms, the rest of this section can be skipped.

Enabling End User Monitoring (for Oracle Forms Version 10.1.2 and Higher)

The following steps are required to activate End User Monitoring for release 10.1.2 and higher.

1. Configure the `$ORACLE_HOME/forms/server/formsweb.cfg` file to enable monitoring of specific applications. Set the following:

       EndUserMonitoringEnabled=true
       EndUserMonitoringURL=http://EBS-hostname:EBS-portnumber/oracle_smp_chronos/oracle_smp_chronos_sdk.gif

2. Restart the Forms server to activate the changes. The changes will only become available for new sessions.

Additional information can be found in the Oracle Application Server Forms Services Deployment Guide 10g Release 2 (10.1.2). This is available at `http://download.oracle.com/docs/cd/B25527_01/doc/frs/forms/B14032_02/chronos.htm#sthref606`. The webcache functionality mentioned in that guide is not required for the correct working of RUEI. The URL mentioned in the guide is incorrect, and is clarified in later release notes.

Enabling Chronos Monitoring (for Oracle Forms Version 6i)

For Forms release 6i, Chronos monitoring should be used as an alternative to the procedure described above. To enable Chronos monitoring, do the following:

1. Ensure that the patch 7130248 for release 6.0.8.28.0 is installed on the Oracle Forms system.

2. Configure the `$ORACLE_HOME/forms/server/formsweb.cfg` file by adding the following lines:

       ChronosEnabled=true
       ChronosURL=http://EBS-hostname:EBS-portnumber/oracle_smp_chronos/oracle_smp_chronos_sdk.gif

   Note:

   The `ChronosEnabled` and `EndUserMonitoringEnabled` settings are case sensitive, and should be set to `true`.

Verifying Chronos End User Monitoring

Verify that Chronos hits are sent by doing the following:

1. Login to Forms.

2. Open the Java console of the JVM in which Oracle Forms is running.

3. Activate trace level 2 by pressing 2.

4. Perform some Forms-based action that leads to a commit.

5. Verify that the reported trace output contains the file `/oracle_smp_chronos/oracle_smp_chronos_sdk.gif`. An example is shown in Figure 1-1:

   Figure 1-1 Java Console

   Description of "Figure 1-1 Java Console"

6. Confirm the hit appears in the log files on the RUEI Reporter system using the following command as the `moniforce` user:

       zgrep oracle_smp_chronos
       $WEBSENSOR_HOME/data/*/http/currentdate/http-*

   Note that the use of the timestamp in the above command is to limit the displayed list. The `currentdate` should be specified in the form `yyyymmdd`.

## 1.5 Enable Forms Over SSL Instead of Forms Encryption

By default, Oracle Forms traffic is send over the HTTP layer. (The socket version is not supported in combination with RUEI). To obscure the information sent over the line, a propriety Forms encryption method is used. This encryption is not assumed to be secure. Instead, the use of SSL encryption is recommended when information is sent over the Internet.

In order to allow RUEI to measure functional errors, Forms-encryption should be disabled, and SSL encryption used instead. Please refer to your Web server's product documentation for information on how to enable SSL encryption. In addition, it is recommended that you read the relevant sections of the Oracle Real User Experience Insight User's Guide for information how SSL-encrypted traffic can be measured within RUEI. The Forms encryption can be influenced by an environment variable set in the `default.env` file used by the Forms server. This variable differs depending on the Forms version. For example:

    FORMS60_MESSAGE_ENCRYPTION=falseFORMS_MESSAGE_ENCRYPTION=false

A restart of the Forms server is required to activate the setting.

## 1.6 Installing the Package RPMs

Important:

The upgrade of an existing Oracle E-Business Suite accelerator package to release 5.1 must be performed at the same time as the upgrade of the RUEI system to version 5.1.

Note it is assumed a working RUEI system has been installed and configured (as described in the Oracle Real User Experience Insight Installation Guide), and is fully operational. Install the EBS support package on the RUEI reporter system using the following commands as the `root` user:

    cd /root/RUEI/51
    rpm -Uhv ux-suites-ebs-*.x86_64.rpm

Note the location of the RPM depends on where you unzipped the package.

## 1.7 Verifying the Scope of Monitoring

Often the EBS software is configured to use a non-standard port, such as 8000. The port on which your EBS installation is running can be found by examining the login URL. This takes the following format:

    https(s)://hostname:portnumber/OA_HTML/AppsLogin

Verify that the `portnumber` is configured as one of the defined ports (HTTP or HTTPS). In addition, if a HTTPS port is specified, ensure that a copy of the Web server's private SSL key is imported into the Collector system.

To verify the port number, do the following:

1. Select Configuration, then Security, and then Protocols. The currently monitored ports are displayed. An example is shown in Figure 1-2:

   Figure 1-2 Monitored Ports

   Description of "Figure 1-2 Monitored Ports"

2. Use the View menu to select each Collector. The System (localhost) item represents the local server system.

3. If the port number is not already listed, click the required protocol (HTTP or HTTPS). The dialog shown in Figure 1-3 appears.

   Figure 1-3 Edit Collector Ports

   Description of "Figure 1-3 Edit Collector Ports"

   To add a new port number, enter the required number in the Port number field, and click Add. The default Oracle Forms port is 8000. Note, if required, this needs to be manually added. To remove a port from the list, click the Remove icon to the right of the port number. When ready, click Save.

4. For each Collector, you are prompted to restart the Collector. This is necessary in order to make your changes effective. Note you can also restart the selected Collector by clicking the Restart Collector icon shown in Figure 1-2.

5. For HTTPS traffic, you should also verify that, for each Collector, the required SSL key is installed by selecting Configuration, then Security, and then SSL keys. Use the View menu to select a Collector. If the host name does not match one of the already listed SSL keys, import the required SSL key. The procedure to do this is fully described in the Oracle Real User Experience Insight User's Guide. In addition, you should verify that the key is not expired, and activated.

## 1.8 Specifying the Cookie Technology

Within RUEI, session information is based on cookies. The cookies are used to connect hits to a specific visit. In general, the cookie is also connected to the user login page which allows RUEI to include a user name to all subsequent hits with the same cookie. There are already some cookies available in EBS. However, these are not generally usable. The main problems with them are they not sufficiently unique (for instance, `oracle.uix`), and not wide enough (for instance, JSESSIONID is only used for the `/OA_HTML/` part of the Web site).

The recommended implementation of client-side cookies is as follows:

1. Add the following code to the EBS login page:

       <SCRIPT
       LANGUAGE="JavaScript">if(document.cookie.indexOf('track=')==-1){document.cookie
       ='track='+parseInt(Math.random()*2147418112)+new
       Date().getTime()+';path=/;domain='+document.location.host.substring(
       document.location.host.lastIndexOf('.',
       document.location.host.lastIndexOf('.') - 1)) ;}</SCRIPT>

2. Select Configuration, then Applications, and then Session tracking. Click Add new cookie. The dialog shown in Figure 1-4 appears.

   Figure 1-4 Custom Cookie

   Description of "Figure 1-4 Custom Cookie"

3. Select the cookie technology (custom) from the list, and specify the cookie name "RUEItrack". When ready, click Save.

A maximum of five session cookies can be specified. Any changes made to this setting are applied after a short interval (typically, 5 - 10 minutes), and are then visible within the Reporter system after this.

Verifying the Cookie Configuration

To verify your cookie configuration, do the following:

1. Clear all cookies in the browser.

2. (Re)login to the EBS application.

3. Execute some actions that load Oracle Forms.

4. Execute some actions in Oracle Forms.

5. Logout.

6. Wait for at least 10 minutes.

7. Open the RUEI Reporter environment.

8. Select Browse data, open the All sessions group, select Session diagnostics, and locate the recorded session (by user ID or time). You can filter on applications.

9. Open the session and verify that:

   - There where more pageviews than just the login page. This verifies that the session ID is preserved in the OA framework after the login.

   - At least some Oracle Forms activity has been recorded with "unidentified action". This verifies that servlet calls are recorded correctly.

   - At least one specific Oracle Forms action, such as "openform, query, commit, or newform", has been recorded. This verifies that the Chronos calls are recorded correctly.

When not all hits are connected with the same cookie, it is recommended that you investigate where the problem is located (for instance, the domain or path option of the cookie), and resolve it in the appropriate manner.

## 1.9 Creating the EBS Suite Definition

Within the RUEI Reporter, create and configure the suite definition(s) required for your EBS-based applications. Do the following:

1. Select Configuration, then Applications, and then Suites. Click New suite. The dialog shown in Figure 1-5 appears.

   Figure 1-5 New Suite

   Description of "Figure 1-5 New Suite"

2. Specify a name for the suite. The name must be unique across suites, services, and applications, and is restricted to a maximum of six characters. Note that the suite cannot be renamed later.

3. Use the remaining fields to specify the scope of the suite. This is defined in terms of partial page URLs. Note that as you enter this information, you can see the effect of your definition through the Filter preview column. The use of blank filters is not permitted. All specified characters are interpreted as literals. When ready, click Next. The dialog shown in Figure 1-6 appears.

   Important:

   Filters definitions must be mutually exclusive across suites, applications, and services. For example, do not define a suite filtered on the domain "us.oracle.com" and then another suite, application, or service filtered on üs.oracle.com/application_servlet". The use of non-mutually exclusive filter definitions can lead to unpredictable results.

   Figure 1-6 Suite Type

   Description of "Figure 1-6 Suite Type"

4. This dialog allows you to specify the Oracle Enterprise architecture upon which the suite is based. The number of options available in this menu depends on the suite packages currently installed. Select the option E-Business Suite. When ready, click Finish. The suite definition you have specified is displayed. An example is shown in Figure 1-7.

   Figure 1-7 Suite Overview

   Description of "Figure 1-7 Suite Overview"

## 1.10 Synchronizing RUEI With the EBS Production Environment

In order for RUEI to understand how the EBS frameworks are implemented within your environment, do the following:

1. Copy the `create_EBS_info.sh` script to the home directory of the EBS server. It is located in the `/var/opt/ruei/processor/local/download/ebs` directory of the RUEI system.

2. Run the `create_EBS_info.sh` script as any user on the EBS serverFoot 1 . This script assigns an identification to the identified page IDs within the environment. The `create_EBS_info.sh` script must be run with the following required parameter:

       create_EBS_info.sh connect-string

   where `connect-string` is the string used to authorize the script to access the EBS database. The script reads from the APPLSYS schema, and generates .`txt` files in the current directory. For example:

       create_EBS_info.sh "APPS/APPS@linux-ebs-r12-pc:1522/VIS12"
       create_EBS_info.sh "APPS/APPS@EBS"

   In multiple instance environments, run the script for each required instance, and separately preserve their created .`txt` files. In addition, create a separate suite definition for each instance, as described in Section 1.9, "Creating the EBS Suite Definition".

   Note:

   If you make new customizations (or changes to existing customizations) to your EBS applications, you will need to re-run the script, and re-import the generated zip file.

3. The script creates a number of `.txt` files in the directory where the script is executed. All relevant .`txt` files are collected and stored in a .`zip` file. Copy this `.zip` file to a location that can be used for uploading the files to the RUEI Reporter system.

4. Select Configuration, then Applications, then Suites, and select the suite you defined earlier in Section 1.9, "Creating the EBS Suite Definition,". Click Upload Configuration. The dialog shown in Figure 1-8 appears.

   Figure 1-8 Upload Suite Configuration

   Description of "Figure 1-8 Upload Suite Configuration"

5. Specify the name of the `.zip` file containing the generated `.txt` files. If you manually create .`txt` files, you should use the same structure present in the .`zip` file. To protect against receiving empty definitions, the upload will fail when it contains empty .`txt` files. When ready, click Upload.

## 1.11 Verifying and Evaluating Your Configuration

To ensure the quality of the data being collected and reported by RUEI for your EBS-based applications, it is strongly recommended that you verify their reported details. You should pay particular attention to the number of associated pages detected for the defined suite(s).

Select Browse data, then select the All pages group, and then the Application sub-group. Within the individual dimensions, such as Pageviews and hits, you can see that pageviews are reported for several applications. The suite name in the definition is shown between brackets. An example is shown in Figure 1-9.

Figure 1-9 Suite Pageviews

Description of "Figure 1-9 Suite Pageviews"

Note:

The Unique pages identified counter and the Last page identified indicator (shown in Figure 1-7) are disabled. Similarly, the manual page naming facility (described in the Oracle Real User Experience Insight User's Guide) is not available.

You can also open an overview of the monitored network traffic by selecting System, then Status, and then Data processing. This provides you with immediate information about hits, pages, and session processing, as well as the system load.

For further information on the user of this and other monitoring facilities, refer to the Oracle Real User Experience Insight User's Guide.

## 1.12 Known Limitations

Currently, RUEI does not work with all EBS functionality. In particular, the following known limitations exist:

- Oracle Forms is only supported in servlet mode.

- The Forms framework includes functionality to create reports. This functionality is highly configurable by customers. As a result, it is not possible to track reports automatically. In addition, there is no useful translation table with a relevant business-oriented name for the reports. The only solution would to rewrite the known report URLs to correct report names based on a translation file.

  An additional side note on this issue is that some customers are using the 'jobs' functionality to create reports. This is an insecure way to do this, because the next and previous numbers can easily be guessed, and allow users to see reports they may not be authorized to view. Because of the randomness of the name (only a number), it is not useful to report on these type of reports when they are used.

  As a result of the issues described above, Forms reports are not monitored.

- Reporting is based on the last activated area. Hence, when an end-user is browsing simultaneously in multiple browser windows, the reported page name might contain incorrect information.

- Currently, the `create_EBS_info.sh` script only runs on Unix EBS servers.

- An error is not immediately reported if an invalid connect string is specified when running the `create_EBS_info.sh` script. You will need to press Enter several times before the error is reported.

- Currently, only applications based on the OA and JTT frameworks are supported. Therefore, such packages as Oracle Applications Manager (OAM) and Oracle Portal are not supported at this time.

Footnote Legend

Footnote 1: The script can also be run in the acceptance environment if it is equivalent to the production environment.