|
Oracle® BPEL Process Analytics User's Guide
10g Release 2 (10.1.2) Part No. B15597-01 |
|
 Previous |
 Next |
|
Oracle® BPEL Process Analytics User's Guide
10g Release 2 (10.1.2) Part No. B15597-01 |
|
|
Previous |
Next |
This chapter describes the steps required to publish and monitor events from applications for which Oracle BPEL Process Analytics does not provide specified support.
Oracle BPEL Process Analytics supports publishing events from the following types of custom applications:
Oracle database applications that use PL/SQL packages installed with Oracle BPEL Process Analytics to publish the events to the preconfigured OJMS queue, bam_genericmonq.
Oracle database applications that publish events to a user-specified OJMS queue.
Java 2 Platform, Enterprise Edition (J2EE) applications that use JMS application programming interfaces (APIs) to publish events to an OJMS or user-specified JMS queue.
Events generated by the Oracle BPEL Process Analytics Web Service published to an OJMS or a user-specified JMS queue.
This chapter includes the following topics:
Basic Steps for Publishing and Monitoring Events from Custom Applications
Example of Monitoring an Oracle Database as a Generic Event Source
|
Note: The directory paths shown in this chapter follow Microsoft Windows conventions (using backslashes (\)). If you are using Unix, modify the directory paths as required (using slashes (/)). |
You monitor events from a custom application by configuring and monitoring them as a generic event source, and then publishing events from those applications to one of queues described in the previous section.
To do so you must define the events that you want to monitor using .xsd or .dtd files, and then ensure that those events are published to a queue to which Oracle BPEL Process Analytics has access.
The steps for monitoring events from a custom application are as follows:
Ensure that the XML document type definition (.dtd files) or W3C XML Schema (.xsd files) that define the events that you want to monitor are available.
If an Oracle database is your generic event source, you can use the XML Schema Utility (XSU) to define the events, as described in "Using the XSU Command Line to Generate .xsd Files for Database Tables".
Use the Admin Console to specify the connection parameters to the generic event source, as documented in "Creating, Modifying, and Deleting Event Source Connections".
Use the Admin Console to create a composite event for the events you intend to publish, as described in "Creating Composite Events".
Publish the events to the queue for Oracle BPEL Process Analytics to capture, as documented in "Publishing Events for Oracle BPEL Process Analytics".
Open the Dashboard and view the published events in the Dashboard Real-Time Viewer, as documented in "Viewing Events and Composite Event Instances".
Oracle BPEL Process Analytics can capture events that you format and publish to a queue as described in the following topics:
Oracle BPEL Process Analytics requires that events published by custom applications use the same format as that which is defined for the publishEvent request document schema, described in "publishEvents Operation".
The preconfigured OJMS queue, bam_genericmonq, is installed when you install Oracle BPEL Process Analytics. It enables Oracle BPEL Process Analytics to monitor events that are generated by the same database as that which serves as the Oracle BPEL Process Analytics repository.
The following topics describe the prerequisites for using this queue and how to publish events to it:
To publish database events to the bam_genericmonq queue, you must first connect to the database as the BAM user and grant privileges as follows, where user-name is the name of the user who will publish events to the queue:
GRANT EXECUTE ON bam_generic_monitor TO user-name; EXECUTE DBMS_AQADM.GRANT_SYSTEM_PRIVILGE ('ENQUEUE_ANY', 'user-name', TRUE);
The specified user can then use the tools described in "PL/SQL Packages for Publishing to the bam_genericmonq Queue" to publish events to the bam_genericmonq queue. No queue configuration is required.
Oracle BPEL Process Analytics provides PL/SQL packages to assist you with installing, deinstalling, and publishing to the bam_genericmonq. These packages are defined in the following SQL script, where OAS_HOME is the Oracle Application Server home in which you installed Oracle BPEL Process Analytics:
OAS_HOME\integration\bam\admin\sql\CreateGenericMonitorPkg.sql
By default, this SQL script is run when you install Oracle BPEL Process Analytics.
You can use the procedures and helper methods defined by this package to deinstall (and then install again, if desired) the generic monitor JMS queue and to publish events to the generic monitor JMS queue. Details about using these procedures are described in the following topics:
The generic monitor JMS queue (bam_genericmonq) is installed when you install Oracle BPEL Process Analytics. However, if you have deinstalled it and now want to reinstall it, follow these steps:
Connect to the database as SYSDBA.
Run the install procedure:
SQL> exec bam.bam_generic_monitor.install; PL/SQL procedure successfully completed.
If you decide you want to deinstall the generic monitor JMS queue (bam_genericmonq), follow these steps:
Connect to the database as SYSDBA.
Run the uninstall procedure:
SQL> exec bam.bam_generic_monitor.uninstall; PL/SQL procedure successfully completed.
The createGenericMonitorPkg.sql script defines two publisher helper methods to assist you in publishing events to the generic monitor JMS queue:
A procedure to publish SQL SELECT statement output
The following procedure converts data returned by a SQL SELECT statement to the event format expected by the generic monitor, and then publishes the data returned by the SQL statement to the queue:
PROCEDURE publish(inSQL varchar2,
inEventType varchar2,
inTimeStamp VARCHAR2 DEFAULT NULL,
inTimeZone VARCHAR2 DEFAULT NULL);
Parameters for this procedure are as follows:
inSQL – The SQL SELECT statement that you want to convert to the required event format
inEventType – The event name to be assigned to the SQL SELECT statement output
inTimeStamp – The time stamp at which the event occurs
See "Required Date Format" for information about formatting the time stamp.
inTimeZone – The time zone in which the event occur
See "Required Date Format" for information about formatting the time zone.
The input to the inSQL procedure is converted to XML (using the DBMS_XMLGEN PL/SQL package) and then published to the bam_genericmonq queue.
|
Note: If this publish procedure is called from within a SQL trigger, you must either select from dual or use statement-level triggers (to avoid a mutating table exception with row-level triggers). |
A procedure to publish XML data to the bam_genericmonq
Use the following procedure to convert XML data to the required event format and publish it to the queue. Setting the constructGenericEvent parameter to FALSE, will publish the XML data to the queue, as is (unconverted):
PROCEDURE publish(inCLOB IN OUT NOCOPY CLOB,
inEventType varchar2,
inTimeStamp VARCHAR2 DEFAULT NULL,
inTimeZone VARCHAR2 DEFAULT NULL,
constructGenericEvent BOOLEAN default TRUE);
Parameters for this procedure are as follows:
inCLOB – The XML data that you want to publish to the bam_genericmonq JMS queue.
inEventType – The event name to be assigned to the XML data.
inTimeStamp – The time stamp at which the event occurs.
See "Required Date Format" for information about formatting the time stamp.
inTimeZone – The time zone in which the event occurs.
See "Required Date Format" for information about formatting the time zone.
constructGenericEvent - A Boolean value that specifies whether you want the XML data converted to the required event format. Specify TRUE to have the conversion performed; specify FALSE if you have already formatted the XML data using the required event format.
Oracle BPEL Process Analytics provides a script that displays the number of events in the queue and a portion of the payload from the most recent event. You can find this script in the following location, where OAS_HOME is the directory specification of the Oracle Application Server home where you installed Oracle BPEL Process Analytics:
OAS_HOME\integration\bam\admin\sql\bamShowGenericEvent.sql
When you connect to the database on which the queue is running and run the script, data such as the following is returned:
SQL> @bamShowGenericEvent.sql Number of events in bam_genericmonq: 7 Displaying the most recent event in queue : <?xml version="1.0"?> <BAMEvent><header> <timestamp>2005-05-13T07:58:36.772</timestamp> <timezone>-07:00</timezone> <type>deleteEmployee</type> </header> <payload><ROWSET><ROW num="1"> <EMPNO>30528</EMPNO> <ENAME>Name_30528</ENAME> <JOB>job_30528</JOB> < <MGR>30528</MGR> <HIREDATE>2005-04-22"T"16:00:00</HIREDATE> <SAL>3500</SAL> <COMM>0</COMM> <DEPTNO>10</DEPTNO> </ROW></ROWSET> </payload> </BAMEvent> PL/SQL procedure successfully completed.
You can publish events to a user-specified OJMS or JMS queue to do either of the following:
Publish events from a J2EE application
See Oracle Application Server Containers for J2EE Services Guide for conceptual information, and see the demonstrations at the following URL for examples:
http://www.oracle.com/technology/tech/java/oc4j/demos/904/index.html
Publish events from an Oracle database
See the scripts for implementing the BooksOnLine example in the Streams Advanced Queuing User's Guide and Reference for examples.
This section provides step-by-step instructions for monitoring an Oracle Database as a generic event source. This example demonstrates the following:
Using the XML SQL Utility (XSU) to create an .xsd file for the EMP table in the Oracle Database SCOTT sample schema.
Defining triggers on the EMP table such that every time an insert or delete operation is performed on the table, the data added or removed from the table is published to the bam_genericmonq.
Specifying the connection parameters to the generic event source.
Creating a composite event that contains both the insert and delete events. The correlation attribute used for the composite event is EMPNO.
Generating an event and viewing it in the Dashboard.
To monitor a generic event source, Oracle BPEL Process Analytics requires that events be defined using XSD or DTD. When the generic event source is an Oracle Database, you can use the XML Schema Utility to generate .xsd files from database tables, which then require minor adjustments for use with Oracle BPEL Process Analytics.
See Oracle XML Developer's Kit Programmer's Guide for complete details about the XML Schema Utility. Follow these steps to generate an .xsd file from an Oracle database table or view for use with Oracle BPEL Process Analytics:
Add the following libraries to the JAVA classpath:
classes12.jar (JDBC)
xsu12.jar (XML Schema Utility, which contains the Oracle XML class)
xmlparserv2.jar (Oracle XML parser)
Create an .xsd file for the database table data for which you want to capture events, by saving the output from the following command, where:
username/password is the user name and password for the account that you want to use to access the database
db-machine-name is the name of the machine on which the database is running
db-port is the port number on which the listener is listening, and db-sid is the database system identifier (SID)
SQL-statement is the SQL statement that specifies the table and table attributes to include in the schema definition file (.xsd)
java -classpath $CLASSPATH OracleXML getXML -user "username/<password" -conn "jdbc:oracle:thin:@db-machine-name:db-port:db-sid" -withSchema SQL-statement"
Delete the <Document> and <ROWSET> elements from the .xsd file and save it. You do not need to save it to a particular directory, but you will be asked to specify the directory location when you create a composite event on the generic event source.
See "Generating an .xsd File for the EMP Table" for an example of this process.
Follow these steps to generate an .xsd file for the EMP table and all of the table attributes:
Step 1: Specify the Java classpath.
Add the following classes to the Java classpath:
classes12.jar (JDBC)
xsu12.jar (XML Schema Utility, which contains the Oracle XML class)
xmlparserv2.jar (Oracle XML parser)
Step 2: Generate XML output for the database table of interest.
Use the XML Schema Utility to generate the required schema definition using the following command, which:
Connects user SCOTT with password TIGER to a database with SID db1 through port 1521 of host myhost, using the Thin driver.
Executes the query SELECT * FROM EMP WHERE ROWNUM < 1
The WHERE ROWNUM < 1 clause is specified to exclude the EMP table data from the generated .xsd file.
Converts the result to XML.
Places the results into a file named Employee.xsd.
If you want to try this example on your system, you need to replace myhost:1521:db1 with the system, port number, and database SID for your environment.
java -classpath $CLASSPATH OracleXML getXML -user "scott/tiger" -conn "jdbc:oracle:thin:@myhost:1521:db1" -withSchema "select * from emp where rownum<1" > Employee.xsd
The output should appear similar to that shown in Example 7-1. However, your output will not contain bold text; the bolding is added in Example 7-1 for clarity in describing the next step.
Example 7-1 Sample XSD Output from the XML Schema Utility
<?xml version = '1.0'?> <DOCUMENT xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="ROWSET"> <xsd:complexType> <xsd:sequence> <xsd:element name="ROW" minOccurs="0" maxOccurs="unbounded"> <xsd:complexType> <xsd:sequence> <xsd:element name="EMPNO" type="xsd:integer" minOccurs="0"/> <xsd:element name="ENAME" nillable="true" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="10"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="JOB" nillable="true" minOccurs="0"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="9"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="MGR" type="xsd:integer" nillable="true" minOccurs="0"/> <xsd:element name="HIREDATE" type="xsd:string" nillable="true" minOccurs="0"/> <xsd:element name="SAL" type="xsd:float" nillable="true" minOccurs="0"/> <xsd:element name="COMM" type="xsd:float" nillable="true" minOccurs="0"/> <xsd:element name="DEPTNO" type="xsd:integer" nillable="true" minOccurs="0"/> </xsd:sequence> <xsd:attribute name="num" type="xsd:integer"/> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema> <ROWSET xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="#/DOCUMENT/xsd:schema[not(@targetNamespace)]"/> </DOCUMENT>
Step 3: Edit and Save the Output.
The output generated in the previous step contains two extraneous elements, <DOCUMENT> and <ROWSET>, that you must delete. These elements are bold in the previous step.
Delete the <DOCUMENT> and <ROWSET> elements.
Save the edited output.
Connect to the database as the BAM user and grant privileges to the user SCOTT, by running the addGrantsForScottSchema.sql file located 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\admin\sql
For example:
> sqlplus BAM/BAM SQL> @addGrantsForScottSchema.sql Grant succeeded. PL/SQL procedure successfully completed. SQL> exit
To create triggers on the EMP table and publish the SQL INSERT and DELETE statements to the bam_genericmonq queue, connect to the database using the username SCOTT and the password TIGER and run the SQL script, createScottSchemaTriggers.sql.
> sqlplus SCOTT/TIGER SQL> @createScottSchemaTriggers.sql Trigger created. No errors. Trigger created. No errors. SQL> exit
Follow these steps to specify Oracle Database as a generic event source:
Open the Oracle BPEL Process Analytics Console and log in, as described in "Getting Started with the Admin Console".
Click Admin.
Click Event Source.
Click the Create button associated with the BPA Generic Sources table.
Specify ScottTiger for the event source name and specify the rest of the field values as described in Table 2-2.
Click Finish.
Follow these steps to create a composite event that includes insert and delete events, correlated by the EMPNO column:
If the Oracle BPEL Process Analytics Console is not open, open it and log in, as described in "Getting Started with the Admin Console".
Click Modeling.
Click Composite Events.
Click the Add Composite Event button.
Select the ScottTiger event source, and then click the Create button. The first page of the Add Composite Event Wizard opens.
On the Properties page of the wizard, follow these steps:
In the Name field, enter ScottTiger_CE.
In the Description field, enter: Composite event for ScottTiger example.
In the Timeout field, leave the values as 0 Days 8 Hours 0 Minutes.
Click Next. The Schema Definitions page opens.
On the Schema Definitions page, follow these steps:
In the Schema File field, enter the complete path to the Employee.xsd file you created in "Generating an .xsd File for the EMP Table".
Click the Add button.
Leave the Root Element for DTD field empty.
Click Next. The Events page opens.
On the Events page, follow these steps:
In the Event Name field, enter Employee. (This string, including uppercase and lowercase characters used in the string, must match the second parameter passed to the first bam.bam_generic_monitor.publish procedure in the SQL script that generates the events (createScottTigerSchemaTriggers.sql, in this example).
In the Schema Name field, keep Employee.xsd.
In the Root Element for DTD field, keep ROWSET.
Click the Add button.
In the Event Name field, enter deleteEmployee. (This string, including uppercase and lowercase characters used in the string, must match the second parameter passed to the first bam.bam_generic_monitor.publish procedure in the SQL script that generates the events (createScottTigerSchemaTriggers.sql, in this example.)
In the Schema Name field, keep Employee.xsd.
In the Root Element for DTD field, keep ROWSET.
Click the Add button.
Select deleteEmployee as the End Event.
Click Next. The Attributes page opens.
In the Attributes page, follow these steps:
In the first table, select Employee.
Expand the navigation tree.
Select EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM, and DEPTNO.
In the first table, select deleteEmployee.
Expand the navigation tree.
Select EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM, and DEPTNO.
Click Next. The Attribute Properties page opens.
In the Attribute Properties page, follow these steps:
In the first table, select Employee.
In the second table, select EMPNO as the correlation attribute.
In the first table, select deleteEmployee.
In the second table, select EMPNO as the correlation attribute.
Click Finish.
In a production system, events would be generated as a result of normal system operations. For the purposes of this example, connect to the database using the SCOTT/TIGER account, and issue the statements such as the following to generate events. Be sure to commit each statement and, for ease of viewing in the Real-Time Viewer, pause for a few minutes in between issuing each statement:
SQL> INSERT INTO EMP VALUES(1249,'istuart','Designer',10,sysdate,2000,0,20); SQL> COMMIT; SQL> INSERT INTO EMP VALUES(1300,'dBradford','ANALYST',10,sysdate,30000,0,30); SQL> COMMIT; SQL> DELETE FROM EMP WHERE EMPNO=1249; SQL> COMMIT; SQL> SQL> DELETE FROM EMP WHERE EMPNO=1300; SQL> COMMIT;
Open the Oracle BPEL Process Analytics Dashboard and view the events:
Open the Oracle BPEL Process Analytics Console and log in, as described in "Getting Started with the Admin Console".
Click Dashboard.
In the Switch View box, select Real-Time Viewer.
In the Composite Event box, select ScottTiger_CE. The Dashboard should appear similar to Figure 7-1.
Figure 7-1 Sample Dashboard for Generic Event Source
Click a data point in the Real-Time Viewer to see details about the event. For example, clicking the first data point in Figure 7-1, reveals the details shown in Figure 7-2.
Figure 7-2 Sample Composite Event Details for Generic Event Source
