Soa Suite 10.1.3.3 – ESB, BPEL – Nice-to-knows, pitfalls

I’ve been checking out the different capabilities and new features of the Adapter-framework in ESB and BPEL for some weeks now and came across some nasty pitfalls, nice-to-knows, … which I would like to share with you.

Of course I would like to share thoughts, opinions and start discussions on these topics.

ESB:

• How to define xsd-validation on file-adapter (validate payload at runtime-option isn’t available in file adapter) : In the ESB console, select the routing service which is invoked after the inbound file adapter. See the “Definition” tab. The validation option is in the “Operation Details” section. (with thanks to Ronald)

• Define error-handling on file-adapter for erroneous files: use the ‘rejectedMessageHandlers’ endpoint property which you need to define manually in the esb-file (for more information have a look at the technical note about error handling http://www.oracle.com/technology/products/integration/adapters/pdf/Adapter_TN_004_Adapter_ErrorManagement.pdf

BPEL:

• Inserting master-detail data using DB Adapter functionality : Referring to my experiences so far it’s best best way to make use of stored procedures instead of the toplink mappings file. I am mainly using the stored procedures because the tooling support in Jdeveloper (wizards, toplink ui), I still miss a good ui for the toplink support. Also it is easy to give the task to create an PL/SQL api to the PL/SQL developers that are working on a certain application. (with thanks to Orjan)

• [Error ORABPEL-10007]: unresolved messageType for “{http://schemas.oracle.com/bpel/extension}RuntimeFaultMessage”: When you’ve defined an empty bpel process (which is best practice to do the brain-work) you will face this issue when defining fault-handling inside your bpel-process. To solve this error you need to import the RuntimeFault.wsdl inside the adapter you’re using. Following import statement needs to be added:

• Best practices when invoking Bpel Processes from different UI’s (Flex, JSF, …) : Many thanks to Hajo for his explanation: It is best practice to use the default ways to invoke a BPEL process – create a WSDL that maps to WSIF binding in a controlled environment and to a SOAP/HTTP binding in a more B2B type of scenario. A call to the BPEL API would be a “custom” solution that needs way more governance to communicate with fellow developers and to maintain properly, when compared to the straightforward standard way. . For more details see OTN Thread: http://forums.oracle.com/forums/thread.jspa?messageID=2329384&#2329384

• Use multiple sources in transform-activity: In 11g a new feature has been added to be able to use multiple sources using bpel 2.0 (bpel:doXslTransform(string, node-set, (string, object)*)). The workaround in 10.1.3.3 is by using the params-approach => http://blogs.oracle.com/rammenon/2007/05/07. Or by using an assign-activity with append-functionality to add the variable inside your source-target and in the same assign-activity add the process-xslt functionality to call your xsl to populate the source with the target-information.

Invoking Web Services from Database:

• Call an esb service using the UTL_HTTP package => ORA-29266: end-of-body reached => make sure to pass variables using String-notation instead of Character-notation

Interesting New Features in 10.1.3.3 :

• Controlling the Size of a Rejected Message (10133technotes.pdf):
  You can now control the size of a rejected message by specifying the following
  endpoint property for the inbound File/FTP adapter partner link.
  In this example, you reject 100 lines from the file since the actual file is too large.
  oracle.tip.adapter.file.debatching.rejection.quantum=”100”

• ESB Endpoint Properties : e.g. ability to add RejectedMessageHandler to file adapter services

Enhancement Requests:

• Ability to validate xml payload at runtime on Adapter-level instead of on domain level or routing service level
• Ability to add xsi:nil attribute using xsl-functionality in transform-activity
• File-adapter: Ability to skip columns besides skipping rows + ability to use special characters in column headers

Well that’s it for now … feel free to share thoughts, comments, etc.

Tips & Tricks that’ll save you a lot of time regarding ODI, Flex, Soa Suite

Latelly I’ve been spending a lot of time regarding deployment and configuration of Adobe Flex applications integrated with Bpel on an OC4J-container.

On the other hand I’ve been experimenting a lot with ODI and how the tool will handle changing data models, changing datasources, …

Lastly I’ve been playing around with invocation of Bpel Processes using Web Service Proxy Clients instead of the Bpel Invocation API.

The question that’s still unanswered because no documentation or benchmarks or best practices are available yet is: ‘What’s the best practice in invoking bpel processes, the Bpel Invocation API or Web Service Proxy Clients?’

Tips & Tricks ODI:

• Interesting Notes: 423740.1, 423817.1
• Grant dba-privileges to your source-db-user, otherwise you’ll get ‘insufficient privileges’ exceptions when trying to execute your interfaces

Handling changing data models (new tables, deletion of existing attributes in tables, addition of new attributes, additional relationships, … ) :

• Go to your datamodel and reverse engineer the changed tables again. New attributes are added, deleted attributes aren’t removed yet because they’re referenced in interfaces in your ODI Designer.
• Go to your interfaces defined in the Designer-tab in ODI: remove all active mappings to the attributes that were deleted
• Go back to the model-tab in designer and right-click the attribute in your tabel and choose delete. When all references are updated correctly (no active mapping), the attribute will be deleted from your datamodel

Tips & Tricks Flex:

• When you’re getting weard errors regarding ‘conversion exception between java.util.Date and java.util.Calendar’ or exceptions regarding producer or consumer-errors => make sure you’ve defined ‘autocommit’-property to false on your data services (Using LCDS)
• How to handle static data without usage of Value Object or Data Transfer Objects => use SQLAssembler without usage of java-classes or actionscript-classes in your data-management-config.
• rtmp-host connection failure on OC4J => try to reset the connection-port to another value than the default one which is ’2038′. I’ve defined the value to ’2035′ and now no errors are thrown anymore
• Use [managed] attribute to make sure all changes on objects are synced between 2 clients
• Deploying data-management-config to different JEE Servers, e.g. Tomcat and OC4J. When you deploy to tomcat you have to define the full JNDI-location which would be for example: java:/comp/env/jdbc/flexDS. When you deploy to an OC4J, you need to define the short JNDI-descriptor: jdbc/flexDS.

The other exceptions, weard behaviour was already addressed in earlier posts:

• You need to add an xsl-choose-when-otherwise xsl-node structure to you transform-activity in your bpel-process and in the otherwise-tag define the xsi:nil=true on your attribute to make sure the web service proxy won’t set this attribute to required.
• You need to update the toplink-mapping file being generated in bpel when using the database adapter. Relationships aren’t defined properly, because the method accessor is checked for all one-to-many relationships whilst these aren’t defined in the java wrapper classes. Uncheck these ‘map to method accessors’ and these exceptions will disappear. You can uncheck these when drilling down in your toplink.mwp file into to your object on your mappedCollections.

A beautiful one were all newbees in SOA Suite spend ages and ages to figure out what the problem is … Oracle please fix this ???

You’ve installed SOA Suite (you can choose which version) and entered a custom password during installation for your oc4jadmin-password, not the ‘welcome1′ password. You can choose your own password wright ?

But when the newbee starts creating his first bpel and esb projects, there are weard errors poping up: ‘connection timed out’, ‘jndi-location for db-adapter isn’t properly defined’, …

Well, weard but true, the ‘welcome1′ password is defined hardcoded in different ‘oc4j-ra.xml’ files used in the jmsadapter-folder, dbadapter-folder, … Make sure to change the passwords correctly when you’re drilling through the different Oracle By Example-exercices or tutorials.

Integrating Flex and Data Management Services with a Bpel process – What about Typed Collections?

As you can remember we’re working out a flex application using Data Management Services and Flex for the client-side and Bpel at server side.

During development I ran into a blocking issue regarding using typed collections in my ActionScript objects.

Why would I use Typed Arguments, Typed Collections or Typed Arrays ?
My bpel process is using a Global Business Object (GBO), an XML Schema Definition, that defines the entire structure of the business objects I will need in the dossier management lifecycle. The bpel process will be cut pu into different sub processes which will define the needed process lifecycle for the dossier management system we’re building.

Of course this kind of business functionality will be handling master-detail data, e.g. a dossier has dossier_members and dossier_members have address_information.

If we create a web service proxy client for our bpel process, the different objects used in this process will be defined as Java Objects. The hierarchical structure of the dossier-element or – object will be defined in the following manner:

public class Dossier implements java.io.Serializable {
protected int id;
protected be.ws.proxy.types.DossierMembersCollection dosMembersCollection;

public class DossierMembersCollection implements java.io.Serializable
{
protected be.kg.ws.proxy.types.DossierMembers[] dossierMember;

The ActionScript Objects I defined for these server side objects :

[Managed]
[RemoteClass(alias="be.kg.ws.proxy.types.Dossier")]
public
class Dossier
{
public var id:int;
public var dosMembersCollection:DossierMembersCollection;

[Managed]
[RemoteClass(alias="be.kg.ws.proxy.types.DossierMembersCollection")]
public class DossierMembersCollection
{
public var dossierMembers:ArrayCollection;
}

The exception I run into :

ArgumentError: Error #2004: One of the parameters is invalid. at
flash.net::NetConnection/flash.net:NetConnection::invokeWithArgsArray()

What does this mean?
In order for this to work, you need to serialize, you’d need to override both the readExternal and writeExternal methods on both the client and server to take of the serialization of the typed collections yourself.

Practical Approach:

• Implement the Externalizable Interface at Client- and Server-side
• Overwrite the readExternal()- and writeExternal()-method in both your client and server classes which match (i.e. the read methods exactly match the write methods on both client and server). You need to serialize your fields as well as the source field of the ArrayCollection (it is an Array).

Take care of serialization and deserialization at server-side, use Externalizable Interface:

public class DossierMembersCollection implements java.io.Serializable ,
Externalizable { protected be.kg.ws.proxy.types.DossierMembers[] dossierMembers;

public DossierMembersCollection() { }

/*** Deserializes the client state of an instance of dossierMembers. */ public void readExternal(ObjectInput in) throws IOException,
ClassNotFoundException {
System.out.println(“Receiving array ———————–”);
Object[] obj2 = (Object[]) in.readObject();
System.out.println(“Read input array obj2 ———————–”);

if (obj2 != null) {
DossierMembers[] dossierMembers = new DossierMembers[obj2.length];
System.out.println(“Initialized dossierMembers———————–”);
loop over the object array and cast the Object-classes to your custom class.
System.out.println(“Looping over array ———————–”); dossierMembers[i] = (DossierMembers) obj2[i];

System.out.println(“DossierMembers: ” + dossierMembers[i].toString());
}}

System.out.println(“Receiving array DONE ————————”); }

/*** Serializes the server state of an instance of dossierMembers. */

public void writeExternal(ObjectOutput out) throws IOException { out.writeObject(dossierMembers); }

Take care of serialization and deserialization at client-side:

[Managed]

[RemoteClass alias="be.kg.ws.proxy.types.DossierMembersCollection")]

public class DossierMembersCollection implements IExternalizable {

public var dossierMembers:ArrayCollection;

public function readExternal(input:IDataInput):void {
trace(“***********Reading dossierMembers”);
var array:Array = input.readObject() as Array;
if (array!=null) {
trace(“****Array received”);
dossierMembers = new ArrayCollection();
Loop over the array and add the arrayElements as typed objects to your collection in the following way:

dossierMembers.addItem(array.pop() as DossierMembers);

trace(“**Number of dossierMembers : ” + dossierMembers.length); }

public function writeExternal(output:IDataOutput):void {

trace(“Write ArrayCollection dossierMembers to array”);

var array:Array = new Array();

loop over object-array and add array-items to the collection: {

array.push(dossierMembers.getItemAt(i));

trace(dossierMembers.getItemAt(i).toString()); }

output.writeObject(array); trace(“Done”); } }

If you get random errors there will propbably be a mismatch between server- and client-side objects. The two approaches you can use are: print statements or stopping in your read/write external methods in the debugger. Step through actionscript classes and Java classes using Flex Debugging mode, so you can ensure that you are reading exactly what you are writing.

Hopefully this will help a lot of people facing the same issues regarding typed objects in an Adobe Flex Environment.

Oracle Open World – Let’s present some Use Cases

One week to go until Oracle Open World kicks of and it will be my 1st attendance, and to be honnest I’m pretty nervous ;o)

The last few weeks I’ve been trying to integrate my oracle bpel processes with a Flex User Interface, and with success … which means I have new material to discuss with the SOA Community.

The case I would like to discuss with the different fusion regional directors, ace’s and of course the product team will hold following topics (already explained on this blog):
- Use Case: Migrate existing Excel data using Oracle Data Integrator
- Use Case: Analyse Business processes using BPA Suite and BPM processes and generate bpel blue print using bpa suite
- Use Case: integrate Flex User Interface with existing Bpel Processes using Web Service Proxy Clients for the middletier

These are the 3 different approaches I’ve used so far for an existing customer, trying to evaluate BPA Suite and ODI using a real-time case and implemting a business process driven application using bpel & flex.

I’m really looking forward to the discussions to exchange experience & expertise !

See you there!

Eclipse & Jdeveloper Join Forces – My Bpel-enabled Flex Application

For one of my projects I need to be able to work out a RIA using Flex as the front-end, integrated with bpel processes as the back-end.

To be able to integrate these bpel processes with my flex user interface, I’ve created web service proxy clients in Jdeveloper.

These web service proxy clients can be invoked by flex using RPC or Livecycle Data Services, we’ve chosen for the last, LCDS.

After defining the architectural blue-print, I’m able to start implementing the first bpel process. In this post I will guide you through the different issues I’ve stumbled into during the development-track!

1. Installation-tips/-problems regarding Middletier with integrated BPEL :

• Tip: Make sure that the version of the Application Server and Bpel Process Manager match the version of your JDeveloper IDE. In my case I’m working with the patched IAS Version 10.1.3.3 and Jdeveloper 10.1.3.3
• Tip: When you’re installing an OracleAS Middle Tier you need to make sure you check ‘Configure this as an Administration OC4J instance’ when you want use Enterprise Manager. This is made optional because you can work in a clustered environment, lets say your production environment, where only 1 oc4j-instance needs to server as the Administration environment
• Problem/Solution: When installing patch 10.1.3.3 on your existing Oracle Application Server you run into an exception when trying to overwrite Apache.exe => this probably means a Virus Scanner is running on your operating system which is preventing Unversial Installer of updating the file.

2. Problem/Solution Development-track, JDeveloper 10.1.3.3 IDE:

• Problem, ‘Cannot edit WebService proxy after Webservice endpoint url has changed’: I’ve defined my bpel process and web service proxy, but my middletier’s hostname has changed which means the bpel processes’ endpoint changed as well. I’ve manually updated the _Stub.java file, generated for the webservice proxy, and changed the endpoint url to the new hostname. If I try to edit the webservice proxy now, by choosing ‘Edit Handlers and Custom Mappings’, I get a message ‘Could Not Invoke Wizard’. The message points out that the old webservice endpoint is still used somewhere/somehow. I couldn’t find a reference to the old endpoint anywhere in the generated java-files. After some digging I finally found the cause, the webservice_proxy.proxy file. You need to change this file to be able to use the wizard again.
• Problem/Solution: I’ve defined an XSD-file with default-attributes for my bpel process, this xsd file is validated and my bpel process is succesfully deployed BUT … If I try to create a web service proxy for this bpel process I’m getting a nullPointerException. This exception is actually true because I’ve defined the default-attribute for an xs:element with a ref-attribute, in other words, this xs:element refers to an existing defined xs:element. Solution: Define the ‘default’-attribute on the xs:element definition, using the name- and type-attribute and not the xs-element used to define your complex-type.

3. Problem/Solution Development-track, Eclipse IDE & Flex Plug-in :

• Problem/Solution: Exception is thrown when you run your flex application ‘illegal override of rtmpChannel’. This error can be due to incompatible project files and eclipse jar-files, as in my case I imported an already existing projet in my new eclipse environment. To solve this issue I’ve created a new flex dataservices project and copied all the jar-files in the web-inf/lib folder into the imported project
• Problem/Solution: ‘Selected wizard could not be started , Plug-in was unable to instantiate class’; this error occurs when you try to create a flex component. The solution in my case was to recreate my development environment, in other words install eclipse, flex plug-in, lcds again.
• Problem/Solution: ‘Unable to access UserTransaction in DataService’, this errors occurs when you try to invoke the dataservice you’ve configured in your flex application using lcds. This probably means you need to configure JOTM in your tomcat server, or appliction server environment. Check out: http://kb.adobe.com/selfservice/viewContent.do?externalId=6b82874f&sliceId=2

I will keep you posted!

Changing the default password ‘welcome1′ of Oracle Bpel Process Manager

When you’re installing Oracle Software you always need to specify username and password settings for the administrator-profile, such as for Oracle Application Server or Oracle Database.

The same applies when installing Oracle SOA Suite 10.1.3.1 or Oracle Bpel Process Manager Option on Oracle Application Server Entprise Edition.

But there’s a catch here, you need to use the default password ‘welcome1′ when installing Oracle Bpel Process Manager to make sure the default processes for the Worklist Application are deployed succesfully.

The samples provided with Oracle Bpel Process Manager still need to be updated to be able to run them, because the default password ‘welcome1′ is used in the configuration files.

After the Oracle Bpel Process Manager has been installed you can update the administrator-password by performing the following steps:

• Go to Enterprise Manager of your Oracle SOA Suite or Application Server installation
  
• Click on the setup-link on top of the Application Server Control to update the password of the IAS Administrator account, which is ‘oc4jadmin’

• To change the password of the Bpel-admin users, you need to navigate back to the home page of your Enterprise Manager and click on the OC4J instance which is created for your Bpel Process Manager. Click on the ‘administration’ tab of your OC4J instance

• Click on the ‘Security Providers’ Task in the Administration Tasks

• Click on the ‘Instance Level Security’ Button to be able to identify the used realms by the oC4j instance and the defined users and roles in this realm.

• Click on the Second Tab in this screen to have a look at the used realms by this OC4J instance. The default realm installed is the ‘jazn.com’ realm. You can add other realms or modify the existing one.

• To change the passwords of the admin-users you need to click on the Users-link which is shown for the given realm ‘jazn.com’. In this screen you can then look-up the bpel-admin users and change the default passwords. The admin-users used by bpel are the ‘oc4jadmin’ and ‘bpeladmin’-user.

First steps in developing sexy screens for Bpel Processes … yep that’s wright … let’s do some Flex-and-Oracle-SOA Integration

Today I started building my first Flex application using Data Management Services … why Data Management Services I hear you thinking.

Don’t get me started on that topic ;o)

The Flex Data Management Service (FDMS) provides a mechanism to maintain data distributed over the client and server tiers.

The Service supports features such as:

• Data Synchronization
• Data Replication
• Occasionally Connected Clients

Additionally, this mechanism offers the possibility of extended functionality in a couple of areas:

• Automatic synchronization of multiple clients viewing the same accounts data via server “push”.
• Automatic re-synchronization of client and server data following a server or communications outage.

Now you know why I would choose for FDMS, indeed less work for me and less code to maintain.

The FDMS will need to communicate with my Oracle BPEL Processes which hold all the nesessary process-flow and business logic. How can I interface Flex and BPEL … well no ifficulty lies in there because every deployed BPEL Process is a Web Service so let’s start interfacing.

This also means I’m working with two IDE’s , one for the front-end and one for the back-end:

• Back-end: JDeveloper to design the bpel processes and define proxies for these processes
• Front-end: Eclipse to integrate flex and bpel processes, to define FDMS, ActionScript, mxml-files, …

So I’ve packaged my webservice proxy’s and added them on the classpath of my flex-application. Now I need to define my Assembler-class to be able to hook up the bpel processes with FDMS.

In order to integrate the prototypes client tier with the back-end server tier using Flex’s Data
Management Service mechanism, I need to implement a custom Java “Assembler” class.

The Flex Data Service instantiates the Assembler java class and invokes its methods.

To enable this, two additional things need to be done on the server side:

• The Web Service Proxy to be called needs to be included in the Flex Data Services classpath.
• The Flex Data Services configuration files need to be updated with a definition of the
  Data Management Service.

For the client tier I need to define the needed ActionScript objects that will be mapped automatically to the POJO’s used in my Bpel Process (Web Service).

The only downside of this, is the need for defining this one-to-one mapping in an ActionScript object whilst in these days you would use IntroSpection to accomplish this. Now I need to duplicate the object-declaration which is already known in POJO’s as well in ActionScript-objects.

Untill now I’m defining all the needed ActionScript-objects manually, aren’t there any generators available for this monkey-task, and afterwards I can start building the UI using mxml.

How to Integrate Bpel Processes with a User Interface

There are different ways to call/instantiate bpel processes from a front-end application.
Depending on the customers’ knowledge and expertise the choice between the different solutions can be made accordingly.

In this blog-post I will explain some of these options in short:

• Call Bpel Process from Java-Code:

String input = “1450″;

// Here you need to define the request-operation of your bpel process

String xml =
“<asyncloanflowprocessrequest
xmlns=”http://xmlns.oracle.com/AsyncLoanFlow”&gt;
<input>”+input+”</input></asyncloanflowprocessrequest>”;

Locator Locator locator = new Locator(“default”,”bpel”);
IDeliveryService deliveryService = (IDeliveryService)locator.lookupService(IDeliveryService.SERVICE_NAME);

// construct the normalized message and send to Oracle BPEL Process Manager
NormalizedMessage nm = new NormalizedMessage();
nm.addPart(“payload”, xml );
deliveryService.post(“AsyncLoanFlow”, “initiate”, nm);

• Call Bpel Process from your User Interface (JSP, JSPX, JSF, …):

This means you need to define the same code as defined in the above java-sample
in a jsp-script tag.

• Use the Databinding layer of ADF Faces to integrate the Faces Application with your Bpel Process:

1. Create BPEL WebService DataControl defined on the WSDL-endpoint of the BPEL Process





2. Create new JSF JSP page
3. Drag & Drop UI Components based on DataControl



4. Run

• Define a Web Service Proxy on your deployed Bpel process:

1. Create WebService Proxy defined on the WSDL-endpoint of the BPEL Process




2. Create new JSF JSP page
3. Call the Web Service Proxy Service from your backing-bean code to initialize the deployed bpel process. Bind this method to the submit/invoke/initiate-button when you want to call the bpel process.
4. Run

Other options can be explored as well, but these are the most common ones to think of.