|Oracle® Real User Experience Insight Accelerator for Oracle E-Business Suite Guide
Release 5.1 for Linux x86-64
Part Number E14896-02
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.
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.
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 .
Manually Creating Functional Mappings
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:
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:
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:
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.
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:
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.
(Optionally) enable Forms over SSL instead of Forms-encryption.
Install the package RPMs on the RUEI Reporter system.
Verify the scope of monitored traffic.
Specify the cookie technology used to track user sessions.
Create and configure the EBS suite(s) required for your EBS-based applications.
Synchronize the information held within RUEI with the EBS production environment.
Verify and evaluate the EBS suite configuration.
Each of these steps are discussed in more detail in the following sections.
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.
$ORACLE_HOME/forms/server/formsweb.cfg file to enable monitoring of specific applications. Set the following:
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:
Ensure that the patch 7130248 for release 18.104.22.168.0 is installed on the Oracle Forms system.
$ORACLE_HOME/forms/server/formsweb.cfg file by adding the following lines:
EndUserMonitoringEnabledsettings are case sensitive, and should be set to
Verifying Chronos End User Monitoring
Verify that Chronos hits are sent by doing the following:
Login to Forms.
Open the Java console of the JVM in which Oracle Forms is running.
Activate trace level 2 by pressing 2.
Perform some Forms-based action that leads to a commit.
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
Confirm the hit appears in the log files on the RUEI Reporter system using the following command as the
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
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:
A restart of the Forms server is required to activate the setting.
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
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.
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:
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:
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
Use the View menu to select each Collector. The System (localhost) item represents the local server system.
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
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.
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.
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.
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:
Add the following code to the EBS login page:
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
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:
Clear all cookies in the browser.
(Re)login to the EBS application.
Execute some actions that load Oracle Forms.
Execute some actions in Oracle Forms.
Wait for at least 10 minutes.
Open the RUEI Reporter environment.
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.
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.
Within the RUEI Reporter, create and configure the suite definition(s) required for your EBS-based applications. Do the following:
Select Configuration, then Applications, and then Suites. Click New suite. The dialog shown in Figure 1-5 appears.
Figure 1-5 New Suite
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.
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
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
In order for RUEI to understand how the EBS frameworks are implemented within your environment, do the following:
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.
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:
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.
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.
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
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.
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
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.
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.
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 LegendFootnote 1: The script can also be run in the acceptance environment if it is equivalent to the production environment.