10 Working With Suites and Web Services

This chapter explains the use of suites for the enhanced monitoring of certain Oracle Enterprise architectures (such as Oracle E-Business suite, Siebel, and WebLogic Portal). The monitoring of Web services is also described.

10.1 Working With Suites

As explained earlier, page identification within RUEI is based on applications. However, if these applications are based on certain Oracle Enterprise architectures (such as Oracle E-Business Suite, Siebel, and WebLogic Portal), then a fourth level, suite, is introduced. A suite is essentially a collection of applications, and Web pages associated with these suites have the structure suite » application » group » page.

Important

If you are using any of the any of the currently supported Oracle Enterprise architectures within your monitored environment, it is strongly recommended that you make use of this facility. It not only saves you time in defining your applications, and makes applications within suites more compatible, but also ensures that these architectures are monitored correctly.

10.1.1 Creating Suite Definitions

To define a suite instance, do the following:

Select Configuration, then Applications, and then Suites from the menu structure shown in Figure 10-1.

Figure 10-1 Suites

Description of "Figure 10-1 Suites"
Click New suite. The dialog shown in Figure 10-2 appears.

Figure 10-2 New Suite

Description of "Figure 10-2 New Suite"
Specify a name for the suite. The name must be unique across suites, services, SSO profiles, and applications, and is restricted to a maximum of six characters. Note that suite instances cannot be renamed later.
Use the remaining fields to specify the scope of the suite. This is defined in terms of partial page URLs. The use of these filter criteria is the same as described in Section 8.2, "Defining Applications". 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. Note that a wildcard character (*) cannot be specified within the Find port field, and network traffic arriving on a non-standard port (that is, ports 80/443), is not associated with the suite instance. Only one port number can be explicitly specified. If more are required, they should be configured as additional filters. Note it is not possible to specify the wildcard character and no other information for domain name and URL argument combinations. When ready, click Next. The dialog shown in Figure 10-3 appears.

Note:
It is advised that filter definitions should be mutually exclusive across suites, SSO profiles, applications, and services. The use of non-mutually exclusive filter definitions can lead to unpredictable results. See Section 12.9, "Controlling Rule Ordering Within RUEI" for more information about how you can control the order in which filters are applied.

Figure 10-3 Suite Type

Description of "Figure 10-3 Suite Type"
This dialog allows you to specify the Oracle Enterprise architecture upon which the suite is based. When ready, click Finish. The suite definition you have specified is displayed. An example is shown in Figure 10-4.

Figure 10-4 Suite Overview

Description of "Figure 10-4 Suite Overview"
This overview provides a summary of the defined suite. This includes the defined page identification filter(s), the number of pages that have so far been matched to the suite, the functional errors (if any) that should be detected and recorded, and the user identification mechanism used within the suite to track visitor sessions. Each of these can be modified as required. The procedure is equivalent to that described in Section 8.2, "Defining Applications".

10.1.2 Uploading Configuration Files

It is strongly recommended that you run the appropriate script supplied for use when monitoring traffic that is based on certain Oracle architecture production environments. For example, the create_EBS_info.pl script. This is in order determine how these architectures have been implemented within your environment. In particular, the page-naming scheme. Do the following:

Download the appropriate script supplied for the selected suite. See the relevant appendix for further information on the use of this facility.
Run the script within our deployment environment. This script assigns an identification to the page IDs within your environment. It creates a number of .txt files in directory where the script is executed.
Create a .zip file from the generated .txt files, and copy this .zip file to a location that can be used for uploading files to the RUEI Reporter System.
Select Configuration, then Applications, then Suites, and select the appropriate suite. An overview of the suite appears. Click the Upload configuration command button. The dialog shown in Figure 10-5 appears.

Figure 10-5 Upload Suite Configuration

Description of "Figure 10-5 Upload Suite Configuration"
Specify the name of the file generated by the script. A Browse button is available to help you locate the required file. This must be a .zip file. When ready, click Upload.

Important:

This configuration file must be uploaded for each required suite instance. It may only contain known (and non-empty) .txt files. All these 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 instance, and that it is based on the actual production environment. If you make any changes to the monitored application(s), you need to re-run the script, and re-import the generated .zip file.The result of importing an erroneous configuration file is incorrect reporting.

10.1.3 Modifying Suite Definitions

As explained earlier, a suite is essentially a collection of applications. Once you have defined your suites, you can modify its associated properties in the same way as described for applications in Section 8.2, "Defining Applications".

You should pay particular to the following points:

The suite instance's Enterprise name must be correctly specified for clickout functionality to be available for the suite (see Section 4.6, "Configuring Clickouts to External Tools"). It can be obtained from the suite's configuration within EMGC. For example, ec2ebs2-Oracle E-Business Suite or siebel_emgc-amp11.us.oracle.com.
A number of default suite-specific functional errors are defined. You should review these to reflect the requirements of your environment. The procedure is the same as described in Section 8.2.11, "Trapping Application Content Messages".
By default, unclassified pages are not reported. You can modify this through the Report unclassified pages check box. The procedure is the same as described in Section 8.2.4, "Reporting Unclassified Pages".
You can use the Report service test traffic check box to specify whether service test traffic configured within Oracle Enterprise Manager for the selected suite should be reported within RUEI. By default, reporting is disabled. For further information on the use of this facility, see Section 8.5, "Reporting Service Test Traffic". Note that monitored service tests can also be converted into RUEI user flows. This is fully described in Section 9.8, "Converting Service Test Sessions into User Flows".
When reporting on user visits, the client IP address is, by default, fetched from the IP packet. However, when the RUEI system is placed in front of a NAT device, it may be more useful for the client IP address to be obtained from a specific header. This is fully explained in Appendix P, "Monitoring NATed Traffic".
A default user identification scheme is defined for each suite. You should review this to reflect the requirements of your environment. The procedure is the same as described in Section 8.2.12, "Defining User Identification".
The suite diagnostics groups (described in Section 3.2.4, "The URL Diagnostics Group") allow you to view the functional URLs reported for hits within suites. The use of this facility is equivalent to that for applications (described in Section 8.2.18, "Controlling Reporting Within the URL Diagnostics Group").
In addition to identifying pages through suites, you can also define pages manually. The procedure is the same as described in Section 8.2.17, "Manually Identifying Pages". However, you cannot define a new page from scratch. You must use an existing page as the basis for a new page.

10.1.4 Verifying and Evaluating Your Suite Definitions

To ensure the quality of the data being collected and reported by RUEI for your Oracle Enterprise architecture-based applications, it is strongly recommended 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 Applications sub-group. Within the individual dimensions, such as Page views and hits, you can see page views are reported for several applications. The suite name in the definition is shown between brackets. The example shown in Figure 10-6 is for a WLP streaming portal.

Figure 10-6 Suite Page Views

Description of "Figure 10-6 Suite Page Views"

10.2 Refining Application Definitions Through Framework Exceptions

As explained earlier in Section 10.1, "Working With Suites", RUEI provides dedicated support for the monitoring of certain Oracle Enterprise architectures (such as Siebel and Oracle E-Business Suite). This support is made possible because each of these architectures is based upon a standard underlying framework. However, when an application has been developed using a customized version of the architecture's framework, RUEI needs information about the modifications made in order to accurately monitor and report its network traffic. This is also the case when an architecture framework has been used as a wrapper to a legacy application. Application developers can use the Framework exception facility to specify the exceptions that should be made to RUEI's standard architecture reporting scheme. Note that this facility is also available for use with non-suite applications.

If you have modified your application's underlying framework to include customized pages, it is strongly recommended that you use the Framework exception facility, rather than manual page definitions (described in Section 8.2.17, "Manually Identifying Pages"), to ensure that these pages are correctly identified.

Application Context Roots

Typically, an application is identified by its domain. For example, myshop.com. Its possible home page is shown in Figure 10-7.

Figure 10-7 Example Application Home Page

Description of "Figure 10-7 Example Application Home Page"

Each of its discrete functional parts is identified by a first-level directory. For example:

myshop.com/catalog: contains a facility for customers to browse and order items from an online catalog of available items. This is based on a standard framework implementation.
myshop.com/preferences: contains a facility where customers can modify the Web site's appearance to reflect their personal preferences. For example, national language, units of measurements, and currency. This is based on a customized framework implementation.
myshop.com/checkout: contains a facility where customers can confirm their orders and arrange payment. This is based on a customized billing implementation.

In this case, information about the customizations made to the preferences and checkout parts of the application needs to be provided in order to ensure correct reporting. The catalog part is based on a standard framework and, therefore, does not require further information to be specified.

Specifying Framework Exceptions

To define the framework exceptions that should be used for an application, do the following:

Select Configuration, then Applications, and then Framework exceptions. Click the New framework exception item. The dialog shown in Figure 10-8 appears.

Figure 10-8 Add Framework Exception Dialog

Description of "Figure 10-8 Add Framework Exception Dialog"
Specify a unique name for the framework exception. This must be unique. Select either "Generic" if it to apply to all application definitions, or "Suites" if it is only to apply to a specific Oracle Enterprise architecture. In the case of the latter, you will need to specify the architecture. Note that suites only appear in the Suites type menu if at least one suite instance of it has been defined. Optionally, specify a brief description. It is recommended that it includes an indication of the purpose and scope of the defined exceptions. When ready, click Save.
Click the newly created framework exception. An overview similar to the one shown in Figure 10-9 appears.

Figure 10-9 Framework Exception Overview

Description of "Figure 10-9 Framework Exception Overview"
Click Identification tab, and then the Add new URL prefix (context root) item. Essentially, this specifies the scope of the framework exception. Note that they must be first-level directories. That is, they must appear directly after the domain name in the application's URLs. For example, www.myshop.com/catalog/*. The specified directory names should not include the slash ("/") character.
Click the Page/object conditions tab. Click the Add new condition item. The dialog shown in Figure 10-10 appears.

Figure 10-10 Add Hit Type Condition Dialog

Description of "Figure 10-10 Add Hit Type Condition Dialog"

Use the Hit type menu to specify how detected hits should be treated. The available options are shown in Table 10-1.

Table 10-1 Hit Type Options

Hit type	Page name^Foot 1	Loading time^Foot 2	Content error^Foot 3	Preview^Foot 4
Page	X	X	X	X
Object	-	X	-	-
Redirect	-	X	-	-
Heartbeat	-	-^Foot 5	-	-

^Footnote 1The reported page name is derived from the hit.

^Footnote 2Hit taken into account when determining page-load time.

^Footnote 3Hit is scanned for content errors.

^Footnote 4Used for previewing in the Session Diagnostics facility.

^Footnote 5The hit is used to determine when the previous page has finished loading.

Specify the events that must be met for the exception to be applied. For each event, use the Dimension level and Value menus to select the dimension that should be checked, and the value that it must hold. Note that if the required value is not available within the Value menu, you can click the Search icon beside it to locate it.

Optionally, use the Exclude check box to specify that the defined dimension level=value pair should be negatively applied. That is, the event should be regarded as achieved if the defined event is not met. When ready, click Add. Note that while only one defined condition needs to be achieved in order for the exception to be applied, all events within a condition must be met for it to be considered achieved. When ready, click Save. You are returned to the dialog shown in Figure 10-9.

Click the Dimensions definitions tab. A list of dimensions specific to the selected application type is displayed. An example is shown in Figure 10-11.

Figure 10-11 Dimension Definitions Section

Description of "Figure 10-11 Dimension Definitions Section"

Click the dimension whose default source you want to modify. Use the Source type and Source value fields to specify how the selected dimension's reported values should be derived. Optionally, you can use the Replace value field to specify a transformation that should be applied to the retrieved value. The available options are explained in Table 10-2. When ready, click Save.

Table 10-2 Identification Options

Option	Description
URL argument	The dimension value should be derived from a specified URL argument.
XPath in request	The dimension value should be derived from an XPath expression applied to the request.
Header in request	The dimension value should derived from a specified request header.
XPath in response	The dimension value should be derived from an XPath expression applied to the response.
Header in response	The dimension value should be derived from a specified response header.
Cookie	The dimension value should be derived from a specified cookie element.
Custom tag	The dimension value should be derived from a specified custom tag.
Custom function	The dimension value should be derived from a specified custom function. Note that only the first parameter is used, and it must be enclosed in single or double quotes. For example: wiViewState("wi_menu_main_menu");
Literal	The dimension value should be set to a specified literal value.

Once created, you can use the ruling facility to specify additional matching rules that should be used to refine the newly created definition. This is described in Section 8.2.3, "Using the Ruling Facility".

10.2.1 Moving Framework Exceptions Between Environments

It is recommended that framework exceptions are developed at the same time as the application itself. This is best achieved by having RUEI monitor the application under development, and refining its defined exceptions based on the obtained results.

Once ready for deployment, the application is then moved to a production environment. If that new environment is monitored by a different RUEI installation, you do not need to manually re-create the application's exception rules. Instead, you can use the download facility to obtain a copy of its latest definitions, and then upload the generated file for use by the new RUEI installation.

This facility is particularly useful when deploying an application across multiple environments. For example, when providing an Extranet-based application for use by your business partners.

Important:

The generated framework exception files are in a proprietary format, and must not be modified in any way.

Downloading Framework Exception Definitions

To download a defined framework exception, do the following:

Select Configuration, then Applications, and then Framework exceptions. Click the Download framework exceptions command button. A window opens showing the currently defined framework exceptions. An example is shown in Figure 10-12.

Figure 10-12 Download Framework Exceptions Window

Description of "Figure 10-12 Download Framework Exceptions Window"
Select the required framework exceptions. When ready, click Download.
Depending on how your browser is configured, you are either prompted to specify the location to which the zip file should be saved, or it is immediately saved to the defined default location.

Uploading Framework Exception Definitions

When uploading an Framework Exception definition with the same name as a currently configured one, the uploaded context roots replace the existing ones, and the counter indicating when they were last used is reset. Hence, this can be used to reset the reported last-used information.

10.3 Defining Web Services

The emergence of Web services has become one of the most important advances in the technology industry. Organizations are increasingly integrating enterprise applications to exchange information such as purchase orders, inventory levels, shipment notices, and interbank transactions, to name but a few.

Understanding Web Services

It is important to distinguish this new breed of Web services from traditional ones. Generally, a Web service was any service available over the Web (such as search engines, language translators, weather guides, maps, and so on). However, these types of Web services required some human intervention.

A Web service is defined by the W3C^Foot 1 as "a software system designed to support interoperable machine-to-machine interaction over a network". It implements a clearly defined business function that operates independently of the state of any other service. It has a well-defined contract with the consumer of the service. Services are loosely coupled - a service does not need to know the technical details of another service in order to work with it - and all interaction takes place through the interfaces. Using this technology, the service provider simply exposes a service on the Web, publishes the interface and service naming specifications, and waits for a connection.

Services are made available through service descriptions. They describe how to call the service, and what information is required to request the service and get a response. The data exchange takes a request-response pattern. RUEI primarily supports the monitoring of XML-SOAP and similar messages.

Creating Web Service Definitions

To define a Web service, do the following:

Select Configuration, and then Services. The currently defined Web services are listed. Click New services. The dialog shown in Figure 10-13 appears.

Figure 10-13 Service Configuration Wizard

Description of "Figure 10-13 Service Configuration Wizard"
Specify a name for the service. This is the name that will be used for the defined service within reports and the Data Browser. The name must be unique across services, SSO profiles, suites, and applications. Note that services cannot be renamed later.
Use the remaining fields to specify the scope of the service. This is defined in terms of partial service URLs. Note that as you enter this information, you can see the effect of your definition through the Filter preview column.

The highest level filter is the domain. You can specify a partial URL instead of, or to refine, a domain. It is not possible to specify a service name and leave all the other fields blank. Note that a wildcard character (*) cannot specified within the Find Port field, and network traffic arriving on a non-standard port (that is, other than ports 80/443), is not associated with the service unless the port number is explicitly stated. You can only specify one port number within the Find Port field. If you want to specify additional ports, these should be specified as additional filters after the new service has been created.

Be aware that while the use of a wildcard character is supported, all other specified characters are interpreted as literals. Note it is not possible to specify the wildcard character and no other information for domain and URL argument combinations.

Note:
It is recommended that filter definitions should be mutually exclusive across services, SSO profiles, applications, and suites. For example, do not define a service filtered on the domain us.oracle.com and then another service, suite, or application filtered on us.oracle.com/application_servlet. The use of non-mutually exclusive filter definitions can lead to unpredictable results. See Section 12.9, "Controlling Rule Ordering Within RUEI" for information about how you can influence the order in which filters are applied.

You can also specify an argument within the partial URL that must be matched. Note that if you use this facility, both the argument and argument name must be complete in order for them to be matched to page URLs. That is, partial matching is not supported. When ready, click Next. The dialog shown in Figure 10-14 appears.

Figure 10-14 Function Naming Scheme Dialog

Description of "Figure 10-14 Function Naming Scheme Dialog"
Use this dialog to specify how the service should be identified and reported. It is important to understand that while applications (see Section 8.2, "Defining Applications") have the structure application » group » page, services have the structure service name » function group » function name. Note that functions that do not belong to a defined group are regarded as belonging to the default group "generic". If you specify a group naming scheme, this must be found within the function call for it to be reported.

When ready, click Finish. An overview of the service definition you have specified is displayed. An example is shown in Figure 10-15.

Figure 10-15 Service Overview

Description of "Figure 10-15 Service Overview"

Refining Your Service Definitions

Once you have defined your service, you can modify its associated function scheme. Within the Identification section, you can click Add new filter to specify additional filters for the functions that should be associated with the service. A function will be assigned to a service when one of the defined filters is matched. You can also modify an existing filter definition by clicking it. In each case, you can select from the same filters as shown in Figure 10-13. The service overview is updated to reflect your additions or modifications.

Client Identification

The procedure for defining the client ID identification scheme is identical to that for applications and suites, and is described in Section 8.2.12, "Defining User Identification".

Specifying the IP Address Source

When reporting on user visits, the client IP address is, by default, fetched from the TCP packet. However, when the RUEI system is placed in front of a NAT device, it may be more useful for the client IP address to be obtained from a specific header. The Client IP source check box within the Advanced section (shown in Figure 10-13) allows you to specify the required scheme. This is explained in Appendix P, "Monitoring NATed Traffic".

10.3.1 Reporting Unclassified Function Calls

By default, function calls that have been identified as belonging to a service through its URL definition, but for which no classified name has been found, are discarded and not reported. However, if you want these unclassified calls to be reported, use the Report unclassified calls check box within the Functions section.

Because hits not identified as belonging to the service are identified as unclassified calls, incorrect or insufficiently defined function calls will be identified as unclassified. Note that unclassified calls are reported in the relevant Data Browser group under the category "Other".

10.3.2 Specifying Function Loading Satisfaction

In order to assess a function's responsiveness, RUEI assigns a satisfaction level for each function call. This is equivalent to the page-loading thresholds described in Section 8.2.9, "Specifying Page Loading Satisfaction".

10.3.3 Trapping Function Call Errors

The procedure for detecting strings associated with functions is equivalent to that for applications, and is described Section 8.2.11, "Trapping Application Content Messages".

Footnote Legend

Footnote 1: The World Wide Web Consortium (W3C) is the main international standards organization for the World Wide Web.