24 Monitoring Instance Message Data With Oracle BAM

This chapter provides end-to-end instructions for setting up Oracle B2B instance message monitoring with Oracle BAM.

The Oracle B2B-BAM integration does not work with Oracle XE database. It will work with Oracle 10g EE and Oracle 11g EE versions.

This chapter contains the following topics:

24.1 Introduction to Monitoring Oracle B2B with Oracle BAM

Oracle BAM provides a framework for creating dashboards that display real-time data inflow and creating rules to send alerts under specified conditions. Oracle BAM can be configured to monitor an Oracle B2B instance by following the procedures in the remaining sections of this chapter.

Note:

While it is possible to create an Oracle BAM dashboard on an external data source defined on the instance message table, active data is not supported on external data sources, so the resulting report does not display real-time updates.

24.2 Creating a Data Source in Oracle WebLogic Server

You could use an existing data source if it exists or create a new data source following the steps below:

  1. Open the Oracle WebLogic Server Administration Console and log in.

    http://host_name:port_number/console
    

    The host_name is the name of the machine where Oracle BAM is installed, and the default port_number for Oracle WebLogic Server is 7001.

  2. Select Data Sources in the JDBC section, and click New.

  3. Configure the data source:

    1. Enter a Name for the data source (for example, BAMAQDataSource).

    2. Enter a JNDI name from the data source (for example, jdbc/oracle/bamaq). This name is used to configure a foreign JMS server.

    3. Select Oracle for the Database Type.

    4. Select Oracle's Driver (Thin) in the Database Driver field.

    5. Click Next.

  4. Uncheck Support Global Transaction, and click Next.

  5. Enter your Database SID into the Database Name field (for example, ORCL).

  6. Enter the host name of the machine where the database is installed as the HostName (for example, localhost).

  7. Enter the database Port number (for example, 1521).

  8. Enter the Username and Password, and click Next.

  9. Click Test Configuration.

  10. Once the test is successful, click Next.

  11. Select the server where Oracle BAM is deployed, and click Finish.

24.3 Creating a Foreign JMS Server

To create a foreign JMS server:

  1. Add an Oracle WebLogic Server JMS module.

    1. In Oracle WebLogic Server Administration Console, on the Home page navigate to the JMS Modules page.

    2. Click New to create a new Oracle WebLogic Server JMS module.

    3. Enter a name for the JMS module (for example, BAMAQsystemModule), and click Next.

    4. Assign the target as the server where Oracle BAM is deployed, click Next, and click Finish.

      Note:

      It is recommended that you create a Subdeployment. Select JMS Module>SubDeployment>New. Use the subdeployment in the subsequent steps where you have the Subdeployment tab.

  2. Target the Subdeployment to the JMS Server by selecting it from the list.

  3. Add an AQ JMS Foreign Server to the JMS module.

    1. Select the JMS module that was previously created.

    2. Click New, and go to the list of JMS resources.

    3. Select the Foreign Server option, and click Next.

    4. Enter a Name for the Foreign Server (for example, BAMAQForeignServer), and click Finish.

  4. Configure the AQ JMS Foreign Server.

    1. Select the AQ JMS Foreign Server that was previously created.

    2. Enter oracle.jms.AQjmsInitialContextFactory in the JNDI Initial Context Factory field.

    3. Enter datasource=data_source_jndi_location In the JNDI Properties field, where data_source_jndi_location is the JNDI location of your data source (for example, jdbc/oracle/bamaq).

    4. Check the Default Targeting Enabled checkbox.

  5. Add Connection Factories to the AQ JMS Foreign Server.

    1. Select the AQ JMS Foreign Server that was previously created.

    2. Select the Connection Factories tab.

    3. Enter a name for the connection factory. This is a logical name referenced by Oracle WebLogic Server.

    4. Enter the local JNDI name that will be used by Oracle BAM Enterprise Message Source to look up this connection factory in the Local JNDI Name field (for example, jms/BAMAQQueueCF).

    5. Enter QueueConnectionFactory in the Remote JNDI Name field.

      Note:

      The following are the alternative options available. If you use this connection factory in a global transaction, select an XA-based connection factory, otherwise select a non-XA based connection factory.

      • QueueConnectionFactory

      • ConnectionFactory

      • XAQueueConnectionFactory

      • XATopicConnectionFactory

      • XAConnectionFactory

    6. Click OK.

  6. Add Destinations to the AQ JMS Foreign Server.

    1. Select the AQ JMS Foreign Server that was previously created.

    2. Select the Destinations tab

    3. Enter a name for the destination. This is a logical name referenced by Oracle WebLogic Server. It is not related to the destination name.

    4. Enter the local JNDI name that will be used by Oracle BAM Enterprise Message Source to look up the destination in the Local JNDI Name field (for example, jms/BAMAQQueue).

    5. In the Remote JNDI Name field, enter Queues/queue_name if the destination is a queue, or enter Topics/topic_name if the destination is a topic.

      For example, the default name for an AQ queue created for the Oracle B2B - Oracle BAM integration is Queues/B2B_BAM_QUEUE.

    6. Click OK.

  7. Restart Oracle WebLogic Server.

24.4 Create a B2B Data Object using Oracle BAM Architect

To create a B2B data object:

  1. Log in to Oracle BAM at the following URL:

    http://host_name:port_number/OracleBAM 
    

    The default port number is 9001.

  2. Select Architect to open the Oracle BAM Architect application.

  3. Select Data Objects in the drop down list.

  4. Select the Samples folder, and create a subfolder named B2B.

  5. Click on the Create Data Object link

  6. Enter B2BDO in the Name field.

  7. Click Add a Field.

  8. Enter values for Fields in Data Object.

  9. Repeat, clicking Add a Field to add all fields as listed in Table 24-2.

For more information about creating Oracle BAM data objects, see "Defining and Managing Oracle BAM Data Objects" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

24.5 Define a JMS Message Source Using an Oracle BAM Enterprise Message Source

To define a JMS message source:

  1. Log in to Oracle BAM at the following URL:

    http://host_name:port_number/OracleBAM 
    

    The default port number is 9001.

  2. Select Architect to open the Oracle BAM Architect application.

  3. Select Enterprise Message Sources in the drop down list.

  4. Click Create, and enter the Enterprise Message Source information for AQ JMS Queue as indicated in Table 24-1, leaving unmentioned fields with default or blank entries.

    Table 24-1 Enterprise Message Source Properties for AQ JMS Queue

    Property Values and Examples

    Name

    Enter a display name for the Enterprise Message Source (for example, B2B_EMS).

    Initial Context Factory

    Enter weblogic.jndi.WLInitialContextFactory

    JNDI Service Provider URL

    Enter t3://localhost:9001

    Note: If Oracle BAM is installed is on an Administrator Server use port 9001. If Oracle BAM is installed on a managed server use default port 7001, or the port number configured by the system administrator.

    Topic/Queue Connection Factory Name

    Enter the name of your connection factory (for example, jms/BAMAQQueueCF).

    Topic/Queue Name

    Enter the name of your JJMS topic (or queue) (for example, jms/BAMAQQueue).

    Data Object Name:

    Choose the B2B data object to send the values received from AQ JMS server

    Operation

    Choose the Insert or Upsert operation, depending on the use case.


  5. To configure Source Value Formatting, check the DateTime Specification checkbox, and select the MM/dd/yy H:mm:ss format in the drop-down list.

    Note:

    The incoming XML value for the date, in the format MM/dd/yy HH24:MI:SS, must be converted into the MM/dd/yy H:mm:ss format that the Enterprise Message Source expects so that it can be stored correctly in the data object

  6. Complete the Source to Data Object Field Mapping so that data from the incoming XML can be mapped to an appropriate field in the B2B data object. See Table 24-2 for a list of fields in the incoming XML which will be retrieved from the B2B instance table.

  7. Click Save.

  8. Select the B2B_EMS Enterprise Message Source, and click Start. The status changes to Started in a few seconds.

After starting the Enterprise Message Source, any messages that are inserted by the database job into the AQ JMS queue are instantly available in the B2BDO data object.

To view the contents of the B2BDO data object, select Data Objects from the Oracle BAM Architect drop-down menu. Browse and select the B2BDO object. Click Contents to view the contents.

New rows are inserted into B2BDO as the database job reads incoming messages from the B2B instance table and inserts them onto the AQ JMS queue.

For more information on creating Oracle BAM Enterprise Message Sources, see "Creating Oracle BAM Enterprise Message Sources" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

24.6 Mapping Oracle B2B Instance Messages to Oracle BAM Data Objects

Table 24-2 lists the Oracle B2B instance message fields. These fields can be used to design data objects and Enterprise Message Sources in Oracle BAM to monitor Oracle B2B performance in real time.

Note that the payloads (APP_PAYLOAD, PAYLOAD, WIREPAYLOAD) are not included in the list below. They are not transferred for performance reasons.

Table 24-2 Oracle B2B Instance Message Fields

Field Type

ID

NOT NULL VARCHAR2(256)

REFERTOID

VARCHAR2(256)

B2BMESSAGEID

NOT NULL VARCHAR2(256)

ACKNOWLEDGEMODE

VARCHAR2(256)

MESSAGEDATETIME

DATE

MESSAGETYPE

VARCHAR2(256)

STATE

VARCHAR2(256)

REMAININGRETRY

NUMBER(10)

DIRECTION

VARCHAR2(256)

TIMETOACK

VARCHAR2(256)

TPA_NAME

VARCHAR2(256)

XPATH_EXPRESSION1

VARCHAR2(1024)

XPATH_EXPRESSION2

VARCHAR2(1024)

XPATH_EXPRESSION3

VARCHAR2(1024)

XPATH_NAME1

VARCHAR2(256)

XPATH_NAME2

VARCHAR2(256)

XPATH_NAME3

VARCHAR2(256)

XPATH_VALUE1

VARCHAR2(256)

XPATH_VALUE2

VARCHAR2(256)

XPATH_VALUE3

VARCHAR2(256)

DOCUMENT_DEFINITION

VARCHAR2(256)

CREATED

DATE

MODIFIED

DATE

SEND_TIMESTAMP

DATE

RECEIVE_TIMESTAMP

DATE

NATIVE_MSG_SIZE

NUMBER(10)

TRANSLATED_MSG_SIZE

NUMBER(10)

BM_RESUBMIT_COUNT

NUMBER(10)

ERRORCODE

VARCHAR2(256)

ERRORTEXT

VARCHAR2(1024)

ERRORDESCRIPTION

VARCHAR2(2000)

PROCESSING_TIME

NUMBER(10)

DOCUMENTTYPE

VARCHAR2(513)

CORRELATIONID

VARCHAR2(256)

FABRIC_ECID

VARCHAR2(512)

FABRIC_COMPOSITE_NAME

VARCHAR2(512)

AM_RESUBMIT_COUNT

NUMBER(10)

TRANSACTIONCONTROLNUMBER

VARCHAR2(256)

GROUPCONTROLNUMBER

VARCHAR2(256)

INTERCHANGECONTROLNUMBER

VARCHAR2(256)

PROTOCOLWORKAREA

CLOB

B2BWIREMESSAGEID

VARCHAR2(256)

B2BTIMESTAMP

DATE

CONVERSATIONID

VARCHAR2(1024)

PROTOCOLMESSAGEID

VARCHAR2(1024)

URL

VARCHAR2(1024)

TRANSPORTPROTOCOL

VARCHAR2(513)

TRANSPORTHEADERS

VARCHAR2(2000)

WM_RESUBMIT_COUNT

NUMBER(10)

DOCUMENTPROTOCOL

VARCHAR2(513)

EXCHANGEPROTOCOL

VARCHAR2(513)

AGREEMENTID

VARCHAR2(256)

SENDERNAME

VARCHAR2(256)

SENDERID

VARCHAR2(513)

RECEIVERNAME

VARCHAR2(256)

RECEIVERID

VARCHAR2(513)


24.7 Creating a Dashboard to Monitor Oracle B2B

Real-time monitoring dashboards are created using Oracle BAM Active Studio. Create a dashboard to monitor Oracle B2B using the B2BDO data object.

To create a simple report:

  1. Log in to Oracle BAM at the following URL:

    http://host_name:port_number/OracleBAM 
    

    The default port number is 9001.

  2. Select Active Studio to open the Oracle BAM Active Studio application.

  3. Click Create A New Report.

  4. Select a Tiled Report with four quadrants.

  5. In the upper left quadrant, select Bar Chart (you may need to click twice).

    A sample bar chart is displayed, and the view editor opens at the bottom of the Oracle BAM Active Studio window.

  6. In the view editor Data Objects selection, select B2BDO and click Next.

  7. In the Group By list, select state.

  8. In the Chart Values list, select b2bMessageId and click Next.

  9. Click Change View Properties and enter the following information:

    Enter B2B State in the View Title field.

    Check the Display Legend checkbox.

  10. Click OK.

  11. Similarly, follow the instructions in the Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring to create display information for the other quadrants in the dashboard.

    For example, you could group by documentProtocol, exchangeProtocol or direction of the messages in the other three quadrants.

  12. Once you are finished configuring view for each of the quadrants, save the dashboard.

  13. Go to the main Oracle BAM page and select Active Viewer.

  14. Select the dashboard that you created to view it in Oracle BAM Active Viewer.

  15. The views in the dashboard refresh automatically when any new instances are created in the b2b_instancemessage view, and the data is pushed into the B2BDO data object. The changes are reflected instantaneously.

For more information about creating Oracle BAM dashboards, see Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring.

24.8 Enabling the Oracle BAM Integration in Oracle B2B

To enable the Oracle BAM integration in Oracle B2B, set the following properties in the Oracle B2B Administration>Configuration tab:

Enable BAM - Set to true. When b2b.enableBAM is set to true, the Oracle B2B user interface automatically starts the database job in the database to monitor new instances in the b2b_instancemessage view. When b2b.enableBAM is set to false, the user interface automatically removes the database job from the database.

BAM Polling Interval – the interval in minutes when the database job polls the Oracle B2B instance table for any updates and puts them on the AQ JMS queue for uptake by Oracle BAM. Values less than a minute can also be specified, for example, 0.5 minutes.

Description of b2b_bam_enable.gif follows
Description of the illustration b2b_bam_enable.gif