Integration with Oracle E-Business Suite

Integration Repository Customization

2009-11-03T11:48:44Z

Oracle E-Business Suite (EBS) Integrated SOA Gateway (ISG) R12.1.1 supports customization of Integration Repository, allowing custom integration interfaces to be published along with Oracle seeded ones in the Integration Repository where they can be exposed to all users.

Users can create and annotate custom interface definitions based on Integration Repository Annotation Standards. The custom interface metadata compiled in a generated iLDT file can be uploaded to Oracle Integration Repository through backend processing. After the upload, these custom integration interfaces are displayed together with Oracle seeded ones through the Integration Repository user interface based on the interface type they belong to. Integration Repository Administrator performs the same administrative tasks for custom integration interfaces as he does for native integration interfaces. These tasks include creating security grants, generating and deploying Web services.

Details on Integration Repository Customization can be found at blog

Primer on Integration Repository

2009-10-13T10:32:00Z

What is Integration Repository?

Integration Repository is a catalog of Publicly defined annotated interfaces available in Oracle E-Business Suite applications. These interfaces are used by partners, consultants and developers for integration with any system, application, or business partner.

These interfaces are classified by Product Family or Interface type. But what is an Interface Type? An Interface type is nothing but the underlying integration technology being used by the E-Business Suite to define public integration points e.g. PL/SQL api’s, Open Interface Tables, XML Gateway Map, EDI gateway Map, Java api etc.

How to Browse/Search?

There are three ways to browse the Integration Repository. Either by Product Family, Standard or Interface type. Here is the snapshot of the classification.

Where can I find Integration Repository?

For 11i release, there is a hosted instance available at irep.oracle.com.

For release R12, the Integration Repository comes bundled with your Oracle E-Business Suite instance. In 12.0.X releases, Integration Repository is available as a Responsibility. But in 12.1.1 release, it is available under Integrated SOA gateway responsibility.

There is no hosted instance available for 12.0.X or 12.1.X releases.

In the next blog, I will discuss more on Integration Repository and the frequently asked questions around it.

PLSQL vs Java Business Event System

2009-07-31T14:50:31Z

Oracle Workflow provides Business Event System implementation within the database and in the middle tier. The implementation is exactly the same in terms of the event subscription processing in both these layers but the only difference is how the Developer wants to leverage Business Event System's capabilities for event processing requirements. With the availability of Business Event System implementation in PLSQL and Java, following subscription processing can be achieved.

Execute PLSQL rule function synchronously or asynchronously. Oracle Workflow provides a bunch of default rule functions in WF_RULE package for your use
Execute Java rule function synchronously or asynchronously. Oracle Workflow provides a default rule function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription to invoke web services.
Launch workflow process
Send event to an agent (AQ)

Workflow Business Events can be raised using one of two following ways.

PLSQL API WF_EVENT.Raise
Java method oracle.apps.fnd.wf.BusinessEvent.raise

As long as the call to these APIs does not throw an error, the event is raised successfully. There is a wrong notion among developers and administrators that all the events raised are enqueued to an agent (AQ) such as WF_DEFERRED or WF_JAVA_DEFERRED. No, it is not enqueued to an agent always, but it is driven based on how the subscription is defined. Now how are the event subscriptions dispatched and how to check the status of a subscription execution?

Subscriptions are either synchronous (phase < 100) or asynchronous (phase >= 100) with respect to the layer it is raised such as either PLSQL or Java and that layer's ability to dispatch the subscriptions. Following table gives an idea about how different subscriptions are dispatched.

Scenario	Event raised in	Subscription type	Subscription phase	Agent (AQ)	Dispatched by
1	PLSQL	PLSQL	>=100	WF_DEFERRED	Workflow Deferred Agent Listener
2	PLSQL	PLSQL	<100	None	Same session as WF_EVENT.Raise
3	PLSQL	Java	Any	WF_JAVA_DEFERRED	Workflow Java Deferred Agent Listener
4	Java	Java	>=100	WF_JAVA_DEFERRED	Workflow Java Deferred Agent Listener
5	Java	Java	<100	None	Same session as BusinessEvent.raise()
6	Java	PLSQL	>=100	WF_JAVA_DEFERRED	Workflow Java Deferred Agent Listener
7	Java	PLSQL	<100	None	Same session as BusinessEvent.raise()

Invoking Web Service from Oracle Workflow process

2009-07-27T00:19:59Z

Introduction

Integrated SOA Gateway (ISG) in Oracle EBusiness Suite 12.1 provides Service Invocation Framework (SIF) to natively consume and invoke web services. SIF uses Oracle Workflow Business Event System to provide necessary infrastructure to consume an abstract Web Service and dynamically invoke the Web Service without requiring any design-time code generation. In this blog post we will see a specific use case of how to invoke web services from an Oracle Workflow process that is designed using Oracle Workflow Builder and executed in the database by the Oracle Workflow Engine.

SIF setup

Please refer to 12.1 ISG Developer Guider topic "Defining Web Service Invocation Metadata" under chapter "Working With Oracle Workflow Business Event System to Invoke Web Services" for detailed information on creating Business Event System meta-data. A summary of the steps are given below.

Create an Invoker Business Event.
Create a Local Subscription of Action Type "Invoke Web Services" to the invoker event.
Create an Error subscription to the invoker event to handle any errors during invocation is also required.

Once the above Business Event System meta-data is created, raise the invoker Business Event to invoke the web service consumed within the Local event subscription. A Business Event can be raised either using a PLSQL API or a Java API. Hence, it can be assumed that SIF can be used to invoke web services from PLSQL or Java.

The PLSQL API is WF_EVENT.Raise and the Java API is oracle.apps.fnd.wf.bes.BusinessEvent.raise. SIF run-time code executes only on Java tier (OACORE or Concurrent Tier). Raising the invoker event using Java API that already runs on middle tier causes the web service to be invoked synchronously and the response available to the caller immediately. Whereas if the invoker event is raised in PLSQL, the web service is invoked asynchronously by Workflow Java Deferred Agent Listener in Concurrent Tier. To receive the web service response back in the database in asynchronous mode following set up is required.

Create a callback business event and set it as part of the "Invoke Web Services" Local subscription.
Specify a callback agent such as WF_JMS_IN to which the callback event can be enqueued. You can create and use any workflow agent to receive the response.
Create an External subscription to the callback event to handle the web service response from WF_JMS_IN.

After successful invocation of the web service, the Java Deferred Agent Listener sets the response to callback event's payload and enqueues to the callback agent. Running event listener on the callback agent executes the External subscription to perform the specified action. With above setup we are now ready to invoke a web service by raising the invoker business event. The invocation can be tested using business event test page.

Invoking from Workflow Process

Workflow processes include standard event activities such as Raise event and Receive event. Since Workflow processes execute within the database we will use the PLSQL message pattern discussed above to invoke the web service from workflow processes. Following steps are required to successfully invoke web service from workflow process using SIF.

Create Raise Event activity

Use Raise Event activity to raise the invoker event. A function activity can be used to create input message required for the web service and set to the invoker event payload.

Create a Receive Event activity

Use a Receive Event activity to receive the callback event in the workflow process. Callback event is raised after successful invocation of web service by Java Deferred Agent Listener.

Create an External Subscription to the callback event

Create an External subscription to the callback event with Workflow Type and Workflow Process set to the workflow process waiting to receive the web service response. The External subscription can also be used to simply execute a rule function to process the web service response.

Code Sample

Above use case is explained using a sample Workflow Process with required Business Event System meta-data. You may download the sample code for testing.

Files Uploaded

WFINVTSTE.wfx - Invoker Event and Callback (Receive) Event
WFINVTSTS.wfx - Local "Invoke Web Service" Subscription to Invoker Event, Error Subscription to Invoker Event, External Subscription to Callback Event
WFINVTST.wft - The Workflow process that raises the Invoker Event and Receives the Callback Event
WFINVTSTS.pls - PLSQL spec for function activities used in above Workflow Process
WFINVTSTB.pls - PLSQL body for function activities used in above Workflow Process

Instructions to use sample

Upload *.wfx files using Workflow Business Event System loader program oracle.apps.fnd.wf.WFXLoad
Upload *.wft file using Workflow Definitions Loader $FND_TOP/bin/WFLOAD
Compile *.pls files to APPS schema
Verify Workflow Java Deferred Agent Listener is up and running
Launch Workflow using LAUNCH.sql script. The workflow process sends a notification with the web service response to a specified recipient after successful invocation of web service.
Wait until Workflow Java Deferred Agent Listener completes execution of the "Invoke Web Service" subscription and enqueues response to WF_JMS_IN agent.
Configure an Agent Listener to run against WF_JMS_IN or another appropriate Callback Agent that you want to use to listen to callback events. An easy way to run listener is exececute PLSQL API WF_EVENT.Listen from sqlplus connected to APPS schema.

You may also launch the Workflow Process from Developer Studio and monitor the Workflow Process from Status Monitor functions available from Workflow Administrator Web Applications responsibility.

Native Services - EBS R12.1

2009-06-12T11:02:00Z

Steven Chan posted a blog which mentioned the presentation done by me and Neeraj.Chauhan in the last OOW’08.Continuing on the same thread, I would like to mention few basic and simple things in this blog.

Starting 12.1 release of e-Business Suite, you not only have Native SOAP based Services available, but also you can invoke external web-services which can be consumed by existing running processes in EBS. Let us go little deeper into this.

Native Services from EBS

From 12.1, Integration Repository allows you to generate and Deploy services for certain interfaces type by a click of a button. The interfaces which are supported on Integration Repository are PL/SQL api’s, XML Messages, Business Service Objects, Concurrent programs etc.

Here is a slide to explain it architecturally

The simple steps are:

Identify the public PL/SQL api you are interested in exposing as a service by searching in the Integration Repository.
Generate a Service (WSDL) out of it, by pressing the Generate WSDL button.
Deploy the Service by pressing Deploy button.
Grant the permission as who can access this Service.

You are all set. Use any industry client, and you should be able to invoke EBS PL/SQL api as services from outside.

Here is a blog written by my colleague Gautam Satpathy, who also works in the SOA Gateway team. It explains clearly how you can take a simple api like FND_PROFILE as a Web-Service and call it from outside.

Invocation of Services

If you are interested in invoking an external web-service from an existing Workflow process, OA framework page or from a Java program, all you need to do is define a Business Event, and create a Subscription of type “Invoke Web Service”. You can easily pass parameters to the called web-service, and take the output of the web-service back into your calling process.

Here is a slide to explain it architecturally

Again thanks to Gautam Satpathy for his blog which takes the previously generated FND_PROFILE api as a web-Service and calls it using the Invocation framework in EBS.

Gathering Stats for Workflow’s Queue Tables

2009-04-24T10:28:00Z

Statistics gathering is an important activity in order to enable the cost based optimizer to take a decision on the execution plan to choose from the various possible ones with which a particular SQL statement can be run. It is recommended to gather the statistics for an object when it is in steady state, i.e. when the corresponding tables have a fair amount of data giving out statistics which would lead the best execution plan to be picked by CBO.

From 10g onwards , Oracle database introduced Automatic Optimizer Statistics Collection feature in which a scheduled job GATHER_STATS_JOB runs in the nights and gathers stats for tables with either empty or stale statistics using DBMS_STATS package APIs. This indeed is a great feature but for highly volatile tables such as AQ/Streams tables it is quite possible that when the stats collection job runs, these tables may not have the data that is representative of their full load period. One scenario can be stats collection on queue tables when they were empty, and the optimizer, as a result, choosing poor execution plans when they have a lot of data in them during normal workload hours.

As a direct fix to tackle the above issue, from 10gR2 database onwards, AQ table stats are getting locked immediately after its creation so that the auto stats collector doesn't change it in the future. This can be confirmed as below:

SQL> CREATE TYPE event_msg_type AS OBJECT   
                  (  name            VARCHAR2(10), 
                     current_status  NUMBER(5),  
                     next_status     NUMBER(5)  
                   ); 
Type created.
--Create Queue Table
SQL> EXEC DBMS_AQADM.create_queue_table(
              queue_table=>'test_queue_tab',
              queue_payload_type=>'event_msg_type')
PL/SQL procedure successfully completed. 
--Create Queue
SQL> EXEC DBMS_AQADM.create_queue(queue_name =>'test_queue',
                             queue_table=>'test_queue_tab');
PL/SQL procedure successfully completed.
--Check for locks on stats
SQL> select owner, table_name, stattype_locked
     from dba_tab_statistics
     where stattype_locked is not null
     and owner='APPS' and table_name='TEST_QUEUE_TAB';
OWNER       TABLE_NAME      STAT
---------- ---------------- ----- 
APPS        TEST_QUEUE_TAB   ALL 
--Gather stats
SQL> EXEC dbms_stats.gather_table_stats('APPS','TEST_QUEUE_TAB')
BEGIN dbms_stats.gather_table_stats('APPS','TEST_QUEUE_TAB'); END; 
* 
ERROR at line 1: 
ORA-20005: object statistics are locked (stattype = ALL) 
ORA-06512: at "SYS.DBMS_STATS", line 18408 
ORA-06512: at "SYS.DBMS_STATS", line 18429 
ORA-06512: at line 1

As we can see above , queue table stats are locked and hence further stats gathering fails. We can still go ahead and use force parameter provided in DBMS_STATS package to override any lock on statistics:

SQL>exec dbms_stats.gather_table_stats('APPS','TEST_QUEUE_TAB'
					      ,force=>TRUE)
PL/SQL procedure successfully completed.

The recommended use is to gather statistics with a representative queue message load and keep the stats locked to avoid getting picked up by auto stats collector.

What happens in Apps Instance?

From Oracle Apps 11i (on top of Oracle Database 10gR2) instance onwards, the automatic statistics gathering job GATHER_STATS_JOB is disabled using $APPL_TOP/admin/adstats.sql , as can be confirmed below:

 
SQL> select job_name, enabled from DBA_SCHEDULER_JOBS 
WHERE job_name = 'GATHER_STATS_JOB';
JOB_NAME                       ENABLE
------------------------------ ------
GATHER_STATS_JOB               FALSE

Oracle Apps provides separate concurrent programs which make use of procedures in FND_STATS package to gather statistics for apps database objects. FND_STATS is basically a wrapper around DBMS_STATS and is recommended by Oracle for stats collection in Oracle Apps environment because of the flexibility it provides in identifying the objects with empty and stale stats. The modification threshold ( % of rows used to estimate) is fixed to 10% in DBMS_STATS while it can vary from 0 to 100% incase of FND_STATS.

But FND_STATS doesn't provide the force parameter to override any lock on statistics and hence fails while gathering statistics for a queue table whose stats are locked :

 
SQL> select owner, table_name, stattype_locked ,last_analyzed
  2   from dba_tab_statistics where table_name='WF_DEFERRED'
  3  and owner='APPLSYS';
OWNER          TABLE_NAME      STATT LAST_ANAL
-------------- --------------- ----- ---------
APPLSYS        WF_DEFERRED     ALL   23-FEB-09
SQL> exec fnd_stats.gather_table_stats('APPLSYS','WF_DEFERRED');
BEGIN fnd_stats.gather_table_stats('APPLSYS','WF_DEFERRED'); END;
*
ERROR at line 1:
ORA-20005: object statistics are locked (stattype = ALL)
ORA-06512: at "APPS.FND_STATS", line 1505
ORA-06512: at line 1

The same error is observed on running the Gather Table Statistics concurrent program for such queue tables. Gather Schema Statistics concurrent program in general skips the table incase any error is encountered while gathering its stats and hence the queue tables with locked stats are also skipped.

Hence currently , in order to carry out stat collection for Workflow queue tables whose stats are locked,the approach should be to unlock the queue table temporarily using DBMS_STAT’s Unlock APIs when the table have a representative load for the correct stats to be gathered, gather the statistics using FND_STATS and lock it again.

SQL> begin
  2    dbms_stats.unlock_table_stats('APPLSYS','WF_DEFERRED');
  3    fnd_stats.gather_table_stats('APPLSYS','WF_DEFERRED');
  4    dbms_stats.lock_table_stats('APPLSYS','WF_DEFERRED');
  5  end;
  6  /
PL/SQL procedure successfully completed.
SQL> select owner, table_name, stattype_locked ,last_analyzed
  2  from dba_tab_statistics where table_name='WF_DEFERRED'
  3  and owner='APPLSYS';
OWNER            TABLE_NAME       STATT LAST_ANALYZED
---------------- ---------------- ----- -------------
APPLSYS          WF_DEFERRED      ALL   12-APR-09

Another approach can be to unlock the WF queue table stats during the adpatch run itself as Oracle’s automatic stats collection feature is disabled in Apps environments and the stats collection in general occurs through the Apps provided concurrent programs. What say?

Looping within a Workflow Process

2009-03-24T07:12:06Z

While designing a workflow process there seems to be a general tendency to make the process as granular as possible.Each steps are broken into several simpler steps, which are executed as part of separate workflow activities. It does give a much finer understanding of the business processes to the end user.But sometimes this drive to 'make it simpler' can get us into different kinds of complexities.

Lets see this with one particular example:

Below is a simplified version of a workflow process part we came across recently:

Fig : Process 1

Here, notifications were being sent using workflow looping wherein completion of an activity causes a transition to another activity that has already been completed earlier. ‘Get Recipient’ activity in this particular case was determining the suitable notification recipient based on certain business rules while ‘Send Notification’ activity simply made use of Notification System’s Send() API to send the notification to the identified recipient. The loop ended when no more eligible recipient were found.

Two issues were observed in this particular set up:

1. The process taking too long a time (>40 hours) to complete when notifications were being sent to around 35K users.

2. The rate at which notifications were being created decreased as the time passed, i.e initially when the process started , around 12-16 notifications(for the respective recipient) got created per second and later this rate got reduced to one notification in 2 minutes.

The issue was reproducible in a separate instance for say 2500 notifications with same observations as mentioned above.It took more than 3 hours for the process to complete and the rate of notification creation did decreased with time.

Now see the below process extract wherein the two activities in Process 1 have been merged into a single activity:

Fig : Process 2

The activity simply does the job being carried out by those in Process 1 but within a PL/SQL loop rather than the workflow loop:

--------------------------------------------------------------

Loop Starts

Get Recipient Logic

Send Notification to the identified recipient

Loop ends

--------------------------------------------------------------

The process 2 completed for 2500 notifications in less than 2 minutes ! And there was no noticeable performance degradation in the rate at which notifications were created.

So , what made the difference?

In general , internally for each execution of a workflow loop , a number of extra DML statements will run while re-executing the same function activity again and again. And workflow never issue any intermediate commits while executing a given flow until it reaches the end of the flow or a blocking activity. Hence the overall DMLs in Process 1 would result in heavy usage of redo logs and rollback segments until a commit happens. The workflow engine in effect is unnecessarily stressed by the loop here leading to performance deterioration when this long running workflow loop can be easily avoided as done in Process 2.

At the end, from a developer perspective use your own judgement and common sense to decide on how granular your workflow process should be such that it doesn't hits us somewhere else as demonstrated above.

JAAS for e-Business Suite

2009-02-19T14:44:00Z

Technorati Tags: e-Business Suite JAAS LoginModule

This is an extension to the blog posted by Steven Chan which highlighted my session on Java Authentication and Authorization (JAAS) for e-Business Suite at the OOW'08. Let us look at how does the LoginModule helps in doing the Authentication and Authorization with the current architecture of EBS(e-Business Suite).

Authentication

In e-Business Suite , we store the user information mainly at two places. If EBS is single sign on (SSO) enabled, Oracle Internet Directory(OID) stores user credentials. Otherwise FND_USER table stores user credentials. The LoginModule carries out the Authentication transparently without an application having to know as how the EBS instance is configured.

Authorization

In EBS the authorization is done either on Function or on a Role. In a Function Based Authorization,each time a user accesses a function, a runtime check is made if the user is granted the function through a responsibility. If yes, the access is permitted, otherwise the access is denied. From 11.5.10 release onwards, EBS supports Role based access control (RBAC) mechanism through which a given user is granted a set of roles that allows access to a particular resource. In Role Based Authorization, the same principle is used in the implementation of LoginModule. The roles assigned to a given user are used for authorization checks.

Time to take an example and explain in detail. So here we go.

Using & Configuring e-Business Suite JAAS LoginModule

Let us configure a simple HelloWorld servlet to use Oracle EBS LoginModule. Assume that you want HelloWorld servlet to be accessed only by valid EBS users having EBS role called 'UMX|HELLOWORLD'. You can download the sample code from internet for HelloWorld servlet. Lets call this instance 'EBS' and assume that HelloWorld servlet is running on an external Application server called 'MYSERVER'. The configuration steps are as follows:

Apply the ARU patch 7211409 on the EBS instance 'EBS'. This is the same instance against which HelloWorld servlet authenticates and authorizes its users.
Successful patch application on 'EBS' creates a signed jar file called fndext.jar in $FND_TOP/java/jar directory. This is the jar file that contains the JAAS LoginModule implementation.
Download this jar file to 'MYSERVER'. This is the same application server where HelloWorld servlet is running. To download file, you can simply use any FTP tool.
Create a war file consisting WEB-INF/lib/fndext.jar, WEB_INF/classes/helloworld/HelloWorld.class and WEB-INF/web.xml. Sample web.xml is provided below for your convenience.
Configure HelloWorld servlet to use EBS Login Module for Authentication and Authorization. The below steps are for OC4J for Oracle Application Server. For other Application Server, please refer to application server specific documentation.
- Open Enterprise Manager's Application Server Control page.
- Deploy your application. One of the steps during your application deployment is to specify ‘Security Provider’ . The page is displayed asking for which JAAS login Module Class to use and its parameters.
- For Login Module Class, you have to specify oracle.apps.fnd.ext.jaas.security.auth.login.AppsLoginModule. This class takes two mandatory parameters: ConnectionMode and ConnectionReference. You have add these two parameters for this class.
  - Enter the value for ConnectionMode parameter as ‘datasource’. The value of ‘datasource’ directs AppsLoginModule class to use a datasource object to connect to EBS database.
  - The JNDI reference to the above datasource is mentioned in the parameter ConnectionReference. Configure a datasource for EBS instance and enter this JNDI reference name for the value of ConnectionReference parameter. For example, ‘jdbc/appsDs’
Create a role called 'UMX|HELLOWORLD' on e-Business Suite instance i.e. EBS. Follow the steps below

Login into the connecting E-Business Suite instance EBS as SYSADMIN. This is the instance which you want your application to authenticate and authorize its users.
Navigate to User Management Roles & Role Inheritance.
Click on Create Role button.
Create a role called UMX|HELLOWORLD.
Now, Navigate to User Management users.
Assign the role UMX| HELLOWORLD to all users that you want to have access to your HelloWorld Servlet application.

Ready to test!!

Try accessing your application. You will be authenticated and then allowed access if authorized, i.e., if you are granted the role UMX|HELLOWORLD.

Application Data Source

2008-11-16T18:41:35Z

E-business Suite now provides a Standard Data Source (javax.sql.DataSource) which can be used for an e-business database connectivity from J2EE application servers. You can configure this data source the same way as any other standard Data Source in your application server. The administrators of both, e-Business Suite instance and the Application Server, needs to configure the data source accordingly.

Let me provide a brief-overview of the steps involved from both administrators.

E-Business Suite Administrator:
1. If you are an 11i customer, please download the following patch 6930112 from Meta-link. For R12 customers, the patch comes bundled with the Oracle Applications Technology Update Pack 12.0.6 (Patch 7237006)
2. Create a new Application User and grant the 'UMX|APPS_SCHEMA_CONNECT’ role.
3. Register the Application Server instance as a trusted node by running the AdminDesktop utility on e-Business Suite instance.

Application Server Administrator:
1. Download the fndds.jar from the e-business Suite application tier.
2. Configure OC4J server with fndds.jar as a shared library.
3. Create a new connection pool using the application data source.
4. Provide the credentials of the newly created Application user.
5. Create a Data source using the above connection pool.

Now you are all set to use the new Data Source for database connectivity to an e-business suite instance. For detailed instructions,please refer to the readme in the metalink patches provided above.

Please stay tuned for more on Best Practices for Apps Adapter.