SOA 11g Technology Adapters – ECID Propagation

Overview

Many SOA Suite 11g deployments include the use of the technology adapters for various activities including integration with FTP, database, and files to name a few. Although the integrations with these adapters are easy and feature rich, there can be some challenges from the operations perspective. One of these challenges is how to correlate a logical business transaction across SOA component instances. This correlation is typically accomplished via the execution context ID (ECID), but we lose the ECID correlation when the business transaction spans technologies like FTP, database, and files.

A new feature has been introduced in the Oracle adapter JCA framework to allow the propagation of the ECID. This feature is available in the forthcoming SOA Suite 11.1.1.7 (PS6). The basic concept of propagating the ECID is to identify somewhere in the payload of the message where the ECID can be stored. Then two Binding Properties, relating to the location of the ECID in the message, are added to either the Exposed Service (left-hand side of composite) or External Reference (right-hand side of composite). This will give the JCA framework enough information to either extract the ECID from or add the ECID to the message. In the scenario of extracting the ECID from the message, the ECID will be used for the new component instance.

Where to Put the ECID

When trying to determine where to store the ECID in the message, you basically have two options:

1. Add a new optional element to your message schema.
2. Leverage an existing element that is not used in your schema.

The best scenario is that you are able to add the optional element to your message since trying to find an unused element will prove difficult in most situations. The schema will be holding the ECID value which looks something like the following:

11d1def534ea1be0:7ae4cac3:13b4455735c:-8000-00000000000002dc

Configuring Composite Services/References

Now that you have identified where you want the ECID to be stored in the message, the JCA framework needs to have this information as well. The two pieces of information that the framework needs relates to the message schema:

1. The namespace for the element in the message.
2. The XPath to the element in the message.

To better understand this, let's look at an example for the following database table:

When an Exposed Service is created via the Database Adapter Wizard in the composite, the following schema is created:

For this example, the two Binding Properties we add to the ReadRow service in the composite are:

<!-- Properties for the binding to propagate the ECID from the database table -->
<property name="jca.ecid.nslist" type="xs:string" many="false">
  xmlns:ns1="http://xmlns.oracle.com/pcbpel/adapter/db/top/ReadRow"
</property>

<property name="jca.ecid.xpath" type="xs:string" many="false">
  /ns1:EcidPropagationCollection/ns1:EcidPropagation/ns1:ecid
</property>

Notice that the property called jca.ecid.nslist contains the targetNamespace defined in the schema and the property called jca.ecid.xpath contains the XPath statement to the element. The XPath statement also contains the appropriate namespace prefix (ns1) which is defined in the jca.ecid.nslist property.

When the Database Adapter service reads a row from the database, it will retrieve the ECID value from the payload and remove the element from the payload. When the component instance is created, it will be associated with the retrieved ECID and the payload contains everything except the ECID element/value. The only time the ECID is visible is when it is stored safely in the resource technology like the database, a file, or a queue.

Simple Database/File/JMS Example

This section contains a simplified example of how the ECID can propagate through a database table, a file, and JMS queue. The composite for the example looks like the following:

The flow of this example is as follows:

1. Invoke database insert using the insertwithecidbpelprocess_client_ep Service.
2. The InsertWithECIDBPELProcess adds a row to the database via the Database Adapter. The JCA Framework adds the ECID to the message prior to inserting.
3. The ReadRow Service retrieves the record and the JCA Framework extracts the ECID from the message. The ECID element is removed from the message.
4. An instance of ReadRowBPELProcess is created and it is associated with the retried ECID.
5. The ReadRowBPELProcess now writes the record to the file system via the File Adapter. The JCA Framework adds the ECID to the message prior to writing the message to file.
6. The ReadFile Service retrieves the record from the file system and the JCA Framework extracts the ECID from the message. The ECID element is removed from the message.
7. An instance of ReadFileBPELProcess is created and it is associated with the retried ECID.
8. The ReadFileBPELProcess now enqueues the message via the JMS Adapter. The JCA Framework adds the ECID to the message prior to enqueuing the message.
9. The DequeueMessage Service retrieves the record and the JCA Framework extracts the ECID from the message. The ECID element is removed from the message.
10. An instance of DequeueMessageBPELProcess is created and it is associated with the retried ECID.
11. The logical flow ends.

When viewing the Flow Trace in the Enterprise Manger, you will now see all the instances correlated via ECID:

Please check back here when SOA Suite 11.1.1.7 is released for this example. With the example you can run it yourself and reinforce what has been shared in this blog via a hands-on experience. One final note: the contents of this blog may be included in the official SOA Suite 11.1.1.7 documentation, but you will still need to come here to get the example.