5 Administering Oracle BPEL Process Analytics

Accessing Oracle BPEL Process Analytics Documentation

Oracle BPEL Process Analytics documentation and help is included in the software installation. Accessing the documentation varies, depending on the operating system, as follows:

• On Microsoft Windows systems, follow these steps to view the documentation, where OAS_Home_Name is the name of the Oracle Application Server home in which you installed Oracle BPEL Process Analytics:

  From the desktop, click Start, then choose Oracle – OAS_Home_Name, then Oracle BPEL Process Analytics, and then click the name of the book that you want to open.

• On Unix systems, you can find the documentation in the following directory, where OAS_HOME is the directory specification for the Oracle Application Server home in which you installed Oracle BPEL Process Analytics:

  OAS_HOME\integration\bam\doc
  
  

  The file containing the Oracle BPEL Process Analytics User's Guide is bam_userguide.pdf; the file containing the Oracle BPEL Process Analytics Quick Start Guide is bam_quickstart.pdf.

To view the help, open the Oracle BPEL Process Analytics Console and click the Help link on any Oracle BPEL Process Analytics console page.

Setting Up Oracle BPEL Process Analytics Samples

Oracle BPEL Process Analytics samples are included in the software installation. The Oracle BPEL Process Analytics Quick Start Guide has step-by-step instructions on using the LoanFlow demo.

The method for setting up the samples varies, depending on the operating system, as follows:

• On Microsoft Windows systems, follow these steps, where OAS_Home_Name is the name of the Oracle Application Server home in which you installed Oracle BPEL Process Analytics:

  1. If it is currently running, stop the Oracle BPEL Process Analytics Server.

     From the desktop Start menu, choose All Programs, then Oracle - OAS_Home_Name, then Oracle BPEL Process Analytics, and then click Stop BPA Server. A command window opens to show the progress of the operation.

  2. When the server stops, from the desktop Start menu, choose All Programs, then Oracle - OAS_Home_Name, then Oracle BPEL Process Analytics, and then click Setup BPA Samples. A command window opens and presents a choice of samples and tutorials to install.

  3. At the Enter your choice prompt, enter your choice, then press Return.

  4. You are prompted to confirm that you want to set up the samples (because doing so overwrites the existing Oracle BPEL Process Analytics configuration). Enter yes to proceed; enter no to stop.

  5. You are prompted to enter the database schema password that you specified when you installed Oracle BPEL Process Analytics. Enter the password and press Return.

  6. When prompted, start Oracle BPEL Process Analytics, as follows:

     From the desktop Start menu, select All Programs, then Oracle - OAS_Home_Name, then Oracle BPEL Process Analytics, and then click Start BPA Server.

• On Unix systems, follow these steps, where OAS_HOME is the directory specification for the Oracle Application Server home in which you installed Oracle BPEL Process Analytics:

  1. If it is currently running, stop Oracle BPEL Process Analytics, by setting the current directory to the Oracle Process Manager and Notification Server (OPMN) bin directory in the Oracle home where you installed Oracle BPEL Process Analytics and issuing the opmnctl stopall command:

     1. > opmnctl stopall
        
        

  2. When the server stops, run setupSamples.sh in the following directory, where ORACLE_HOME is the directory specification for Oracle home into which you installed Oracle BPEL Process Analytics.

     ORACLE_HOME\integration\bam\bin\setupSamples.sh
     
     

  3. At the Enter your choice prompt, enter your choice, then press Return.

  4. You are prompted to confirm that you want to set up the samples (because doing so overwrites the existing Oracle BPEL Process Analytics configuration). Enter yes to proceed; enter no to stop.

  5. You are prompted to enter the database schema password that you specified when you installed Oracle BPEL Process Analytics. Enter the password and press Return.

  6. When prompted, start Oracle BPEL Process Analytics, as follows:

     From the Oracle Process Manager and Notification Server (OPMN) bin directory in the Oracle home where you installed Oracle BPEL Process Analytics, issue the opmnctl startall command.

     > opmnctl startall
     
     

User Management for Oracle BPEL Process Analytics Console Access

Oracle BPEL Process Analytics uses Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider in Oracle Application Server Containers for J2EE (OC4J) to restrict access to the Oracle BPEL Process Analytics Console based on the user who is logging in and what JAAS provider groups or roles have been granted to that user.

By default, Oracle BPEL Process Analytics defines the following JAAS roles, and users for the XML-based provider type:

• Roles (for the XML-based provider type)

  • BAMUsers role

  • Administrator role - the BAMUsers role is granted to this role

  • Manager - the BAMUsers role is granted to this role

• Users

  • Administrator, with the password Administrator

  • Manager, with the password Manager

In addition, the following Oracle BPEL Process Analytics Console user accounts are defined:

• Administrator

• Manager

No default groups or users are created for the LDAP-based provider type.

The following topics describe and provide an example of how to configure a JAAS provider for an LDAP-based provider type and an XML-based provider type, respectively:

• Configuring a JAAS Provider for an LDAP-Based Provider Type

• Configuring a JAAS Provider for an XML-Based Provider Type

Using Oracle Enterprise Manager 10g

Oracle BPEL Process Analytics is integrated with Oracle Enterprise Manager 10g to allow you to stop, start, or restart the following components associated with Oracle BPEL Process Analytics:

• The Oracle Application Server Containers for J2EE (OC4J)

• The Oracle BPEL Process Analytics Server

• The Oracle BPEL Process Analytics monitor

In addition, it provides access to the port numbers in use by the event sources supported by Oracle BPEL Process Analytics.

The following topics describe how to access and use Oracle Enterprise Manager 10g with Oracle BPEL Process Analytics:

• Accessing Oracle Enterprise Manager 10g Application Server Control

• Starting, Stopping, or Restarting Components

• Determining Port Numbers for Event Source Specifications and URLs

Accessing Oracle Enterprise Manager 10g Application Server Control

Oracle Enterprise Manager 10g is installed when you install Oracle Application Server. To access Oracle Enterprise Manager 10g Application Server Control:

1. In a Web browser, enter the URL for the Oracle Enterprise Manager 10g Application Server Control that was presented at the end of the Oracle Application Server installation.

   This URL is also available in the setupinfo.txt file in the following location, where OAS_HOME is the directory specification for the Oracle Application Server home into which you installed Oracle BPEL Process Analytics:

   OAS_HOME\install
   
   

2. After you enter the URL in a Web browser, a login window opens. Enter the user name and password for Oracle Application Server.

After you log in, your browser should look similar to that shown in Figure 5-1:

Figure 5-1 Sample Oracle Enterprise Manager 10g Control

Description of the illustration oem_control.gif

Starting, Stopping, or Restarting Components

To start, stop, or restart Oracle BPEL Process Analytics components:

1. Open Oracle Enterprise Manager 10g Application Server Control, as described in "Accessing Oracle Enterprise Manager 10g Application Server Control".

2. Click BPEL Process Analytics. The browser refreshes and appears similar to Figure 5-2.

3. Click the Start, Stop, or Restart button associated with the desired component to perform the desired operation.

Alternatively, you can click the Stop All, Restart All or Stop All button to perform the operation on all of the Oracle BPEL Process Analytics components.

Figure 5-2 Sample Oracle Enterprise Manager - BPEL Process Analytics Page

Description of the illustration bpa_components.gif

Determining Port Numbers for Event Source Specifications and URLs

When you specify event sources for Oracle BPEL Process Analytics or specify URLs related to Oracle BPEL Process Analytics, you are sometimes required to enter the port number of various event source components or the Oracle HTTP Server for Oracle BPEL Process Analytics. To determine what these values should be, follow these steps:

1. Open the Oracle Enterprise Manager 10g Application Server Control associated with the event source as described in "Accessing Oracle Enterprise Manager 10g Application Server Control".

2. Click the Ports tab. The Ports page opens.

3. In the Ports page, search the Component and Type columns for the component and type of interest; the Port in Use column will specify the value of interest.

Figure 5-3 shows a sample Ports page.

Figure 5-3 Sample Ports Page

Description of the illustration oem_ports.gif

For example, suppose you are interested in using Oracle BPEL Process Analytics with an Oracle BPEL Process Manager event source that was installed in the Oracle Application Server middle tier. One of the values you must specify is the ORMI port. If you open Oracle Enterprise Manager 10g Application Server Control and click the Ports tab, you will find the following columns and values that correspond to Oracle BPEL Process Manager and the ORMI port, respectively:

• Component: OraBPEL

• Type: rmi

If you view the Port in Use column for this component and type, you see the required number for the ORMI port.

See "Oracle BPEL Process Manager Event Source Configuration Values" for all of the values required to specify an Oracle BPEL Process Manager event source.

Locating Oracle BPEL Process Analytics Log Files

Oracle BPEL Process Analytics generates a number of log files that can be useful in troubleshooting problems that may arise. The format of each of these files is text. Table 5-1 provides the file name and description of the log files generated by Oracle BPEL Process Analytics. All of the log files are located in the following directory, where OAS_HOME is the directory specification for the Oracle Application Server home into which you installed Oracle BPEL Process Analytics:

OAS_HOME\integration\bam\log

Setting Log File, Dashboard, and Other Properties

Oracle BPEL Process Analytics allows you to set some properties for the Oracle BPEL Process Analytics engine, monitor, and console log files, as well as for the Oracle BPEL Process Analytics Dashboard.

The bam.properties file is a text file located in the following directory where OAS_HOME is directory specification for the Oracle Application Server home into which you installed Oracle BPEL Process Analytics:

OAS_HOME\integration\bam\config

The following tables describe properties that you can set by editing the file in any text editor. Oracle recommends that you do not adjust values for properties included in the file which are not described in one of the following tables:

• Log file and related properties are described in Table 5-2.

• Oracle BPEL Process Analytics Dashboard properties and properties that affect the speed at which the event simulator generates events are described in Table 5-3.

See "Starting, Stopping, or Restarting Components" for information about how to restart the various components that must be restarted for a property value change to take effect.

Running Multiple Instances of Oracle BPEL Process Analytics

It may be desirable to install and run multiple instances of Oracle BPEL Process Analytics. You might do this, for example, to enable multiple administrators to configure and manage event sources for a subset of Dashboard users within a single business. However, if you choose to do so, be aware that two or more instances of Oracle BPEL Process Analytics should not be configured to monitor the same event source.

If two or more instances of Oracle BPEL Process Analytics are monitoring the same event source, it is possible any given instance will capture all, some, or none of the events being published by that event source. This results in unpredictable behavior, including problems correlating the events and missing or incorrectly correlated events in the Real-Time Viewer.

Note however, that this restriction does not prevent multiple Dashboard users from viewing data from an event source monitored by a single instance of Oracle BPEL Process Analytics. Multiple Dashboard users can connect to the same instance of Oracle BPEL Process Analytics and view the events presented in the Real-Time Viewer without a problem (assuming they have privileges to access the Real-Time Viewer).

Archiving an Oracle BPEL Process Analytics Scenario

This topic describes how to archive an Oracle BPEL Process Analytics scenario (using Oracle BPEL Process Manager as the event source) running on one site so that you can quickly set it up on another site. You may find this useful if you need to demonstrate at remote sites how Oracle BPEL Process Analytics can be used in your organization.

The following list provides step-by-step instructions for creating an archive on the local system. These instructions assume that Oracle Application Server middle tier, Oracle BPEL Process Manager, and Oracle BPEL Process Analytics are installed on both the local and remote systems.

1. Create a main directory, for example MyScenario, to serve as the main directory for the archive. (The remainder of these steps assume you have used the name MyScenario.)

2. Within the MyScenario directory, create the following two subdirectories: config and sql.

   The directory structure you create will appear similar to the structure of the following directory, which is created when you install Oracle BPEL Process Analytics (where OAS_HOME is the specification for the Oracle Application Server middle tier where Oracle BPEL Process Analytics is installed):

   OAS_HOME\integration\bam\test\tutorials\bpel
   
   

3. Copy the following files from the OAS_HOME\integration\bam\config directory to the MyScenario\config directory, where OAS_HOME is the specification for the Oracle Application Server middle tier where Oracle BPEL Process Analytics is installed:

   • Alerts.xml

   • BusinessProcessMapService.xml

   • CSFs.xml

   • DimensionColorMap.xml

   • eventSources.xml

   • PCBPELEventSources.xml

   • insite_insightdirectdefault.xml

   • UserManagerService.xml

   • UserPages.xml

4. Copy the insightdirectdefault.xml file from the OAS_HOME\integration\bam\data\metadataServiceData directory to the MyScenario\config directory, where OAS_HOME is the specification for the Oracle Application Server middle tier where Oracle BPEL Process Analytics is installed.

5. Write a script named CreateTables.sql that creates the fact and budget tables that are associated with each composite event currently defined in your scenario, and that creates the dimension tables for the dimensions that are associated with these composite events, if any.

   You can determine the names of the currently defined fact, budget, and dimension tables by connecting to the Oracle BPEL Process Analytics repository as the bam user and running SQL queries to find all tables that include the string BAM_FACT, BAM_BUDGET, or BAM_DIM as shown in the following example, where db1 is the server ID for the Oracle BPEL Process Analytics repository:

   SQL> connect bam/bam@db1
   SQL> SELECT TABLE_NAME FROM ALL_TABLES WHERE TABLE_NAME LIKE 'BAM_FACT%';
   TABLE_NAME
   ------------------------------
   BAM_FACT_LOANFLOWDIM_T
   
   SQL> SELECT TABLE_NAME FROM ALL_TABLES 
        WHERE TABLE_NAME LIKE 'BAM_BUDGET%';
   TABLE_NAME
   ------------------------------
   BAM_BUDGET_LOANFLOWHDIM_T
   
   SQL> SELECT TABLE_NAME FROM ALL_TABLES WHERE TABLE_NAME LIKE 'BAM_DIM%';
   TABLE_NAME
   ------------------------------
   BAM_DIM_CARMAKEMODEL_T
   
   

   You can then determine the definition for each table using the SQL*Plus DESCRIBE statement with each table name, such as shown in the following examples:

   SQL> describe BAM_FACT_COMPEVENTNAME_T;
   Name                   Null?     Type
   ---------------------  --------  ----------------------------
   TIMEID                 NOT NULL   NUMBER
   CARMAKEMODELID                    VARCHAR2(40)
   COUNTREQ                          NUMBER
   REQAPPROVALTIME                   NUMBER
   COUNTLOANOFFERS                   NUMBER 
   
   SQL> describe BAM_DIM_DIMNAME_T;
    Name                  Null?    Type
    ---------------------- -------- ----------------------------
    CARMAKEMODELID         NOT NULL VARCHAR2(40)
    CARMAKE                         VARCHAR2(20)
    CARMODEL                        VARCHAR2(20)
   
   

6. For each dimension in your current scenario, create a data (.dat) file that contains SQL INSERT statements to load data into the dimension table.

   For example, to load data into the BAM_DIM_DIMNAME_T table shown in the previous step, several SQL INSERT statements similar to the following would be included in the BAM_DIM_DIMNAME_T.dat file for that table:

   INSERT INTO BAM_DIM_CARMODEL_T (CARMODELID, CARMAKE, CARMODEL)VALUES ('BMW 320i', 'BMW', '320i');
   
   

7. Create a file named SetupSample.sql that runs the CreateTables.sql script and loads all of the DIMENSION_TABLE.dat files.

8. Copy CreateTables.sql, SetupSamples.sql, and all the DIMENSION_TABLE.dat files to the MyScenario\sql directory.

9. Create a .jar or .zip file to hold the contents (and preserve the directory structure) of the MyScenario directory and its subdirectories.

You have now completed archiving your scenario. To install the archive in another Oracle BPEL Process Analytics instance on a remote system, follow these steps:

1. Open the archive (.jar or .zip file) and copy all of the files in the MyScenario\config directory, except insightdirectdefault.xml, to the OAS_HOME\integration\bam\config directory on the new system, where OAS_HOME is the specification for the Oracle Application Server middle tier where Oracle BPEL Process Analytics is installed

2. Copy insightdirectdefault.xml from MyScenario\config to the OAS_HOME\integration\bam\data\metadataServiceData directory on the new system.

3. Copy all the.sql files from the MyScenario\sql directory to a temporary directory on the new system.

4. Log in to SQL*Plus and connect to the Oracle BPEL Process Analytics repository as user bam with password bam.

5. Run SetupSamples.sql.