Page 1 of 33

Integration between Oracle E-Business Suite 12g and Oracle

BAM 11g (11.1.1.2.0)

Technical WhitePaper

March 2010

Created by Shafakut Hasanali (Ali)

Page 2 of 33

Acronyms ......................................................................................................................... 3

Introduction .................................................................................................................... 3

Oracle Business Activity Monitoring ...................................................................... 3

Business Event System .............................................................................................. 4

Oracle E-Business Suite Setup ............................................................................ 4

Package Creation .................................................................................................. 5

Queue Creation ..................................................................................................... 7

Agent & Subscription Setup ............................................................................. 8

Weblogic Setup ....................................................................................................... 11

Data Source .......................................................................................................... 11

JMS Components ................................................................................................ 16

Oracle BAM Setup .................................................................................................. 24

Create a Data Object ........................................................................................ 24

Define an Enterprise Message Source........................................................ 27

Conclusion ..................................................................................................................... 33

Page 3 of 33

Acronyms Abbreviation Description

EBS Oracle E-Business Suite

BAM Oracle Business Activity Monitoring

BES Business Event System

EMS Enterprise Message Source

AQ Advanced Queuing

PL/SQL Procedural Language/Structured Query Language

JMS Java Messaging System

JNDI Java Naming Directory Interface

JDBC Java DataBase Connectivity

XML EXtensible Markup Language

KPI Key Performance Indicator

SLA Service Level Agreement

Introduction Oracle E-Business Suite (EBS) provides applications to manage, capture, and analyze an

enterprise‟s business operations. In today‟s hyper-competitive marketplace, business operations must be monitored in real time, for instance, on demand manufacturing shops need to monitor suppliers‟ inventory levels and outstanding orders. Clearly, actionable real-time business intelligence solutions provide immense business

advantage to an enterprise. Today, Oracle E-Business Suite customers can leverage Oracle Business Activity Monitoring (Oracle BAM) (an Oracle Fusion Middleware component) to build

that business advantage. This whitepaper demonstrates integration between the Oracle E-Business Suite and Oracle BAM by building a custom procedure to monitor order entry status from Oracle E-Business Suite in real time. The following three steps describe the report building process:

1. Publish order details generated by the Oracle E-Business Suite using the Business

Event System (BES). 2. Load order details into Oracle BAM. 3. Create an Oracle BAM report based on order details.

Oracle Business Activity Monitoring Customer demands and choices have forced enterprises to streamline their business

operations and required enterprises to promise 24x7 customer services and SLA (service level agreements). The enterprises themselves need to measure KPIs (key performance indicators) to have real time visibility into their businesses to deliver on SLAs. For example, stockbrokers are promising transaction execution within a minute and FedEx is bound to package delivery dates. Clearly, enterprises need real time visibility into their operations, which can be provided by

Oracle BAM, a key technology component of Oracle Fusion Middleware. Oracle BAM also provides capabilities to correlate real-time information with business operations that have already happened, hence providing perspective around real-time metrics.

Page 4 of 33

The core components of Oracle BAM include:

Enterprise Message Sources (EMS) – providers of the real-time information flowing

through the enterprise to the Active Data Cache. Active Data Cache – high-performance, persistent, and memory-based storage system

to feed active streaming dashboard reports. Event Engine – monitors complex changing conditions in data in real time, based on

user-defined rules. Active Report Engine – assembles and formats the data for presentation in live

reports. Active reports are not static reports, but rather any data change is directly fed

into the report. Alerts – An alert on a report is triggered based on a rule to start another business

process, send an email to a mobile device, or any other corrective measure.

Business Event System A business event is a high-level business activity, which is about to happen or has happened.

For example, “purchase order created” is a business event, which serves two purposes:

An integration point for customers to connect with other applications. For instance when a purchase order is created in the Oracle E-Business Suite, update the promised inventory level in a legacy warehouse application.

A milestone in a business process that shall be monitored, and analyzed. For instance

an operations manager might want to monitor the purchase order pipeline and offer promotions when the order pipeline is not looking good.

Oracle E-Business Suite provides the Business Event System (BES) framework to manage business events.

Subscriptions can be registered with the BES framework, which are invoked upon occurrence

of the business event. The application behaviors and extensions that can be triggered and extended via BES subscriptions are:

Launching an Oracle Workflow process Executing custom Java or PL/SQL code Publishing the event as a message on a JMS-compliant Advanced Queue (AQ)

Oracle E-Business Suite Setup

We will perform multiple steps such as custom package creation, queue creation, and BES setup within Oracle E-Business Suite. The custom package provides flexibility of retrieving data from base or custom tables within the EBS Order management system.

Page 5 of 33

Package Creation Note: The following package script is provided as a sample, and requires more customization as per your business requirements. -- Script of procedure within package to enqueue message onto an AQ queue. CREATE OR REPLACE PACKAGE BODY APPS.xx_bam_enqueue_pkg AS -- Function that would be invoked by the business event. FUNCTION order_entry_enqueue ( p_subscription_guid IN RAW, p_event IN OUT NOCOPY wf_event_t ) RETURN VARCHAR2 IS l_xml_complete varchar2(2000); l_enqueue_options dbms_aq.enqueue_options_t; l_message_properties dbms_aq.message_properties_t; l_msgid raw(16);

l_jms_text_message sys.aq$_jms_text_message; l_recipients dbms_aq.aq$_recipient_list_t; l_jmsOracleConnectionID raw(16); l_order_start_dt varchar2(30) := ''; l_order_booked_dt varchar2(30) := ''; l_creation_dt varchar2(30) := ''; l_last_update_dt varchar2(30) := ''; l_key_id1 xx_om_monitor_events_log.key_id1%TYPE; l_header_id oe_order_headers_all.header_id%TYPE; l_module_name varchar2(30) := 'ORDER_ENTRY'; l_operating_unit varchar2(10) := ''; CURSOR lcu_order_details (cp_header_id NUMBER) IS -- Temporary table that was created in EBS to hold order-related information; you can access the related details from order header tables. SELECT * FROM xx_om_order_events_all WHERE header_id = cp_header_id; BEGIN l_key_id1 := TO_NUMBER (p_event.getvalueforparameter ('KEY_ID1')); l_header_id := l_key_id1; l_creation_dt = sysdate; FOR lcr_order_details IN lcu_order_details(l_header_id) LOOP -- date formatting to match BAM datetime pitcure. IF lcr_order_details.ORDER_START_DATE is not NULL THEN l_order_start_dt := to_char(lcr_order_details.ORDER_START_DATE,'YYYY-MM-DD')||'T'||to_char(lcr_order_details.ORDER_START_DATE,'HH24:MM:SS'); END IF; IF lcr_order_details.ORDER_BOOKED_DATE is not NULL THEN l_order_booked_dt := to_char(lcr_order_details.ORDER_BOOKED_DATE,'YYYY-MM-DD')||'T'||to_char(lcr_order_details.ORDER_BOOKED_DATE,'HH24:MM:SS'); END IF; IF lcr_order_details.MIN_LINE_CREATION_DATE is not NULL THEN l_min_line_creation_dt := to_char(lcr_order_details.MIN_LINE_CREATION_DATE,'YYYY-MM-DD')||'T'||to_char(lcr_order_details.MIN_LINE_CREATION_DATE,'HH24:MM:SS'); END IF;

Page 6 of 33

IF lcr_order_details.MAX_LINE_CREATION_DATE is not NULL THEN l_max_line_creation_dt := to_char(lcr_order_details.MAX_LINE_CREATION_DATE,'YYYY-MM-DD')||'T'||to_char(lcr_order_details.MAX_LINE_CREATION_DATE,'HH24:MM:SS'); END IF; IF lcr_order_details.LAST_UPDATE_DATE is not NULL THEN l_last_update_dt := to_char(lcr_order_details.LAST_UPDATE_DATE,'YYYY-MM-DD')||'T'||to_char(lcr_order_details.LAST_UPDATE_DATE,'HH24:MI:SS'); END IF; l_jms_text_message:=sys.aq$_jms_text_message.construct; -- 'TEMP' subscriber used for enqueueing messages. l_recipients(1) := sys.aq$_agent('TEMP', NULL, NULL); l_message_properties.recipient_list := l_recipients; -- jmsOracleConnection Id used to address local message filtering. SELECT SYS_GUID() INTO l_jmsOracleConnectionID FROM DUAL; l_jms_text_message.set_string_property('JMS_OracleConnectionID', l_jmsOracleConnectionID); -- 'bamfilter' message selector used for controlling type of messages being enqueued. l_jms_text_message.set_string_property('bamfilter',l_module_name); -- complete XML creation with the data embedded, the structure is similar to the BAM data object that would be created later. l_xml_complete := '<?xml version="1.0"?>' ||

'<ORDER>' || '<HEADER_ID>' || l_HEADER_ID || '</HEADER_ID>' || '<ORDER_NUMBER>' || lcr_order_details.ORDER_NUMBER || '</ORDER_NUMBER>' || '<ORG_ID>' || lcr_order_details.ORG_ID || '</ORG_ID>' || '<OPERATING_UNIT>' || l_operating_unit || '</OPERATING_UNIT>' || '<ORGANIZATION_CODE>' || lcr_order_details.ORG_CODE || </ORGANIZATION_CODE>' || '<ORDER_START_DATE>' || l_order_start_dt || '</ORDER_START_DATE>' || '<ORDER_BOOKED_DATE>' || l_order_booked_dt || '</ORDER_BOOKED_DATE>' || '<NUMBER_OF_LINES>' || lcr_order_details.NUMBER_OF_LINES || '</NUMBER_OF_LINES>' || '<ORDER_TYPE>' || lcr_order_details.ORDER_TYPE || '</ORDER_TYPE>' || '<USER_NAME>' || lcr_order_details.USER_NAME || '</USER_NAME>' || '<LAST_LOG_ID>' || lcr_order_details.LAST_LOG_ID || '</LAST_LOG_ID>' || '<CREATION_DATE>' || l_creation_dt || '</CREATION_DATE>' || '<LAST_UPDATE_DATE>' || l_last_update_dt || '</LAST_UPDATE_DATE>' || '<LAST_UPDATED_BY>' || lcr_order_details.LAST_UPDATED_BY || '</LAST_UPDATED_BY>' || '<LAST_UPDATE_LOGIN>' || lcr_order_details.LAST_UPDATE_LOGIN || '</LAST_UPDATE_LOGIN>' || '</ORDER>' ; -- Set the XML payload as text for the message being enqueued. l_jms_text_message.set_text(l_xml_complete); -- Enqueue the message with the header data onto the defined AQ queue. dbms_aq.enqueue(queue_name => 'XX_OM_MONITOR_Q', enqueue_options => l_enqueue_options, message_properties => l_message_properties, payload => l_jms_text_message, msgid => l_msgid ); EXIT; END LOOP; RETURN 'SUCCESS'; EXCEPTION WHEN OTHERS THEN -- for debug purpose, you can also try sending this message to your own custom table. DBMS_OUTPUT.put_line('xx_bam_enqueue_pkg.order_entry_enqueue EXCEPTION' || SQLERRM); RETURN 'ERROR'; End order_entry_enqueue; END xx_bam_enqueue_pkg;

Page 7 of 33

Queue Creation

In the example, a new queue using Oracle Advanced Queuing (AQ) technology was created. The queue name and queue table name used were called „XX_MONITOR_Q‟ and „XX_MONITOR_QTab‟ respectively. Normally, Oracle does not recommend making modifications to Oracle E-Business Suite‟s database schemas, but for this example a queue in the APPS schema was created for convenience. The SQL commands are as follows:

-- Script to drop objects if they exist with the same name. BEGIN SYS.DBMS_AQADM.STOP_QUEUE ( QUEUE_NAME => 'APPS.XX_OM_MONITOR_Q'); SYS.DBMS_AQADM.DROP_QUEUE ( QUEUE_NAME => 'APPS.XX_OM_MONITOR_Q'); SYS.DBMS_AQADM.DROP_QUEUE_TABLE ( 'XX_OM_MONITOR_QTab'); END; / -- Script for creating the queue table of type JMS Text Message. BEGIN dbms_aqadm.create_queue_table( queue_table => 'XX_OM_MONITOR_QTab', queue_payload_type => 'sys.aq$_jms_text_message', multiple_consumers => true ); END; -- Script for creating an AQ queue BEGIN SYS.DBMS_AQADM.CREATE_QUEUE

( QUEUE_NAME => 'APPS.XX_OM_MONITOR_Q' ,QUEUE_TABLE => 'APPS.XX_OM_MONITOR_QTab' ,QUEUE_TYPE => SYS.DBMS_AQADM.NORMAL_QUEUE ,MAX_RETRIES => 5 ,RETRY_DELAY => 0 ,RETENTION_TIME => 0 ); END; / -- Script for starting up the queue once created. BEGIN SYS.DBMS_AQADM.START_QUEUE ( QUEUE_NAME => 'APPS.XX_OM_MONITOR_Q' ,ENQUEUE => TRUE ,DEQUEUE => TRUE ); END; / -- Script for defining subscriber which is used for enqueue and dequeue. DECLARE aSubscriberTemp sys.aq$_agent; BEGIN aSubscriberTemp := sys.aq$_agent('TEMP', '', 0); dbms_aqadm.add_subscriber ( queue_name => 'XX_OM_MONITOR_Q' ,subscriber => aSubscriberTemp ); END;

Page 8 of 33

Event & Subscription Setup

The event setup is required for determining which business event is used for tracking the progress of order within EBS, while the subscription setup helps us invoke the custom code

once the event occurs. The following section elaborates the complete steps. Log into E-Business Suite with user having “Workflow Administrator Web (New)” responsibility. Note: Oracle E-Business Suite provides the Oracle Workflow administrator Web pages as a web-based application. Please contact your Oracle E-Business Suite administrator for access to

the Workflow Administrator Web Applications responsibility to set up Oracle E-Business Suite for integration with Oracle BAM.

Click on the Business Events link. For this tutorial we are using an existing business event that was defined in the system already and contains „BAM‟ in its name. Search for that business event using wild card characters:

Page 9 of 33

Once the business event is found, click the Subscription icon as shown below:

Create a new subscription on the event to invoke the custom PL/SQL. Click Create Subscription as shown below:

Specify the System. By default it is the machine on which E-Business Suite is hosted. The business event name is populated by default. Set the Phase greater than 100 (e.g. 102) as we want the processing to happen asynchronously (would be done through WF_DEFERRED listener).

Provide the Action Type as Custom, because we need custom processing (PL/SQL API

invocation). Select the value Stop and Rollback from the On Error drop down list, and then click Next.

Page 10 of 33

On the next page within the PL/SQL Rule Function text box specify the custom PL/SQL API

(e.g. xx_bam_enqueue_pkg.order_entry_enqueue) that was defined earlier in order to

enqueue a message into the AQ (Advanced Queuing) queue.

Provide SYSADMIN for the Owner Name and Owner Tag. In the following graphic it has been

assigned as Oracle Receivables and AR as the business event existed under it.

Click Apply, and the subscription should be added successfully to the business event and appear as enabled.

Page 11 of 33

Oracle WebLogic Server Setup In 11g, Oracle WebLogic Server is used as an application server, and in order to setup an AQ queue, the following components must be configured: data source, JMS Module, JMS Foreign Server, JMS Connection Factory, and JMS Destination. The setup steps for each component are explained in the following sections.

Data Source

AQ is kind of queue on database, therefore we need to define a data source which points to the database where the queue is hosted. Access the Oracle WebLogic Server Administration console and log in using administrative privileges.

Once logged in expand the left hand side tree view and click Services -> JDBC -> Data Sources.

Page 12 of 33

Click New within the Data Sources table.

Provide a Name for the data source (e.g. EBIZ_DEV_DB) and provide the JNDI Name (e.g.

jdbc/db/EBSAM2) that is used to reference this data source as it is later used in the JMS

configuration. Select Oracle as the Database Type and select *Oracle’s Driver (Thin)

for Instance connections; Version 9.0.1,9.2.0,10,11 for the Database Driver.

Then click Next.

Page 13 of 33

Deselect the Support Global Transactions checkbox, and click Next.

Provide the values for Database Name, Host Name, Port, Database User Name,

Password, and Confirm Password. This is the EBS database and the apps user that is used

to access the queue. Then click Next.

Page 14 of 33

On the next page the wizard will create the JDBC URL as well as all the information provided on the previous screen. Click Test Configuration to ensure that the connection to the EBS database is successful, then click Next.

Page 15 of 33

The next screen prompts you to select the target server on which the data source is deployed. Select bam_server1 as the target on which the data source is deployed, then click Finish.

Page 16 of 33

This completes the setup of the data source used by AQ. Proceed with the setup of the rest of the JMS components.

JMS Components

In order to configure AQ on Oracle WebLogic Server in 11g we must define the JMS components (module, foreign server, connection factory, destination). Start by first creating a

JMS module as a top-level container for hosting the rest of the components. In the Oracle WebLogic Server Administration console, on the left hand side Domain Structure tree view click Services -> Messaging -> JMS Modules.

Page 17 of 33

Click New within the JMS Modules table listed on the right hand side.

Provide the Name (e.g. BAM_EBIZ) and then click Next.

Page 18 of 33

Select the Target Servers for the JMS Modules, which in our case is bam_server1, then click Next.

Click Finish, but do not select the checkbox for adding resources, because you will add it later.

Page 19 of 33

The new JMS module is listed as one of the modules within the JMS Modules table:

Click on the newly created JMS module BAM_EBIZ.

The Configuration tab is displayed, and you can add the rest of the resources (Foreign

Server, Connection Factory, etc.) Click New, select the Foreign Server radio button within the type of resources listed, and then click Next.

Page 20 of 33

Provide the Name of the Foreign Server (e.g. BAM_EBIZ_FOREIGN), and then click Next.

By default, the target server selected is bam_server1. Click Finish.

Page 21 of 33

The Foreign Server is now listed as one of the resources within the table.

Click on the newly created Foreign Server BAM_EBIZ_FOREIGN. The Configuration tab is displayed. Proceed with adding the rest of the configuration to this server by providing the following values: JNDI Initial Context Factory: oracle.jms.AqjmsInitialContextFactory

JNDI Properties: datasource=jdbc/db/EBSAM2 (Note: This must be the same JNDI provided

during creation of datasource in the earlier step.) Default targeting Enabled checkbox: Yes

Page 22 of 33

Click Save, click the Destinations sub-tab within the Configuration tab, and click New.

Page 23 of 33

Provide the following values, and then click OK. Name: BAM_OM_EBIZ

Local JNDI Name: jms/BAMEBIZTopic (Note: This JNDI name would then be used as JMS Destination within the EMS configuration in Oracle BAM.) Remote JNDI Name: Topics/XX_OM_MONITOR_Q (Note: This is the topic that was used during the queue creation.)

The newly created Destination is displayed in the Destinations table.

Click the Connection Factories sub-tab within the Configuration tab, and click New.

Page 24 of 33

Provide the following values, then click OK.

Name: BAM_EBIZ_CF

Local JNDI Name: jms/BAMEBIZTopicCF (Note: This JNDI name would then be used for JMS Connection Factory within the EMS configuration in Oracle BAM.) Remote JNDI Name: TopicConnectionFactory

The newly created connection factory is displayed within the Foreign Connection Factories

table.

The console prompts you to restart the server so that the JMS changes can take affect. This completes the setup required on the Oracle WebLogic Server side for AQ. Now proceed with the Oracle BAM EMS setup described in the next section.

Oracle BAM Setup

The Oracle BAM setup involves creating a data object, and then defining an Enterprise Message Source in order to dequeue the messages from the AQ defined in the earlier section.

Create a Data Object Access the Oracle BAM home page using the following URL: http://<host_name>:<port>/OracleBAM.

Page 25 of 33

Provide a valid set of credentials that has access to complete Oracle BAM functionality as shown below:

Click Architect to open the Web application where you can define the data object and the EMS (The data object must be defined first because it is required in the EMS setup). Oracle BAM Architect is launched in a new browser window. On the top left-hand side dropdown list select Data Objects. The right-hand side frame allows you to create sub-folders and data objects.

Page 26 of 33

Click the Create Data Object link.

Provide the Name for the new data object (e.g. EBS_ORDER_ENTRY). Provide the Location

for the new data object, which in this example is the Amway folder. Browse and select that

location.

Page 27 of 33

Click the Add a field link, and add the fields required to be tracked for an order entry within

EBS. The structure of the fields has been provided below:

FieldName Field Type Field Length

HEADER_ID STRING 100

ORDER_NUMBER FLOAT

ORG_ID STRING 100

ORGANIZATION_CODE STRING 3

ORDER_START_DATE DATETIME

ORDER_BOOKED_DATE DATETIME

NUMBER_OF_LINES INTEGER

USER_NAME STRING 100

LAST_LOG_ID INTEGER

CREATION_DATE DATETIME

LAST_UPDATE_DATE DATETIME

LAST_UPDATED_BY INTEGER

LAST_UPDATE_LOGIN INTEGER

Once all of the fields are added, click the Create Data Object button. The graphic below shows how the data object layout looks after creation:

Define an Enterprise Message Source

The next step is to define an Enterprise Message Source (EMS) that dequeues the messages from the EMS AQ queue, and maps the data to the data object. If necessary, launch Oracle BAM Architect again from the Oracle BAM home page, select

Enterprise Message Source from the top left-hand dropdown list, and click the Create link.

Page 28 of 33

Provide the following values in the Enterprise Message Source definition form: FieldName Description Example

Name The name of the EMS. OrderEntryMessageSource

Initial Context Factory The Oracle WebLogic Server JNDI factory that would be used for looking up the initial context.

weblogic.jndi.WLInitialContextFactory

JNDI Service Provider URL

The JNDI URL for accessing the queue. (ensure protocol is t3 and port is included)

t3://uslx46c.intranet.local:9001

Topic/Queue Connection Factory

Name

The JNDI name of the Connection Factory defined

within Oracle WebLogic Server.

jms/BAMEBIZTopicCF

Topic / Queue Name The JNDI name of the Topic defined within Oracle WebLogic Server

jms/BAMEBIZTopic

JNDI UserName & JNDI Password

They are optional and if specified then it should have Oracle WebLogic Server console access.

Weblogic/welcome1

JMS Message Type Type of message which would

be sent by source (text / map)

TextMessage

Durable Subscriber Name (Optional)

The subscriber used for dequeuing the message.

TEMP (It is essential to provide this since we are using the same for enqueue, check the package script

above.)

Message Selector

(Optional)

Used for filtering messages,

only one key-value pair can be used.

bamfilter=ORDER_ENTRY (We have

set the filter using the setStringProperty, check the package script above.)

Data Object Name The data object which would receive data from this EMS

/Amway/EBS_ORDER_ENTRY (Browse and select the data object we created in the earlier section.)

Operation The operation to be performed on the input record

received (Insert/Update/Upsert/Delete)

Upsert (As the order would be progressing through various stages

we selected Upsert [Insert if the record does not exist, else update].)

Batching Used for batching multiple transactions together for

No

Page 29 of 33

performance.

Transaction If batching is enabled then

should be set to Yes in order to commit in one single transaction.

No

Start When BAM Server Starts.

Start the EMS once the server is up & operational.

Yes

JMS UserName & JMS Password (Optional)

This EMS will not perform any XML Formatting, as the XML enqueued by AQ contains the related fields. The Message Specification is used for defining the kind of XML that is received within the queue.

Specify the Message Element Name as ORDER since that is being used in the XML that is

created within the package (check the script above). Because the Column Value contains the exact tags itself, select the Element Tag radio button. The date time formatting has already

been taken care of in the package script so there is no need to select that checkbox.

The Source to Data Object Field mapping would be a straight map, because the XML enqueued has the same tags as the data object field name. From the right-hand side dropdown, select the data object field and provide the same value in the left-hand side textbox as shown below.

Select the Key field checkbox on HEADER_ID as that is unique across multiple transactions

related to the same order.

Page 30 of 33

Once all the fields are specified, click Save, and the EMS should look like this:

Page 31 of 33

Click the Test link to verify that the EMS can connect to the queue, and the configuration defined within Oracle WebLogic Server is working as expected. It should display the status as

Test OK.

Page 32 of 33

Click the Start link to trigger the EMS to start dequeuing messages received in AQ and passing those values onto the data object.

Click the Metrics link to display the statistics on the dequeued messages:

The data object also reflects the same within its contents:

Page 33 of 33

This data object can now be used for plotting reports using the Oracle BAM Active Studio tool.

A sample report created through this data object is displayed below:

Conclusion Oracle E-Business Suite customers can build real-time monitoring and analytical solutions by

leveraging integration between the Business Event System and Oracle BAM to provide enterprise wide operations, KPIs, and SLA visibility.